Repository navigation
feat(cache-components): tagReadMode "on-demand" reads tag markers per entry instead of scanning per request - #32
Merged
Merged
Conversation
… entry instead of scanning per request (#31)
…ts for tagPubSub interplay and tag cardinality; bench the many-entries case
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #31.
What
New
tagReadModeoption on the'use cache'handler."scan"(default, unchanged):refreshTags()SCANs the namespace's tag markers into a local mirror once per request."on-demand":refreshTags()does nothing.get()reads the markers for the entry's own tags plus the route's soft tags with oneMGETand merges them into the mirror;getExpiration()does the same for the tags it is given. One extra round trip perget(), no per-request scan.tagPubSubworks in either mode.A failed on-demand read falls back to the local mirror (
fallback: "auto") or is a miss (fallback: "never").Also in this PR:
mergeTagStatenow keeps the stricter deadline when two invalidations carry the same millisecond stamp (a soft one from instance A and a hard one from instance B). The integration test against a real Redis hit that case on the first run.Why
Redis
SCANwalks the whole keyspace regardless of theMATCHpattern, so the per-request cost ofrefreshTags()grows with the total number of keys in the database, not with the number of tags. The singular handler andgetExpiration()already read tags on demand; the plural handler was the odd one out.Numbers
scripts/bench-tag-read.mjs(new), local Redis 7, redis@5, p50 over several runs:refreshTags()per requestget()incl. itsMGET| 20.8k | 500 |
refreshTags()+ 50 parallelget(): 17 ms | 50 parallelget(): 0.7 ms || 100.8k | 500 |
refreshTags()+ 50 parallelget(): 63 ms | 50 parallelget(): 0.8 ms |At 20k keys the scan is roughly 400 round trips (about 200
SCANcalls plus anMGETper chunk); on a networked Redis multiply by the RTT. The per-get()MGETs of one page are pipelined by redis@5 / ioredis, which is why 50 of them cost under a millisecond.QA pass after the first push
pruneOldestByTimestampon everyget()once it reached the 10k cap, which sorts the whole map each time. It now trims to 90% only when over the cap, so the sort runs about once per thousand new tags. Covered by a test that reads 12k distinct tags.tagPubSubtogether with on-demand: subscription is still established, messages still merge into the mirror, and no SCAN happens. Covered by a test.fallback: "always"skip Redis entirely (on-demand path not entered), a connection in reconnect cooldown yieldsnulland is treated as a failed read (mirror or miss depending onfallback), Redis Cluster needshashTag: trueas before so theMGETkeys share a slot, duplicate tags between an entry and its route are harmless inMGET.Tests
tests/unit/tag-read-mode.test.ts, 16 tests, two handlers on one mock Redis): no SCAN in on-demand mode; soft and hard invalidations from the other instance are seen byget()withoutrefreshTags(); route soft tags are read; oneMGETperget()covering entry and soft tags;getExpiration()answers from Redis rather than a stale mirror; failure paths forfallback: "auto"and"never"; read-your-own-writes; same-millisecond soft/hard merge.tests/integration/tag-read-mode.test.ts, redis@5 and ioredis against a real Redis 7): no SCAN, cross-instance soft invalidation, route soft tags, hard deadline enforced after it passes,getExpiration()reports the other instance's hard deadline.Docs
README (configuration block and a new "Tag reads at scale" section with the table),
docs/api.md,docs/architecture.md, the agent skill's option table, and aminorchangeset.Default stays
"scan"for this release. If on-demand holds up in deployments with many keys, the next minor can flip it.