← All templates

Read-through cache, explicit invalidation, no stale reads after writes.

Spec — Caching with invalidation

Status: draft · Created: 2026-11-10

1. Context and goal

Hot reads come from a cache to cut latency and database load, without anyone seeing old data after a change.

2. Functional requirements (EARS)

  • FR-1: WHEN a cached entity is read and missing from the cache, THE SYSTEM SHALL load it from the database, store it with a TTL of 10 minutes and return it.
  • FR-2: WHEN many requests miss the same key at once, THE SYSTEM SHALL let only one of them load it from the database while the others wait up to 1 second for that value.
  • FR-3: WHEN an entity is written, THE SYSTEM SHALL delete its cache keys after the transaction commits and before answering the write, so the writer's next read sees the new value.
  • FR-4: THE SYSTEM SHALL store a version with each entry, so a load that started before a write can never store the older value after the invalidation.
  • FR-5: IF the cache is unreachable, THEN THE SYSTEM SHALL time out cache calls after 50 ms, read from the database and answer normally.
  • FR-6: THE SYSTEM SHALL report the hit rate, latency and evictions per key prefix, and alert when the hit rate stays below 80% for 10 minutes.

3. Out of scope

  • Caching whole HTTP responses at a CDN.
  • Warming the cache before traffic arrives.