Cache API

Cache API reference: open a named cache from a function, then store, match, and delete responses with CacheStorage and Cache.

Last updated

View as Markdown Agent setup

The Azion Runtime Cache API lets a function read from and write to Cache. The global caches object is a CacheStorage that opens caches by name. Each Cache it returns stores Response objects under a key, so a function can keep a response it built and return it again.

Under azion dev, caches is not defined, and any call throws ReferenceError: caches is not defined. The export async function fetch handler shape also stops azion dev with SyntaxError: Unexpected token 'export'. Test Cache API code on a deployed function.

Access

A function reaches the Cache API through the global caches object. Open a cache by name with caches.open(), then call the Cache methods on the object it returns:

const cache = await caches.open("my-cache");

CacheStorage

The global caches object is a CacheStorage. It has three methods, and each one takes the name of a cache.

MethodReturnsDescription
open(name)CacheOpens the cache with this name.
has(name)booleantrue when the cache was opened earlier in the same request. false for a name the request has not opened.
delete(name)booleanDeletes the cache with this name. Returns false for a name the request has not opened.

caches.keys() and caches.default are not available: both are undefined.

Cache

caches.open() returns a Cache. A Cache stores each response under a key, which is a Request object or a URL string.

MethodReturnsDescription
match(request)Response, or no valueReturns the response stored under the key. When the key has no entry, the promise resolves to no response, and if (cached) is false.
put(request, response)—Stores the response under the key. The request method must be GET.
delete(request)booleanRemoves the entry for the key and returns true. A later match() for the key returns no response.

matchAll(), add(), addAll(), and keys() are not available on a Cache.

Stored responses

The cache-control header of a response does not stop put() from storing it. A response with cache-control: no-store is stored, and match() returns it in the same request.

A response stored with cache-control: max-age=600 is matched by later requests. After delete() removes the entry, match() returns no response.

Example

The function below runs CacheStorage and Cache operations chosen by request headers. It reads three headers:

HeaderValuesDescription
x-storage-operationopen, has, deleteThe CacheStorage operation to run.
x-cache-operationmatch, put, delete, none, allThe Cache operation to run after open. none only opens the cache, and all runs put, match, and delete in one request.
x-storage-nameAny stringName of the cache. Optional; the default is my-cache.

Deployed, the env argument is an empty object, so a request without x-storage-name uses my-cache.

JavaScript
01function generateResponse(message, status) {
02 return new Response(message, {
03 headers: { "content-type": "text/plain" },
04 status,
05 });
06}
07
08async function runCacheOperation(cache, op, request) {
09 switch (op) {
10 case "none":
11 return generateResponse("success in cache open!", 200);
12
13 case "match": {
14 console.log("[INFO] 'match' operation");
15 const cached = await cache.match(request);
16 if (cached) {
17 console.log("[INFO] Cache hit for: " + request.url);
18 return cached;
19 }
20 console.log("[INFO] No content cached");
21 return generateResponse("No content cached", 404);
22 }
23
24 case "put": {
25 console.log("[INFO] 'put' operation");
26 const resp = generateResponse("my content", 200);
27 await cache.put(request, resp.clone());
28 return resp;
29 }
30
31 case "delete":
32 console.log("[INFO] 'delete' operation");
33 await cache.delete(request);
34 return generateResponse("OK", 200);
35
36 case "all": {
37 console.log("[INFO] 'all' operations (put -> match -> delete)");
38 const resp = generateResponse("my content", 200);
39 await cache.put(request, resp.clone());
40 await cache.match(request);
41 await cache.delete(request);
42 return generateResponse("all ops ok", 200);
43 }
44
45 default:
46 console.log("[INFO] invalid cache operation");
47 return generateResponse("Invalid cache operation", 400);
48 }
49}
50
51export async function fetch(request, env, ctx) {
52 const storageOp = request.headers.get("x-storage-operation");
53 const cacheOp = request.headers.get("x-cache-operation");
54 const storageName =
55 request.headers.get("x-storage-name") ||
56 env.DEFAULT_CACHE_NAME || // optional
57 "my-cache";
58
59 try {
60 switch (storageOp) {
61 /* ---------- cacheStorage.open ---------- */
62 case "open": {
63 console.log("[INFO] cache storage 'open' operation");
64 const cache = await caches.open(storageName);
65 console.log("[INFO] storage cache '" + storageName + "' opened");
66 return runCacheOperation(cache, cacheOp, request);
67 }
68
69 /* ---------- cacheStorage.has ---------- */
70 case "has": {
71 console.log("[INFO] cache storage 'has' operation");
72 const exists = await caches.has(storageName);
73 const msg = exists
74 ? "Cache storage '" + storageName + "' exists."
75 : "Cache storage '" + storageName + "' does NOT exist.";
76 console.log("[INFO] " + msg);
77 return generateResponse(msg, 200);
78 }
79
80 /* ---------- cacheStorage.delete ---------- */
81 case "delete": {
82 console.log("[INFO] cache storage 'delete' operation");
83 const deleted = await caches.delete(storageName);
84 const msg = deleted
85 ? "Success deleting cache storage '" + storageName + "'."
86 : "Cache storage '" + storageName + "' doesn't exist.";
87 console.log("[INFO] " + msg);
88 return generateResponse(msg, 200);
89 }
90
91 /* ---------- invalid op ---------- */
92 default:
93 console.log("[INFO] invalid cache storage operation");
94 return generateResponse("Invalid cache storage operation", 400);
95 }
96 } catch (err) {
97 console.error("[ERROR]", err);
98 return generateResponse(err.message, 500);
99 }
100}

The function answers requests sent in the order below with these responses:

x-storage-operationx-cache-operationStatusBody
Not sentNot sent400Invalid cache storage operation
opennone200success in cache open!
openput200my content
openmatch404No content cached
opendelete200OK
openall200all ops ok
hasNot sent200Cache storage 'my-cache' does NOT exist.
deleteNot sent200Cache storage 'my-cache' doesn't exist.
bogusNot sent400Invalid cache storage operation

The response this function stores carries no cache-control header, and a match request after the put request answers 404. A response stored with cache-control: max-age is matched by later requests, as Stored responses describes. The has and delete requests do not open the cache, and both report that my-cache does not exist.

Errors

ErrorCauseFix
TypeError: Request method must be GETput() received a request whose method is not GET, such as POST.Store the response under a GET request or a URL string.
ReferenceError: caches is not definedThe code runs under azion dev, which does not provide caches.Test the code on a deployed function.
Handlers

The handler shapes a function exports, and the arguments each one receives.

Response

The Response object that put() stores and match() returns.

Request

The Request object a Cache uses as the key of an entry.

Cache settings

The settings an application uses to cache responses without a function.