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 by the header fields a response states, and a response stating no expiration is reused for a share of the interval its content had gone unchanged, or, where it reports no change time either, for as long as the consumer is willing to assume.

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, max-age, must-revalidate and proxy-revalidate, Expires, Vary and the ETag and Last-Modified validators. Freshness is never inferred from the content: a response stating none is reused under the volatility its Last-Modified reports, or, where it reports none, under the freshness the consumer assumes in its place. Directives a request states, no-cache and only-if-cached among them, are not honoured; a directive granting a shared cache a freedom a private one doesn't have, such as s-maxage, plays no part, as each client holds a store of its own, while one asking for revalidation is honoured whoever it addresses.

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