What belongs in the cache key for a rendered document

Why the default answer is wrong here

A document is a function of more inputs than the obvious one. The data is the input people think of. The template version, the stylesheet, the embedded fonts, the logo, the render options, the locale and the code that assembled the markup are all inputs too, and any of them changing produces a different document from the same data. A key built from the data alone is not a key for the document, it is a key for one of its arguments.

The decisions

Reasons rather than a description of the code. Each has a default that is defensible in general and wrong for documents specifically.

• Hash the assembled markup rather than the data, which folds the template, the stylesheet and the assembling code into one value at no extra effort.
• Include the render options in the key, because the same markup at a different page size is a different document.
• Include a version for the assets the markup references by URL, since a logo or a font served from a stable URL can change underneath a stable key.
• Include the locale, explicitly, even when it is currently always the same. It is the input most likely to be added later and forgotten.
• Prefer a deploy-scoped prefix over trying to enumerate every code input. Adding the build identifier to the key is coarse, and it makes a deploy correct by construction.
• Write down what is deliberately excluded. A key that excludes the requesting user is a decision, and it should be a recorded one rather than an omission.

In practice

A fragment, with the thing that goes wrong kept in a comment where it is the more instructive half.

import { createHash } from "node:crypto";

function cacheKey(spec) {
  const h = createHash("sha256");

  // Folds the template, the stylesheet and the assembling code into one
  // value, which is why hashing the markup beats hashing the data.
  h.update(spec.html);

  // The same markup at a different page size is a different document.
  h.update(JSON.stringify(sortKeys(spec.options ?? {})));

  // Assets referenced by a stable URL can change underneath a stable key.
  h.update(spec.assetVersion ?? "");

  // Explicit even when it is currently constant: it is the input most
  // likely to be added later and forgotten.
  h.update(spec.locale ?? "en-GB");

  // Coarse and correct by construction: a deploy invalidates everything.
  return `doc:${process.env.BUILD_ID}:${h.digest("hex")}`;

  /* Deliberately excluded, and recorded as a decision rather than an
     omission:
       the requesting user  documents here do not vary by viewer; if one
                            ever does, it must not use this cache      */
}

function sortKeys(o) {
  return Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b)));
}

What people do instead

Serialising the options object without sorting its keys. Two logically identical option sets hash differently depending on insertion order, the cache misses constantly, and it looks like the cache is not working rather than like the key is unstable.

What the symptom looks like

A hit rate near zero usually means an unstable key: a timestamp, an unsorted object, or something per-request that crept into the hash. A hit rate that survives a deploy means the build identifier is missing.

Frequently asked

Related operational topics

The decisions that depend on each other, then the rest of the same group.