A cache is part of the evidence chain. It reduces unnecessary requests and supports outage recovery, but it can also disguise stale data. Every cache hit must say what was stored, when it was captured, why it is still acceptable, and which parser/configuration produced the normalized form.
Use content-addressed raw storage: hash response bytes and store them immutably. Maintain a small index from request fingerprint to the latest raw hash and capture metadata. The fingerprint includes source adapter version, canonical path, sorted public query parameters, and response-relevant headers—never secrets. Normalized cache keys additionally include parser schema version.
Define freshness by task. A historical backtest fixture may be immutable. A dashboard snapshot might have a 15-minute maximum age. A resolution label might be rechecked until final. Store captured_at, expires_at, and freshness_policy_id; do not infer freshness from file modification time.
Apply stale-if-error carefully. A report may display the last valid snapshot during an outage only when it is visibly marked stale with age and failure time. Research evaluation requiring a current observation must abstain. Never update the cached timestamp when serving old content.
For rate limits, prefer documented limits, conditional requests when supported, one shared token bucket per host, and bounded concurrency. Record 429 responses and Retry-After. The scheduler should delay work rather than start a retry storm. Random jitter prevents multiple workers from waking simultaneously.
Version migrations must not rewrite raw files. When parser v2 arrives, read the same raw hash and write a new normalized artifact with its own hash. A comparison report should show changed fields and validation decisions before v2 becomes default.
Cache metrics should distinguish request avoidance from correctness: hit rate, fresh-hit rate, stale-display count, stale-abstention count, bytes saved, and validation failures by parser version. A high hit rate with old data is not success. Add a garbage-collection dry run that lists candidates and referenced manifests; delete nothing until the retention policy proves no sealed run depends on the object.
🇵🇰 Pakistan Angle
Caching saves mobile data and makes labs possible during connectivity interruptions. That benefit does not justify presenting an old quote as current. Display “captured at” in UTC and Pakistan time, plus exact age. Keep caches free of personal or account data; this course needs only public records.
Hands-On Exercise
Implement cache miss, fresh hit, stale hit, and stale-on-error paths. Freeze time in tests. Confirm a stale analytical request returns ABSTAIN, while a dashboard request returns the old snapshot with a prominent warning. Reparse one raw hash under schema v1 and v2 and produce a field-level diff.
Completion Rubric
- Raw cache objects are content-addressed and immutable.
- Freshness policy and capture/expiry times are stored explicitly.
- Stale display never changes the original timestamp.
- Host-level rate limits and retry jitter are enforced.
- Parser upgrades create new artifacts and diffs.
Sources
Key takeaway: A smart cache saves requests while making age, provenance, and parser version impossible to miss.