Cache API

Fine-grained control over reading and writing from the bunny.net edge cache from Edge Scripting.

The Cache API is an implementation of the MSDN Cache Interface. It stores Request and Response pairs in long lived memory.

The API is available globally, but cache contents do not replicate outside the originating region. A GET /users response cached in one region will not exist in another until a request for that resource is made from there.

An origin can have multiple, named Cache objects, and it is up to your script to decide how cache updates happen. Items in a Cache respect the Cache-Control request header, which is how you control the life cycle of your caches. Entries are purged automatically a short time after they expire. Version your caches by name, and only use a cache from a version of the script that can safely operate on it.

Cache instances are shared across all domains associated with your PullZone, but they must be accessed via the currently requesting host name. Use the current Request object as the key, or build the key from the current request URL, for example const key = new URL(req.url).origin + "/img/example.png";. Either way your caches will work reliably across every domain on the PullZone.

Note: There is a hard limit of 100MB per cache file.

Limitations

API surface limits:

• CacheStorage (the global caches object)
  • Supported: caches.default, caches.open(name)
  • Not supported: caches.has, caches.delete, caches.keys, caches.match
• Cache (an instance returned by caches.default or caches.open)
  • Supported: match, put, delete
  • Not supported: matchAll, add, addAll, keys

We recommend versioning your cache names (e.g. cache:v1, cache:v2) so that a cache is completely purged when updating scripts.

Quickstart

A minimal cache-aside pattern: look up by URL, generate on miss, write back in the background.

import * as BunnySDK from "@bunny.net/edgescript-sdk@0.12.0";

BunnySDK.net.http.serve(async (request: Request): Promise<Response> => {
  const url = new URL(request.url);

  try {
    // Normalize the key to a GET on the request URL so reads and writes
    // resolve to the same entry regardless of the inbound method.
    const cacheKey = new Request(url.toString(), { method: "GET" });
    const cache = caches.default;

    const cached = await cache.match(cacheKey);
    if (cached) {
      console.log(`Cache hit for: ${request.url}.`);
      return cached;
    }

    console.log(`Cache miss for: ${request.url}. Generating and caching.`);

    // In a real script this is typically `await fetch(originUrl)`.
    const response = Response.json(
      { value: Math.random() },
      { headers: { "Cache-Control": "s-maxage=10" } },
    );

    // Fire-and-forget the write so we can return immediately.
    Bunny.v1.waitUntil(cache.put(cacheKey, response.clone()));

    return response;
  } catch (e) {
    return new Response(`Cache error: ${(e as Error).message}`, { status: 500 });
  }
});

See Examples for longer recipes: HTMLRewriter integration, middleware writes, and on-demand refresh and purge.

References

• MSDN CacheStorage - Mozilla’s CacheStorage interface documentation
• MSDN Cache API - Mozilla’s Cache interface documentation