@brust/cache-cloudflare 2.0.0-alpha.34 → 2.0.0-alpha.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brust/cache-cloudflare",
-  "version": "2.0.0-alpha.34",
+  "version": "2.0.0-alpha.35",
   "description": "brust cache adapters for Cloudflare Workers: KV store, Durable Object broadcast/store, and their combination",
   "license": "MIT",
   "homepage": "https://brust.dev",
@@ -27,10 +27,10 @@
     "typecheck": "bun check"
   },
   "peerDependencies": {
-    "@brust/core": "2.0.0-alpha.34"
+    "@brust/core": "2.0.0-alpha.35"
   },
   "devDependencies": {
-    "@brust/core": "2.0.0-alpha.34",
+    "@brust/core": "2.0.0-alpha.35",
     "@types/bun": "^1.4.4",
     "typescript": "^7.0.2"
   },

package/src/combine.ts

@@ -36,14 +36,14 @@ export function combine(kvIn: CacheAdapter, d: DoAdapter): CacheAdapter {
       const { result, meta } = await kv.store.getWithMeta(key)
       if (!result.page || !meta) return { page: null, stamp, entryStamp: null, storedAt: null }
       // A hit written under a stamp below its floor (or one with no stamp at all) is judged invalid.
-      if (result.entryStamp === null || result.entryStamp < floors.floorOf(meta.tags, meta.method, meta.path)) return { page: null, stamp, entryStamp: null, storedAt: null }
+      if (result.entryStamp === null || result.entryStamp < floors.floorOf(meta.tags, meta.method, meta.path, meta.prefix)) return { page: null, stamp, entryStamp: null, storedAt: null }
       return { ...result, stamp }
     },
     async set(key: string, page: StoredPage, meta: SetMeta) {
       if (!seeded) await seed()
       // `stamp: null` = an unguarded write: it is stamped with the seq known now, so floors judge it from here on.
       const stamp = meta.stamp ?? lastSeq
-      if (meta.stamp !== null && stamp < floors.floorOf(meta.tags, meta.method, meta.path)) return false
+      if (meta.stamp !== null && stamp < floors.floorOf(meta.tags, meta.method, meta.path, meta.prefix)) return false
       return kv.store.set(key, page, { ...meta, stamp })
     },
     async invalidate(args: InvalidateArgs) {

package/src/do-adapter.ts

@@ -109,8 +109,9 @@ export function doAdapter(options: DoOptions = {}, deps: DoDeps = {}): DoAdapter
         if (page.body.length > MAX_DO_BODY_BYTES) return false
         const at = now()
         const expiresAt = at + meta.ttlMs
-        const frame = encodeEntry(page, { tags: meta.tags, method: meta.method, path: meta.path, entryStamp: meta.stamp, storedAt: at, expiresAt })
-        return (await shard(shardIndex(key))).set(key, frame, { tags: meta.tags, method: meta.method, path: meta.path, expiresAt }, meta.stamp)
+        const prefix = meta.prefix ?? ''
+        const frame = encodeEntry(page, { tags: meta.tags, method: meta.method, path: meta.path, prefix, entryStamp: meta.stamp, storedAt: at, expiresAt })
+        return (await shard(shardIndex(key))).set(key, frame, { tags: meta.tags, method: meta.method, path: meta.path, prefix, expiresAt }, meta.stamp)
       },
       async invalidate(args: InvalidateArgs) {
         const head = await (await epoch()).head()

package/src/do-class.ts

@@ -3,13 +3,13 @@
 // persist (R7) so seqs never regress across a restart; the ring stays in memory and `gen` is new on every construction, so isolates clear once.
 import { DurableObject } from 'cloudflare:workers'
 import type { EpochSince, InvalidateArgs } from '@brust/core/cache-adapter'
-import { namesOf, pathName } from './floors'
+import { entryNames, namesOf, pathName } from './floors'
 import { Ring } from './ring'
 
 export const INVAL_CAP = 4096
 const SWEEP_MS = 60_000
 
-export interface PageMeta { tags: string[]; method: string; path: string; expiresAt: number }
+export interface PageMeta { tags: string[]; method: string; path: string; /** F493; absent from older callers = `''`. */ prefix?: string; expiresAt: number }
 export interface FloorsPayload { gen: string; seq: number; names: [string, number][]; evicted: number }
 
 export class BrustCacheDO extends DurableObject {
@@ -31,6 +31,10 @@ export class BrustCacheDO extends DurableObject {
       sql.exec('CREATE INDEX IF NOT EXISTS inval_seq ON inval(seq)')
       sql.exec('CREATE TABLE IF NOT EXISTS pages(key TEXT PRIMARY KEY, meta TEXT NOT NULL, body BLOB NOT NULL, mpath TEXT NOT NULL, expires_at INTEGER NOT NULL)')
       sql.exec('CREATE TABLE IF NOT EXISTS tags(tag TEXT NOT NULL, key TEXT NOT NULL, PRIMARY KEY(tag, key))')
+      // F493: the page's route-cache key prefix, for `invalidate({ prefix })`. Added in place to a table made before it.
+      if (!sql.exec<{ name: string }>('PRAGMA table_info(pages)').toArray().some((c) => c.name === 'prefix'))
+        sql.exec("ALTER TABLE pages ADD COLUMN prefix TEXT NOT NULL DEFAULT ''")
+      sql.exec('CREATE INDEX IF NOT EXISTS pages_prefix ON pages(prefix)')
       const m = (k: string) => (sql.exec<{ v: number }>('SELECT v FROM meta WHERE k = ?', k).toArray()[0]?.v ?? 0)
       this.evicted = m('evicted')
       this.invalCount = sql.exec<{ c: number }>('SELECT count(*) AS c FROM inval').one().c
@@ -107,13 +111,14 @@ export class BrustCacheDO extends DurableObject {
     const ok = this.ctx.storage.transactionSync(() => {
       if (stamp !== null) {
         if (this.evicted > stamp) return false
-        for (const n of [...meta.tags.map((t) => `t:${t}`), pathName(meta.method, meta.path)]) {
+        for (const n of entryNames(meta.tags, meta.method, meta.path, meta.prefix)) {
           const r = this.sql.exec<{ seq: number }>('SELECT seq FROM inval WHERE name = ?', n).toArray()[0]
           if (r && r.seq > stamp) return false
         }
       }
       this.dropKeys([key])
-      this.sql.exec('INSERT INTO pages(key, meta, body, mpath, expires_at) VALUES(?, ?, ?, ?, ?)', key, JSON.stringify({ tags: meta.tags, method: meta.method, path: meta.path }), frame, pathName(meta.method, meta.path), meta.expiresAt)
+      const prefix = meta.prefix ?? ''
+      this.sql.exec('INSERT INTO pages(key, meta, body, mpath, expires_at, prefix) VALUES(?, ?, ?, ?, ?, ?)', key, JSON.stringify({ tags: meta.tags, method: meta.method, path: meta.path, prefix }), frame, pathName(meta.method, meta.path), meta.expiresAt, prefix)
       for (const t of new Set(meta.tags)) this.sql.exec('INSERT OR IGNORE INTO tags(tag, key) VALUES(?, ?)', t, key)
       return true
     })
@@ -124,8 +129,21 @@ export class BrustCacheDO extends DurableObject {
     return this.ctx.storage.transactionSync(() => {
       this.bump(namesOf(args), seq)
       const keys = new Set<string>()
-      for (const t of args.tags ?? []) for (const r of this.sql.exec<{ key: string }>('SELECT key FROM tags WHERE tag = ?', t)) keys.add(r.key)
-      if (args.path !== undefined) for (const r of this.sql.exec<{ key: string }>('SELECT key FROM pages WHERE mpath = ?', pathName(args.method, args.path))) keys.add(r.key)
+      const pre = args.prefix
+      const tags = args.tags ?? []
+      if (pre === undefined) {
+        for (const t of tags) for (const r of this.sql.exec<{ key: string }>('SELECT key FROM tags WHERE tag = ?', t)) keys.add(r.key)
+        if (args.path !== undefined) for (const r of this.sql.exec<{ key: string }>('SELECT key FROM pages WHERE mpath = ?', pathName(args.method, args.path))) keys.add(r.key)
+      } else if (tags.length || args.path !== undefined) {
+        // F493: only that prefix's pages; the other prefixes' rows and tag rows stay.
+        for (const t of tags)
+          for (const r of this.sql.exec<{ key: string }>('SELECT t.key AS key FROM tags t JOIN pages p ON p.key = t.key WHERE t.tag = ? AND p.prefix = ?', t, pre)) keys.add(r.key)
+        if (args.path !== undefined)
+          for (const r of this.sql.exec<{ key: string }>('SELECT key FROM pages WHERE mpath = ? AND prefix = ?', pathName(args.method, args.path), pre)) keys.add(r.key)
+      } else if (args.method === undefined || args.method.toUpperCase() === 'GET') {
+        // `{ prefix }` alone: every (GET) page of that prefix.
+        for (const r of this.sql.exec<{ key: string }>('SELECT key FROM pages WHERE prefix = ?', pre)) keys.add(r.key)
+      }
       this.dropKeys([...keys])
       return keys.size
     })

package/src/floors.ts

@@ -1,11 +1,30 @@
-// Per-name invalidation floors (names `t:<tag>` and `p:<METHOD> <path>`): an entry written under a stamp below its floor is invalid.
+// Per-name invalidation floors (names `t:<tag>` and `p:<METHOD> <path>`; F493 adds prefix-scoped `px:<prefix>`,
+// `pt:<prefix><tag>` and `pp:<prefix><METHOD> <path>`, the prefix JSON-quoted so names of different prefixes never meet): an
+// entry written under a stamp below its floor is invalid.
 import type { InvalidateArgs } from '@brust/core/cache-adapter'
 
 export const pathName = (method: string | undefined, path: string) => `p:${method ?? 'GET'} ${path}`
+const q = (prefix: string) => JSON.stringify(prefix)
 
-/** The floor names an invalidation touches. */
+/** The floor names an invalidation touches. `{ prefix }` alone floors every page of that prefix (GET pages only are stored). */
 export function namesOf(args: InvalidateArgs): string[] {
-  return [...(args.tags ?? []).map((t) => `t:${t}`), ...(args.path !== undefined ? [pathName(args.method, args.path)] : [])]
+  const tags = args.tags ?? []
+  const pre = args.prefix
+  if (pre === undefined) return [...tags.map((t) => `t:${t}`), ...(args.path !== undefined ? [pathName(args.method, args.path)] : [])]
+  if (!tags.length && args.path === undefined) return args.method === undefined || args.method.toUpperCase() === 'GET' ? [`px:${q(pre)}`] : []
+  return [...tags.map((t) => `pt:${q(pre)}${t}`), ...(args.path !== undefined ? [`pp:${q(pre)}${pathName(args.method, args.path).slice(2)}`] : [])]
+}
+
+/** Every floor name that covers an entry (its tags, its path, and the same scoped by its prefix). */
+export function entryNames(tags: string[], method: string, path: string, prefix = ''): string[] {
+  const p = q(prefix)
+  return [
+    ...tags.map((t) => `t:${t}`),
+    pathName(method, path),
+    `px:${p}`,
+    ...tags.map((t) => `pt:${p}${t}`),
+    `pp:${p}${pathName(method, path).slice(2)}`,
+  ]
 }
 
 export interface FloorsSnapshot { names: [string, number][]; evicted: number }
@@ -33,9 +52,9 @@ export class Floors {
     for (const n of namesOf(args)) this.raise(n, seq)
   }
   /** The highest floor over an entry's names; a name never seen is only as safe as `evicted`. */
-  floorOf(tags: string[], method: string, path: string): number {
+  floorOf(tags: string[], method: string, path: string, prefix = ''): number {
     let f = this.evicted
-    for (const n of [...tags.map((t) => `t:${t}`), pathName(method, path)]) f = Math.max(f, this.m.get(n) ?? 0)
+    for (const n of entryNames(tags, method, path, prefix)) f = Math.max(f, this.m.get(n) ?? 0)
     return f
   }
 }

package/src/frame.ts

@@ -8,6 +8,8 @@ export interface EntryMeta {
   tags: string[]
   method: string
   path: string
+  /** The route-cache key prefix (F493); absent in frames written before it = `''`. */
+  prefix?: string
   entryStamp: number | null
   storedAt: number
   expiresAt: number

package/src/kv-adapter.ts

@@ -50,8 +50,9 @@ export function kvAdapter(options: KvOptions = {}, deps: KvDeps = {}): KvAdapter
       if (meta.ttlMs < minTtlS * 1000) return false
       if (page.body.length > store.maxBodyBytes) return false
       const at = now()
-      const frame = encodeEntry(page, { tags: meta.tags, method: meta.method, path: meta.path, entryStamp: meta.stamp, storedAt: at, expiresAt: at + meta.ttlMs })
-      const fp = `${fingerprint(page.body)}:${JSON.stringify([page.status, page.headers, meta.tags, meta.method, meta.path, meta.stamp])}`
+      const prefix = meta.prefix ?? ''
+      const frame = encodeEntry(page, { tags: meta.tags, method: meta.method, path: meta.path, prefix, entryStamp: meta.stamp, storedAt: at, expiresAt: at + meta.ttlMs })
+      const fp = `${fingerprint(page.body)}:${JSON.stringify([page.status, page.headers, meta.tags, meta.method, meta.path, prefix, meta.stamp])}`
       const prev = memo.get(key)
       if (prev && prev.fp === fp && at - prev.at < 60_000) return true
       try {
@@ -66,7 +67,8 @@ export function kvAdapter(options: KvOptions = {}, deps: KvDeps = {}): KvAdapter
       return true
     },
     async invalidate(_args: InvalidateArgs) {
-      // R5: an L2Key hashes prefix+method+path+query, so a tag or path cannot be enumerated without index writes; KV alone is "stale <= ttl".
+      // R5: an L2Key hashes prefix+method+path+query, so a tag, path or prefix cannot be enumerated without index writes; KV alone is
+      // "stale <= ttl". Paired with the DO broadcast (combine), the floors judge each hit by its stored prefix too (F493): no index.
     },
   }
   return { name: 'cloudflare-kv', runtimes: ['workers'], store }