@fastly/js-compute
Version:
JavaScript SDK and CLI for building JavaScript applications on [Fastly Compute](https://www.fastly.com/products/edge-compute/serverless).
231 lines (225 loc) • 9.97 kB
TypeScript
declare module 'fastly:cache-override' {
/**
* Cache customization options for responses, provided through the afterSend hook.
*
* For customizing the response status, headers, and other cache options, these
* can be modified directly on the response.
*
* @version 3.30.0
*/
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 '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 `uncacheable` disables.
*/
cache?: boolean | 'uncacheable';
/**
* Provide a function 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 `bodyTransformFn` will
* be applied to it. The original backend body is passed in to the transform function, and the function is expected
* to return the new body.
*/
bodyTransformFn?: (
body: Uint8Array<ArrayBuffer>,
) => Uint8Array<ArrayBuffer> | PromiseLike<Uint8Array<ArrayBuffer>>;
}
/**
* The cache override mode for a request
*
* If set to:
* - "none": Do not override the behavior specified in the origin response’s cache control headers.
* - "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.
*/
type CacheOverrideMode = 'none' | 'pass' | 'override';
interface ICacheOverride {
/**
* Override the caching behavior of this request to use the given Time to Live (TTL), in seconds.
*/
ttl?: number;
/**
* Override the caching behavior of this request to use the given `stale-while-revalidate` time,
* in seconds.
*/
swr?: number;
/**
* 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.
*/
surrogateKey?: string;
/**
* Override the caching behavior of this request 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;
/**
* 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 request
* @returns {void | PromiseLike<void>}
*
* @version 3.30.0
*/
beforeSend?: (request: Request) => void | PromiseLike<void>;
/**
* 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.
*
* @param response
* @returns {void | CacheOptions | PromiseLike<void | CacheOptions>}
*
* @version 3.30.0
*/
afterSend?: (
response: Response,
) => void | CacheOptions | PromiseLike<void | CacheOptions>;
}
/**
* Configures the caching behavior of a {@linkcode "globals".Response | Response}.
*
* Normally, the HTTP Headers on a {@linkcode "globals".Response | Response} would control how the {@linkcode "globals".Response | Response} is cached,
* but `CacheOverride` can be set on a {@linkcode "globals".Request | Request}, to define custom caching behavior.
*
* @example
* In this example we override the cache for all the requests prefixed /static/ to have a long TTL (Time To Live),
* and the home page to have a short TTL and a long SWR (Stale While Revalidate).
*
* ```js
* import { CacheOverride } from "fastly:cache-override";
*
* async function app(event) {
* const path = (new URL(event.request.url)).pathname;
* let cacheOverride;
* if (path == '/') {
* cacheOverride = new CacheOverride('override', {ttl: 10, swr: 86_400});
* } else if (path.startsWith('/static/')) {
* cacheOverride = new CacheOverride('override', {ttl: 86_400});
* } else {
* cacheOverride = new CacheOverride('none')
* }
* return fetch(event.request.url, {
* cacheOverride,
* backend: 'my-backend'
* });
* }
* addEventListener("fetch", event => event.respondWith(app(event)));
* ```
* @fiddle meta
* {
* "title": "CacheOverride Example",
* "request": "/status=200"
* }
*/
class CacheOverride {
/**
* @param mode Sets the cache override mode for a request
*
* If set to:
* - "none": Do not override the behavior specified in the origin response’s cache control headers.
* - "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 Sets the cache override init options
*/
constructor(mode: CacheOverrideMode, init?: ICacheOverride);
/**
* When an init object is provided as the first argument, the mode defaults to `"override"`.
*
* @param overrideInit Sets the cache override init options
* @version 3.30.0
*/
constructor(overrideInit?: ICacheOverride);
/**
* Sets the cache override mode for a request
*
* If set to:
* - "none": Do not override the behavior specified in the origin response’s cache control headers.
* - "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.
*/
public mode: CacheOverrideMode;
/**
* Override the caching behavior of this request to use the given Time to Live (TTL), in seconds.
*/
public ttl?: number;
/**
* Override the caching behavior of this request to use the given `stale-while-revalidate` time,
* in seconds
*/
public swr?: number;
/**
* 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 surrogateKey?: string;
/**
* Override the caching behavior of this request 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.
*/
public pci?: boolean;
/**
* Callback 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.
*
* @version 3.30.0
*/
public beforeSend?: (request: Request) => void | PromiseLike<void>;
/**
* Callback 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.
*
* @version 3.30.0
*/
public afterSend?: (
response: Response,
) => void | CacheOptions | PromiseLike<void | CacheOptions>;
}
}