Cache API

A Cache API do Azion Runtime permite que uma function leia e grave no Cache. O objeto global caches é um CacheStorage que abre caches pelo nome. Cada Cache que ele retorna armazena objetos Response sob uma chave, de modo que uma function pode guardar uma resposta que construiu e retorná-la novamente.

nota — Com azion dev, caches não está definido, e qualquer chamada lança ReferenceError: caches is not defined. O formato de handler export async function fetch também interrompe o azion dev com SyntaxError: Unexpected token 'export'. Teste o código da Cache API em uma function com deploy feito.

Acesso

Uma function acessa a Cache API por meio do objeto global caches. Abra um cache pelo nome com caches.open() e, em seguida, chame os métodos de Cache no objeto que ele retorna:

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

CacheStorage

O objeto global caches é um CacheStorage. Ele tem três métodos, e cada um recebe o nome de um cache.

Método	Retorna	Descrição
`open(name)`	`Cache`	Abre o cache com esse nome.
`has(name)`	booleano	`true` quando o cache foi aberto antes na mesma requisição. `false` para um nome que a requisição não abriu.
`delete(name)`	booleano	Exclui o cache com esse nome. Retorna `false` para um nome que a requisição não abriu.

caches.keys() e caches.default não estão disponíveis: os dois são undefined.

Cache

caches.open() retorna um Cache. Um Cache armazena cada resposta sob uma chave, que é um objeto Request ou uma string de URL.

Método	Retorna	Descrição
`match(request)`	`Response` ou nenhum valor	Retorna a resposta armazenada sob a chave. Quando a chave não tem entrada, a promise é resolvida sem resposta, e `if (cached)` é falso.
`put(request, response)`	—	Armazena a resposta sob a chave. O método da requisição precisa ser `GET`.
`delete(request)`	booleano	Remove a entrada da chave e retorna `true`. Um `match()` posterior para a chave não retorna resposta.

matchAll(), add(), addAll() e keys() não estão disponíveis em um Cache.

Respostas armazenadas

O header cache-control de uma resposta não impede que put() a armazene. Uma resposta com cache-control: no-store é armazenada, e match() a retorna na mesma requisição.

Uma resposta armazenada com cache-control: max-age=600 é encontrada por requisições posteriores. Depois que delete() remove a entrada, match() não retorna resposta.

Exemplo

A function abaixo executa operações de CacheStorage e de Cache escolhidas pelos headers da requisição. Ela lê três headers:

Header	Valores	Descrição
`x-storage-operation`	`open`, `has`, `delete`	A operação de `CacheStorage` a executar.
`x-cache-operation`	`match`, `put`, `delete`, `none`, `all`	A operação de `Cache` a executar depois de `open`. `none` apenas abre o cache, e `all` executa `put`, `match` e `delete` em uma única requisição.
`x-storage-name`	Qualquer string	Nome do cache. Opcional; o padrão é `my-cache`.

Em uma function com deploy feito, o argumento env é um objeto vazio, então uma requisição sem x-storage-name usa my-cache.

JavaScript

01function generateResponse(message, status) {

02 return new Response(message, {

03 headers: { "content-type": "text/plain" },

04 status,

05 });

06}

08async function runCacheOperation(cache, op, request) {

09 switch (op) {

10 case "none":

11 return generateResponse("success in cache open!", 200);

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 }

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 }

31 case "delete":

32 console.log("[INFO] 'delete' operation");

33 await cache.delete(request);

34 return generateResponse("OK", 200);

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 }

45 default:

46 console.log("[INFO] invalid cache operation");

47 return generateResponse("Invalid cache operation", 400);

48 }

49}

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";

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 }

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 }

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 }

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}

A function responde às requisições enviadas na ordem abaixo com estas respostas:

`x-storage-operation`	`x-cache-operation`	Status	Corpo
Não enviado	Não enviado	400	`Invalid cache storage operation`
`open`	`none`	200	`success in cache open!`
`open`	`put`	200	`my content`
`open`	`match`	404	`No content cached`
`open`	`delete`	200	`OK`
`open`	`all`	200	`all ops ok`
`has`	Não enviado	200	`Cache storage 'my-cache' does NOT exist.`
`delete`	Não enviado	200	`Cache storage 'my-cache' doesn't exist.`
`bogus`	Não enviado	400	`Invalid cache storage operation`

A resposta que essa function armazena não tem header cache-control, e uma requisição match após a requisição put responde 404. Uma resposta armazenada com cache-control: max-age é encontrada por requisições posteriores, como descreve a seção Respostas armazenadas. As requisições has e delete não abrem o cache, e as duas informam que my-cache não existe.

Erros

Erro	Causa	Solução
`TypeError: Request method must be GET`	`put()` recebeu uma requisição cujo método não é `GET`, como `POST`.	Armazene a resposta sob uma requisição `GET` ou uma string de URL.
`ReferenceError: caches is not defined`	O código roda com `azion dev`, que não fornece `caches`.	Teste o código em uma function com deploy feito.

Recursos relacionados

Handlers

Os formatos de handler que uma function exporta e os argumentos que cada um recebe.

Response

O objeto Response que put() armazena e match() retorna.

Request

O objeto Request que um Cache usa como chave de uma entrada.

Cache settings

As configurações que uma aplicação usa para fazer cache de respostas sem uma function.