@brust/core 2.0.0-alpha.2 → 2.0.0-alpha.3

package/src/cache-adapter/conformance.ts

@@ -0,0 +1,226 @@
+// `@brust/core/cache-adapter/conformance`: the cases every cache adapter must pass (spec §9),
+// registered with bun:test. Built-ins (lanes B/C) and custom adapters run the same suite:
+//
+//   import { runConformance } from '@brust/core/cache-adapter/conformance'
+//   runConformance(() => myAdapter(opts), { push: true, guard: true })
+//
+// Each case builds a fresh adapter with `make()` and closes it afterwards. Keys are unique per case.
+import { afterEach, describe, expect, test } from 'bun:test'
+import type { CacheAdapter, InvalidationEvent, SetMeta, StoredPage } from './types'
+
+export interface ConformanceCaps {
+  /** The broadcast is push (`subscribe`). */
+  push?: boolean
+  /** The broadcast is pull (`since`). */
+  pull?: boolean
+  /** The store refuses stale writes exactly (Redis Lua, DO, memory). */
+  guard?: boolean
+  /** The store invalidates (default true); `false` skips the tag/path invalidation cases (Cloudflare KV alone never invalidates). */
+  invalidate?: boolean
+}
+
+const enc = new TextEncoder()
+const page = (body: string | Uint8Array, headers: [string, string][] = [['content-type', 'text/html']]): StoredPage => ({
+  status: 200,
+  headers,
+  body: typeof body === 'string' ? enc.encode(body) : body,
+})
+const meta = (o: Partial<SetMeta> = {}): SetMeta => ({ ttlMs: 60_000, tags: [], method: 'GET', path: '/', stamp: null, ...o })
+
+async function until(what: string, f: () => boolean | Promise<boolean>, ms = 2000): Promise<void> {
+  const t0 = Date.now()
+  while (!(await f())) {
+    if (Date.now() - t0 > ms) throw new Error(`timed out: ${what}`)
+    await new Promise(r => setTimeout(r, 10))
+  }
+}
+
+export function runConformance(make: () => CacheAdapter | Promise<CacheAdapter>, caps: ConformanceCaps = {}): void {
+  let open: CacheAdapter[] = []
+  let n = 0
+  const key = () => `conf:${Date.now().toString(36)}:${n++}`
+  const fresh = async () => {
+    const a = await make()
+    await a.init?.({ namespace: 'conformance', buildId: 'b0', runtime: 'bun', workerId: 0 })
+    open.push(a)
+    return a
+  }
+  const store = async () => {
+    const a = await fresh()
+    if (!a.store) throw new Error(`adapter ${a.name} has no store`)
+    return { a, s: a.store }
+  }
+  afterEach(async () => {
+    const all = open
+    open = []
+    await Promise.allSettled(all.map(a => a.close?.()))
+  })
+
+  describe('cache adapter conformance', () => {
+    test('get of an absent key is a miss', async () => {
+      const { s } = await store()
+      const r = await s.get(key())
+      expect(r.page).toBeNull()
+      expect(r.entryStamp).toBeNull()
+    })
+
+    test('set then get round-trips status, headers (order + repeats) and body', async () => {
+      const { s } = await store()
+      const k = key()
+      const headers: [string, string][] = [
+        ['content-type', 'text/html; charset=utf-8'],
+        ['x-a', '1'],
+        ['x-a', '2'],
+        ['cache-control', 'no-store'],
+      ]
+      expect(await s.set(k, { status: 203, headers, body: enc.encode('<p>hi</p>') }, meta())).toBe(true)
+      const r = await s.get(k)
+      expect(r.page?.status).toBe(203)
+      expect(r.page?.headers).toEqual(headers)
+      expect(new TextDecoder().decode(r.page!.body)).toBe('<p>hi</p>')
+      expect(typeof r.storedAt === 'number' || r.storedAt === null).toBe(true)
+    })
+
+    test('bodies are binary-safe (all 256 byte values)', async () => {
+      const { s } = await store()
+      const k = key()
+      const body = Uint8Array.from({ length: 512 }, (_, i) => i % 256)
+      expect(await s.set(k, page(body), meta())).toBe(true)
+      expect(Array.from((await s.get(k)).page!.body)).toEqual(Array.from(body))
+    })
+
+    test('entryStamp round-trips the set stamp', async () => {
+      const { a, s } = await store()
+      const k = key()
+      const g = await s.get(k)
+      if (a.broadcast) expect(typeof g.stamp).toBe('number')
+      expect(await s.set(k, page('x'), meta({ stamp: g.stamp }))).toBe(true)
+      expect((await s.get(k)).entryStamp).toBe(g.stamp)
+    })
+
+    test('entries expire after ttlMs', async () => {
+      const { s } = await store()
+      const k = key()
+      expect(await s.set(k, page('x'), meta({ ttlMs: 1 }))).toBe(true)
+      await until('expiry', async () => (await s.get(k)).page === null)
+    })
+
+    if (caps.invalidate !== false) test('tag invalidation drops tagged pages and keeps unrelated ones', async () => {
+      const { s } = await store()
+      const [k1, k2, k3] = [key(), key(), key()]
+      await s.set(k1, page('1'), meta({ tags: ['items'], path: '/a' }))
+      await s.set(k2, page('2'), meta({ tags: ['other', 'items'], path: '/b' }))
+      await s.set(k3, page('3'), meta({ tags: ['other'], path: '/c' }))
+      await s.invalidate({ tags: ['items'] })
+      expect((await s.get(k1)).page).toBeNull()
+      expect((await s.get(k2)).page).toBeNull()
+      expect((await s.get(k3)).page).not.toBeNull()
+    })
+
+    if (caps.invalidate !== false) test('path + method invalidation drops that page only', async () => {
+      const { s } = await store()
+      const [k1, k2] = [key(), key()]
+      await s.set(k1, page('1'), meta({ path: '/x' }))
+      await s.set(k2, page('2'), meta({ path: '/y' }))
+      await s.invalidate({ path: '/x', method: 'POST' })
+      expect((await s.get(k1)).page).not.toBeNull()
+      await s.invalidate({ path: '/x' })
+      expect((await s.get(k1)).page).toBeNull()
+      expect((await s.get(k2)).page).not.toBeNull()
+    })
+
+    test('key invalidation is a store no-op', async () => {
+      const { s } = await store()
+      const k = key()
+      await s.set(k, page('1'), meta({ tags: ['t'] }))
+      await s.invalidate({ key: 'job-key' })
+      expect((await s.get(k)).page).not.toBeNull()
+    })
+
+    test('a body over maxBodyBytes is refused', async () => {
+      const { s } = await store()
+      const k = key()
+      expect(await s.set(k, page(new Uint8Array(s.maxBodyBytes + 1)), meta())).toBe(false)
+      expect((await s.get(k)).page).toBeNull()
+    })
+
+    if (caps.guard) {
+      test('a set whose stamp predates an invalidation of its tag is refused', async () => {
+        const { a, s } = await store()
+        const k = key()
+        const g = await s.get(k)
+        await s.invalidate({ tags: ['items'] })
+        await a.broadcast?.publish({ tags: ['items'] }, 'conf')
+        expect(await s.set(k, page('stale'), meta({ tags: ['items'], stamp: g.stamp }))).toBe(false)
+        expect((await s.get(k)).page).toBeNull()
+        const g2 = await s.get(k)
+        expect(await s.set(k, page('fresh'), meta({ tags: ['items'], stamp: g2.stamp }))).toBe(true)
+      })
+
+      test('L7b: a stale set racing invalidate (before its publish) never lands', async () => {
+        const { s } = await store()
+        const k = key()
+        const g = await s.get(k)
+        await s.invalidate({ tags: ['items'], path: '/p' })
+        expect(await s.set(k, page('stale'), meta({ tags: ['items'], stamp: g.stamp }))).toBe(false)
+        expect(await s.set(k, page('stale'), meta({ path: '/p', stamp: g.stamp }))).toBe(false)
+        expect((await s.get(k)).page).toBeNull()
+      })
+    }
+
+    test('publish seqs strictly increase; get().stamp is the last seq (one space)', async () => {
+      const a = await fresh()
+      if (!a.broadcast) return
+      const s1 = await a.broadcast.publish({ tags: ['a'] }, 'conf')
+      const s2 = await a.broadcast.publish({ path: '/b' }, 'conf')
+      expect(s2).toBeGreaterThan(s1)
+      if (a.store) expect((await a.store.get(key())).stamp).toBe(s2)
+    })
+
+    if (caps.push) {
+      test('push: in-order delivery with origin and args; unsubscribe stops it', async () => {
+        const a = await fresh()
+        const got: InvalidationEvent[] = []
+        const stop = await a.broadcast!.subscribe!(e => got.push(e), () => {})
+        const s1 = await a.broadcast!.publish({ tags: ['a'] }, 'o1')
+        const s2 = await a.broadcast!.publish({ path: '/b', method: 'GET' }, 'o2')
+        await until('delivery', () => got.length === 2)
+        expect(got).toEqual([
+          { seq: s1, origin: 'o1', args: { tags: ['a'] } },
+          { seq: s2, origin: 'o2', args: { path: '/b', method: 'GET' } },
+        ])
+        await stop()
+        await a.broadcast!.publish({ tags: ['c'] }, 'o1')
+        await new Promise(r => setTimeout(r, 50))
+        expect(got.length).toBe(2)
+      })
+    }
+
+    if (caps.pull) {
+      test('pull: since(0) after three publishes is contiguous', async () => {
+        const a = await fresh()
+        const b = a.broadcast!
+        const before = await b.since!(0)
+        const base = before.seq
+        for (const t of ['a', 'b', 'c']) await b.publish({ tags: [t] }, 'o')
+        const r = await b.since!(base)
+        expect(r.behind).toBe(false)
+        expect(r.seq).toBe(base + 3)
+        expect(r.events.map(e => e.seq)).toEqual([base + 1, base + 2, base + 3])
+        expect(r.events.map(e => e.args.tags?.[0])).toEqual(['a', 'b', 'c'])
+        expect(r.events[0]!.origin).toBe('o')
+        expect((await b.since!(r.seq)).events).toEqual([])
+        expect(typeof r.gen).toBe('string')
+      })
+
+      test('pull: a reader past the retained history is behind', async () => {
+        const a = await fresh()
+        const b = a.broadcast!
+        const base = (await b.since!(0)).seq
+        // 1025 events is beyond the spec's 1024-event ring.
+        for (let i = 0; i < 1025; i++) await b.publish({ tags: [`t${i}`] }, 'o')
+        expect((await b.since!(base)).behind).toBe(true)
+      })
+    }
+  })
+}

package/src/cache-adapter/index.ts

@@ -0,0 +1,10 @@
+// `@brust/core/cache-adapter`: the contract, the in-memory adapter and `defineCacheAdapter`.
+// No `bun`/`bun:*` import here (the Cloudflare bundle imports it); the conformance suite is its own
+// subpath, `@brust/core/cache-adapter/conformance`.
+import type { CacheAdapter, CacheAdapterFactory } from './types'
+
+export type * from './types'
+export { type MemoryAdapter, type MemoryAdapterOptions, type MemoryAdapterTest, memoryAdapter } from './memory'
+
+/** Identity, for type inference: `export default defineCacheAdapter((opts) => ({ … }))`. */
+export const defineCacheAdapter = <T extends CacheAdapter | CacheAdapterFactory>(a: T): T => a

package/src/cache-adapter/load.ts

@@ -0,0 +1,144 @@
+// Resolving and validating the configured adapter (cache-adapter R1, R8, R14). The build checks
+// that a built-in package is installed; this runs where the adapter lives (each Bun worker, or the
+// Workers isolate's `install`). No `bun` import: resolution is the caller's (`resolve`).
+import type { CacheAdapter, CacheAdapterFactory } from './types'
+
+/** What `brust build` writes to `manifest.cache` / `CONFIG.cache`. */
+export interface CacheManifest {
+  adapter: string
+  /** `custom`: the bundled module, relative to dist (native) — Workers import it in the entry. */
+  module?: string
+  /** A built-in broadcast composed onto the adapter (`broadcast = "cloudflare-do"`). */
+  broadcast?: string
+  options: Record<string, unknown>
+  /** Options of the composed broadcast's factory. */
+  broadcastOptions?: Record<string, unknown>
+  namespace: string
+  getTimeoutMs: number
+  maxBodyBytes: number
+  epochIntervalMs: number
+  buildId: string
+}
+
+/** The built-in adapters: each package subpath's default export is a factory (the lanes B/C contract). */
+export const BUILTINS: Readonly<Record<string, string>> = {
+  redis: '@brust/cache-redis',
+  dragonfly: '@brust/cache-redis/dragonfly',
+  'cloudflare-kv': '@brust/cache-cloudflare/kv',
+  'cloudflare-do': '@brust/cache-cloudflare/do',
+}
+
+export const ADAPTER_NAMES = ['redis', 'dragonfly', 'cloudflare-kv', 'cloudflare-do', 'custom'] as const
+
+/** A built-in name's install hint (the build's error). */
+export function installHint(name: string): string {
+  const spec = BUILTINS[name] ?? name
+  const pkg = spec.split('/').slice(0, 2).join('/')
+  return `adapter "${name}" needs ${pkg} (bun add ${pkg})`
+}
+
+/** `env:NAME` strings of a built-in's option table → `env[NAME]` (missing → a boot error naming NAME only). */
+export function resolveEnvOptions(o: Record<string, unknown>, env: Record<string, string | undefined>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(o)) {
+    if (typeof v === 'string' && v.startsWith('env:')) {
+      const name = v.slice(4)
+      const val = env[name]
+      if (val === undefined || val === '') throw new Error(`cache adapter option ${k}: environment variable ${name} is not set`)
+      out[k] = val
+    } else out[k] = v
+  }
+  return out
+}
+
+/** A module's default export → the adapter (a factory is called with `options`). */
+export function instantiate(mod: unknown, options: Record<string, unknown>, what: string): CacheAdapter {
+  const d = (mod as { default?: unknown } | null)?.default ?? mod
+  const a = typeof d === 'function' ? (d as CacheAdapterFactory)(options) : d
+  return validateAdapter(a, what)
+}
+
+const fn = (o: unknown, k: string) => typeof (o as Record<string, unknown> | undefined)?.[k] === 'function'
+
+/** The shape check (TypeError naming what is wrong). */
+export function validateAdapter(a: unknown, what: string): CacheAdapter {
+  const bad = (m: string): never => {
+    throw new TypeError(`cache adapter ${what}: ${m}`)
+  }
+  if (!a || typeof a !== 'object') bad('the default export is not an adapter or a factory returning one')
+  const x = a as CacheAdapter
+  if (typeof x.name !== 'string' || !x.name) bad('no name')
+  if (!Array.isArray(x.runtimes) || x.runtimes.some(r => r !== 'bun' && r !== 'workers')) bad('runtimes must list "bun" and/or "workers"')
+  if (x.store && !(fn(x.store, 'get') && fn(x.store, 'set') && fn(x.store, 'invalidate') && typeof x.store.maxBodyBytes === 'number'))
+    bad('store needs get, set, invalidate and maxBodyBytes')
+  if (x.broadcast) {
+    if (!fn(x.broadcast, 'publish')) bad('broadcast needs publish')
+    const push = fn(x.broadcast, 'subscribe')
+    const pull = fn(x.broadcast, 'since')
+    if (push === pull) bad('broadcast needs exactly one of subscribe (push) or since (pull)')
+  }
+  if (!x.store && !x.broadcast) bad('neither a store nor a broadcast')
+  return x
+}
+
+/** R1 (native) / R14 (Workers): the runtime and the broadcast mode must fit where it runs. */
+export function checkRuntime(a: CacheAdapter, runtime: 'bun' | 'workers'): void {
+  if (!a.runtimes.includes(runtime))
+    throw new TypeError(`cache adapter "${a.name}" does not run on ${runtime === 'bun' ? 'Bun' : 'Cloudflare Workers'} (runtimes: ${a.runtimes.join(', ')})`)
+  if (!a.broadcast) return
+  const push = typeof a.broadcast.subscribe === 'function'
+  if (runtime === 'bun' && !push) throw new TypeError(`cache adapter "${a.name}": native needs a push broadcast (subscribe); pull (since) is Workers-only in v1`)
+  if (runtime === 'workers' && push) throw new TypeError(`cache adapter "${a.name}": push-only broadcast (subscribe) cannot run on Workers; it needs since (pull)`)
+}
+
+/**
+ * The configured adapter. `load(spec, builtin)` imports a module (the caller resolves it: a custom
+ * `module` relative to dist natively, a built-in package from the app root). `env` resolves
+ * built-in `env:` options.
+ */
+export async function loadAdapter(
+  m: CacheManifest,
+  runtime: 'bun' | 'workers',
+  load: (spec: string, builtin: boolean) => Promise<unknown>,
+  env: Record<string, string | undefined>,
+): Promise<CacheAdapter> {
+  let adapter: CacheAdapter
+  if (m.adapter === 'custom') {
+    if (!m.module) throw new Error('cache: adapter "custom" without a module')
+    adapter = instantiate(await load(m.module, false), m.options, `"custom" (${m.module})`)
+  } else {
+    const spec = BUILTINS[m.adapter]
+    if (!spec) throw new Error(`cache: unknown adapter "${m.adapter}"`)
+    adapter = instantiate(await load(spec, true), resolveEnvOptions(m.options, env), `"${m.adapter}"`)
+  }
+  if (m.broadcast) {
+    const spec = BUILTINS[m.broadcast]
+    if (!spec) throw new Error(`cache: unknown broadcast "${m.broadcast}"`)
+    const other = instantiate(await load(spec, true), resolveEnvOptions(m.broadcastOptions ?? {}, env), `"${m.broadcast}" (broadcast)`)
+    if (!other.broadcast) throw new TypeError(`cache adapter "${m.broadcast}" has no broadcast to compose`)
+    adapter = compose(adapter, other)
+  }
+  checkRuntime(adapter, runtime)
+  return adapter
+}
+
+/** `base`'s store with `other`'s broadcast; both are initialised and closed. Built explicitly (not a
+ * spread) so a class-based adapter keeps its prototype methods. */
+export function compose(base: CacheAdapter, other: CacheAdapter): CacheAdapter {
+  // A broadcast that knows its store partner (the Cloudflare DO + KV floors) composes itself.
+  const own = (other as { composeWith?: (store: CacheAdapter) => CacheAdapter }).composeWith
+  if (typeof own === 'function') return own.call(other, base)
+  return {
+    name: base.name,
+    runtimes: base.runtimes.filter(r => other.runtimes.includes(r)),
+    ...(base.store ? { store: base.store } : {}),
+    broadcast: other.broadcast,
+    async init(ctx) {
+      await base.init?.(ctx)
+      await other.init?.(ctx)
+    },
+    async close() {
+      await Promise.allSettled([base.close?.(), other.close?.()])
+    },
+  }
+}

package/src/cache-adapter/memory.ts

@@ -0,0 +1,229 @@
+// The in-memory cache adapter: the reference implementation of the contract (exact stale-write
+// guard, push or pull broadcast with a bounded ring) and the test double for brust's own suites.
+// Not a production backend: it shares nothing across processes. No `bun` import (CF-bundle safe).
+import type {
+  CacheAdapter,
+  CacheBroadcast,
+  CacheStore,
+  EpochSince,
+  GetResult,
+  InvalidateArgs,
+  InvalidationEvent,
+  SetMeta,
+  StoredPage,
+} from './types'
+
+export interface MemoryAdapterOptions {
+  broadcast?: 'push' | 'pull' | 'none'
+  /** Ring capacity in events (pull). Default 1024. */
+  ring?: number
+  /** Ring capacity in serialized bytes (pull). Default 1 MiB. */
+  ringBytes?: number
+  /** Default 8 MiB. */
+  maxBodyBytes?: number
+  now?: () => number
+}
+
+/** One event above this many serialized bytes is kept as a gap marker (readers clear). */
+const OVERSIZE_EVENT = 64 * 1024
+
+interface Entry {
+  page: StoredPage
+  tags: string[]
+  method: string
+  path: string
+  entryStamp: number | null
+  storedAt: number
+  expiresAt: number
+}
+
+type Slot = { seq: number; bytes: number; event: InvalidationEvent | null }
+
+export interface MemoryAdapterTest {
+  /** A new generation (a restarted broadcast): readers see `gen` change. */
+  regen(): void
+  /** The next `get` settles as a miss after `ms` (default 2000). */
+  hangNextGet(ms?: number): void
+  /** The next store/broadcast call rejects. */
+  failNext(): void
+  /** The next `store.invalidate` waits `ms` before it marks and deletes (a slow networked store). */
+  delayNextInvalidate(ms: number): void
+  publishCount(): number
+  /** Stored entries (expired ones included). */
+  size(): number
+}
+
+export type MemoryAdapter = CacheAdapter & { store: CacheStore; __test: MemoryAdapterTest }
+
+const pathName = (method: string | undefined, path: string) => `${method ?? 'GET'} ${path}`
+
+export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
+  const mode = o.broadcast ?? 'push'
+  const ringCap = o.ring ?? 1024
+  const ringBytes = o.ringBytes ?? 1_048_576
+  const maxBodyBytes = o.maxBodyBytes ?? 8_388_608
+  const now = o.now ?? Date.now
+  const entries = new Map<string, Entry>()
+  const tagSeq = new Map<string, number>()
+  const pathSeq = new Map<string, number>()
+  let seq = 0
+  // Drawn on first use: a Workers module may not make random values at global scope.
+  let genValue: string | null = null
+  const gen = () => (genValue ??= randomGen())
+  const ring: Slot[] = []
+  let ringUsed = 0
+  /** The highest seq no longer in the ring (a reader at or below seq-1 of it is behind). */
+  let dropped = 0
+  let publishes = 0
+  let hang: number | null = null
+  let fail = false
+  let invalidateDelay = 0
+  const subscribers = new Set<{ on: (e: InvalidationEvent) => void; onGap: () => void }>()
+
+  const guarded = mode !== 'none'
+  const failing = () => {
+    if (!fail) return false
+    fail = false
+    return true
+  }
+  const raise = (m: Map<string, number>, k: string, s: number) => m.set(k, Math.max(m.get(k) ?? 0, s))
+  const mark = (args: InvalidateArgs, s: number) => {
+    for (const t of args.tags ?? []) raise(tagSeq, t, s)
+    if (args.path !== undefined) raise(pathSeq, pathName(args.method, args.path), s)
+  }
+
+  const store: CacheStore = {
+    maxBodyBytes,
+    async get(key: string): Promise<GetResult> {
+      if (failing()) throw new Error('memory adapter: injected failure')
+      if (hang !== null) {
+        const ms = hang
+        hang = null
+        await new Promise(r => setTimeout(r, ms))
+        return { page: null, stamp: guarded ? seq : null, entryStamp: null, storedAt: null }
+      }
+      const e = entries.get(key)
+      const stamp = guarded ? seq : null
+      if (!e || e.expiresAt <= now()) {
+        if (e) entries.delete(key)
+        return { page: null, stamp, entryStamp: null, storedAt: null }
+      }
+      return { page: copyPage(e.page), stamp, entryStamp: e.entryStamp, storedAt: e.storedAt }
+    },
+    async set(key: string, page: StoredPage, meta: SetMeta): Promise<boolean> {
+      if (failing()) throw new Error('memory adapter: injected failure')
+      if (page.body.length > maxBodyBytes) return false
+      if (meta.stamp !== null) {
+        const s = meta.stamp
+        const stale = (m: Map<string, number>, k: string) => (m.get(k) ?? 0) > s
+        if (meta.tags.some(t => stale(tagSeq, t)) || stale(pathSeq, pathName(meta.method, meta.path))) return false
+      }
+      const at = now()
+      entries.set(key, {
+        page: copyPage(page),
+        tags: [...meta.tags],
+        method: meta.method,
+        path: meta.path,
+        entryStamp: meta.stamp,
+        storedAt: at,
+        expiresAt: at + meta.ttlMs,
+      })
+      return true
+    },
+    async invalidate(args: InvalidateArgs): Promise<void> {
+      if (failing()) throw new Error('memory adapter: injected failure')
+      if (invalidateDelay > 0) {
+        const ms = invalidateDelay
+        invalidateDelay = 0
+        await new Promise(r => setTimeout(r, ms))
+      }
+      // L7b: the marker first, at the seq the matching publish will take (seq + 1), so a set whose
+      // stamp was read before this call is refused from now on; then the delete.
+      mark(args, seq + 1)
+      const tags = new Set(args.tags ?? [])
+      const p = args.path === undefined ? null : pathName(args.method, args.path)
+      for (const [k, e] of entries) {
+        if (e.tags.some(t => tags.has(t)) || (p !== null && pathName(e.method, e.path) === p)) entries.delete(k)
+      }
+    },
+  }
+
+  const push = (event: InvalidationEvent) => {
+    const bytes = JSON.stringify(event).length
+    const slot: Slot = { seq: event.seq, bytes: Math.min(bytes, OVERSIZE_EVENT), event: bytes > OVERSIZE_EVENT ? null : event }
+    ring.push(slot)
+    ringUsed += slot.bytes
+    while (ring.length > ringCap || ringUsed > ringBytes) {
+      const old = ring.shift()!
+      ringUsed -= old.bytes
+      dropped = old.seq
+    }
+  }
+
+  const broadcast: CacheBroadcast = {
+    async publish(args: InvalidateArgs, origin: string): Promise<number> {
+      if (failing()) throw new Error('memory adapter: injected failure')
+      seq += 1
+      publishes += 1
+      mark(args, seq)
+      const event: InvalidationEvent = { seq, origin, args: structuredClone(args) }
+      push(event)
+      for (const s of subscribers) queueMicrotask(() => s.on(structuredClone(event)))
+      return seq
+    },
+  }
+  if (mode === 'push') {
+    broadcast.subscribe = async (on, onGap) => {
+      const sub = { on, onGap }
+      subscribers.add(sub)
+      return async () => {
+        subscribers.delete(sub)
+      }
+    }
+  }
+  if (mode === 'pull') {
+    broadcast.since = async (from: number): Promise<EpochSince> => {
+      if (failing()) throw new Error('memory adapter: injected failure')
+      const after = ring.filter(s => s.seq > from)
+      const behind = from < dropped || after.some(s => s.event === null)
+      return { gen: gen(), seq, behind, events: behind ? [] : after.map(s => structuredClone(s.event!)) }
+    }
+  }
+
+  return {
+    name: 'memory',
+    runtimes: ['bun', 'workers'],
+    store,
+    ...(mode === 'none' ? {} : { broadcast }),
+    __test: {
+      regen() {
+        genValue = randomGen()
+        ring.length = 0
+        ringUsed = 0
+        dropped = seq
+        for (const s of subscribers) queueMicrotask(() => s.onGap())
+      },
+      hangNextGet(ms = 2000) {
+        hang = ms
+      },
+      failNext() {
+        fail = true
+      },
+      delayNextInvalidate(ms: number) {
+        invalidateDelay = ms
+      },
+      publishCount: () => publishes,
+      size: () => entries.size,
+    },
+  }
+}
+
+function copyPage(p: StoredPage): StoredPage {
+  return { status: p.status, headers: p.headers.map(([k, v]) => [k, v] as [string, string]), body: p.body.slice() }
+}
+
+function randomGen(): string {
+  const b = new Uint8Array(8)
+  crypto.getRandomValues(b)
+  return Array.from(b, x => x.toString(16).padStart(2, '0')).join('')
+}