Cache
Background
The Cache API allows fine grained control of reading and writing from the Cloudflare edge 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: *(required by the Cache API specification).
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 returns a 504 error when the content is stale.
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.