[PR #552] [MERGED] feat: implement revalidateByPathPrefix on KVCacheHandler #667

New issue

Closed

opened 2026-05-06 13:09:26 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 13:09:26 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/552
Author: @NathanDrake2406
Created: 3/15/2026
Status: ✅ Merged
Merged: 3/16/2026
Merged by: @james-elicx

Base: main ← Head: feat/kv-revalidate-by-path-prefix

📝 Commits (3)

2fc3435 feat: implement revalidateByPathPrefix on KVCacheHandler
c21d258 fix: guard against KV metadata 1024-byte limit
d381ef0 test: add regression test for KV metadata 1024-byte overflow

📊 Changes

2 files changed (+246 additions, -5 deletions)

View changed files

📝 packages/vinext/src/cloudflare/kv-cache-handler.ts (+73 -1)
📝 tests/kv-cache-handler.test.ts (+173 -4)

📄 Description

Summary

Follow-up to #544 — implements revalidateByPathPrefix on KVCacheHandler so revalidatePath('/dashboard', 'layout') works on Cloudflare Workers production (not just the dev-mode MemoryCacheHandler).

Depends on #544 — this PR adds the KV implementation; #544 adds the CacheHandler interface method and the revalidatePath() dispatch logic that calls it.

Key design choice: Uses KV list metadata instead of fetching every entry's JSON body.

set() now stores tags in KV metadata (kv.put(key, value, { metadata: { tags } }))
revalidateByPathPrefix() calls kv.list() which returns metadata inline with each key — zero extra kv.get() calls
Makes prefix invalidation O(list_pages) instead of O(entries × get)
Guards against Cloudflare KV's 1024-byte metadata limit — if tags exceed the budget, metadata is omitted and the entry degrades gracefully (prefix invalidation skips it, exact-path invalidation still works)
Entries written before metadata support are gracefully skipped
Segment-aware matching via isPathChildOf() — /dashboard does NOT match /dashboard-admin

Test plan

Invalidates entries whose paths match the prefix
Segment-aware: /dashboard does not match /dashboard-admin
Root / prefix invalidates all path-tagged entries
Skips entries with only non-path custom tags
Gracefully skips legacy entries without metadata
Metadata overflow: entry still cached, exact invalidation works, prefix invalidation skips
Mock KV updated with metadata support on put/list
All 52 KV cache handler tests pass
Typecheck and lint clean

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/cloudflare/vinext/pull/552 **Author:** [@NathanDrake2406](https://github.com/NathanDrake2406) **Created:** 3/15/2026 **Status:** ✅ Merged **Merged:** 3/16/2026 **Merged by:** [@james-elicx](https://github.com/james-elicx) **Base:** `main` ← **Head:** `feat/kv-revalidate-by-path-prefix` --- ### 📝 Commits (3) - [`2fc3435`](https://github.com/cloudflare/vinext/commit/2fc34354d30a717aab2d37b4978b3f9df55ee45f) feat: implement revalidateByPathPrefix on KVCacheHandler - [`c21d258`](https://github.com/cloudflare/vinext/commit/c21d2583101a75adec8b83dd0d73a18d1f8335ba) fix: guard against KV metadata 1024-byte limit - [`d381ef0`](https://github.com/cloudflare/vinext/commit/d381ef05d35c48519893a1a8eab83205a22eb0d8) test: add regression test for KV metadata 1024-byte overflow ### 📊 Changes **2 files changed** (+246 additions, -5 deletions) <details> <summary>View changed files</summary> 📝 `packages/vinext/src/cloudflare/kv-cache-handler.ts` (+73 -1) 📝 `tests/kv-cache-handler.test.ts` (+173 -4) </details> ### 📄 Description ## Summary Follow-up to #544 — implements `revalidateByPathPrefix` on `KVCacheHandler` so `revalidatePath('/dashboard', 'layout')` works on Cloudflare Workers production (not just the dev-mode `MemoryCacheHandler`). > **Depends on #544** — this PR adds the KV implementation; #544 adds the `CacheHandler` interface method and the `revalidatePath()` dispatch logic that calls it. **Key design choice:** Uses KV list metadata instead of fetching every entry's JSON body. - `set()` now stores tags in KV metadata (`kv.put(key, value, { metadata: { tags } })`) - `revalidateByPathPrefix()` calls `kv.list()` which returns metadata inline with each key — zero extra `kv.get()` calls - Makes prefix invalidation **O(list_pages)** instead of O(entries × get) - Guards against Cloudflare KV's 1024-byte metadata limit — if tags exceed the budget, metadata is omitted and the entry degrades gracefully (prefix invalidation skips it, exact-path invalidation still works) - Entries written before metadata support are gracefully skipped - Segment-aware matching via `isPathChildOf()` — `/dashboard` does NOT match `/dashboard-admin` ## Test plan - [x] Invalidates entries whose paths match the prefix - [x] Segment-aware: `/dashboard` does not match `/dashboard-admin` - [x] Root `/` prefix invalidates all path-tagged entries - [x] Skips entries with only non-path custom tags - [x] Gracefully skips legacy entries without metadata - [x] Metadata overflow: entry still cached, exact invalidation works, prefix invalidation skips - [x] Mock KV updated with metadata support on put/list - [x] All 52 KV cache handler tests pass - [x] Typecheck and lint clean --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>