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-Control
directives 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
Expires
string
- 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
undefined
regardless 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
request
passed is a method other thanGET
. - The
response
passed has astatus
of206 Partial Content
. - The
response
passed contains the headerVary: *
. The value of theVary
header 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
206
response if a matching response with a Content-Length header is found. Your Cloudflare cache always respects range requests, even if anAccept-Ranges
header is on the response.
- Results in a
If-Modified-Since
- Results in a
304
response if a matching response is found with aLast-Modified
header with a value after the time specified inIf-Modified-Since
.
- Results in a
If-None-Match
- Results in a
304
response if a matching response is found with anETag
header 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.