feat: HTTP Cache API (#1051)

Author: Guy Bedford

.github/workflows/main.yml

@@ -21,7 +21,7 @@ jobs:
     if: github.ref != 'refs/heads/main'
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: actions/setup-node@v3
       with:
         node-version: 'lts/*'
@@ -32,7 +32,7 @@ jobs:
     if: github.ref != 'refs/heads/main'
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: actions/setup-node@v3
       with:
         node-version: 'lts/*'
@@ -68,7 +68,7 @@ jobs:
       SHELLCHECK_VERSION: v0.8.0
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: actions/cache@v3
       id: cache-shellcheck
       with:
@@ -98,7 +98,7 @@ jobs:
     if: github.ref != 'refs/heads/main'
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: "Install wasi-sdk-20 (linux)"
       run: |
         set -x
@@ -133,7 +133,7 @@ jobs:
           node-version: 18
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node-version }}
@@ -161,7 +161,7 @@ jobs:
     needs: [ensure-cargo-installs]
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: true
     - name: Install Rust 1.77.1
@@ -190,7 +190,7 @@ jobs:
       matrix:
         profile: [release, weval]
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: true
     - name: Install Rust 1.77.1
@@ -226,7 +226,7 @@ jobs:
     needs: [build-debug, ensure-cargo-installs]
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: true
     - uses: actions/setup-node@v3
@@ -274,7 +274,7 @@ jobs:
     needs: [build, ensure-cargo-installs]
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: true
     - uses: actions/setup-node@v3
@@ -329,10 +329,14 @@ jobs:
       matrix:
         platform: [viceroy, compute]
         profile: [release, weval]
+        features: [none, http-cache]
+        exclude:
+          - platform: viceroy
+            features: http-cache
     needs: [build, ensure-cargo-installs]
     steps:
     - name: Checkout fastly/js-compute-runtime
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         submodules: false
         ref: ${{ github.head_ref || github.ref_name }}
@@ -375,12 +379,12 @@ jobs:
       run: npm install && cd ./integration-tests/js-compute && npm install
 
     - name: Run Tests
-      run: SUFFIX_STRING=${{matrix.profile}} node integration-tests/js-compute/test.js ${{ matrix.platform == 'viceroy' && '--local' || '' }} ${{ matrix.profile == 'weval' && '--aot' || '' }}
+      run: SUFFIX_STRING=${{matrix.profile}} node integration-tests/js-compute/test.js --ci --skip-teardown${{ matrix.platform == 'viceroy' && ' --local' || '' }}${{ matrix.profile == 'weval' && ' --aot' || '' }}${{ matrix.features == 'http-cache' && ' --http-cache' || '' }}
       env:
         FASTLY_API_TOKEN: ${{ secrets.FASTLY_API_TOKEN }}
 
     - name: Run Module Mode Tests
-      run: SUFFIX_STRING=${{matrix.profile}} node integration-tests/js-compute/test.js --module-mode ${{ matrix.platform == 'viceroy' && '--local' || '' }} ${{ matrix.profile == 'weval' && '--aot' || '' }}
+      run: SUFFIX_STRING=${{matrix.profile}} node integration-tests/js-compute/test.js --ci --skip-setup --module-mode${{ matrix.platform == 'viceroy' && ' --local' || '' }}${{ matrix.profile == 'weval' && ' --aot' || '' }}${{ matrix.features == 'http-cache' && ' --http-cache' || '' }}
       env:
         FASTLY_API_TOKEN: ${{ secrets.FASTLY_API_TOKEN }}  
 
@@ -393,10 +397,14 @@ jobs:
       fail-fast: false
       matrix:
         platform: [viceroy, compute]
+        features: [none, http-cache]
+        exclude:
+          - platform: viceroy
+            features: http-cache
     needs: [build-debug, ensure-cargo-installs]
     steps:
     - name: Checkout fastly/js-compute-runtime
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         submodules: false
         ref: ${{ github.head_ref || github.ref_name }}
@@ -438,11 +446,11 @@ jobs:
       run: npm install && cd ./integration-tests/js-compute && npm install
 
     - name: Run Tests
-      run: SUFFIX_STRING=debug node integration-tests/js-compute/test.js --debug-build ${{ matrix.platform == 'viceroy' && '--local' || '' }}
+      run: SUFFIX_STRING=debug node integration-tests/js-compute/test.js --ci --skip-teardown --debug-build${{ matrix.platform == 'viceroy' && ' --local' || '' }}${{ matrix.features == 'http-cache' && ' --http-cache' || '' }}
       env:
         FASTLY_API_TOKEN: ${{ secrets.FASTLY_API_TOKEN }}
 
     - name: Run Module Mode Tests
-      run: SUFFIX_STRING=debug node integration-tests/js-compute/test.js --module-mode --debug-build ${{ matrix.platform == 'viceroy' && '--local' || '' }}
+      run: SUFFIX_STRING=debug node integration-tests/js-compute/test.js --ci --skip-setup --module-mode --debug-build${{ matrix.platform == 'viceroy' && ' --local' || '' }}${{ matrix.features == 'http-cache' && ' --http-cache' || '' }}
       env:
         FASTLY_API_TOKEN: ${{ secrets.FASTLY_API_TOKEN }}  

DEVELOPMENT.md

@@ -51,6 +51,7 @@ To build from source, you need to have the following tools installed to successf
   ```
 
 Build the runtime using npm:
+
 ```sh
 npm run build
 ```
@@ -79,7 +80,7 @@ npm run build
 - Python
   ```sh
   brew install python@3
-  ``` 
+  ```
 - Rust
   ```sh
   curl -so rust.sh https://sh.rustup.rs && sh rust.sh -y
@@ -104,49 +105,95 @@ npm run build
   ```
 
 Build the runtime using npm:
+
 ```sh
 npm run build
 ```
 
 ## Testing a Local build in a Compute application
-:warning:	**You should not use this for production workloads!!!!!!!!**
+
+:warning: **You should not use this for production workloads!!!!!!!!**
 
 You can test a local build of the JS Compute runtime by installing it in your JavaScript Compute application and running that locally or by uploading it to your Fastly service.
 
 1. First, follow the directions in [Building the JS Compute Runtime](#building-the-js-compute-runtime) for your platform to obtain a local build. The build outputs are the following files:
+
    - `fastly.wasm`
    - `fastly.debug.wasm`
    - `fastly-weval.wasm`
    - `fastly-ics.wevalcache`
 
 2. Create a local tarball using npm.
+
    ```shell
    npm pack
    ```
 
    The resulting tarball will have a filename such as `fastly-js-compute-<version>.tgz`.
 
 3. In your Compute application, install the tarball using `npm`:
+
    ```shell
    npm install /path/to/fastly-js-compute-<version>.tgz
    ```
 
 4. Build and test or deploy your application as usual, using `fastly compute serve` or `fastly compute publish`, or an appropriate npm script.
 
 ## Testing a Dev Release in a Compute application
-:warning:	**You should not use this for production workloads!!!!!!!!**
+
+:warning: **You should not use this for production workloads!!!!!!!!**
 
 Dev builds are released before production releases to allow for further testing. These are not released upstream to NPM, however you can acquire them from the [Releases](https://github.com/fastly/js-compute-runtime/releases/) section. Download the runtime for your platform, extract the executable and place it in the /node_modules/@fastly/js-compute/bin/PLATFORM folder of your Fastly Compute project. Then you can use the normal [Fastly CLI](https://github.com/fastly/cli) to build your service.
 
 Please submit an [issue](https://github.com/fastly/js-compute-runtime/issues) if you find any problems during testing.
 
-## Automated Testing
+## Tests
+
+All tests are automatically run on pull requests via CI.
+
+### Unit Testing
+
+Unit tests are run via `npm run test`, currently including:
+
+- CLI tests (`npm run test:cli`)
+- Typing tests (`npm run test:types`)
+
+### Integration Tests
+
+Complete test applications are tested from the `./integration-tests/js-compute/fixtures/app/src` and `./integration-tests/js-compute/fixtures/module-mode/src` directories.
+
+Tests themselves are listed in the `./integration-tests/js-compute/fixtures/app/tests.json` and `./integration-tests/js-compute/fixtures/module-mode/tests.json` files.
+
+Integration tests can be run via `npm run test:integration`, which defaults to the release build.
+
+In addition the following flags can be added after the command (passed via `npm run test:debug -- ...` after the `--`):
+
+- `--local`: Test locally using Viceroy, instead of publishing to a staging Compute service.
+- `--bail`: Immediately stop testing on the first failure, and report the failure.
+- `--verbose`: Adds verbose logging to `fastly compute publish` and Viceroy (which provides hostcall logging as well).
+- `--debug-build`: Use the debug build
+- `--debug-log`: Enable debug logging for the tests (engine-level DEBUG_LOG)
+- `--module-mode`: Run the module mode test suite (`fixtures/module-mode` instead of `fixtures/app`).
+- `--http-cache`: Run the HTTP cache test suite
+- `[...args]`: Additional arguments allow for filtering tests
+
+A typical development test command is therefore something like:
+
+```
+npm run build:debug && npm run test:integration -- --debug-build --debug-log --local --bail /crypto
+```
+
+Which would run a debug build, enable debugging logging, and then that build against all the crypto tests locally on Viceroy, throwing an error as soon as one is found.
+
+Some tests can only be run on Compute and not Viceroy and will be automatically skipped. A green tick is always shown for a test that ran successfully - if it is missing that means it did not run.
+
+### Web Platform Tests
+
+The Web Platform tests are included as a submodule, and can be run via `npm run test:wpt` or `npm run test:wpt:debug`.
+
+The WPT test runner supports the following options (passed via `npm run test:wpt -- ...` after the `--`):
 
-The JS Compute Runtime has automated tests which run on all pull-requests. The test applications are located within <./integration-tests/js-compute>.
+- `--update-expectations`: Update the WPT test expectations JSON files based on the current PASS/FAIL test statuses, instead of throwing an error when the current PASS/FAIL lists are not matched.
+- `[...args]`: Filter to apply to WPT tests to run
 
-To run an end-to-end test which builds and deploys an application to fastly:
-- Build the runtime and cli: `npm run build` in the root of the project
-- Change to the test directory for the runtime: `cd integration-tests/js-compute/`
-- Install the test dependencies: `npm install`
-- Get a list of all the applications to test: `node test.js`
-- Test a single application via: `node test.js <name>` or test all via `node test.js --all`
+Run `./tests/wpt-harness/run-wpt.mjs --help` for further options information.

documentation/docs/cache-override/CacheOverride/CacheOverride.mdx

@@ -18,6 +18,7 @@ but `CacheOverride` can be set on a [`Request`](../../globals/Request/Request.md
 ```js
 new CacheOverride(mode)
 new CacheOverride(mode, init)
+new CacheOverride(init)
 ```
 
 > **Note:** `CacheOverride()` can only be constructed with `new`. Attempting to call it without `new` throws a [`TypeError`](../../globals/TypeError/TypeError.mdx).
@@ -30,6 +31,7 @@ new CacheOverride(mode, init)
     - `"none"`: Do not override the behavior specified in the origin response’s cache control headers.
     - `"pass"`: Do not cache the response to this request, regardless of the origin response’s headers.
     - `"override"`: Override particular cache control settings using the `CacheOverride` object's settings.
+       This options is also the default when providing an init object directly as the first argument.
 
 - `init`
 
@@ -48,6 +50,27 @@ new CacheOverride(mode, init)
 
     - `ttl` _: number_ _**optional**_
       - Override the caching behavior of this request to use the given Time to Live (TTL), in seconds.
+    
+    - `beforeSend` _:Function_ _**optional**_
+      - `(request: Request) => void | PromiseLike<void>`
+      - Callback to be invoked if a request is going all the way to a backend, allowing the request to be modified beforehand.
+      - See [Modifying a request as it is forwarded to a backend](https://www.fastly.com/documentation/guides/concepts/edge-state/cache/#modifying-a-request-as-it-is-forwarded-to-a-backend) in the Fastly cache interfaces documentation for details.
+
+    - `afterSend` _: Function_ _**optional**_
+      - `(response: Response) => void | CacheOptions | PromiseLike<void | CacheOptions>`
+      - Callback to be invoked after a response has been sent, but before it is stored into the cache.
+      - Where `CacheOptions` contains:
+        - `cache` _: boolean | 'uncacheable'_ _**optional**_
+          - Whether to cache this response. By default, leaving this field empty, responses will be cached based on their cache header information.
+          - Setting this to true or false will override this default cache behaviour, setting in the cache or not setting in the cache, even if the default behaviour would have been otherwise.
+          - Setting to 'uncacheable' the response will not only not be cached, but the cache will record that the originating request led to an uncacheable response, so that future cache lookups will result in immediately going to the backend, rather than attempting to coordinate concurrent requests to reduce backend traffic.
+          - See the [Fastly request collapsing guide](https://www.fastly.com/documentation/guides/concepts/edge-state/cache/request-collapsing/) for more details on the mechanism that `uncacheable` disables.
+        - `bodyTransformFn` _: Function_ _**optional**_
+          - `(body: Uint8Array) => Uint8Array | PromiseLike<Uint8Array>`
+          - Provide a function to be used for transforming the response body prior to caching.
+          - Body transformations are performed by specifying a transform, rather than by directly working with the body during the onAfterSend callback function, because not every response contains a fresh body: 304 Not Modified responses, which are used to revalidate a stale cached response, are valuable precisely because they do not retransmit the body.
+          - For any other response status, the backend response will contain a relevant body, and the `bodyTransformFn` will be applied to it. The original backend body is passed in to the transform function, and the function is expected to return the new body.
+      - See [Controlling cache behavior based on backend response](https://www.fastly.com/documentation/guides/concepts/edge-state/cache/#controlling-cache-behavior-based-on-backend-response) in the Fastly cache interfaces documentation for details.
 
 ### Return value
 

documentation/docs/globals/Request/Request.mdx

@@ -39,7 +39,7 @@ new Request(input, options)
     - `body`
       - : Any body that you want to add to your request: this can be an `ArrayBuffer`, a `TypedArray`, a `DataView`, a `URLSearchParams`, string object or literal, or a `ReadableStream` object.
     - `backend` _**Fastly-specific**_
-    - `cacheOverride` _**Fastly-specific**_
+    - `cacheOverride` _**Fastly-specific**_, see [`CacheOverride`](../../cache-override/CacheOverride/CacheOverride.mdx).
     - `cacheKey` _**Fastly-specific**_
     - `manualFramingHeaders`_: boolean_ _**optional**_ _**Fastly-specific**_
       - : The default value is `false`, which means that the framing headers are automatically created based on the message body.