wip

types/cache-override.d.ts

@@ -1,4 +1,48 @@
 declare module 'fastly:cache-override' {
+  /**
+   * Cache customization options for responses, provided through the beforeCache hook
+   * 
+   * For customizing the response status, headers, and other cache options, these
+   * can be modified directly on the response.
+   */
+  interface CacheOptions {
+    /**
+     * 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 'record-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 `recordUncacheable` disables.
+     */
+    cache?: boolean | 'uncacheable',
+    /**
+     * 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>;
+  }
+
   /**
    * Configures the caching behavior of a {@linkcode "globals".Response}.
    *
@@ -98,6 +142,20 @@ 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.beforeSend]
+     * 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.beforeCache]
+     * 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',
@@ -106,6 +164,8 @@ declare module 'fastly:cache-override' {
         swr?: number;
         surrogateKey?: string;
         pci?: boolean;
+        beforeSend?: (request: Request) => void | PromiseLike<void>;
+        beforeCache?: (response: Response) => void | CacheOptions | PromiseLike<void | CacheOptions>;
       },
     );
 

types/globals.d.ts

@@ -1274,7 +1274,7 @@ interface Request extends Body {
   /**
    * The request backend, null for the downstream request itself
    */
-  backend: import('fastly:backend').Backend | undefined;
+  readonly backend: import('fastly:backend').Backend | undefined;
   setCacheOverride(
     override: import('fastly:cache-override').CacheOverride,
   ): void;
@@ -1311,10 +1311,18 @@ declare interface ResponseInit {
  * @group Fetch API
  */
 interface Response extends Body {
+  /**
+   * The response headers.
+   * 
+   * May be modified event for upstream responses prior to storage in the cache.
+   */
   readonly headers: Headers;
   readonly ok: boolean;
   // readonly redirected: boolean;
-  readonly status: number;
+  /**
+   * The response status. May be modified prior to storage in the cache.
+   */
+  status: number;
   readonly statusText: string;
   // readonly type: ResponseType;
   readonly url: string;
@@ -1337,7 +1345,66 @@ interface Response extends Body {
   /**
    * The response backend, if an upstream response
    */
-  backend: import('fastly:backend').Backend | undefined;
+  readonly backend: import('fastly:backend').Backend | undefined;
+  /**
+   * Fastly-specific property - Returns whether the `Response` resulted from a cache hit.
+   * For request collapsing, typically one response will show as a miss, and the others
+   * (that awaited that response) will show as hits.
+   */
+  readonly cached: boolean;
+  /**
+   * Fastly-specific property - If this was a backend response, whether it should be cached
+   */
+  readonly isCacheable: boolean;
+  /**
+   * Fastly-specific property - Returns whether the cached `Response` is considered stale.
+   * 
+   * Undefined if the response is not cached.
+   */
+  readonly isStale: boolean | undefined;
+
+  /**
+   * Fastly-specific property - Get the Time to Live (TTL) in the cache for this response, if it is cached.
+   *
+   * The TTL determines the duration of "freshness" for the cached response
+   * after it is inserted into the cache.
+   *
+   * Undefined if the response is not cached. May be modified prior to injection into the cache.
+   */
+  ttl: number | undefined;
+  /**
+   * Fastly-specific property - The current age of the response, if it is cached.
+   *
+   * Undefined if the response is not cached. May be modified prior to injection into the cache.
+   */
+  readonly age: number | undefined;
+  /**
+   * Fastly-specific property - The time for which the response can safely be used despite being considered stale, if it is cached.
+   *
+   * Undefined if the response is not cached. May be modified prior to injection into the cache.
+   */
+  swr: number | undefined;
+  /**
+   * Fastly-specific property - The set of request headers for which the response may vary.
+   *
+   * Undefined if the response is not cached. May be modified prior to injection into the cache.
+   */
+  vary: Set<string> | undefined;
+  /**
+   * Fastly-specific property - The surrogate keys for the cached response.
+   *
+   * Undefined if the response is not cached. May be modified prior to injection into the cache.
+   */
+  surrogateKeys: Set<string> | undefined;
+  /**
+   * Fastly-specific property - 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.
+   * 
+   * Undefined if the response is not cached. May be modified prior to injection into the cache.
+   */
+  pci: boolean;
 }
 
 /**