Skip to content

perf(redis): skip refills behind observed watermarks - #143

Open
lan17 wants to merge 1 commit into
mainfrom
codex/issue-141-fenced-refills
Open

perf(redis): skip refills behind observed watermarks#143
lan17 wants to merge 1 commit into
mainfrom
codex/issue-141-fenced-refills

Conversation

@lan17

@lan17 lan17 commented Aug 29, 2026

Copy link
Copy Markdown
Owner

Closes #141

Summary

Tracked Redis misses now preserve a trustworthy numeric watermark when the existing authoritative MGET observed one. After fallback, DialCache samples one candidate timestamp before serialization:

tracked MGET -> RedisWatermarkMiss(W) -> source fallback -> candidate N
                                                       |-> N <= W: skip
                                                       `-> N > W: dump/compress/SET frame(N)

This removes serializer, compression, frame-allocation, network, Redis, replication, and AOF work for refills that are already known to remain unreadable. It adds no Redis command or round trip and changes no key, frame, or watermark encoding.

Design

Adapter boundary

  • Add RedisReadResult = DecodedRedisFrame | RedisWatermarkMiss | null.
  • Add decodeTrackedRedisReadResult for adapters that intentionally opt into typed watermark misses.
  • Preserve decodeTrackedRedisFrame and its established DecodedRedisFrame | null behavior for legacy custom adapters.
  • Add optional RedisWriteRequest.createdAtMs. Adapters returning typed misses must encode a supplied value exactly; ordinary and direct writes that omit it retain adapter-side clock sampling.
  • Node-redis and GLIDE use the same typed decoder and exact-timestamp behavior.

Core flow

  • Carry a validated typed miss through caller and detached shadow paths.
  • Skip at candidateCreatedAtMs <= observedWatermarkMs before serializer dump, compression, size observations, frame construction, TTL-clamp reporting, or adapter dispatch.
  • Pass the exact admitted candidate into the adapter so the decision and stored frame cannot diverge.
  • Preserve existing behavior for untracked, missing/malformed-watermark, future-frame, and legacy null misses.
  • Preserve tracked local-publication suppression and the existing later-invalidation race boundary.
  • Report a skipped shadow fill as fill_fenced; typed confirmation misses remain superseded.

Compatibility and safety

  • Existing custom adapters returning DecodedRedisFrame | null remain correct and keep their prior write request/timestamp behavior; they simply do not receive this optimization.
  • Structurally augmented custom frames remain hits rather than being mistaken for watermark misses.
  • RedisReadResult, optional RedisWriteRequest.createdAtMs, and fill_fenced are documented public type-surface changes. Exhaustive ShadowValidationOutcome consumers must add the new outcome.
  • Missing, malformed, out-of-range, or wrong-type watermark metadata retains the established generic behavior.
  • A watermark that advances after the authoritative read can still fence an admitted write. Avoiding that race remains intentionally out of scope.

Validation

  • corepack pnpm check — 543 unit tests, typecheck, build/declarations, and packed ESM/CJS consumer checks pass.
  • corepack pnpm test:integration — 127 tests pass across node-redis and GLIDE on Redis 6.2 and Valkey 8; the two GLIDE cluster cases skip locally because Docker Desktop cannot route announced container IPs, while CI remains fail-closed for those cases.
  • corepack pnpm benchmark:redis-write against Redis 6.2 — admitted writes remain exactly one SET each with zero Lua and zero TIME calls.
  • Focused command assertions prove known-fenced caller and shadow refills dispatch zero SETs and admitted refills add no reads.
  • git diff --check passes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Skip tracked Redis refills that remain behind the observed watermark

1 participant