Skip to content

feat(cache-components): tagReadMode "on-demand" reads tag markers per entry instead of scanning per request - #32

Merged
leejpsd merged 2 commits into
mainfrom
feat/tag-read-mode
Nov 19, 2026
Merged

leejpsd merged 2 commits into
mainfrom
feat/tag-read-mode

Conversation

@leejpsd

@leejpsd leejpsd commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

Fixes #31.

What

New tagReadMode option 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 one MGET and merges them into the mirror; getExpiration() does the same for the tags it is given. One extra round trip per get(), no per-request scan. tagPubSub works 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: mergeTagState now 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 SCAN walks the whole keyspace regardless of the MATCH pattern, so the per-request cost of refreshTags() grows with the total number of keys in the database, not with the number of tags. The singular handler and getExpiration() 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:

keys in Redis tag markers scan: refreshTags() per request on-demand: get() incl. its MGET
2.5k 500 3–4 ms 0.1 ms
20.5k 500 17–35 ms 0.1 ms
100k 500 65–166 ms 0.1 ms

| 20.8k | 500 | refreshTags() + 50 parallel get(): 17 ms | 50 parallel get(): 0.7 ms |
| 100.8k | 500 | refreshTags() + 50 parallel get(): 63 ms | 50 parallel get(): 0.8 ms |

At 20k keys the scan is roughly 400 round trips (about 200 SCAN calls plus an MGET per 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

  • The on-demand mirror was pruned with pruneOldestByTimestamp on every get() 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.
  • tagPubSub together with on-demand: subscription is still established, messages still merge into the mirror, and no SCAN happens. Covered by a test.
  • Walked the remaining paths: build phase and fallback: "always" skip Redis entirely (on-demand path not entered), a connection in reconnect cooldown yields null and is treated as a failed read (mirror or miss depending on fallback), Redis Cluster needs hashTag: true as before so the MGET keys share a slot, duplicate tags between an entry and its route are harmless in MGET.

Tests

  • Unit (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 by get() without refreshTags(); route soft tags are read; one MGET per get() covering entry and soft tags; getExpiration() answers from Redis rather than a stale mirror; failure paths for fallback: "auto" and "never"; read-your-own-writes; same-millisecond soft/hard merge.
  • Integration (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.
  • Full runs: 212 unit, 35 integration (redis@5 and ioredis against a real Redis 7).

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 a minor changeset.

Default stays "scan" for this release. If on-demand holds up in deployments with many keys, the next minor can flip it.

…ts for tagPubSub interplay and tag cardinality; bench the many-entries case
@leejpsd
leejpsd merged commit 247f38f into main Nov 19, 2026
5 checks passed
@leejpsd
leejpsd deleted the feat/tag-read-mode branch November 19, 2026 03:59
@github-actions github-actions Bot mentioned this pull request Nov 19, 2026
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.

Consider reducing the amount of time spent on scan operations

1 participant