feat: expose purgeSurrogateKey hostcall (#953)

Author: Guy Bedford

.github/workflows/main.yml

@@ -56,6 +56,7 @@ jobs:
         path: "/home/runner/.cargo/bin/${{ matrix.crate }}"
         key: crate-cache-${{ matrix.crate }}-${{ matrix.version }}
     - name: Install ${{ matrix.crate }} ${{ matrix.version }}
+      if: steps.cache-crate.output.cache-hit != 'true'
       run: cargo install ${{ matrix.crate }} ${{ matrix.options }} --version ${{ matrix.version }} --force
 
   shellcheck:

documentation/docs/fastly:runtime/purgeSurrogateKey.mdx

@@ -0,0 +1,33 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# purgeSurrogateKey
+
+The **`purgeSurrogateKey()`** function is used to purge the given surrogate key string from Fastly's cache.
+
+There are two purge modes: soft purge and hard purge, with hard purge as the default which clears all items
+from the cache immediately. When using a soft purge, stale entries are maintained in the cache, reducing
+orgin load, while also enabling stale revalidations.
+
+See the [Fastly Purge Documentation](https://www.fastly.com/documentation/guides/concepts/edge-state/cache/purging/#surrogate-key-purge) for more information on caching and purge operations.
+
+## Syntax
+
+```js
+purgeSurrogateKey(surrogateKey, soft?)
+```
+
+### Parameters
+
+- `surrogateKey` _: string_
+  - The surrogate key string
+- `soft?` _: boolean_
+  - Enables a soft purge, retaining stale entries in the cache. Default is a hard purge.
+
+### Return value
+
+`undefined`.

documentation/docs/fastly:runtime/vCpuTime.mdx

@@ -0,0 +1,24 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# vCpuTime
+
+The **`vCpuTime()`** function provides the vCPU time used by the current request handler in milliseconds.
+
+## Syntax
+
+```js
+vCpuTime()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+`undefined`.

integration-tests/js-compute/compare-downstream-response.js

@@ -20,13 +20,9 @@ export async function compareDownstreamResponse(
   let errors = [];
   // Status
   if (configResponse.status != actualResponse.statusCode) {
-    let bodySummary = '';
-    try {
-      bodySummary = (await actualResponse.body.text()).slice(0, 1000);
-    } catch {}
     errors.push(
       new Error(
-        `[DownstreamResponse: Status mismatch] Expected: ${configResponse.status} - Got: ${actualResponse.statusCode}\n${bodySummary ? `BODY: "${bodySummary}"` : ''}`,
+        `[DownstreamResponse: Status mismatch] Expected: ${configResponse.status} - Got: ${actualResponse.statusCode}\n${actualBodyChunks.length ? `"${Buffer.concat(actualBodyChunks)}"` : ''}`,
       ),
     );
   }

integration-tests/js-compute/fixtures/app/src/runtime.js

@@ -1,12 +1,8 @@
-import {
-  pass,
-  ok,
-  strictEqual
-} from "./assertions-throwing.js";
-import { routes } from "./routes.js";
-import { vCpuTime } from "fastly:runtime";
+import { pass, ok, strictEqual, assertThrows } from './assertions-throwing.js';
+import { routes } from './routes.js';
+import { purgeSurrogateKey, vCpuTime } from 'fastly:runtime';
 
-routes.set("/runtime/get-vcpu-ms", () => {
+routes.set('/runtime/get-vcpu-ms', () => {
   const cpuTime = vCpuTime();
   strictEqual(typeof cpuTime, 'number');
   ok(cpuTime > 0);
@@ -21,3 +17,24 @@ routes.set("/runtime/get-vcpu-ms", () => {
   ok(cpuTime2 - cpuTime < 3000);
   return pass('ok');
 });
+
+routes.set('/runtime/purge-surrogate-key-invalid', () => {
+  assertThrows(
+    () => {
+      purgeSurrogateKey();
+    },
+    TypeError,
+    'purgeSurrogateKey: At least 1 argument required, but only 0 passed',
+  );
+  return pass('ok');
+});
+
+routes.set('/runtime/purge-surrogate-key-hard', () => {
+  purgeSurrogateKey('test');
+  return pass('ok');
+});
+
+routes.set('/runtime/purge-surrogate-key-soft', () => {
+  purgeSurrogateKey('test', true);
+  return pass('ok');
+});