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.defaultThis 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
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- Adds to the cache a response keyed to the given request. Returns a promise that resolves to
undefinedonce 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
requestpassed is a method other thanGET - the
responsepassed is astatusof206 Partial Content - the
responsepassed 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
206response if a matching response 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
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
requeststring|Request- The string or
Requestobject used as the lookup key. Strings are interpreted as the URL for a newRequestobject.
- 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: