diff --git a/types/cache-override.d.ts b/types/cache-override.d.ts index f16b516802..4bdcace44f 100644 --- a/types/cache-override.d.ts +++ b/types/cache-override.d.ts @@ -1,4 +1,51 @@ declare module 'fastly:cache-override' { + interface ICacheOverride { + /** + * The cache key for this cache entry + */ + cacheKey?: string | undefined; + /** + * Override the caching behavior of this request/response to use the given Time to Live (TTL), in seconds. + */ + ttl?: number | undefined; + /** + * Override the caching behavior of this request/response to use the given `stale-while-revalidate` time, + * in seconds + */ + swr?: number | undefined; + /** + * Override the caching behavior of this request/response to include the given surrogate key, provided as + * a header value. + * + * See the [Fastly surrogate keys guide](https://docs.fastly.com/en/guides/purging-api-cache-with-surrogate-keys) + * for details. + */ + surrogateKeys?: Set; + /** + * Override the caching behavior of this request/response to include the given surrogate keys, provided as + * a header value. + * + * See the [Fastly surrogate keys guide](https://docs.fastly.com/en/guides/purging-api-cache-with-surrogate-keys) + * for details. + */ + surrogateKey?: string | undefined; + /** + * Override the caching behavior of this request/response to enable or disable PCI/HIPAA-compliant + * non-volatile caching. + * + * By default, this is false, which means the request may not be PCI/HIPAA-compliant. Set it to + * true to enable compliant caching. + * + * See the [Fastly PCI-Compliant Caching and Delivery documentation](https://docs.fastly.com/products/pci-compliant-caching-and-delivery) + * for details. + */ + pci?: boolean; + /** + * Get or set the set of request headers for which the response may vary. + */ + vary?: Set; + } + /** * Configures the caching behavior of a {@linkcode "globals".Response}. * @@ -17,8 +64,6 @@ declare module 'fastly:cache-override' { * "origins": [ * "https://http-me.glitch.me" * ], - * "src": { - * "deps": "{\n \"@fastly/js-compute\": \"^0.7.0\"\n}", * "main": "/// \nimport { CacheOverride } from \"fastly:cache-override\";\n\n// In this example we override the cache for all the requests prefixed /static/ \n// to have a long TTL (Time To Live), and the home page to have a short TTL and \n// a long SWR (Stale While Revalidate).\nasync function app (event) {\n const path = (new URL(event.request.url)).pathname;\n let cacheOverride;\n if (path == '/') {\n cacheOverride = new CacheOverride('override', {ttl: 10, swr: 86_400});\n } else if (path.startsWith('/static/')) {\n cacheOverride = new CacheOverride('override', {ttl: 86_400});\n } else {\n cacheOverride = new CacheOverride('none')\n }\n return fetch(event.request.url, {\n cacheOverride,\n backend: 'origin_0'\n });\n}\naddEventListener(\"fetch\", event => event.respondWith(app(event)));\n" * }, * "requests": [ @@ -64,6 +109,7 @@ declare module 'fastly:cache-override' { * ``` * */ + class CacheOverride { /** * @param mode Sets the cache override mode for a request @@ -73,41 +119,12 @@ declare module 'fastly:cache-override' { * - "pass": Do not cache the response to this request, regardless of the origin response’s headers. * - "override": Override particular cache control settings using a {@linkcode CacheOverride} object. * - * @param [init] - * - * @param {number} [init.ttl] - * Override the caching behavior of this request to use the given Time to Live (TTL), in seconds. - * - * @param {number} [init.swr] - * Override the caching behavior of this request to use the given `stale-while-revalidate` time, - * in seconds - * - * @param {string} [init.surrogateKey] - * Override the caching behavior of this request to include the given surrogate key, provided as - * a header value. - * - * See the [Fastly surrogate keys guide](https://docs.fastly.com/en/guides/purging-api-cache-with-surrogate-keys) - * for details. - * - * @param {boolean} [init.pci] - * Override the caching behavior of this request to enable or disable PCI/HIPAA-compliant - * non-volatile caching. + * @param [init] Init options for the cache override * - * By default, this is false, which means the request may not be PCI/HIPAA-compliant. Set it to - * true to enable compliant caching. - * - * See the [Fastly PCI-Compliant Caching and Delivery documentation](https://docs.fastly.com/products/pci-compliant-caching-and-delivery) - * for details. */ - constructor( - mode: 'none' | 'pass' | 'override', - init?: { - ttl?: number; - swr?: number; - surrogateKey?: string; - pci?: boolean; - }, - ); + constructor(mode: 'none' | 'pass' | 'override', init?: ICacheOverride); + + cacheKey?: string; /** * Sets the cache override mode for a request @@ -121,12 +138,12 @@ declare module 'fastly:cache-override' { /** * Override the caching behavior of this request to use the given Time to Live (TTL), in seconds. */ - public ttl?: number; + public ttl: number | undefined; /** * Override the caching behavior of this request to use the given `stale-while-revalidate` time, * in seconds */ - public swr?: number; + public swr: number | undefined; /** * Override the caching behavior of this request to include the given surrogate key, provided as * a header value. @@ -134,7 +151,15 @@ declare module 'fastly:cache-override' { * See the [Fastly surrogate keys guide](https://docs.fastly.com/en/guides/purging-api-cache-with-surrogate-keys) * for details. */ - public surrogateKey?: string; + public surrogateKey: string | undefined; + /** + * Override the caching behavior of this request to include the given surrogate key, provided as + * a header value. + * + * See the [Fastly surrogate keys guide](https://docs.fastly.com/en/guides/purging-api-cache-with-surrogate-keys) + * for details. + */ + public surrogateKeys: Set | undefined; /** * Override the caching behavior of this request to enable or disable PCI/HIPAA-compliant * non-volatile caching. @@ -145,6 +170,10 @@ 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. */ - public pci?: boolean; + public pci: boolean | undefined; + /** + * Get or set the set of request headers for which the response may vary. + */ + public vary: Set | undefined; } } diff --git a/types/globals.d.ts b/types/globals.d.ts index aed21792ef..9558e6e678 100644 --- a/types/globals.d.ts +++ b/types/globals.d.ts @@ -1225,6 +1225,25 @@ declare interface RequestInit { /** The Fastly configured backend name or instance the request should be sent to. */ backend?: string | import('fastly:backend').Backend; cacheOverride?: import('fastly:cache-override').CacheOverride; + /** + * Provide a callback to modify the request before sending to the backend. + */ + beforeSend?: (req: Request) => Promise; + /** + * Provide a callback to modify the response before storing in the cache. + * + * May return another response entirely. + * + * Alternatively a void return indicates that the request will not be cached. + */ + beforeCache?: (res: Response) => Promise; + /** + * Boolean indicating if the request is cacheable under standard cache rules. + */ + isCacheable: boolean; + /** + * @deprecated use cacheOverride.cacheKey instead + */ cacheKey?: string; fastly?: { decompressGzip?: boolean; @@ -1272,12 +1291,24 @@ interface Request extends Body { clone(): Request; /** - * The request backend, null for the downstream request itself + * The request backend, undefined for the downstream request itself + */ + readonly backend: import('fastly:backend').Backend | undefined; + + /** + * The cache override options for this request. May be modified up until the point that + * the request is stored in the cache. + */ + readonly cacheOverride: import('fastly:cache-override').CacheOverride; + /** + * @deprecated use {@link cacheOverride} directly. */ - backend: import('fastly:backend').Backend | undefined; setCacheOverride( override: import('fastly:cache-override').CacheOverride, ): void; + /** + * @deprecated set {@link cacheOverride.cacheKey} instead. + */ setCacheKey(key: string): void; setManualFramingHeaders(manual: boolean): void; } @@ -1311,10 +1342,18 @@ declare interface ResponseInit { * @group Fetch API */ interface Response extends Body { + /** + * The response headers. + * + * May be modified even 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; @@ -1334,10 +1373,24 @@ interface Response extends Body { readonly port: number | undefined; // clone(): Response; setManualFramingHeaders(manual: boolean): void; + /** + * The cache override options for this response. + * + * May be modified prior to storage in the cache. + */ + readonly cacheOverride: import('fastly:cache-override').CacheOverride; + /** + * Set a custom transform stream for the origin on cache miss. + * Can only be called when the onAfterSend hook is triggered, and before the promise has resolved. + * + * @param transformStream A transform stream to transform the backend response before storing + * in the cache and returning the response to the client. + */ + setCacheTransform(transformStream: TransformStream): void; /** * The response backend, if an upstream response */ - backend: import('fastly:backend').Backend | undefined; + readonly backend: import('fastly:backend').Backend | undefined; } /**