Skip to content
Runtime APIs / Cache API

Runtime APIs

Cache API

Use caches.default and caches.open() on OpenOrange, where each cache name is one Rivet Actor with its own SQLite database.

Partial

Runs on Internal Rivet Actor per cache name, with Miniflare's freshness rules

Works
caches.default, caches.open(), put(), match(), and delete(), with workerd's checks and Miniflare's freshness rules
Differs
One cache for each name, not one per data center, and entries stay until they expire. Vary is ignored when matching.
Missing
cache.add(), cache.addAll(), and the edge cache that fetch() options such as cf.cacheTtl control
Migration
Not needed A cache fills again on Orange.
Scales by
Cache name
Checks
1 pass

The Cache API stores responses so your Worker can answer a repeat request without building the response again. On OpenOrange, each cache name is one Rivet Actor with its own SQLite database.

Quickstart

This caches each page of a Worker for 60 seconds.

  1. Create the Worker

    The Cache API needs no binding, so any wrangler.jsonc works.

    {
      "name": "cached-pages",
      "main": "src/index.ts",
      "compatibility_date": "2026-09-03"
    }
  2. Cache each response

    Look the request up with match(), and store a miss with put(). The response’s max-age sets how long its entry lives.

    export default {
      async fetch(request): Promise<Response> {
        if (request.method !== "GET") {
          return new Response("Method Not Allowed", { status: 405 });
        }
        const cache = caches.default;
        const cached = await cache.match(request);
        if (cached) return cached;
    
        const response = new Response(`Rendered at ${new Date().toISOString()}`, {
          headers: { "cache-control": "public, max-age=60" },
        });
        await cache.put(request, response.clone());
        return response;
      },
    } satisfies ExportedHandler;
  3. Run it

    Start orange dev, which serves the Worker on port 8787, then request the page twice.

    orange dev
    curl -i localhost:8787/
    curl -i localhost:8787/

    The second response has the same body and the header cf-cache-status: HIT. After 60 seconds the entry expires, and the next request renders the page again.

How it works

  • Entries survive a restart of orange dev.
  • caches.default is one actor, so spread busy traffic over named caches with caches.open().
  • Set ORANGE_CACHE=off to turn the cache off.
AI context Compatibility, limits and details

Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.

Compatibility

FeatureStatusNotes
caches.default and caches.open(name)Supported
put()Supportedworkerd’s checks and errors. A response with no-store, private, no-cache, or Set-Cookie is not stored, and put() still resolves.
match()Supported304 for If-None-Match and If-Modified-Since, and 206 or 416 for a Range.
delete()SupportedReturns true only when it removed a live entry.
ignoreMethodSupported
request.cf.cacheKey in Cache API callsSupportedReplaces the URL as the key.
VaryPartialIgnored for matching. Vary: * makes put() throw.
A Range with several rangesPartialGets the whole body with 200.
cache.add() and cache.addAll()Not supportedNot defined.
ctx.cacheNot supportedundefined, as in local workerd.
fetch() with cf.cacheTtl, cf.cacheEverything, cf.cacheKey, or cf.cacheTagsNot supportedThe subrequest goes to the origin.

Two differences reach most projects:

  • Vary is ignored when matching. Responses that vary by a request header share one entry, so put what varies into the key, for example the URL or request.cf.cacheKey.
  • fetch() cache options do nothing. On Cloudflare, cf.cacheTtl and cf.cacheEverything control the zone’s edge cache, which is separate from the Cache API. Orange has no edge cache, so the subrequest always goes to the origin, as in wrangler dev.

Limits

WhatLimitWhat happens over it
How long an entry staysIts s-maxage, max-age, or Expiresmatch() misses, and Orange deletes the entry.
Body of one entryNo limit set by Orange. Cloudflare’s is 512 MB.
Cache API calls in one requestNo limit set by Orange. Cloudflare’s is 50 or 1,000.
Length of a cache nameNo limit set by Orange. Cloudflare’s is 1,024 characters.

What Orange reads

The Cache API stores entries by default. ORANGE_CACHE changes that. Set it in the shell or in .dev.vars, and the shell wins.

SettingOn Orange
ORANGE_CACHE unset, empty, or onEntries are stored.
ORANGE_CACHE=offNothing is stored, as on a workers.dev subdomain: put() resolves, match() returns undefined, and delete() returns false.
Any other ORANGE_CACHE valueorange dev stops with an error.

put()

put() reads freshness as a shared cache does: s-maxage, then max-age, then Expires. The request’s own Cache-Control does not count.

Validation and its error text follow workerd’s Cache::put(). Each of these throws a TypeError:

CallError message
A second argument that is not a ResponseFailed to execute 'put' on 'Cache': parameter 2 is not of type 'Response'.
An error responseCache is unable to store an error response
A request that is not GETCannot cache response to non-GET request.
A 206 responseCannot cache response to a range request (206 Partial Content).
A response with Vary: *Cannot cache response with 'Vary: *' header.
A WebSocket upgrade responseCannot cache WebSocket upgrade response.
  • A 304 response is discarded, and its body is left alone, as in workerd.
  • Freshness comes from http-cache-semantics with shared: true, as in Miniflare. A response with only Last-Modified stays fresh for 10% of the time since it was modified, that library’s heuristic. A response with no freshness at all is not stored.
  • Cache-Control: private=Set-Cookie stores the response without its Set-Cookie header.
  • put() reads the whole body even when it does not store it, as workerd does, so a Worker that streams a body into put() sees its writes succeed. The body is disturbed when put() returns.
  • A put() whose upload pauses for more than 5 minutes between chunks can lose its chunks. It then fails with Cache put failed: its body upload expired before it was committed.

match() and delete()

  • A hit has cf-cache-status: HIT. An expired entry is a miss, and match() returns undefined.
  • Responses follow Miniflare’s order: 416, then 304, then 206, then the whole entry.
  • A Range that cannot be met gets 416 with Content-Range: bytes */<size>.
  • If-None-Match matches the stored ETag, strong or weak, and * matches any entry with an ETag. If-Modified-Since matches a stored Last-Modified at or before it.
  • A stored 204, 205, or 304 entry returns no body.
  • match() and delete() treat a request that is not GET as a miss, and return undefined or false, unless ignoreMethod: true. A Worker can answer HEAD from the GET entry with ignoreMethod: true.
  • An empty request.cf.cacheKey falls back to the URL.
  • delete() of an expired entry returns false, because it was already a miss.
  • A match() response streams the body that its entry pointed to. When the entry is replaced or expires, that body stays readable for 5 minutes. After that, a read fails with Cached response body is no longer available. Its entry was replaced or expired more than 5 minutes ago.

Storage

  • The actor’s class is the internal openorange:cache. RivetKit shows it as Cache API (Orange). caches.default uses the name default, and caches.open("x") uses named:x, as Miniflare does.
  • Each Worker of a multi-Worker session has its own caches.
  • Entries persist in the local Engine state under .open-orange/rivetkit/.
  • A Worker with no Durable Objects or storage bindings starts the Rivet Engine on its first Cache API call, which waits a few seconds.
  • A put() writes each 512 KiB chunk in its own request and commit, then a final commit points the entry at the new body. So Rivet’s commit limit does not bound an entry.
  • A match() during a put() on the same URL gets one complete body, never a mix of two.
  • Chunks are read over a WebSocket to the actor, with up to 4 chunk reads in flight. A body that is never read opens no WebSocket, so it does not keep the actor awake.
  • An alarm removes expired entries, at most 16 per run. It deletes the chunks of a replaced, deleted, or expired body 5 minutes after the body lost its entry, and of an abandoned upload 5 minutes after its last chunk, at most 16 chunks per run.

Configuration edge cases

  • ORANGE_CACHE also works in .env and vars. For ORANGE_* settings, the shell’s value wins over the Worker’s vars.
  • An invalid value fails with ORANGE_CACHE must be "on" or "off", not "<value>".
  • The cache key of the Wrangler configuration is ignored. No cache runs in front of the Worker.
  • new Cache() and new CacheStorage() throw TypeError: Illegal constructor, as in workerd.
  • The cache export of cloudflare:workers does not exist. A Worker that imports it fails to load with The requested module does not provide an export named 'cache'.

Deviations

These add to the differences under Compatibility and Limits.

  • A request for several ranges gets the whole body with 200, which HTTP allows. Miniflare sends multipart/byteranges.
  • Orange serves 206 for any stored entry. Cloudflare requires a stored Content-Length.

Conformance

  • tests/bindings/cache.test.ts drives the Cache API through a real orange dev over HTTP. It covers hits in one cache only, expiry, delete, no-store, private, and Set-Cookie, puts of clones and streamed bodies that are not stored, 304, 206 and 416, puts of different bodies that race on one URL, workerd’s TypeErrors, a restart, and ORANGE_CACHE=off.
  • The runnable example tests/fixtures/examples/cache-api is a caching proxy in front of a slow origin, with a named cache, purges, and ORANGE_CACHE=off. tests/examples/runnable-examples.test.ts runs it end to end.
  • workerd’s upstream cache-test runs against orange dev. putOperations, headersOperations, and conditionalRequestOperations pass. matchOperations and deleteOperations fail, because they depend on workerd’s mock cache backend. cache-put-stream-test’s concurrentClonePuts passes.

Recorded results from the conformance run of 2026-11-10 (Orange ea40348), 1,670 of 1,851 tests passing across every area. Each check is works when every result passed and partial when some did. The full feature matrix is on the compatibility page.

Cache API
Check Status Results
Cache API Works
  • Pass: example: cache-api