Define TypeScript types for API surface

Author: harmony7

types/cache-override.d.ts

@@ -99,15 +99,31 @@ declare module "fastly:cache-override" {
      *
      * See the [Fastly PCI-Compliant Caching and Delivery documentation](https://docs.fastly.com/products/pci-compliant-caching-and-delivery)
      * for details.
+     *
+     * @param {void} [init.onBeforeSend]
+     * Set a [callback function](https://developer.mozilla.org/en-US/docs/Glossary/Callback_function) 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.
+     *
+     * @param {void} [init.onAfterSend]
+     * Set a [callback function](https://developer.mozilla.org/en-US/docs/Glossary/Callback_function) to be invoked after
+     * a response has been sent, but before it is stored into the cache.
+     *
+     * 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.
      */
     constructor(
       mode: "none" | "pass" | "override",
       init?: {
         ttl?: number,
         swr?: number,
         surrogateKey?: string,
-        pci?: boolean
-      }
+        pci?: boolean,
+        onBeforeSend(request: Request): void,
+        onAfterSend(candidateResponse: CandidateResponse): void,
+      },
     );
 
     /**
@@ -148,4 +164,109 @@ declare module "fastly:cache-override" {
     */
     public pci?: boolean;
   }
+
+  /**
+   * Represents a response from the backend fetched through the readthrough cache interface before it is potentially
+   * stored into the cache. It contains interfaces to read and manipulate headers and cache policy, and a
+   * `bodyTransform` may be set allowing the body to be modified before it is potentially stored.
+   *
+   * If the backend response had a 304 Not Modified status, the `CandidateResponse`
+   * will have status matching the original response, headers corresponding to the
+   * original response updated with the 304 response headers, and will be marked to
+   * revalidate the cache only (i.e., not alter the stored body).
+   */
+  interface CandidateResponse {
+    /**
+     * Get the HTTP headers of the response. Use this object to manipulate the response's
+     * headers.
+     */
+    readonly headers: Headers;
+
+    /* version: string; // HTTP Version */
+
+    /**
+     * Get or set the HTTP status code of the response.
+     */
+    status: number;
+
+    /**
+     * Get or set the Time to Live (TTL) in the cache for this response.
+     */
+    ttl: number;
+
+    /**
+     * The current age of the cached item, relative to the originating backend.
+     */
+    readonly age: number;
+
+    /**
+     * Get or set the time for which a cached item can safely be used after being considered stale.
+     */
+    swr: number;
+
+    /**
+     * Determines whether the cached response is stale.
+     *
+     * A cached response is stale if it has been in the cache beyond its TTL period.
+     */
+    readonly isStale: boolean;
+
+    /**
+     * Get or set the set of request headers for which the response may vary.
+     */
+    vary: Set<string>;
+
+    /**
+     * Get or set the surrogate keys for the cached response.
+     */
+    surrogateKeys: Set<string>;
+
+    /**
+     * Get or set whether this response should only be stored via PCI/HIPAA-compliant non-volatile caching.
+     *
+     * See the [Fastly PCI-Compliant Caching and Delivery documentation](https://docs.fastly.com/products/pci-compliant-caching-and-delivery)
+     * for details.
+     */
+    pci: boolean;
+
+    /**
+     * Determines whether this response should be cached.
+     */
+    readonly isCacheable: boolean;
+
+    /**
+     * Force this response to be stored in the cache, even if its headers or status would normally prevent that.
+     */
+    setCacheable(): void;
+
+    /**
+     * Set the response to not be stored in the cache.
+     *
+     * @param {boolean} recordUncacheable (optional) If true, 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 `recordUncacheable` disables.
+     */
+    setUncacheable(recordUncacheable?: boolean): void;
+
+    /**
+     * Get or set a [TransformStream](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) 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 `bodyTransform` will
+     * be applied to it. The original backend body is piped to the [`writeable`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/writable)
+     * end of the transform, and transform is responsible for writing the new body, which will be read out from the
+     * [`readable`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/readable) end of the transform.
+     * This setup allows the transform to work with streamed chunks of the backend body, rather
+     * than necessarily reading it entirely into memory.
+     */
+    bodyTransform?: TransformStream<Uint8Array, Uint8Array>;
+  }
 }