How the Cache works
Since Workers was built atop Cloudflare’s network, since its early days, it was designed to allow developers to interact directly with the Cloudflare cache. The cache can provide ephemeral, colo-local storage, as a convenient way to frequently access static or dynamic content.
By allowing developers to write to the cache, Workers provide a way to customize cache behavior on Cloudflare’s CDN. To learn about the benefits of caching see our Learning Center’s article on What is Caching?.
Since Cloudflare’s Workers can run before, and after the cache, a Worker can also be utilized to modify assets once they are returned from the cache, to sign or personalize responses, while reducing load on an origin, or latency to the end user by serving assets from a nearby location.
Interacting with the Cloudflare Cache
Conceptually, there are two ways to interact with Cloudflare’s Cache using a Worker:
Call to
fetch()
in a Workers script. Requests proxied through Cloudflare are cached even without Workers according to a zone’s default or configured behavior (e.g. static assets like files ending in .jpg are cached by default). Workers can further customize this behavior by:- Setting Cloudflare cache rules (i.e. operating on the
cf
object of a request).
- Setting Cloudflare cache rules (i.e. operating on the
Store responses using the Cache API from a Workers script. This allows caching responses that did not come from an origin and also provides finer control by:
Customizing cache behavior of any asset by setting headers such as
Cache-Control
on the response passed tocache.put()
Caching responses generated by the Worker itself through
cache.put()
Edge vs. browser caching
The browser cache is controlled through the Cache-Control
header sent in the response to the eyeball (the response passed or promised to event.respondWith()
). Workers can customize browser cache behavior by setting this header on the response.
We won’t discuss in this article, but other means to control Cloudflare’s cache include: Page rules and Cloudflare cache settings. I highly recommend the article How to Control Cloudflare’s cache if you wish to avoid writing JavaScript with still some granularity of control.
What should I use: the Cache API or fetch for caching objects on Cloudflare?
For requests where Workers are behaving as middleware (i.e. they are sending a subrequest via fetch
) it is recommended to use fetch. This is because pre existing settings are in place that optimize caching while preventing unintended dynamic caching. For projects where there is no backend (i.e. the entire project is on Workers as in Workers Sites) the Cache API is the only option to customize caching.
fetch
In the context of Workers a fetch
provided by the runtime communicates with the Cloudflare cache. First, fetch
checks to see if the URL matches a different zone. If it does, it reads through that zone’s cache (or Worker!). Otherwise, it reads through its own zone’s cache, even if the URL is for a non-Cloudflare site. Cache settings on fetch
automatically apply caching rules based on your Cloudflare settings. fetch
does not allow you to modify or inspect objects before they reach the cache, but does allow you to modify how it will cache.
When a response fills the cache, the response header contains CF-Cache-Status: HIT
. You can tell an object is attempting to cache if one sees the CF-Cache-Status
at all.
This template shows ways to customize Cloudflare cache behavior on a given request using fetch.
Cache API
The Cache API can be thought of as an ephemeral key-value store, whereby the Request
object (or more specifically, the request URL) is the key, and the Response
is the value.
There are two types of cache namespaces available to the Cloudflare Cache:
caches.default
– You can access the default cache (the same cache shared withfetch
requests) by accessingcaches.default
. This is useful when needing to override content that is already cached, after receiving the response.- New namespaces – When writing new content to the cache, for example after running a more compute heavy operation such as parsing HTML, or running a computation, you can use
caches.open(CACHE_NAME)
to store them locally in the colo, and readily access them on the following request, rather having to rerun the same operation.
When to use the Cache API:
- When you need to read from cache without calling fetch. (i.e. send me the response from
slow.com/resource
if and only if it’s already a HIT on cache usingcaches.default.match(..)
. - Explicitly store a response in the cache using
caches.default.put(..)
and explicitly deletecaches.default.delete(..)
. For example, say your origin is returningmax-age:0
and you can’t figure out how to change that header at your origin. You can explicitly tell Cloudflare to cache this response by settingcache-control: max-age=1000
on the response passed intocache.put()
.
This template shows ways to use the cache API. For limits of the cache API see limits.