Skip to content

Commit bcb8477

Browse files
committed
harden(cache): fold post-reconcile review findings into CFCacheStore
Adversarial review of the #534<->#558 reconcile surfaced ten findings; this folds the worthwhile ones in before the single CI run (cheaper than a second follow-up round). Read-your-own-writes / correctness: - fetchTagMarker no longer clobbers a concurrent invalidateTags() memo write that lands mid-read, so a parallel-slot updateTag() stays read-your-own-writes. - Per-store isolation of the tag-marker memo/inflight maps: two stores in one request (app store + a cache({ store }) override on a different KV binding) can no longer cross-pollute marker values. - kvGetOrEvict guards a KV body that parses to null/a primitive BEFORE validate(), so 'null'/'42' are evicted as corrupt instead of throwing past the validator into a transient cache-read that never self-heals. - Non-array tags fail safe (Array.isArray at the write guards and the central isGloballyInvalidated check) instead of throwing .map on every read. Fail-safe reads/writes (no perf degradation): - Corrupt-entry KV eviction is dispatched via waitUntil, never awaited on the read path (an unbounded kv.delete would re-add exactly the stall the read budgets exist to prevent). - The transient L1 tag-marker match error is reported as cache-read like the data read paths, instead of being silently discarded at the destructuring. - The L1 marker write-through failure on invalidate is surfaced (cache-invalidate) and the stale marker evicted, instead of swallowed while updateTag reports success. DX / hygiene: - tagInvalidationTtl below KV's 60s expirationTtl floor is raised (with a one-time warning) so a too-small value no longer makes EVERY invalidation throw; a non-finite tagCacheTtl is coerced to 0 (disabled) rather than silently enabling an invalid max-age=Infinity marker. - Remove the now-dead parseOrEvict (replaced during the reconcile by readJsonWithTimeout/healCorruptL1 + kvGetOrEvict). Observability + API completeness (review below-the-cut items): - New `markerMs` debug field: the tagged-read marker-resolution tail (memo -> L1 marker cache -> KV) is no longer invisible in CFCacheReadDebugEvent (measured only under debug). New `match-error` debug outcome so a match() rejection is distinct from a genuine l1-miss and agrees with the cache-read on onError. - Export CacheItemOptions / CacheItemResult from ./cache so a custom SegmentCacheStore author can name every type its getItem/setItem methods use. Docs/comments corrected: caching skill corrupt-entry self-heal table (serves from L2, evicts only when no L2 copy), healCorruptL1 cross-request timeout note, the tag-invalidated tier-divergence comment, and a tagCacheTtl same-colo race caveat. Tests: +15 (11 proven red-before-green); strengthened the corrupt-L1 heal-by-overwrite and fail-open assertions to be non-vacuous; the fail-open mock keys on the exported TAG_MARKER_PREFIX so a prefix rename can't make it pass vacuously; added real-timer teardown to both CF suites. Unit 3562 green; cache-tag e2e green dev+production against the real CFCacheStore.
1 parent a7b3c53 commit bcb8477

5 files changed

Lines changed: 762 additions & 110 deletions

File tree

‎packages/rangojs-router/skills/caching/SKILL.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -316,12 +316,13 @@ new CFCacheStore({
316316

317317
Failure handling, by kind — none of these fail the request:
318318

319-
| Failure | Behavior |
320-
| ------------------------------- | -------------------------------------------------- |
321-
| Transient read error (5xx/blip) | Degrade to the next tier; entry left intact |
322-
| Read budget exceeded (timeout) | Abandon the read, degrade to the next tier |
323-
| Corrupt / unparseable entry | Evict it (self-heal) + re-render; reported corrupt |
324-
| Write failure | No-op (entry simply not cached); never throws |
319+
| Failure | Behavior |
320+
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
321+
| Transient read error (5xx/blip) | Degrade to the next tier; entry left intact |
322+
| Read budget exceeded (timeout) | Abandon the read, degrade to the next tier |
323+
| Corrupt / unparseable L1 entry | Reported corrupt; degrade to L2 (served if present). The L1 entry is evicted ONLY when L2 has no copy — so the evict can't race the L2→L1 promote |
324+
| Corrupt / unparseable KV entry | Reported corrupt; evicted (self-heal) + render (no tier below it) |
325+
| Write failure | No-op (entry simply not cached); never throws |
325326

326327
Each is surfaced to the router's `onError` callback (phase `"cache"`, with
327328
`metadata.category` one of `cache-read`, `cache-corrupt`, `cache-write`,

0 commit comments

Comments
 (0)