workbox-cacheable-response

Ao armazenar recursos em cache no ambiente de execução, não há uma regra única que determina se uma determinada resposta é "válida" e está qualificada para ser salva e reutilizada.

O módulo workbox-cacheable-response fornece uma maneira padrão de determinar se uma resposta precisa ser armazenada em cache com base no código de status numérico, a presença de um cabeçalho com um valor específico ou uma combinação dos dois.

Armazenamento em cache com base em códigos de status

É possível configurar uma estratégia de caixa de trabalho para considerar um conjunto de códigos de status como qualificado para armazenamento em cache adicionando uma instância CacheableResponsePlugin ao parâmetro plugins de uma estratégia:

import {registerRoute} from 'workbox-routing';
import {CacheFirst} from 'workbox-strategies';
import {CacheableResponsePlugin} from 'workbox-cacheable-response';

registerRoute(
  ({url}) =>
    url.origin === 'https://third-party.example.com' &&
    url.pathname.startsWith('/images/'),
  new CacheFirst({
    cacheName: 'image-cache',
    plugins: [
      new CacheableResponsePlugin({
        statuses: [0, 200],
      }),
    ],
  })
);

Essa configuração informa ao Workbox que, ao processar respostas de solicitações em relação a https://third-party.example.com/images/, armazenar em cache todas as solicitações com código de status 0 ou 200.

Armazenamento em cache baseado em cabeçalhos

É possível configurar uma estratégia de caixa de trabalho para verificar a presença de valores de cabeçalho específicos como critérios para serem adicionados ao cache definindo o objeto headers ao criar o plug-in:

import {registerRoute} from 'workbox-routing';
import {StaleWhileRevalidate} from 'workbox-strategies';
import {CacheableResponsePlugin} from 'workbox-cacheable-response';

registerRoute(
  ({url}) => url.pathname.startsWith('/path/to/api/'),
  new StaleWhileRevalidate({
    cacheName: 'api-cache',
    plugins: [
      new CacheableResponsePlugin({
        headers: {
          'X-Is-Cacheable': 'true',
        },
      }),
    ],
  })
);

Ao processar respostas para URLs de solicitação contendo /path/to/api/, observe o cabeçalho chamado X-Is-Cacheable, que seria adicionado à resposta pelo servidor. Se esse cabeçalho estiver presente e definido como um valor "true", a resposta poderá ser armazenada em cache.

Se vários cabeçalhos forem especificados, apenas um deles precisará corresponder aos valores associados.

Armazenamento em cache com base em cabeçalhos e códigos de status

É possível misturar a configuração do status e do cabeçalho. As duas condições precisam ser atendidas para que uma resposta seja considerada armazenável em cache. Em outras palavras, a resposta precisa ter um dos códigos de status configurados e pelo menos um dos cabeçalhos fornecidos.

import {registerRoute} from 'workbox-routing';
import {StaleWhileRevalidate} from 'workbox-strategies';
import {CacheableResponsePlugin} from 'workbox-cacheable-response';

registerRoute(
  ({url}) => url.pathname.startsWith('/path/to/api/'),
  new StaleWhileRevalidate({
    cacheName: 'api-cache',
    plugins: [
      new CacheableResponsePlugin({
        statuses: [200, 404],
        headers: {
          'X-Is-Cacheable': 'true',
        },
      }),
    ],
  })
);

Quais são os padrões?

Se você usar uma das estratégias integradas do Workbox sem configurar explicitamente um cacheableResponse.CacheableResponsePlugin, os critérios padrão a seguir serão usados para determinar se uma resposta recebida da rede precisa ser armazenada em cache:

  • SantienanteRevalidate e networkFirst: as respostas com um status 0 (ou seja, respostas opacas) ou 200 são consideradas armazenáveis em cache.
  • cacheFirst: as respostas com status 200 são consideradas armazenáveis em cache.

Por padrão, os cabeçalhos de resposta não são usados para determinar a capacidade de cache.

Por que existem padrões diferentes?

Os padrões variam se as respostas com um status 0 (ou seja, respostas opacas) serão armazenadas em cache. Devido à natureza "preta" das respostas opacas, o service worker não pode saber se a resposta é válida ou se reflete uma resposta de erro retornada do servidor de origem cruzada.

Para estratégias que incluem alguns meios de atualizar a resposta em cache, como biaswhileRevalidate e networkFirst, o risco de armazenar uma resposta de erro temporária é atenuado pelo fato de que, na próxima vez que o cache for atualizado, uma resposta adequada e bem-sucedida será usada.

Para estratégias que envolvem o armazenamento em cache da primeira resposta recebida e a reutilização dessa resposta armazenada em cache indefinidamente, as repercussões de um erro temporário que é armazenado em cache e reutilizada são mais graves. Para errar pelo lado seguro por padrão, o cacheFirst se recusará para salvar uma resposta, a menos que tenha um código de status de 200.

Uso avançado

Caso queira usar a mesma lógica de armazenamento em cache fora de uma estratégia do Workbox, use a classe CacheableResponse diretamente.

import {CacheableResponse} from 'workbox-cacheable-response';

const cacheable = new CacheableResponse({
  statuses: [0, 200],
  headers: {
    'X-Is-Cacheable': 'true',
  },
});

const response = await fetch('/path/to/api');

if (cacheable.isResponseCacheable(response)) {
  const cache = await caches.open('api-cache');
  cache.put(response.url, response);
} else {
  // Do something when the response can't be cached.
}

Tipos

CacheableResponse

Essa classe permite configurar regras que determinam quais códigos de status e/ou cabeçalhos precisam estar presentes para que um Response seja considerado armazenável em cache.

Propriedades

  • construtor

    void

    Para criar uma nova instância CacheableResponse, forneça pelo menos uma das propriedades config.

    Se statuses e headers forem especificados, ambas as condições precisarão ser atendidas para que Response seja considerado armazenável em cache.

    A função constructor tem esta aparência: 

    (config?: CacheableResponseOptions) => {...}

  • isResponseCacheable

    void

    Verifica uma resposta para saber se pode ser armazenada em cache ou não, com base na configuração desse objeto.

    A função isResponseCacheable tem esta aparência: 

    (response: Response) => {...}

    • resposta

      Resposta

      A resposta com a capacidade de cache que está sendo verificada.

    • retorna

      boolean

      true se o Response puder ser armazenado em cache. Caso contrário, será false.

CacheableResponseOptions

Propriedades

  • headers

    objeto opcional

  • statuses

    number[] opcional

CacheableResponsePlugin

Uma classe que implementa o callback do ciclo de vida cacheWillUpdate. Isso facilita a adição de verificações de armazenamento em cache a solicitações feitas pelas estratégias integradas do Workbox.

Propriedades

  • construtor

    void

    Para construir uma nova instância CacheableResponsePlugin, você precisa fornecer pelo menos uma das propriedades config.

    Se statuses e headers forem especificados, ambas as condições precisarão ser atendidas para que Response seja considerado armazenável em cache.

    A função constructor tem esta aparência: 

    (config: CacheableResponseOptions) => {...}