Expand description
On-disk cache of a server’s cassette surface.
§Why a cache is not optional here
The generated nouns are the cassette listing, so they have to be present
for --help — which means the surface is needed on essentially
every invocation, including the ones that never make a request. Discovering
it costs one call to /v1/cassettes plus one per cassette; paying that to
print a help screen would make a CLI feel broken on a slow link and unusable
on a plane.
So the surface is cached per server and revalidated on a timer. Inside
CacheConfig::revalidate_after nothing touches the network at all. After
it, discovery is re-fetched and each spec is revalidated with
If-None-Match — the route answers a match with a 304 and no body, which is
what the ETag is there for. A cassette whose document has not changed
costs one conditional request and no parsing.
The cache is keyed by base URL, because two servers have two different cassette sets and a shared cache would offer one server’s nouns for the other’s data.
§The consumer names the cache
Extracted from tapesctl, whose cache lives at <cache>/tapesctl/cassettes
and is overridden by TAPESCTL_CACHE_DIR. Both names — and the
revalidation window and the key — are the consumer’s, carried in
CacheConfig, so the on-disk paths, environment contract, and file
format of an existing install do not move when the machinery does.
§Failure is always survivable
Nothing in this module returns an error. An unreadable cache is a cache miss, an unwritable one is a lost optimization, and an unreachable server falls back to whatever is on disk regardless of age — a stale surface is far more useful than none when the network is the thing that is broken. Only when there is neither a server nor a cache does the CLI go without cassette nouns, and even then a consumer’s hand-written surface is untouched.
Structs§
- Cache
Config - How one consumer’s cache is named, keyed, and aged.
- Cached
- A server’s cached surface.
- Cached
Spec - One cassette’s cached document and the validator to revalidate it with.