From 2cfc3a443fa1037426eb8f36d0b230e16abade80 Mon Sep 17 00:00:00 2001 From: Aditya Tewari Date: Fri, 1 Nov 2024 11:48:47 -0500 Subject: [PATCH] Added docs for cache: no-store --- .../compatibility-dates/cache-no-store.md | 39 +++++++++++++++++++ .../workers/examples/cache-using-fetch.mdx | 10 +++++ .../docs/workers/runtime-apis/fetch.mdx | 8 +++- .../docs/workers/runtime-apis/request.mdx | 7 +++- 4 files changed, 61 insertions(+), 3 deletions(-) create mode 100644 src/content/compatibility-dates/cache-no-store.md diff --git a/src/content/compatibility-dates/cache-no-store.md b/src/content/compatibility-dates/cache-no-store.md new file mode 100644 index 000000000000000..c42db8faf81c18d --- /dev/null +++ b/src/content/compatibility-dates/cache-no-store.md @@ -0,0 +1,39 @@ +--- +_build: + publishResources: false + render: never + list: never + +name: "Enable `cache: no-store` HTTP standard API" +sort_date: "2024-11-11" +enabled_date: "2024-11-11" +enable_flag: "cache_option_enabled" +disable_flag: "cache_option_disabled" +--- + +When you enable the `cache_option_enabled` compatibility flag, you can specify a value for the `cache` property of the Request interface. +When this compatibility flag is not enabled, or `cache_option_disabled` is set, the Workers runtime will throw an `Error` saying `The 'cache' field on +'RequestInitializerDict' is not implemented.` + +When this flag is enabled you can instruct Cloudflare not to cache the response from a subrequest you make from your Worker using the [`fetch()` API](/workers/runtime-apis/fetch/): + +The only cache option enabled with `cache_option_enabled` is `'no-store'`. +Specifying any other value will cause the Workers runtime to throw a `TypeError` with the message `Unsupported cache mode: `. + +When `no-store` is specified: +* All requests have the headers `Pragma: no-cache` and `Cache-Control: no-cache` are set on them. + +* Subrequests to origins not hosted by Cloudflare bypasses Cloudflare's cache. + +Examples using `cache: 'no-store'`: + +```js +const response = await fetch("https://example.com", { cache: 'no-store'}); +``` + +The cache value can also be set on a `Request` object. + +```js +const request = new Request("https://example.com", { cache: 'no-store'}); +const response = await fetch(request); +``` \ No newline at end of file diff --git a/src/content/docs/workers/examples/cache-using-fetch.mdx b/src/content/docs/workers/examples/cache-using-fetch.mdx index 1227b0394f79644..36c402db97ce166 100644 --- a/src/content/docs/workers/examples/cache-using-fetch.mdx +++ b/src/content/docs/workers/examples/cache-using-fetch.mdx @@ -466,3 +466,13 @@ async function handleRequest(request) { ``` + +## Using the HTTP Cache API + +The `cache` mode can be set in `fetch` options. +Currently Workers only support the `no-store` mode for controlling the cache. +When `no-store` is supplied the cache is bypassed both on the way to the origin and on the way back. + +```js +fetch(request, { cache: 'no-store'}); +``` \ No newline at end of file diff --git a/src/content/docs/workers/runtime-apis/fetch.mdx b/src/content/docs/workers/runtime-apis/fetch.mdx index 019f4980e5beb59..2751542bab13c39 100644 --- a/src/content/docs/workers/runtime-apis/fetch.mdx +++ b/src/content/docs/workers/runtime-apis/fetch.mdx @@ -75,6 +75,12 @@ async function eventHandler(event) { * [`resource`](https://developer.mozilla.org/en-US/docs/Web/API/fetch#resource) Request | string | URL * `options` options + * `cache` `undefined | 'no-store'` optional + * Standard HTTP `cache` header. Only `cache: 'no-store'` is supported. + Any other `cache` header will result in a `TypeError` with the message `Unsupported cache mode: `. + * For cross-zone requests this simply forwards the `Pragma: no-cache` and `Cache-Control: no-cache` headers to the origin. + This is because the cache is on the origin side for cross-zone requests. + * For requests to origins not hosted by Cloudflare, `no-store` bypasses the use of Cloudflare's caches. * An object that defines the content and behavior of the request. @@ -121,4 +127,4 @@ export default { * [Example: Fetch HTML](/workers/examples/fetch-html/) * [Example: Fetch JSON](/workers/examples/fetch-json/) * [Example: cache using Fetch](/workers/examples/cache-using-fetch/) -* Write your Worker code in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience. +* Write your Worker code in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience. \ No newline at end of file diff --git a/src/content/docs/workers/runtime-apis/request.mdx b/src/content/docs/workers/runtime-apis/request.mdx index fdd95875cf0a490..7edeabf214797c3 100644 --- a/src/content/docs/workers/runtime-apis/request.mdx +++ b/src/content/docs/workers/runtime-apis/request.mdx @@ -62,7 +62,10 @@ let request = new Request(input, options) An object containing properties that you want to apply to the request. +* `cache` `undefined | 'no-store'` optional + * Standard HTTP `cache` header. Only `cache: 'no-store'` is supported. + Any other cache header will result in a `TypeError` with the message `Unsupported cache mode: `. * `cf` RequestInitCfProperties optional @@ -180,7 +183,7 @@ All properties of an incoming `Request` object (the request you receive from the :::caution - If the response is a redirect and the redirect mode is set to `follow` (see below), then all headers will be forwarded to the redirect destination, even if the destination is a different hostname or domain. This includes sensitive headers like `Cookie`, `Authorization`, or any application-specific headers. If this is not the behavior you want, you should set redirect mode to `manual` and implement your own redirect policy. Note that redirect mode defaults to `manual` for requests that originated from the Worker's client, so this warning only applies to `fetch()`es made by a Worker that are not proxying the original request. + If the response is a redirect and the redirect mode is set to `follow` (see below), then all headers will be forwarded to the redirect destination, even if the destination is a different hostname or domain. This includes sensitive headers like `Cookie`, `Authorization`, or any application-specific headers. If this is not the behavior you want, you should set redirect mode to `manual` and implement your own redirect policy. Note that redirect mode defaults to `manual` for requests that originated from the Worker's client, so this warning only applies to `fetch()`es made by a Worker that are not proxying the original request. ::: * `method` string read-only @@ -410,4 +413,4 @@ Using any other type of `ReadableStream` as the body of a request will result in * [Examples: Modify request property](/workers/examples/modify-request-property/) * [Examples: Accessing the `cf` object](/workers/examples/accessing-the-cloudflare-object/) * [Reference: `Response`](/workers/runtime-apis/response/) -* Write your Worker code in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience. +* Write your Worker code in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience. \ No newline at end of file