Cloudflare Docs
Workers
Cloudflare Docs
Workers
Search icon (depiction of a magnifying glass)
GitHub icon
Visit Workers on GitHub
Set theme to dark (⇧+D)

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
  • Cache-Tag
    • Allows resource purging by tag(s) later (Enterprise only).
  • ETag
    • Allows cache.match() to evaluate conditional requests with If-None-Match.
  • Expires string
    • A string that specifies when the resource becomes invalid.
  • Last-Modified
    • Allows cache.match() to evaluate conditional requests with If-Modified-Since.

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.

Parameters

  • request string | Request

    • Either a string or a Request object to serve as the key. If a string is passed, it is interpreted as the URL for a new Request object.

  • response Response

    • A Response object to store under the given key.

Invalid parameters

cache.put will throw an error if:

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>}

    • Returns a promise wrapping the response object keyed to that request.

Parameters

  • request string | Request

    • The string or Request object used as the lookup key. Strings are interpreted as the URL for a new Request object.

  • options

    • Can contain one possible property: ignoreMethod (Boolean). When true, the request is considered to be a GET request regardless of its actual value.

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 an Accept-Ranges header is on the response.

  • If-Modified-Since

    • Results in a 304 response if a matching response is found with a Last-Modified header with a value after the time specified in If-Modified-Since.

  • If-None-Match

    • Results in a 304 response if a matching response is found with an ETag header with a value that matches a value in If-None-Match.

  • 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 with undefined.

Errors

cache.match returns a 504 error when the content is stale.

Delete

cache.delete(request, options);

Deletes the Response object from the cache and returns a Promise for a Boolean response:

  • true: The response was cached but is now deleted
  • false: 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 new Request object.
  • options
    • Can contain one possible property: ignoreMethod (Boolean) Consider the request method a GET regardless of its actual value.