CF Workers SWR Cache

SWR (stale-while-revalidate) has become more and more popular since the introduction in the HTTP spec in 2010 (RFC5861). This post will show how you can use the Cloudflare Workers Cache API as a Request/Response based SWR cache. The Cache API itself allows you to store a Response for a specific Request but it does not allow you to store any other Request than GET requests and it currently does not support the stale-while-revalidate Cache Control variants. The method used and explained in this Post will allow both.

Straight to the Code

If you just wan't to get or see the code here is a link to a Gist including all the needed code. One note here, the Cache API only works if you have a dedicated Subdomain assigned to your Worker using *.workers.dev will not work.

Where you could use this or a similar Cache?

I personally use this cache method in combination with Remix to cache external API requests. For requests that can be served stale for a specific amount of time this works great. But you could also modify or use specific methods I used for the implementation to serve your caching needs.

Implementation

We will approach the implementation in various steps therefore you can read or copy the steps you need.

1. Creating a Cache Key

Ths first step is to create a unique cache key for every request so that we can check if we already cached this particulary request. This also is the first code part that you might want to adjust if you have different needs or want to adjust based on what certain request should match.

First of all we need a small function which can hash a dedicard string. For this we will use the available Web Crypto API which is offered by Cloudflare Workers.

async function sha256(message: string) {
  // encode as UTF-8
  const msgBuffer = new TextEncoder().encode(message);

  // hash the message
  const hashBuffer = await crypto.subtle.digest("SHA-256", msgBuffer);

  // convert ArrayBuffer to Array
  const hashArray = Array.from(new Uint8Array(hashBuffer));

  // convert bytes to hex string
  const hashHex = hashArray
    .map((b) => ("00" + b.toString(16)).slice(-2))
    .join("");
  return hashHex;
}

With the above function and several valued from our request we can create a unique hash we can use to identify a certain request. To identify the requests method, the headers and if applicable the requests body are used.

Here is the code that creates the hash:

const method = request.method.toLowerCase();

let hashText = "";
hashText += method;
hashText += request.url;
for (const header of request.headers) {
  hashText += header[0];
  hashText += header[1];
}
let body: string | null = null;
if (method !== "get" && method !== "head" && request.body) {
  body = await request.clone().text();
}
if (typeof body === "string") {
  hashText += body;
}
const key = await sha256(hashText);

2. Preparing our cache

We need a way to store both the Response data as well as the time our SWR Cache is valid via the Workers Cache API. Since the Cache API uses a Request to figure as the identifier to save and retrieve a cached value the first thing we do is to create two fake Requests which use the previously generated cacheKey in the URL to be uniquely identifiable.

const responseKeyUrl = new URL(request.url);
responseKeyUrl.pathname = `/posts/swr:request:${key}`;
const responseKey = new Request(responseKeyUrl.toString(), {
  method: "GET",
});

const stillGoodKeyUrl = new URL(request.url);
stillGoodKeyUrl.pathname = `/posts/swr:stillgood:${key}`;
const stillGoodKey = new Request(stillGoodKeyUrl.toString(), {
  method: "GET",
});

With those in place we can ask the Cache API for a cached value or store new values.

const cache = caches.default // to get the default cache

// to recieve a already cached value
const cachedValue = cache.match(cacheKey)

// to store a value (body) to a certain cacheKey Request
await cache.put(cacheKey, new Reponse(body, {
  headers: {
    "cache-control", "max-age= 6000"
  }
}))

We use the cache.match() function to check wheater there is a already cached response and to validate if our cached value is still considered fresh or if we should revalidate the cached value.

3. How our SWR mechanism is working

The following is a simplified diagram to explain how our SWR mechanism is working.

Here is the basic structure of the code we use to represent both the path if there is an already cached value and if there was no value already cached.

let response = await cache.match(responseKey).then(async (cachedResponse) => {
  if (!cachedResponse) {
    return null;
  }

  cachedResponse = new Response(cachedResponse?.body, cachedResponse);

  // check if the cache is still fresh or stale and act acordingly

  return cachedResponse;
});

if (!response) {
  // fetch Response and save to cache
}
return response;

Let's jump more into the detailed implementations starting with the path that chacks and revalidates the already cached values. First we use a simple Promise to check weather the cached response is still considered good / fresh.

const cachedStillGoodPromise = cache
  .match(stillGoodKey)
  .then((cachedStillGood) => {
    if (!cachedStillGood) {
      return false;
    }
    return true;
  })
  .catch(() => false);

Using the result of that Promise in both cases a Header indicating the status of the cach value is set and in the stale case the response data is refetched. To make sure the actual cached response is returned as fast as possible the waitUntil function available on the FetchEvent provided by Cloudflare is used to make the worker run our revalidation code after returning the data retrieved from the cache. To refetch the data the original request is cloned and the returned data is cached for one year because the stillGoodKey is used to define the length of the cached value.

Here is the code that checks the cache status and revalidates if needed:

if (await cachedStillGoodPromise) {
  // the cached value is still up to data and not stale so there is no need to refetch the data
  cachedResponse.headers.set("X-SWR-Cache", "hit");
} else {
  // here the cached value is stale, it still be delivered stale but revalidated in the background
  cachedResponse.headers.set("X-SWR-Cache", "stale");

  // this function will refetch the data and update both the result cache entry as well as the stillGood entry
  async function saveCache() {
    let responseToCache = await fetch(request.clone());
    responseToCache = new Response(responseToCache.body, {
      headers: {
        "Cache-Control": `max-age=${YEAR_AGE}`,
      },
    });
    if (responseToCache.status === 200) {
      await cache.put(responseKey, responseToCache.clone());
      await cache.put(
        stillGoodKey,
        new Response(null, {
          headers: {
            "cache-control": `max-age=${maxAgeSeconds}`,
          },
        })
      );
    }
    return null;
  }

  // we call the saveCache function with `event.waitUntil` to make sure the worker runs until it is funished
  // but also respond to our request as fast as possible
  event.waitUntil(saveCache());
}

For the case, that there is not already a cached value most of the code is very similar. The response is fetched using the incoming request and again by using event.waitUntil() the response and the newly calculated stillGoodKey are saved via the Cache API. Here is the detailed code.

response = await fetch(request.clone());
response = new Response(response.body, {
  headers: {
    "X-SWR-Cache": "miss",
    "Cache-Control": `max-age=${YEAR_AGE}`,
  },
});

if (response !== null && response.status === 200) {
  // this function will fetch the data and set both the result cache entry as well as the stillGood entry
  async function saveCache(response: Response) {
    await cache.put(responseKey, response.clone());
    await cache.put(
      stillGoodKey,
      new Response(null, {
        headers: {
          "cache-control": `max-age=${maxAgeSeconds}`,
        },
      })
    );
    return null;
  }
  // we call the saveCache function with `event.waitUntil` to make sure the worker runs until it is funished
  // but also respond to our request as fast as possible
  event.waitUntil(saveCache(response));
}

That wraps up all the steps needed to implement a SWR Cache approach on Cloudflare Workers using the provided Cache API. Again if you want the whole code here is a link to a GitHub Gist containing all the code you need. Again a small note here, the Cache API only works if you have a dedicated Subdomain assigned to your Worker using *.workers.dev will not work.

Example usage in Remix

I created a example application in remix using the described approach. You can find the Repo here and the deployed Cloudflare Worker here.

Credits

Some insporation and code was taken from Jacob Ebeys SWR Redis Implementation in his remix-ecommerce App. Also the Cloudflare Worker Examples dedicated to the Cache API helped a lot. %