experimental-a2 0.10.0 → 0.11.0

package/src/store-redis.ts

@@ -21,18 +21,17 @@
  * `call`/`duplicate`/`on`/`disconnect`.
  */
 
-import type { PresencePatch } from './contract.ts'
 import { A2Error } from './errors.ts'
-import { NOTIFY_TIMINGS } from './internal.ts'
-import { defaultSleep, type Sleeper } from './store-polling.ts'
-import { createRedisStoreCore } from './store-redis-core.ts'
+import {
+  createRedisNotifyStore,
+  type RedisConnection,
+} from './store-redis-notify.ts'
 import { retryableLazy } from './retryable-lazy.ts'
 import {
   RANDOM_IDS,
   SYSTEM_CLOCK,
   type A2Store,
   type Clock,
-  type Event,
   type IdSource,
 } from './store.ts'
 
@@ -46,15 +45,7 @@ import {
  * re-read delivers everything — but every live feed silently degrades
  * to safety-read latency from that point on.
  */
-export type RedisConnection = {
-  call(command: string, ...args: Array<string | number>): Promise<unknown>
-  duplicate(): RedisConnection
-  on(
-    event: 'message',
-    listener: (channel: string, message: string) => void,
-  ): unknown
-  disconnect(): void
-}
+export type { RedisConnection } from './store-redis-notify.ts'
 
 export type RedisStoreOptions = {
   /** Creates an `ioredis` client lazily (optional peer dep `ioredis`). */
@@ -74,16 +65,6 @@ export type RedisStore = A2Store & {
   close(): Promise<void>
 }
 
-/** A published presence patch: the patch fields plus the publishing
- * instance's tag, so its own loopback delivery is not repeated. */
-type PresenceWireMessage = {
-  src: string
-  participant: string
-  values: Record<string, unknown>
-  seen: number
-  at: number
-}
-
 export function redis(options: RedisStoreOptions = {}): RedisStore {
   const clock = options.clock ?? SYSTEM_CLOCK
   const ids = options.ids ?? RANDOM_IDS
@@ -106,352 +87,16 @@ export function redis(options: RedisStoreOptions = {}): RedisStore {
   })
   const client = connection.get
 
-  const notifyChannel = (sessionId: string): string =>
-    `${prefix}:${sessionId}:notify`
-  const presenceChannel = (ns: string): string => `${prefix}:${ns}:presence`
-
-  const core = createRedisStoreCore({
-    call: async (command, ...args) => {
-      const c = await client()
-      return c.call(command, ...args)
-    },
+  return createRedisNotifyStore({
+    client,
     clock,
     ids,
     keyPrefix: prefix,
-    // Fire-and-forget: the wake-up is disposable, so a failed PUBLISH
-    // must never fail the write it follows.
-    notify: (sessionId, count) => {
-      void client()
-        .then((c) => c.call('publish', notifyChannel(sessionId), count))
-        .catch(() => {})
-    },
-  })
-
-  // ── the shared subscriber ──────────────────────────────────────────
-  // One duplicated connection serves every local feed: subscriber mode
-  // monopolizes a connection, so it cannot be the command client.
-
-  let severed = false
-  let subscriber: Promise<RedisConnection> | null = null
-  /** channel → parked-feed wake-ups, armed before each catch-up read. */
-  const wakers = new Map<string, Set<() => void>>()
-  /** channel → refcounted subscription held for each live iterator. */
-  const subscriptions = new Map<
-    string,
-    { refs: number; ready: Promise<unknown> }
-  >()
-  /**
-   * channel → last presence-marker refresh, throttling the SET.
-   * Deliberately real time (`Date.now()`), not the injected clock:
-   * the marker's PX expiry runs on server real time, and the throttle
-   * must tick with the TTL it refreshes or time-traveling tests would
-   * desync the two. Process-local and never stored, so the injected
-   * clock's every-stored-timestamp pledge is untouched.
-   */
-  const watchedRefreshedAt = new Map<string, number>()
-  /**
-   * `:presence` channel → live listeners. Same-instance patches are
-   * delivered here synchronously by `presence.set`, so subscribe/set
-   * ordering never depends on the SUBSCRIBE command settling; the
-   * channel carries only other instances' patches, with own echoes
-   * skipped by `src`.
-   */
-  const presenceListeners = new Map<
-    string,
-    Set<(patch: PresencePatch) => void>
-  >()
-  const instanceId = crypto.randomUUID()
-
-  const deliverRemotePresence = (
-    listeners: Set<(patch: PresencePatch) => void>,
-    message: string,
-  ): void => {
-    let parsed: PresenceWireMessage
-    try {
-      parsed = JSON.parse(message) as PresenceWireMessage
-    } catch {
-      return
-    }
-    if (parsed.src === instanceId) return
-    const patch: PresencePatch = {
-      participant: parsed.participant,
-      values: parsed.values,
-      seen: parsed.seen,
-      at: new Date(parsed.at),
-    }
-    for (const listener of listeners) listener(patch)
-  }
-
-  const getSubscriber = (): Promise<RedisConnection> => {
-    subscriber ??= (async () => {
-      const conn = (await client()).duplicate()
-      conn.on('message', (channel, message) => {
-        // wake() only resolves a promise; removal happens later via
-        // disarm(), so iterating the live set is safe.
-        const set = wakers.get(channel)
-        if (set) {
-          for (const wake of set) wake()
-        }
-        const listeners = presenceListeners.get(channel)
-        if (listeners) deliverRemotePresence(listeners, message)
-      })
-      return conn
-    })()
-    return subscriber
-  }
-
-  /**
-   * The subscriber, gated on connection readiness — for channel
-   * commands only (`close` uses the ungated promise, so it can never
-   * hang on an unreachable server). SUBSCRIBE carries redis's
-   * ok-loading flag, so ioredis writes it mid-handshake, ahead of the
-   * ready check's INFO — which then finds the connection already in
-   * subscriber mode and fails the check (a spurious error event plus
-   * a reconnect). ECHO has no such flag: it resolves only once the
-   * connection is ready, so every channel command chained behind it
-   * lands after the check.
-   */
-  let subscriberGate: Promise<RedisConnection> | null = null
-  const gatedSubscriber = (): Promise<RedisConnection> => {
-    subscriberGate ??= getSubscriber().then(async (conn) => {
-      await conn.call('echo', 'ready')
-      return conn
-    })
-    return subscriberGate
-  }
-
-  const acquireChannel = async (channel: string): Promise<void> => {
-    const existing = subscriptions.get(channel)
-    if (existing) {
-      existing.refs += 1
-      try {
-        await existing.ready
-      } catch (err) {
-        existing.refs -= 1
-        throw err
-      }
-      return
-    }
-    const lease = {
-      refs: 1,
-      // Lowercase on purpose: ioredis keys its subscriber-mode
-      // bookkeeping (and reconnect resubscription) on the exact
-      // command name.
-      ready: gatedSubscriber().then((conn) => conn.call('subscribe', channel)),
-    }
-    subscriptions.set(channel, lease)
-    try {
-      await lease.ready
-    } catch (err) {
-      if (subscriptions.get(channel) === lease) subscriptions.delete(channel)
-      throw err
-    }
-  }
-
-  const releaseChannel = (channel: string): void => {
-    const lease = subscriptions.get(channel)
-    if (!lease) return
-    lease.refs -= 1
-    if (lease.refs > 0) return
-    subscriptions.delete(channel)
-    watchedRefreshedAt.delete(channel)
-    void gatedSubscriber()
-      .then((conn) => conn.call('unsubscribe', channel))
-      .catch(() => {})
-  }
-
-  const armWaker = (
-    channel: string,
-  ): { wakeup: Promise<void>; wake: () => void; disarm: () => void } => {
-    let wake!: () => void
-    const wakeup = new Promise<void>((resolve) => {
-      wake = resolve // assigned synchronously by the executor
-    })
-    let set = wakers.get(channel)
-    if (!set) {
-      set = new Set()
-      wakers.set(channel, set)
-    }
-    set.add(wake)
-    return {
-      wakeup,
-      wake,
-      disarm: () => {
-        set.delete(wake)
-        if (set.size === 0) wakers.delete(channel)
-      },
-    }
-  }
-
-  return {
-    append: core.append,
-    read: core.read,
-    claimAvailable: core.claimAvailable,
-    renewClaims: core.renewClaims,
-    completeAttempt: core.completeAttempt,
-    failAttempt: core.failAttempt,
-    readState: core.readState,
-    putSnapshots: core.putSnapshots,
-
-    presence: {
-      async set(ns, participant, values, meta) {
-        const patch = await core.presence.set(ns, participant, values, meta)
-        if (!patch) return
-        const channel = presenceChannel(ns)
-        const listeners = presenceListeners.get(channel)
-        if (listeners) {
-          for (const listener of listeners) listener(patch)
-        }
-        // Broadcast for other instances — best-effort like the notify
-        // PUBLISH (a failed one must never fail the applied write),
-        // but awaited so a patch can never reach a subscribe() that
-        // starts after this set resolved.
-        const message = JSON.stringify({
-          src: instanceId,
-          participant: patch.participant,
-          values: patch.values,
-          seen: patch.seen,
-          at: patch.at.getTime(),
-        } satisfies PresenceWireMessage)
-        await client()
-          .then((c) => c.call('publish', channel, message))
-          .catch(() => {})
-      },
-
-      read: core.presence.read,
-
-      subscribe(ns, onPatch) {
-        const channel = presenceChannel(ns)
-        let listeners = presenceListeners.get(channel)
-        if (!listeners) {
-          listeners = new Set()
-          presenceListeners.set(channel, listeners)
-        }
-        listeners.add(onPatch)
-        // Fire-and-forget on the shared refcounted subscription: it
-        // only carries remote patches, so settling late (or failing)
-        // degrades cross-instance latency, never same-process
-        // delivery.
-        void acquireChannel(channel).catch(() => {})
-        let stopped = false
-        return () => {
-          if (stopped) return
-          stopped = true
-          listeners.delete(onPatch)
-          if (listeners.size === 0) presenceListeners.delete(channel)
-          releaseChannel(channel)
-        }
-      },
-    },
-
-    stream(sessionId, opts) {
-      const startAfter = opts?.startAfter ?? 0
-      const channel = notifyChannel(sessionId)
-
-      return {
-        [Symbol.asyncIterator](): AsyncIterator<Event> {
-          let last = startAfter
-          let buffer: Event[] = []
-          let closed = false
-          let subscribed = false
-          let pending: Sleeper | null = null
-          let interrupt: (() => void) | null = null
-
-          const release = (): void => {
-            if (!subscribed) return
-            subscribed = false
-            releaseChannel(channel)
-          }
-
-          return {
-            async next(): Promise<IteratorResult<Event>> {
-              for (;;) {
-                if (closed) {
-                  release()
-                  return { value: undefined, done: true }
-                }
-                const row = buffer.shift()
-                if (row) {
-                  last = row.index
-                  return { value: row, done: false }
-                }
-                if (severed) {
-                  release()
-                  throw new A2Error('STORE_UNAVAILABLE', 'the store was closed')
-                }
-                const waker = armWaker(channel)
-                interrupt = waker.wake
-                try {
-                  if (!subscribed) {
-                    // Subscribe before reading: anything appended
-                    // after the read lands as a wake-up, so nothing
-                    // can slip between catch-up and park.
-                    // oxlint-disable-next-line no-await-in-loop -- one-time setup
-                    await acquireChannel(channel)
-                    subscribed = true
-                  }
-                  // Mark watched before reading, for the same reason:
-                  // a write after this read sees the marker and
-                  // publishes. Throttled — one SET per safety period
-                  // per session per process, shared across feeds.
-                  const markedAt = watchedRefreshedAt.get(channel) ?? 0
-                  if (Date.now() - markedAt >= NOTIFY_TIMINGS.safetyReadMs) {
-                    watchedRefreshedAt.set(channel, Date.now())
-                    // oxlint-disable-next-line no-await-in-loop -- live-feed loop
-                    await core.markWatched(
-                      sessionId,
-                      NOTIFY_TIMINGS.safetyReadMs * 3,
-                    )
-                  }
-                  // oxlint-disable-next-line no-await-in-loop -- live-feed loop
-                  buffer = await core.readEvents(sessionId, last)
-                  if (buffer.length === 0 && !closed && !severed) {
-                    pending = defaultSleep(NOTIFY_TIMINGS.safetyReadMs)
-                    // oxlint-disable-next-line no-await-in-loop -- live-feed loop
-                    await Promise.race([waker.wakeup, pending.promise])
-                    pending.cancel()
-                    pending = null
-                  }
-                } catch (err) {
-                  release()
-                  if (closed) return { value: undefined, done: true }
-                  if (err instanceof A2Error) throw err
-                  throw new A2Error(
-                    'STORE_UNAVAILABLE',
-                    'redis store operation failed',
-                    { cause: err },
-                  )
-                } finally {
-                  waker.disarm()
-                  interrupt = null
-                }
-              }
-            },
-            async return(): Promise<IteratorResult<Event>> {
-              closed = true
-              pending?.cancel()
-              interrupt?.() // wakes an in-flight next() immediately
-              release()
-              return { value: undefined, done: true }
-            },
-          }
-        },
-      }
-    },
-
-    async close() {
-      severed = true
-      for (const set of wakers.values()) {
-        for (const wake of set) wake()
-      }
-      if (subscriber) {
-        const sub = await subscriber.catch(() => null)
-        sub?.disconnect()
-      }
+    async closeClient() {
       const current = connection.peek()
       if (!current) return
       const c = await current.catch(() => null)
       c?.disconnect()
     },
-  }
+  })
 }

package/src/store.ts

@@ -321,10 +321,9 @@ export interface A2Store {
     read(ns: string): Promise<PresenceRow[]>
 
     /**
-     * Push-tier patch delivery; present only on backends with a real
-     * broadcast primitive. Without it the backend is the degraded
-     * tier: live feeds surface presence by re-reading on their
-     * existing poll cadence.
+     * Adapter-managed patch delivery. Without it, live feeds re-read
+     * presence on their poll cadence. HTTP Redis uses adaptive polling
+     * here when its endpoint does not support subscriptions.
      */
     subscribe?(ns: string, onPatch: (patch: PresencePatch) => void): () => void
   }

package/src/stream-activity.ts

@@ -0,0 +1,32 @@
+export type StreamActivity = {
+  readonly idle: boolean
+  setIdle(idle: boolean): void
+  activate(): void
+  subscribe(listener: (idle: boolean) => void): () => void
+}
+
+export const streamActivities: WeakMap<object, StreamActivity> = new WeakMap()
+
+export function createStreamActivity(wake: () => void): StreamActivity {
+  let idle = false
+  const listeners = new Set<(idle: boolean) => void>()
+  const setIdle = (next: boolean): void => {
+    if (idle === next) return
+    idle = next
+    for (const listener of listeners) listener(idle)
+  }
+  return {
+    get idle() {
+      return idle
+    },
+    setIdle,
+    activate() {
+      setIdle(false)
+      wake()
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+  }
+}

package/src/wire.ts

@@ -5,7 +5,7 @@
  * public.
  */
 
-import { A2Error, type A2ErrorCode } from './errors.ts'
+import { A2Error, type A2ErrorCode, type A2ServerErrorCode } from './errors.ts'
 import { nullProtoRecord } from './internal.ts'
 import type { Event } from './store.ts'
 import type {
@@ -171,10 +171,10 @@ export function isWirePresenceSnapshot(
 // ── the A2Error envelope ─────────────────────────────────────────────
 
 export type WireError = {
-  error: { code: A2ErrorCode; message: string; details?: unknown }
+  error: { code: A2ServerErrorCode; message: string; details?: unknown }
 }
 
-const ERROR_STATUS: Record<A2ErrorCode, number> = {
+const ERROR_STATUS: Record<A2ServerErrorCode, number> = {
   INVALID_PAYLOAD: 400,
   FORBIDDEN: 403,
   UNKNOWN_EVENT_TYPE: 400,
@@ -188,23 +188,27 @@ const ERROR_STATUS: Record<A2ErrorCode, number> = {
 }
 
 export function errorStatus(code: A2ErrorCode): number {
-  return ERROR_STATUS[code]
+  return ERROR_STATUS[isServerErrorCode(code) ? code : 'STORE_UNAVAILABLE']
 }
 
 export function errorToWire(error: A2Error): WireError {
+  const failure = asA2Error(error)
   const body: WireError = {
-    error: { code: error.code, message: error.message },
+    error: {
+      code: failure.code as A2ServerErrorCode,
+      message: failure.message,
+    },
   }
-  if (error.details !== undefined) body.error.details = error.details
+  if (failure.details !== undefined) body.error.details = failure.details
   return body
 }
 
-/** Wrap an arbitrary thrown value for the wire: A2Errors pass through,
+/** Wrap an arbitrary thrown value for the wire: known server codes pass through,
  * anything else becomes STORE_UNAVAILABLE — from the client's
  * perspective an unknown server failure is retryable-once, not a
  * protocol contract. */
 export function asA2Error(error: unknown): A2Error {
-  return error instanceof A2Error
+  return error instanceof A2Error && isServerErrorCode(error.code)
     ? error
     : new A2Error('STORE_UNAVAILABLE', 'internal error', { cause: error })
 }
@@ -215,13 +219,15 @@ export function errorFromWire(body: unknown): A2Error | null {
   const err = (body as { error?: unknown }).error
   if (err === null || typeof err !== 'object') return null
   const { code, message, details } = err as Record<string, unknown>
-  if (typeof code !== 'string' || !Object.hasOwn(ERROR_STATUS, code))
-    return null
-  return new A2Error(code as A2ErrorCode, String(message ?? code), {
+  if (typeof code !== 'string' || !isServerErrorCode(code)) return null
+  return new A2Error(code, String(message ?? code), {
     details,
   })
 }
 
+const isServerErrorCode = (code: string): code is A2ServerErrorCode =>
+  Object.hasOwn(ERROR_STATUS, code)
+
 // ── the ws frame layer ───────────────────────────────────────────────
 // The SSE lanes reframed for a socket (specs/a2-api.md §13): every
 // message is one JSON text frame, and a frame is its wire payload plus
@@ -254,7 +260,12 @@ export type SocketDownFrame =
   | { kind: 'ack'; req: number; events: WireEvent[]; sessionId?: string }
   | { kind: 'ack'; req: number; error: A2Error; sessionId?: string }
   | { kind: 'subscribed'; sessionId: string }
-  | { kind: 'unsubscribed'; sessionId: string; reason?: string }
+  | {
+      kind: 'unsubscribed'
+      sessionId: string
+      reason?: string
+      error?: A2Error
+    }
   | { kind: 'ping' }
 
 /**
@@ -361,11 +372,13 @@ export function socketSubscribedFor(sessionId: string): string {
 export function socketUnsubscribedFor(
   sessionId: string,
   reason?: string,
+  error?: A2Error,
 ): string {
   return JSON.stringify({
     kind: 'unsubscribed',
     sessionId,
     ...(reason === undefined ? {} : { reason }),
+    ...(error === undefined ? {} : errorToWire(error)),
   })
 }
 
@@ -417,9 +430,20 @@ export function parseSocketFrame(data: string): SocketDownFrame | null {
       const sessionId = frame['sessionId']
       if (typeof sessionId !== 'string') return null
       const reason = frame['reason']
-      return typeof reason === 'string'
-        ? { kind: 'unsubscribed', sessionId, reason }
-        : { kind: 'unsubscribed', sessionId }
+      const error =
+        errorFromWire(parsed) ??
+        ('error' in frame
+          ? new A2Error(
+              'STORE_UNAVAILABLE',
+              'unintelligible subscription error',
+            )
+          : null)
+      return {
+        kind: 'unsubscribed',
+        sessionId,
+        ...(typeof reason === 'string' ? { reason } : {}),
+        ...(error === null ? {} : { error }),
+      }
     }
     case 'ack': {
       const req = frame['req']