Cache
Background
The Cache API allows fine grained control of reading and writing from the Cloudflare global network cache.
The Cache API is available globally but the contents of the cache do not replicate outside of the originating data center. A GET /users response can be cached in the originating data center, but will not exist in another data center unless it has been explicitly created.
However, any Cache API operations in the Cloudflare Workers dashboard editor, Playground previews, and any *.workers.dev deployments will have no impact. For Workers fronted by Cloudflare Access, the Cache API is not currently available. Only Workers deployed to custom domains have access to functional cache operations.
Accessing Cache
The caches.default API is strongly influenced by the web browsers’ Cache API, but there are some important differences. For instance, Cloudflare Workers runtime exposes a single global cache object.
let cache = caches.default;
await cache.match(request);
You may create and manage additional Cache instances via the caches.open method.
let myCache = await caches.open('custom:cache');
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. Refer to Edge TTL for a list of HTTP response codes and their TTL when
Cache-Controldirectives are not present.
- Controls caching directives. This is consistent with Cloudflare Cache-Control Directives. Refer to Edge TTL for a list of HTTP response codes and their TTL when
Cache-Tag- Allows resource purging by tag(s) later (Enterprise only).
ETag- Allows
cache.match()to evaluate conditional requests withIf-None-Match.
- Allows
Expiresstring- A string that specifies when the resource becomes invalid.
Last-Modified- Allows
cache.match()to evaluate conditional requests withIf-Modified-Since.
- Allows
This differs from the web browser Cache API as they do not honor any headers on the request or response.
Methods
Put
cache.put(request, response);
put(request, response):Promise- Attempts to add a response to the cache, using the given request as the key. Returns a promise that resolves to
undefinedregardless of whether the cache successfully stored the response.
- Attempts to add a response to the cache, using the given request as the key. Returns a promise that resolves to
Parameters
Invalid parameters
cache.put will throw an error if:
- The
requestpassed is a method other thanGET. - The
responsepassed has astatusof206 Partial Content. - The
responsepassed contains the headerVary: *. The value of theVaryheader is an asterisk (*). Refer to the Cache API specification for more information.
Errors
cache.put returns a 413 error if Cache-Control instructs not to cache or if the response is too large.
Match
cache.match(request, options);
match(request, options):Promise<Response | undefined>- Returns a promise wrapping the response object keyed to that request.
Parameters
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
206response if a matching response with a Content-Length header is found. Your Cloudflare cache always respects range requests, even if anAccept-Rangesheader is on the response.
- Results in a
If-Modified-Since- Results in a
304response if a matching response is found with aLast-Modifiedheader with a value after the time specified inIf-Modified-Since.
- Results in a
If-None-Match- Results in a
304response if a matching response is found with anETagheader with a value that matches a value inIf-None-Match.
- Results in a
cache.match()- Never sends a subrequest to the origin. If no matching response is found in cache, the promise that
cache.match()returns is fulfilled withundefined.
- Never sends a subrequest to the origin. If no matching response is found in cache, the promise that
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.
If you use Cloudflare Logs, you may see these 504 responses with the RequestSource of edgeWorkerCacheAPI. Again, these are expected if the cached asset was missing or expired. Note that edgeWorkerCacheAPI requests are already filtered out in other views, such as Cache Analytics. To filter out these requests or to filter requests by end users of your website only, refer to Filter end users.
Delete
cache.delete(request, options);
delete(request, options):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 deletedfalse: The response was not in the cache at the time of deletion.