Cache
Background
The Cache API allows fine grained control of reading and writing from cache, and deciding exactly when to fetch data from your origin.
For each individual zone, the Cloudflare Workers runtime exposes a single global cache object: caches.default
. Though this cache object persists on all of Cloudflare’s data centers, objects are not replicated to any other data centers.
The Service Workers Cache API is currently unimplemented in the Cloudflare Workers Preview. Cache API operations in the preview will have no impact. You must deploy the Worker on a zone to test cache operations.
Constructor
let cache = caches.default
This 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.
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-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
- Adds to the cache a response keyed to the given request. Returns a promise that resolves to
undefined
once the cache stores the response.
- Adds to the cache a response keyed to the given request. Returns a promise that resolves to
Parameters
Invalid parameters
cache.put
throws an error if:
- the
request
passed is a method other thanGET
- the
response
passed is astatus
of206 Partial Content
- the
response
passed contains the headerVary: *
(required by the Cache API specification)
Match
cache.match(request, options)
match(request, options)
Promise<Response>
- 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 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
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.
Parameters
request
string
|Request
- The string or
Request
object used as the lookup key. Strings are interpreted as the URL for a newRequest
object.
- The string or
options
- Can contain one possible property:
ignoreMethod
(Boolean) Consider the request method a GET regardless of its actual value.
- Can contain one possible property: