HTTP Cache Semantics (RFC 9111)

Decides whether a response may be stored, whether a shared cache may keep it, and for how long -- with the rule that drove each decision.

THE SILENT FAILURE. Caching bugs do not throw. They serve the WRONG USER'S DATA, or serve stale content long after it changed, and both look like the system working. A response with Cache-Control private stored in a shared cache leaks one user's page to another -- the most expensive bug in this category and invisible until somebody reports seeing another person's name. A missing Vary on Authorization does the same by a different route.

Heuristic freshness is the quiet one: a response with no explicit expiry MAY be cached using a heuristic per RFC 9111, so an endpoint the author never intended to be cached gets cached anyway, and the author never knew it was a decision.

It FAILS CLOSED TOWARD NOT CACHING. Where the specification permits heuristic freshness it reports that a heuristic WOULD apply and what it would be, rather than quietly adopting it. An unparseable or contradictory header set is treated as not cacheable and reported, never resolved by picking the more permissive reading. Every rule cites its RFC 9111 section, and every decision carries the directive that drove it.

It computes decisions from headers you supply. It is not an HTTP client and stores nothing.

VERIFIED: 169 tests. Every mutation was observed FAILING before the source was restored -- a test never seen to fail is a decoration. Independently reviewed by a verifier whose job was to find what is wrong, not to agree.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function parseAgeHeader(headers: HeaderMap | undefined): number | null;
  export function computeAge( responseHeaders: HeaderMap | undefined, now: number | Date, responseTime: number | Date, ): AgeResult;
  export function tokenizeCacheControl(raw: string): CacheDirectiveEntry[];
  export function resolveSingle( entries: CacheDirectiveEntry[], name: string, field: string, issues: ParseIssue[], ): ResolvedSingle;
  export function resolveDeltaSecondsDirective( entries: CacheDirectiveEntry[], name: string, field: string, issues: ParseIssue[], ): ResolvedDeltaSeconds;
  export function resolveQualifiedFlag( entries: CacheDirectiveEntry[], name: string, field: string, issues: ParseIssue[], ): ResolvedQualifiedFlag;
  export function hasFlag(entries: CacheDirectiveEntry[], name: string): boolean;
  export function parseResponseCacheControl( raw: string | null, issues: ParseIssue[], ): ResponseDirectives;
  export function parseRequestCacheControl( raw: string | null, _issues: ParseIssue[], ): RequestDirectives;
  export function evaluateCacheability( request: CacheRequest, response: CacheResponse, options: EvaluateOptions = {}, ): CacheDecision;
  export function getHeader(headers: HeaderMap | undefined, name: string): string | null;
  export function hasHeader(headers: HeaderMap | undefined, name: string): boolean;

  export type HeaderMap = Record<string, string | string[] | undefined>;
  export type CacheType = "shared" | "private";