Skip to content

[Workers] Fix formatting #21946

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 24, 2025
Merged

[Workers] Fix formatting #21946

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 8 additions & 39 deletions src/content/docs/workers/runtime-apis/cache.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,8 @@ The Cache API is available globally but the contents of the cache do not replica

:::caution[Tiered caching]


The `cache.put` method is not compatible with tiered caching. Refer to [Cache API](/workers/reference/how-the-cache-works/#cache-api) for more information. To perform tiered caching, use the [fetch API](/workers/reference/how-the-cache-works/#interact-with-the-cloudflare-cache).


:::

Workers deployed to custom domains have access to functional `cache` operations. So do [Pages functions](/pages/functions/), whether attached to custom domains or `*.pages.dev` domains.
Expand All @@ -26,10 +24,8 @@ However, any Cache API operations in the Cloudflare Workers dashboard editor and

:::note


This individualized zone cache object differs from Cloudflare’s Global CDN. For details, refer to [How the cache works](/workers/reference/how-the-cache-works/).


:::

***
Expand All @@ -49,7 +45,9 @@ You may create and manage additional Cache instances via the [`caches.open`](htt
let myCache = await caches.open('custom:cache');
await myCache.match(request);
```

:::note

When using the cache API, avoid overriding the hostname in cache requests, as this can lead to unnecessary DNS lookups and cache inefficiencies. Always use the hostname that matches the domain associated with your Worker.

```js
Expand All @@ -59,15 +57,15 @@ request.url = "https://your-Worker-hostname.com/";
let myCache = await caches.open('custom:cache');
let response = await myCache.match(request);
```

:::

***

## Headers

Our implementation of the Cache API respects the following HTTP headers on the response passed to `put()`:



* `Cache-Control`
* Controls caching directives. This is consistent with [Cloudflare Cache-Control Directives](/cache/concepts/cache-control#cache-control-directives). Refer to [Edge TTL](/cache/how-to/configure-cache-status-code#edge-ttl) for a list of HTTP response codes and their TTL when `Cache-Control` directives are not present.
* `Cache-Tag`
Expand All @@ -79,18 +77,14 @@ Our implementation of the Cache API respects the following HTTP headers on the r
* `Last-Modified`
* Allows `cache.match()` to evaluate conditional requests with `If-Modified-Since`.



This differs from the web browser Cache API as they do not honor any headers on the request or response.

:::note


Responses with `Set-Cookie` headers are never cached, because this sometimes indicates that the response contains unique data. To store a response with a `Set-Cookie` header, either delete that header or set `Cache-Control: private=Set-Cookie` on the response before calling `cache.put()`.

Use the `Cache-Control` method to store the response without the `Set-Cookie` header.


:::

***
Expand All @@ -103,21 +97,17 @@ Use the `Cache-Control` method to store the response without the `Set-Cookie` he
cache.put(request, response);
```



* <code>put(request, response)</code> : Promise

* Attempts to add a response to the cache, using the given request as the key. Returns a promise that resolves to `undefined` regardless of whether the cache successfully stored the response.



:::note


The `stale-while-revalidate` and `stale-if-error` directives are not supported when using the `cache.put` or `cache.match` methods.
#### Parameters

:::

#### Parameters

* `request` string | Request

Expand All @@ -126,8 +116,6 @@ The `stale-while-revalidate` and `stale-if-error` directives are not supported w
* `response` Response
* A [`Response`](/workers/runtime-apis/response/) object to store under the given key.



#### Invalid parameters

`cache.put` will throw an error if:
Expand All @@ -146,21 +134,17 @@ The `stale-while-revalidate` and `stale-if-error` directives are not supported w
cache.match(request, options);
```



* <code>match(request, options)</code> : Promise`<Response | undefined>`

* Returns a promise wrapping the response object keyed to that request.



:::note


The `stale-while-revalidate` and `stale-if-error` directives are not supported when using the `cache.put` or `cache.match` methods.
#### Parameters
:::


#### Parameters

* `request` string | Request

Expand All @@ -169,14 +153,10 @@ The `stale-while-revalidate` and `stale-if-error` directives are not supported w
* `options`
* Can contain one possible property: `ignoreMethod` (Boolean). When `true`, the request is considered to be a `GET` request regardless of its actual value.



Unlike the browser Cache API, Cloudflare Workers do not support the `ignoreSearch` or `ignoreVary` options on `match()`. You can accomplish this behavior by removing query strings or HTTP headers at `put()` time.

Our implementation of the Cache API respects the following HTTP headers on the request passed to `match()`:



* `Range`

* Results in a `206` response if a matching response with a Content-Length header is found. Your Cloudflare cache always respects range requests, even if an `Accept-Ranges` header is on the response.
Expand All @@ -193,7 +173,6 @@ Our implementation of the Cache API respects the following HTTP headers on the r
* Never sends a subrequest to the origin. If no matching response is found in cache, the promise that `cache.match()` returns is fulfilled with `undefined`.



#### Errors

`cache.match` generates a `504` error response when the requested content is missing or expired. The Cache API does not expose this `504` directly to the Worker script, instead returning `undefined`. Nevertheless, the underlying `504` is still visible in Cloudflare Logs.
Expand All @@ -206,38 +185,28 @@ If you use Cloudflare Logs, you may see these `504` responses with the `RequestS
cache.delete(request, options);
```



* <code>delete(request, options)</code> : Promise`<boolean>`



Deletes the `Response` object from the cache and returns a `Promise` for a Boolean response:

* `true`: The response was cached but is now deleted
* `false`: The response was not in the cache at the time of deletion.

:::caution[Global purges]


The `cache.delete` method only purges content of the cache in the data center that the Worker was invoked. For global purges, refer to [Purging assets stored with the Cache API](/workers/reference/how-the-cache-works/#purge-assets-stored-with-the-cache-api).


:::

#### Parameters



* `request` string | Request

* The string or [`Request`](/workers/runtime-apis/request/) object used as the lookup key. Strings are interpreted as the URL for a new `Request` object.

* `options` object
* Can contain one possible property: `ignoreMethod` (Boolean). Consider the request method a GET regardless of its actual value.



***

## Related resources
Expand Down