@brust/cache-redis 0.0.0-stage → 2.0.0-alpha.3

package/README.md

@@ -1,3 +1,6 @@
-# Temporary Holding Version
+# @brust/cache-redis
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Redis and Dragonfly cache adapter for brust (`[cache] adapter = "redis"` or `"dragonfly"`).
+Built on Bun's `RedisClient`: no npm dependency, Bun only (not Cloudflare Workers).
+
+Configure it in `brust.toml` (`[cache]` + `[cache.redis]`, the URL always via `env:NAME`); see the brust docs, "Redis / Dragonfly".

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@brust/cache-redis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-alpha.3",
+  "description": "brust cache adapter for Redis and Dragonfly (Bun RedisClient, no npm dependency)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AssetsArt/brust.git"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./dragonfly": {
+      "types": "./src/dragonfly.ts",
+      "default": "./src/dragonfly.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bun check"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@brust/core": "2.0.0-alpha.3"
+  },
+  "devDependencies": {
+    "@brust/core": "2.0.0-alpha.3",
+    "@types/bun": "^1.4.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "bun": ">=1.2.23"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,114 @@
+import type { CacheAdapter, CacheAdapterInit, GetResult, InvalidateArgs, InvalidationEvent, SetMeta, StoredPage } from '@brust/core/cache-adapter'
+import { Link } from './conn'
+import { decodeFrame, encodeFrame } from './frame'
+import { type Keys, keys as makeKeys } from './keys'
+import { evalsha, SET_SCRIPT } from './lua'
+import { Pairing } from './pairing'
+import { parseOptions, type ResolvedOptions } from './options'
+import { type SubscriberState, startSubscriber } from './subscriber'
+
+const STAGE_TTL_MS = 30_000
+
+export interface RedisAdapterTest {
+  /** Close the subscriber socket as a network loss would. */
+  dropSubscriber(): void
+  state(): { connected: boolean; subscribed: boolean; last: number | null; reconnects: number }
+  /** The command client (raw access for tests). */
+  client(): import('bun').RedisClient
+  keys(): Keys
+}
+
+export type RedisAdapter = CacheAdapter & { __test: RedisAdapterTest }
+
+export function createAdapter(name: 'redis' | 'dragonfly', raw: Record<string, unknown>): RedisAdapter {
+  const o: ResolvedOptions = parseOptions(raw)
+  let ks: Keys | null = null
+  let cmd: Link | null = null
+  const k = (): Keys => ks ?? fail()
+  const link = (): Link => cmd ?? fail()
+  const fail = (): never => {
+    throw new Error('cache-redis: used before init')
+  }
+  const sub: SubscriberState = { link: null, subscribed: false, last: null }
+  const pairing = new Pairing(() => link().c, k, o.markerTtlMs)
+
+  const store = {
+    maxBodyBytes: o.maxBodyBytes,
+    async get(key: string): Promise<GetResult> {
+      const c = link().c
+      const [buf, seq] = await Promise.all([c.getBuffer(k().page(key)), c.get(k().seq)])
+      const stamp = Number(seq ?? 0)
+      if (buf === null) return { page: null, stamp, entryStamp: null, storedAt: null }
+      const f = decodeFrame(buf)
+      if (f === null) throw new Error('cache-redis: stored page has an unknown frame version')
+      return { page: f.page, stamp, entryStamp: f.entryStamp, storedAt: f.storedAt }
+    },
+    async set(key: string, page: StoredPage, meta: SetMeta): Promise<boolean> {
+      if (page.body.length > o.maxBodyBytes) return false
+      const c = link().c
+      const K = k()
+      const method = meta.method.toUpperCase()
+      const tags = [...new Set(meta.tags)]
+      const stage = K.stage(crypto.randomUUID())
+      const idx = [...tags.map((t) => K.tag(t)), K.path(method, meta.path)]
+      const marks = [...tags.map((t) => K.markTag(t)), K.markPath(method, meta.path)]
+      const frame = encodeFrame(page, { entryStamp: meta.stamp, storedAt: Date.now(), tags, method, path: meta.path })
+      // Both commands go out on the one auto-pipelined connection: one round trip.
+      const staged = c.set(stage, frame, 'PX', STAGE_TTL_MS)
+      const ran = evalsha(c, SET_SCRIPT, [stage, K.page(key), ...idx, ...marks], [meta.stamp === null ? '' : meta.stamp, Math.max(1, Math.ceil(meta.ttlMs)), idx.length])
+      const [a, b] = await Promise.allSettled([staged, ran])
+      if (a.status === 'rejected') throw a.reason
+      if (b.status === 'rejected') throw b.reason
+      if (b.value === -1) {
+        console.warn('[brust] cache-redis: staging key vanished before the guarded write')
+        return false
+      }
+      return b.value === 1
+    },
+    async invalidate(args: InvalidateArgs): Promise<void> {
+      const { members } = await pairing.run(args, 'invalidate')
+      if (!members.length) return
+      const c = link().c
+      // UNLINK frees off the main thread (Dragonfly too); batched so one call never carries every key.
+      const jobs: Promise<number>[] = []
+      for (let i = 0; i < members.length; i += o.unlinkBatch) jobs.push(c.unlink(...members.slice(i, i + o.unlinkBatch)))
+      await Promise.all(jobs)
+    },
+  }
+
+  const broadcast = {
+    async publish(args: InvalidateArgs, origin: string): Promise<number> {
+      const { seq } = await pairing.run(args, 'publish')
+      await link().c.publish(k().channel, JSON.stringify({ seq, origin, args }))
+      return seq
+    },
+    async subscribe(on: (e: InvalidationEvent) => void, onGap: () => void): Promise<() => Promise<void>> {
+      return startSubscriber(o, k(), async () => Number((await link().c.get(k().seq)) ?? 0), sub, on, onGap)
+    },
+  }
+
+  const adapter: RedisAdapter = {
+    name,
+    runtimes: ['bun'],
+    store,
+    broadcast,
+    async init(ctx: CacheAdapterInit) {
+      ks = makeKeys(ctx.namespace)
+      cmd = new Link(o, 'commands')
+      await cmd.start()
+    },
+    async close() {
+      sub.link?.close()
+      cmd?.close()
+    },
+    __test: {
+      dropSubscriber: () => sub.link?.drop(),
+      state: () => ({ connected: !!cmd?.connected, subscribed: sub.subscribed, last: sub.last, reconnects: (cmd?.reconnects ?? 0) + (sub.link?.reconnects ?? 0) }),
+      client: () => link().c,
+      keys: () => k(),
+    },
+  }
+  return adapter
+}
+
+export type { InvalidationEvent }

package/src/conn.ts

@@ -0,0 +1,128 @@
+// A Bun RedisClient with an adapter-owned reconnect loop (cache-redis R8): the client itself never
+// reconnects and never queues offline, so a dead server fails commands at once instead of pinning
+// a worker slot until the get budget. A fresh client per attempt (a closed one is not reusable).
+import { RedisClient } from 'bun'
+import type { ResolvedOptions } from './options'
+import { redact } from './redact'
+
+export class Link {
+  private client: RedisClient | null = null
+  private closing = false
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private fails = 0
+  private warned = 0
+  /** Reconnect attempts started (a test hook: stable once `close()` ran). */
+  reconnects = 0
+
+  constructor(
+    private readonly o: ResolvedOptions,
+    private readonly what: string,
+    /** Runs on every successful connect (subscribe + gap check); a throw drops the connection and retries. */
+    private readonly onUp?: (c: RedisClient) => Promise<void>,
+    /** Runs when a live connection is lost. */
+    private readonly onDown?: () => void,
+  ) {}
+
+  get connected(): boolean {
+    return this.client !== null
+  }
+
+  /** The live client; throws at once when disconnected. */
+  get c(): RedisClient {
+    if (!this.client) throw new Error(`cache-redis: not connected to ${redact(this.o.url)}`)
+    return this.client
+  }
+
+  /** One bounded connect; a failure starts the loop. Never throws for network reasons (R9). */
+  async start(): Promise<void> {
+    if (!(await this.attempt())) this.schedule()
+  }
+
+  /** Close the socket as a network loss would (the loop reconnects). */
+  drop(): void {
+    const cl = this.client
+    if (cl) {
+      cl.close()
+      this.lost(cl)
+    }
+  }
+
+  close(): void {
+    this.closing = true
+    if (this.timer) clearTimeout(this.timer)
+    this.timer = null
+    const cl = this.client
+    this.client = null
+    cl?.close()
+  }
+
+  private async attempt(): Promise<boolean> {
+    const { url, tls, connectTimeoutMs } = this.o
+    const cl = new RedisClient(url, { autoReconnect: false, enableOfflineQueue: false, connectionTimeout: connectTimeoutMs, ...(tls ? { tls } : {}) })
+    cl.onclose = (e) => {
+      if (this.client === cl) this.lost(cl, e)
+    }
+    let timer: ReturnType<typeof setTimeout> | undefined
+    try {
+      await Promise.race([
+        cl.connect(),
+        new Promise<never>((_, rej) => {
+          timer = setTimeout(() => rej(new Error('connect timed out')), connectTimeoutMs)
+        }),
+      ])
+      clearTimeout(timer)
+      if (this.closing) {
+        cl.close()
+        return true
+      }
+      this.client = cl
+      await this.onUp?.(cl)
+      this.fails = 0
+      this.warned = 0
+      return true
+    } catch (e) {
+      clearTimeout(timer)
+      if (this.client === cl) this.client = null
+      cl.close()
+      this.warn(e)
+      return false
+    }
+  }
+
+  private lost(cl: RedisClient, e?: unknown): void {
+    if (this.client !== cl) return
+    this.client = null
+    this.onDown?.()
+    if (this.closing) return
+    this.warn(e ?? new Error('connection lost'))
+    this.schedule()
+  }
+
+  private schedule(): void {
+    if (this.closing || this.timer) return
+    const { reconnectMinMs, reconnectMaxMs } = this.o
+    const base = Math.min(reconnectMaxMs, reconnectMinMs * 2 ** Math.min(this.fails++, 20))
+    const delay = base * (0.8 + Math.random() * 0.4)
+    this.timer = setTimeout(async () => {
+      this.timer = null
+      if (this.closing) return
+      this.reconnects++
+      if (!(await this.attempt())) this.schedule()
+    }, delay)
+  }
+
+  /** The first failure, then every 10th; host:port only, the password scrubbed from the message. */
+  private warn(e: unknown): void {
+    if (this.warned++ % 10 !== 0) return
+    console.warn(`[brust] cache-redis ${this.what}: ${redact(this.o.url)} unavailable (${this.scrub(e)}); retrying`)
+  }
+
+  private scrub(e: unknown): string {
+    let m = e instanceof Error ? e.message : String(e)
+    try {
+      const u = new URL(this.o.url)
+      for (const s of [this.o.url, u.password, u.username]) if (s) m = m.split(s).join('<redacted>')
+    } catch {}
+    return m.slice(0, 200)
+  }
+}

package/src/dragonfly.ts

@@ -0,0 +1,11 @@
+import { createAdapter, type RedisAdapter } from './adapter'
+
+export type { RedisAdapter, RedisAdapterTest } from './adapter'
+export type { RedisCacheOptions } from './options'
+
+/** `[cache] adapter = "dragonfly"`: the same code as Redis (every script declares all its keys). */
+export function dragonflyAdapter(options: Record<string, unknown>): RedisAdapter {
+  return createAdapter('dragonfly', options)
+}
+
+export default dragonflyAdapter

package/src/frame.ts

@@ -0,0 +1,46 @@
+// One page = one binary string (cache-redis R3): [u32 LE meta_len][meta JSON][body].
+import type { StoredPage } from '@brust/core/cache-adapter'
+
+export interface FrameMeta {
+  v: 1
+  status: number
+  headers: [string, string][]
+  entryStamp: number | null
+  storedAt: number
+  tags: string[]
+  method: string
+  path: string
+}
+
+export interface DecodedFrame {
+  page: StoredPage
+  entryStamp: number | null
+  storedAt: number
+}
+
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+
+export function encodeFrame(page: StoredPage, m: Omit<FrameMeta, 'v' | 'status' | 'headers'>): Uint8Array {
+  const meta = enc.encode(JSON.stringify({ v: 1, status: page.status, headers: page.headers, ...m } satisfies FrameMeta))
+  const out = new Uint8Array(4 + meta.length + page.body.length)
+  new DataView(out.buffer).setUint32(0, meta.length, true)
+  out.set(meta, 4)
+  out.set(page.body, 4 + meta.length)
+  return out
+}
+
+/** `null` = a frame of an unknown version (a miss); throws on a truncated or corrupt frame. */
+export function decodeFrame(buf: Uint8Array): DecodedFrame | null {
+  if (buf.length < 4) throw new Error('cache-redis: truncated page frame')
+  const len = new DataView(buf.buffer, buf.byteOffset, buf.byteLength).getUint32(0, true)
+  if (4 + len > buf.length) throw new Error('cache-redis: page frame meta length exceeds the frame')
+  const meta = JSON.parse(dec.decode(buf.subarray(4, 4 + len))) as Partial<FrameMeta> & { v?: unknown }
+  if (meta.v !== 1) return null
+  if (typeof meta.status !== 'number' || !Array.isArray(meta.headers)) throw new Error('cache-redis: corrupt page frame meta')
+  return {
+    page: { status: meta.status, headers: meta.headers, body: buf.slice(4 + len) },
+    entryStamp: typeof meta.entryStamp === 'number' ? meta.entryStamp : null,
+    storedAt: typeof meta.storedAt === 'number' ? meta.storedAt : 0,
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+import { createAdapter, type RedisAdapter } from './adapter'
+
+export type { RedisAdapter, RedisAdapterTest } from './adapter'
+export type { RedisCacheOptions } from './options'
+
+/** `[cache] adapter = "redis"`: the factory brust calls with `[cache.redis]` (after `env:` resolution). */
+export function redisAdapter(options: Record<string, unknown>): RedisAdapter {
+  return createAdapter('redis', options)
+}
+
+export default redisAdapter

package/src/keys.ts

@@ -0,0 +1,47 @@
+// The key schema (cache-redis R1): every key of a namespace carries the cluster hash tag
+// `{brust:<ns>}`, so the multi-key scripts stay on one slot. Only page keys are build-scoped
+// (their L2 key carries the build); index sets, markers, seq and the channel are namespace-level.
+import type { InvalidateArgs } from '@brust/core/cache-adapter'
+
+export interface Keys {
+  page(l2Key: string): string
+  tag(tag: string): string
+  path(method: string | undefined, path: string): string
+  markTag(tag: string): string
+  markPath(method: string | undefined, path: string): string
+  seq: string
+  stage(id: string): string
+  channel: string
+  /** SCAN pattern of every key of the namespace. */
+  all: string
+}
+
+const pathName = (method: string | undefined, path: string) => `${(method ?? 'GET').toUpperCase()} ${path}`
+
+export function keys(ns: string): Keys {
+  const p = `{brust:${ns}}`
+  return {
+    page: (k) => `${p}:page:${k}`,
+    tag: (t) => `${p}:tag:${t}`,
+    path: (m, path) => `${p}:path:${pathName(m, path)}`,
+    markTag: (t) => `${p}:inval:tag:${t}`,
+    markPath: (m, path) => `${p}:inval:path:${pathName(m, path)}`,
+    seq: `${p}:seq`,
+    stage: (id) => `${p}:stage:${id}`,
+    channel: `brust:${ns}:inval`,
+    all: `${p}:*`,
+  }
+}
+
+/** Order- and case-insensitive identity of an invalidation (pairs its store and broadcast halves). */
+export function canonical(a: InvalidateArgs): string {
+  return JSON.stringify({
+    tags: [...new Set(a.tags ?? [])].sort(),
+    ...(a.path !== undefined ? { path: a.path, method: (a.method ?? 'GET').toUpperCase() } : {}),
+  })
+}
+
+/** Does the invalidation touch pages? (A key-only one is tier 1's business: the store holds none by key.) */
+export function hasStoreWork(a: InvalidateArgs): boolean {
+  return (a.tags?.length ?? 0) > 0 || a.path !== undefined
+}

package/src/lua.ts

@@ -0,0 +1,59 @@
+// The two scripts (cache-redis R4, R6). The text is exact: the reviewer diffs it against the plan.
+// Every key a script touches is declared in KEYS (Dragonfly needs it; cluster needs one slot).
+import type { RedisClient } from 'bun'
+
+// SET_LUA  KEYS = [stage, page, idx_1..idx_n, mark_1..mark_n]  ARGV = [stamp|"", ttl_ms, n]
+export const SET_LUA = `local n = tonumber(ARGV[3]); local ttl = tonumber(ARGV[2])
+if ARGV[1] ~= '' then
+  local stamp = tonumber(ARGV[1])
+  for i = 1, n do
+    local m = redis.call('GET', KEYS[2 + n + i])
+    if m and tonumber(m) > stamp then redis.call('DEL', KEYS[1]); return 0 end
+  end
+end
+if redis.call('EXISTS', KEYS[1]) == 0 then return -1 end
+redis.call('RENAME', KEYS[1], KEYS[2]); redis.call('PEXPIRE', KEYS[2], ttl)
+for i = 1, n do
+  redis.call('SADD', KEYS[2 + i], KEYS[2])
+  local t = redis.call('PTTL', KEYS[2 + i])
+  if t == -1 or (t >= 0 and t < ttl) then redis.call('PEXPIRE', KEYS[2 + i], ttl) end
+end
+return 1`
+
+// INVAL_LUA  KEYS = [seq, idx_1..idx_n, mark_1..mark_n]  ARGV = [mode ('both'|'delete'|'publish'), n, marker_ttl_ms]
+export const INVAL_LUA = `local unpack = table.unpack or unpack  -- Lua 5.1 (Redis) and 5.4 (Dragonfly)
+local mode = ARGV[1]; local n = tonumber(ARGV[2]); local mttl = tonumber(ARGV[3])
+local v
+if mode == 'delete' then v = tonumber(redis.call('GET', KEYS[1]) or '0') + 1 else v = redis.call('INCR', KEYS[1]) end
+for i = 1, n do
+  local k = KEYS[1 + n + i]; local c = tonumber(redis.call('GET', k) or '0')
+  if v > c then redis.call('SET', k, v, 'PX', mttl) else redis.call('PEXPIRE', k, mttl) end
+end
+local out = { mode == 'delete' and v - 1 or v }
+if mode ~= 'publish' and n > 0 then
+  local idx = {}; for i = 1, n do idx[i] = KEYS[1 + i] end
+  for _, m in ipairs(redis.call('SUNION', unpack(idx))) do out[#out + 1] = m end
+  redis.call('DEL', unpack(idx))
+end
+return out`
+
+const sha1 = (s: string) => new Bun.CryptoHasher('sha1').update(s).digest('hex')
+
+export interface Script {
+  readonly source: string
+  readonly sha: string
+}
+
+export const SET_SCRIPT: Script = { source: SET_LUA, sha: sha1(SET_LUA) }
+export const INVAL_SCRIPT: Script = { source: INVAL_LUA, sha: sha1(INVAL_LUA) }
+
+/** EVALSHA; a NOSCRIPT reply (restart, failover, SCRIPT FLUSH) → EVAL, which also caches it. */
+export async function evalsha(c: RedisClient, s: Script, keys: string[], argv: (string | number)[]): Promise<unknown> {
+  const tail = [String(keys.length), ...keys, ...argv.map(String)]
+  try {
+    return await c.send('EVALSHA', [s.sha, ...tail])
+  } catch (e) {
+    if (!/NOSCRIPT/.test(e instanceof Error ? e.message : String(e))) throw e
+    return await c.send('EVAL', [s.source, ...tail])
+  }
+}

package/src/options.ts

@@ -0,0 +1,82 @@
+// `[cache.redis]` (cache-redis R10, R11): validated at worker boot; the same key list is checked at
+// `brust build` by `parseCache`. Errors name the key and never echo the url (it may hold a password).
+import { readFileSync } from 'node:fs'
+
+export const OPTION_KEYS = ['url', 'tls', 'connect_timeout_ms', 'max_body_bytes', 'marker_ttl_ms', 'unlink_batch', 'reconnect_min_ms', 'reconnect_max_ms'] as const
+
+export interface RedisCacheOptions {
+  url: string
+  tls?: boolean | { reject_unauthorized?: boolean; server_name?: string; ca_file?: string }
+  connect_timeout_ms?: number
+  max_body_bytes?: number
+  marker_ttl_ms?: number
+  unlink_batch?: number
+  reconnect_min_ms?: number
+  reconnect_max_ms?: number
+}
+
+export interface ResolvedOptions {
+  url: string
+  tls: boolean | Bun.TLSOptions
+  connectTimeoutMs: number
+  maxBodyBytes: number
+  markerTtlMs: number
+  unlinkBatch: number
+  reconnectMinMs: number
+  reconnectMaxMs: number
+}
+
+const bad = (m: string): never => {
+  throw new TypeError(`cache-redis: ${m}`)
+}
+
+function int(o: Record<string, unknown>, k: string, min: number, max: number, dflt: number): number {
+  const v = o[k]
+  if (v === undefined) return dflt
+  if (typeof v !== 'number' || !Number.isInteger(v) || v < min || v > max) return bad(`${k} must be an integer in ${min}..${max} (got ${JSON.stringify(v)})`)
+  return v
+}
+
+function tlsOf(v: unknown): boolean | Bun.TLSOptions {
+  if (v === undefined || typeof v === 'boolean') return v ?? false
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return bad('tls must be true, false or a table')
+  const t = v as Record<string, unknown>
+  for (const k of Object.keys(t)) if (k !== 'reject_unauthorized' && k !== 'server_name' && k !== 'ca_file') bad(`unknown option "tls.${k}"`)
+  const out: Bun.TLSOptions = {}
+  if (t.reject_unauthorized !== undefined) {
+    if (typeof t.reject_unauthorized !== 'boolean') bad('tls.reject_unauthorized must be a boolean')
+    out.rejectUnauthorized = t.reject_unauthorized as boolean
+  }
+  if (t.server_name !== undefined) {
+    if (typeof t.server_name !== 'string' || t.server_name === '') bad('tls.server_name must be a non-empty string')
+    out.serverName = t.server_name as string
+  }
+  if (t.ca_file !== undefined) {
+    if (typeof t.ca_file !== 'string' || t.ca_file === '') bad('tls.ca_file must be a non-empty path')
+    try {
+      out.ca = readFileSync(t.ca_file as string, 'utf8')
+    } catch {
+      bad('tls.ca_file cannot be read')
+    }
+  }
+  return out
+}
+
+export function parseOptions(raw: Record<string, unknown>): ResolvedOptions {
+  for (const k of Object.keys(raw)) if (!(OPTION_KEYS as readonly string[]).includes(k)) bad(`unknown option "${k}"`)
+  const url = raw.url
+  if (typeof url !== 'string' || url.trim() === '') bad('url is required (set it as "env:NAME" in [cache.redis])')
+  const reconnectMinMs = int(raw, 'reconnect_min_ms', 10, 60_000, 100)
+  const reconnectMaxMs = int(raw, 'reconnect_max_ms', 10, 600_000, Math.max(5000, reconnectMinMs))
+  if (reconnectMaxMs < reconnectMinMs) bad('reconnect_max_ms must be >= reconnect_min_ms')
+  return {
+    url: (url as string).trim(),
+    tls: tlsOf(raw.tls),
+    connectTimeoutMs: int(raw, 'connect_timeout_ms', 100, 60_000, 2000),
+    maxBodyBytes: int(raw, 'max_body_bytes', 1, 67_108_864, 1_048_576),
+    markerTtlMs: int(raw, 'marker_ttl_ms', 60_000, 604_800_000, 86_400_000),
+    unlinkBatch: int(raw, 'unlink_batch', 1, 10_000, 500),
+    reconnectMinMs,
+    reconnectMaxMs,
+  }
+}

package/src/pairing.ts

@@ -0,0 +1,75 @@
+// Pairs the two halves of one invalidation (cache-redis R4). lane A issues `store.invalidate` and
+// `broadcast.publish` for the same args; when both arrive in the same tick ONE INVAL_LUA run does
+// INCR + markers + SUNION/DEL atomically (mode `both`). Otherwise each half runs alone: `delete`
+// (markers at seq+1, seq untouched, so it never jumps without an event) or `publish` (INCR + markers).
+import type { RedisClient } from 'bun'
+import type { InvalidateArgs } from '@brust/core/cache-adapter'
+import { canonical, hasStoreWork, type Keys } from './keys'
+import { evalsha, INVAL_SCRIPT } from './lua'
+
+export type Side = 'invalidate' | 'publish'
+export interface InvalResult {
+  seq: number
+  members: string[]
+}
+
+interface Entry {
+  sides: Set<Side>
+  promise: Promise<InvalResult>
+}
+
+export class Pairing {
+  private readonly pending = new Map<string, Entry[]>()
+
+  constructor(
+    private readonly c: () => RedisClient,
+    private readonly keys: () => Keys,
+    private readonly markerTtlMs: number,
+  ) {}
+
+  run(args: InvalidateArgs, side: Side): Promise<InvalResult> {
+    if (side === 'invalidate' && !hasStoreWork(args)) return Promise.resolve({ seq: 0, members: [] })
+    const id = canonical(args)
+    const list = this.pending.get(id) ?? []
+    // Created synchronously, before any await: the partner finds it in the same tick.
+    const open = list.find((e) => !e.sides.has(side))
+    if (open) {
+      open.sides.add(side)
+      return open.promise
+    }
+    const entry: Entry = { sides: new Set([side]), promise: undefined as never }
+    entry.promise = new Promise<InvalResult>((resolve, reject) => {
+      queueMicrotask(() => {
+        const l = this.pending.get(id)
+        if (l) {
+          l.splice(l.indexOf(entry), 1)
+          if (!l.length) this.pending.delete(id)
+        }
+        const mode = entry.sides.size === 2 ? 'both' : side === 'invalidate' ? 'delete' : 'publish'
+        this.exec(args, mode).then(resolve, reject)
+      })
+    })
+    list.push(entry)
+    this.pending.set(id, list)
+    return entry.promise
+  }
+
+  private async exec(args: InvalidateArgs, mode: 'both' | 'delete' | 'publish'): Promise<InvalResult> {
+    const K = this.keys()
+    const method = args.method
+    const tags = [...new Set(args.tags ?? [])]
+    const idx: string[] = []
+    const marks: string[] = []
+    // A publish-only half marks but deletes nothing; a key-only publish has n = 0.
+    for (const t of tags) {
+      idx.push(K.tag(t))
+      marks.push(K.markTag(t))
+    }
+    if (args.path !== undefined) {
+      idx.push(K.path(method, args.path))
+      marks.push(K.markPath(method, args.path))
+    }
+    const r = (await evalsha(this.c(), INVAL_SCRIPT, [K.seq, ...idx, ...marks], [mode, idx.length, this.markerTtlMs])) as (number | string)[]
+    return { seq: Number(r[0]), members: r.slice(1).map(String) }
+  }
+}

package/src/redact.ts

@@ -0,0 +1,10 @@
+/** `host:port` of a Redis URL, never the userinfo, path or query (a URL may carry a password). */
+export function redact(url: string): string {
+  try {
+    const u = new URL(url)
+    if (!u.hostname) return '<invalid url>'
+    return u.port ? `${u.hostname}:${u.port}` : u.hostname
+  } catch {
+    return '<invalid url>'
+  }
+}

package/src/subscriber.ts

@@ -0,0 +1,65 @@
+// The push half (cache-redis R7, R8): a dedicated subscriber connection with the adapter-owned
+// reconnect loop, and a gap check on every (re)subscribe so an event lost during an outage clears
+// tier 1 (spec §4.2.5) instead of leaving a stale page for up to its ttl.
+import type { InvalidationEvent } from '@brust/core/cache-adapter'
+import { Link } from './conn'
+import type { Keys } from './keys'
+import type { ResolvedOptions } from './options'
+
+export interface SubscriberState {
+  link: Link | null
+  subscribed: boolean
+  last: number | null
+}
+
+export async function startSubscriber(
+  o: ResolvedOptions,
+  keys: Keys,
+  readSeq: () => Promise<number>,
+  state: SubscriberState,
+  on: (e: InvalidationEvent) => void,
+  onGap: () => void,
+): Promise<() => Promise<void>> {
+  const listener = (message: string) => {
+    let e: InvalidationEvent
+    try {
+      const j = JSON.parse(message) as Partial<InvalidationEvent>
+      if (!Number.isSafeInteger(j.seq) || typeof j.origin !== 'string' || typeof j.args !== 'object' || j.args === null) throw new Error('shape')
+      e = j as InvalidationEvent
+    } catch {
+      console.warn('[brust] cache-redis: dropped a malformed invalidation message')
+      return
+    }
+    state.last = Math.max(state.last ?? 0, e.seq)
+    try {
+      on(e)
+    } catch (err) {
+      console.error(`[brust] cache-redis: invalidation handler failed: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+  const link = new Link(o, 'subscriber', async (cl) => {
+    state.subscribed = false
+    await cl.subscribe(keys.channel, listener)
+    // The command link may be down too: a throw here drops this attempt and retries after the backoff.
+    const seq = await readSeq()
+    const first = state.last === null
+    if (first) state.last = seq
+    else if (seq > state.last!) {
+      state.last = seq
+      try {
+        onGap()
+      } catch (err) {
+        console.error(`[brust] cache-redis: gap handler failed: ${err instanceof Error ? err.message : String(err)}`)
+      }
+    }
+    state.subscribed = true
+  }, () => {
+    state.subscribed = false
+  })
+  state.link = link
+  await link.start()
+  return async () => {
+    link.close()
+    state.subscribed = false
+  }
+}