npm package: @my-liminal-space/cw-site-assets
Description: A library for pulling Cloudflare Workers Site assets from the site KV based on local path.
Author: Andy Redhead
Latest version: 1.1.0

# cw-site-assets

## Introduction

Access arbitrary site assets from a Cloudflare Workers Site. Helps you 
dynamically control (using Workers hosted code) which "page" (from the pages 
published in your site) to return for a given user request, for example by 
returning the contents of a "not authorised" page if the user issuing the 
request has not logged in.

This code was found to be useful as the default behaviour of Workers Site is 
heavily oriented towards serving the originally requested page (and doesn't 
make it easy to fetch a different page instead).

The primary method is:

    async function fetchSiteAssetFromKv(event, assetPath)

This method fetches a site asset from site KV based on its path.

The "event" object is a wrapper for the information required to process 
requests. This is an API change in response to having to adopt ES format worker
structure to get the code working in the "new" workers platform.

An important change is that __STATIC_CONTENT_MANIFEST is no longer an 
automatically provided KV binding. Instead the __STATIC_CONTENT_MANIFEST must 
be "imported":

```
import manifestJSON from '__STATIC_CONTENT_MANIFEST';
const assetManifest = JSON.parse(manifestJSON);
```

The assetManifest object can then be included in an "event" object by doing 
something like:

```
export default {
  async fetch(request, env, ctx) {
    const event = { request, env, ctx, assetManifest }
    try {
      return await handleEvent(event);
    } catch (e) {
      if (DEBUG) {
        return new Response(e.message || e.toString(), { status: 500 });
      }
      return new Response('Internal Error', { status: 500 });
    }
  },
};
```


The path is absolute path within the site with no leading '/', no protocol 
and no hostname, so it's of the form:

    app-dir/page-a.html


Returns a "Response" object with the body set as an 'arrayBuffer' created 
from the result of awaiting a 'get' of the asset from the _STATIC_CONTENT KV 
namespace (as per getAssetFromKV).

Throws an exception if assetPath isn't a key in __STATIC_CONTENT_MANIFEST.

Uses 'await' on call to KV, so this method needs to be awaited...

NOTE, Current implementation:
- Does not set any headers (such as Content-Type)
- Assumes site content is in the default namespace
- Does not handle URL encoded paths
- Doesn't try to do any of the caching stuff that getAssetFromKV does
- Relies upon the Workers Site platform setting up global vars
    - __STATIC_CONTENT_MANIFEST
    - __STATIC_CONTENT

There are a couple of useful subsidiary methods:

    async function fetchSiteAssetFromKvAsHtmlPage(assetPath)

        adds a Content-Type header with value text/html

    function addStandardResponseHeaders(response)

        adds the headers that the workers site example adds


## Development

The code lives in [this GitHub repo](https://github.com/my-liminal-space/cw-site-assets).

Testing code that depends upon features of the Cloudflare Workers Site platform 
(such as the voodoo setup of __STATIC_CONTENT_MANIFEST and _STATIC_CONTENT) is 
"interesting". In order to build confidence that the code will work as 
expected, the approach taken is to test by deploying the lib along with a [test 
site](https://cf-site-assets.deaddodgeydigitaldeals.com/index.html) into Cloudflare Workers.
The index.js file handles requests coming into the test site.

If you want to replicate the test environment, you will need to modify 
wrangler.toml to use your own values.


## Distribution

When packaged for deployment (using pkg.sh), a new folder structure is created 
that is sets up a package focussed on distribtion, which means:
 - only cw-site-assets.js is included (renamed as index.js)
 - an alternative package.json is included, pointing to index.js