Holds validated artifacts in ETS so serving them never touches disk.

Documentation JSON is read constantly and written rarely. Reading and decoding a file per request wastes work on every one of them, so the cache loads the whole artifact directory once at startup and answers from memory afterwards.

Add it to the host's supervision tree:

children = [
  {DocShell.Web.Cache, dir: "priv/doc_shell/public"}
]

fetch/2 reads an immutable generation in ETS directly from the calling process, so lookups never queue behind the GenServer. The process exists to own the table and serialize reloads, not to serve reads.

Disposable by design

The cache is derived state. The JSON files are the source of truth, so crashing, restarting, or reloading cannot lose anything durable — which is why init/1 can afford to fail hard. A directory of artifacts that will not load is a deployment error, and starting anyway with a half-populated table would turn it into a scattering of 404s that look like missing documentation.

reload/1 re-reads the directory after a rebuild. It is all-or-nothing: the manifest and every listed artifact must carry the same generation_id. The replacement generation is filled before one ETS pointer is switched, so readers see the complete old or complete new snapshot, never an empty or mixed table. DocShell.Artifact writes each file atomically for the same reason.

Multiple caches

The registered :name doubles as the ETS table name, so several caches can coexist over different directories:

{DocShell.Web.Cache, name: :docs_internal, dir: "priv/doc_shell/private"}

Pass that name to fetch/2, or to DocShell.Web.Plug as :cache.

This module does not require Plug and is useful on its own to any host that wants artifacts in memory.