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.
Runs on Internal Rivet Actor per cache name, with Miniflare's freshness rules
- Works
caches.default,caches.open(),put(),match(), anddelete(), 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.
Varyis ignored when matching. - Missing
cache.add(),cache.addAll(), and the edge cache thatfetch()options such ascf.cacheTtlcontrol- 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.
-
Create the Worker
The Cache API needs no binding, so any
wrangler.jsoncworks.{ "name": "cached-pages", "main": "src/index.ts", "compatibility_date": "2026-09-03" } -
Cache each response
Look the request up with
match(), and store a miss withput(). The response’smax-agesets 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; -
Run it
Start
orange dev, which serves the Worker on port 8787, then request the page twice.orange devcurl -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.defaultis one actor, so spread busy traffic over named caches withcaches.open().- Set
ORANGE_CACHE=offto 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
| Feature | Status | Notes |
|---|---|---|
caches.default and caches.open(name) | Supported | |
put() | Supported | workerd’s checks and errors. A response with no-store, private, no-cache, or Set-Cookie is not stored, and put() still resolves. |
match() | Supported | 304 for If-None-Match and If-Modified-Since, and 206 or 416 for a Range. |
delete() | Supported | Returns true only when it removed a live entry. |
ignoreMethod | Supported | |
request.cf.cacheKey in Cache API calls | Supported | Replaces the URL as the key. |
Vary | Partial | Ignored for matching. Vary: * makes put() throw. |
A Range with several ranges | Partial | Gets the whole body with 200. |
cache.add() and cache.addAll() | Not supported | Not defined. |
ctx.cache | Not supported | undefined, as in local workerd. |
fetch() with cf.cacheTtl, cf.cacheEverything, cf.cacheKey, or cf.cacheTags | Not supported | The subrequest goes to the origin. |
Two differences reach most projects:
Varyis ignored when matching. Responses that vary by a request header share one entry, so put what varies into the key, for example the URL orrequest.cf.cacheKey.fetch()cache options do nothing. On Cloudflare,cf.cacheTtlandcf.cacheEverythingcontrol 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 inwrangler dev.
Limits
| What | Limit | What happens over it |
|---|---|---|
| How long an entry stays | Its s-maxage, max-age, or Expires | match() misses, and Orange deletes the entry. |
| Body of one entry | No limit set by Orange. Cloudflare’s is 512 MB. | |
| Cache API calls in one request | No limit set by Orange. Cloudflare’s is 50 or 1,000. | |
| Length of a cache name | No 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.
| Setting | On Orange |
|---|---|
ORANGE_CACHE unset, empty, or on | Entries are stored. |
ORANGE_CACHE=off | Nothing is stored, as on a workers.dev subdomain: put() resolves, match() returns undefined, and delete() returns false. |
Any other ORANGE_CACHE value | orange 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:
| Call | Error message |
|---|---|
A second argument that is not a Response | Failed to execute 'put' on 'Cache': parameter 2 is not of type 'Response'. |
| An error response | Cache is unable to store an error response |
A request that is not GET | Cannot cache response to non-GET request. |
A 206 response | Cannot cache response to a range request (206 Partial Content). |
A response with Vary: * | Cannot cache response with 'Vary: *' header. |
| A WebSocket upgrade response | Cannot cache WebSocket upgrade response. |
- A
304response is discarded, and its body is left alone, as in workerd. - Freshness comes from
http-cache-semanticswithshared: true, as in Miniflare. A response with onlyLast-Modifiedstays 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-Cookiestores the response without itsSet-Cookieheader.put()reads the whole body even when it does not store it, as workerd does, so a Worker that streams a body intoput()sees its writes succeed. The body is disturbed whenput()returns.- A
put()whose upload pauses for more than 5 minutes between chunks can lose its chunks. It then fails withCache 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, andmatch()returnsundefined. - Responses follow Miniflare’s order:
416, then304, then206, then the whole entry. - A
Rangethat cannot be met gets416withContent-Range: bytes */<size>. If-None-Matchmatches the storedETag, strong or weak, and*matches any entry with anETag.If-Modified-Sincematches a storedLast-Modifiedat or before it.- A stored
204,205, or304entry returns no body. match()anddelete()treat a request that is notGETas a miss, and returnundefinedorfalse, unlessignoreMethod: true. A Worker can answerHEADfrom theGETentry withignoreMethod: true.- An empty
request.cf.cacheKeyfalls back to the URL. delete()of an expired entry returnsfalse, 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 withCached 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 asCache API (Orange).caches.defaultuses the namedefault, andcaches.open("x")usesnamed: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 aput()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_CACHEalso works in.envandvars. ForORANGE_*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
cachekey of the Wrangler configuration is ignored. No cache runs in front of the Worker. new Cache()andnew CacheStorage()throwTypeError: Illegal constructor, as in workerd.- The
cacheexport ofcloudflare:workersdoes not exist. A Worker that imports it fails to load withThe 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 sendsmultipart/byteranges. - Orange serves
206for any stored entry. Cloudflare requires a storedContent-Length.
Conformance
tests/bindings/cache.test.tsdrives the Cache API through a realorange devover HTTP. It covers hits in one cache only, expiry, delete,no-store,private, andSet-Cookie, puts of clones and streamed bodies that are not stored,304,206and416, puts of different bodies that race on one URL, workerd’sTypeErrors, a restart, andORANGE_CACHE=off.- The runnable example
tests/fixtures/examples/cache-apiis a caching proxy in front of a slow origin, with a named cache, purges, andORANGE_CACHE=off.tests/examples/runnable-examples.test.tsruns it end to end. - workerd’s upstream
cache-testruns againstorange dev.putOperations,headersOperations, andconditionalRequestOperationspass.matchOperationsanddeleteOperationsfail, because they depend on workerd’s mock cache backend.cache-put-stream-test’sconcurrentClonePutspasses.
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 |
|