diff --git a/types/cache-override.d.ts b/types/cache-override.d.ts index befa772af9..f0bd8cde53 100644 --- a/types/cache-override.d.ts +++ b/types/cache-override.d.ts @@ -99,6 +99,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.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", @@ -106,8 +120,10 @@ declare module "fastly:cache-override" { 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; + + /** + * Get or set the surrogate keys for the cached response. + */ + surrogateKeys: Set; + + /** + * 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; + } } diff --git a/types/globals.d.ts b/types/globals.d.ts index c78a96d8c1..f0bd228dc8 100644 --- a/types/globals.d.ts +++ b/types/globals.d.ts @@ -1160,6 +1160,45 @@ interface Response extends Body { * Set cacheOverride: new CacheOverride("pass") to ensure a value. */ readonly port: number | 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 wasCached: boolean; + /** + * 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. + */ + readonly ttl?: number; + /** + * Fastly-specific property - The current age of the response, if it is cached. + * + * Undefined if the response is not cached. + */ + readonly age?: number; + /** + * 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. + */ + readonly swr?: number; + /** + * Fastly-specific property - The set of request headers for which the response may vary. + * + * Undefined if the response is not cached. + */ + readonly vary?: Set; + /** + * Fastly-specific property - The surrogate keys for the cached response. + * + * Undefined if the response is not cached. + */ + readonly surrogateKeys?: Set; // clone(): Response; setManualFramingHeaders(manual: boolean): void; }