Module cache

HTTP response caching middleware.

Replays the response held for a safe http or https exchange while the origin server allows it to be reused, and revalidates it against the origin server once that allowance is up, so that content is transferred again only when what is held is known to be outdated.

Responsibility is limited to replay and revalidation: reuse is governed entirely by the header fields a response states, and a response stating no freshness is revalidated on every exchange rather than reused heuristically.

Unsafe exchanges are relayed as they are; once one succeeds, the entries for its target and for whatever else the response reports as changed are given up, so that a client that both reads and writes never serves what it has just replaced.

Exchanges targeting any other scheme are relayed untouched and never stored, as freshness is defined for HTTP responses alone.

Freshness and validation rest on what a response states, that is Cache-Control no-store, no-cache and max-age, Expires, Vary and the ETag and Last-Modified validators. Freshness is never guessed, so a response stating neither max-age nor Expires is revalidated on every exchange; directives a request states, no-cache and only-if-cached among them, are not honoured; directives addressed to shared caches alone, such as s-maxage, play no part, as each client holds a store of its own.

Complete responses are the only ones replayed: an exchange stating a Range, a partial response and a response setting a cookie are relayed as they stand and never stored, and GET and HEAD are held apart, so a stored HEAD never answers a GET. Concurrent exchanges for one target are relayed on their own, and a failed exchange is reported as it stands rather than answered from a stale entry. Targets the consumer selects with glob patterns are kept out altogether, so that a resource is held back whatever the origin server states about it.

Entries are held in memory unless a backing store is supplied, so caching is available with no setup and moved to the file system or to a shared service once a process-local cache is no longer enough: a Store holds entries whole, while a Bucket holds their content as opaque bytes, as a cloud object storage service does.

Usage

import { createFetch } from "@metreeca/http";
import { cache } from "@metreeca/http/cache";

const client = createFetch(cache());
Copy