experimental-a2 0.16.0 → 0.17.0

package/src/store-redis-http.ts

@@ -1,6 +1,11 @@
 import { A2Error } from './errors.ts'
 import { NOTIFY_TIMINGS } from './internal.ts'
 import { redisHttpSubscriptions } from './redis-http-subscriptions.ts'
+import {
+  readRedisStreamPage,
+  REDIS_HTTP_STREAM_READ_COUNT,
+} from './redis-http-stream.ts'
+import type { RedisStreamRead } from './store-redis-core.ts'
 import {
   createRedisNotifyStore,
   type RedisConnection,
@@ -74,6 +79,14 @@ export function redisHttp(options: RedisHttpStoreOptions): RedisHttpStore {
     return body.result
   }
 
+  const readStream: RedisStreamRead = (read) =>
+    readRedisStreamPage({
+      ...read,
+      url,
+      token,
+      count: REDIS_HTTP_STREAM_READ_COUNT,
+    })
+
   let subscriber: RedisConnection | undefined
   let onReconnect: ((channel: string) => void) | undefined
   const client: RedisConnection = {
@@ -85,7 +98,7 @@ export function redisHttp(options: RedisHttpStoreOptions): RedisHttpStore {
         onReconnect: (channel) => onReconnect?.(channel),
         fallback: {
           enabled: () => polling,
-          enable() {
+          checkCommands() {
             fallbackCheck ??= call('PING')
               .then((result) => {
                 if (result !== 'PONG')
@@ -93,7 +106,6 @@ export function redisHttp(options: RedisHttpStoreOptions): RedisHttpStore {
                     'STORE_UNAVAILABLE',
                     'redis rest capability check failed',
                   )
-                polling = true
                 return undefined
               })
               .catch((error: unknown) => {
@@ -102,6 +114,9 @@ export function redisHttp(options: RedisHttpStoreOptions): RedisHttpStore {
               })
             return fallbackCheck
           },
+          enable() {
+            polling = true
+          },
         },
       })),
     on() {},
@@ -117,5 +132,6 @@ export function redisHttp(options: RedisHttpStoreOptions): RedisHttpStore {
     clock: options.clock ?? SYSTEM_CLOCK,
     ids: options.ids ?? RANDOM_IDS,
     keyPrefix: options.keyPrefix ?? 'a2',
+    readStream,
   })
 }

package/src/store-redis-notify.ts

@@ -1,11 +1,23 @@
 import type { PresencePatch } from './contract.ts'
 import { A2Error } from './errors.ts'
-import { NOTIFY_TIMINGS } from './internal.ts'
+import { NOTIFY_TIMINGS, stateTailReaders } from './internal.ts'
 import { defaultSleep, pollingStream, type Sleeper } from './store-polling.ts'
 import { pollPresence } from './store-presence-polling.ts'
 import { presenceRecovery } from './presence-recovery.ts'
 import { createStreamActivity, streamActivities } from './stream-activity.ts'
-import { createRedisStoreCore } from './store-redis-core.ts'
+import {
+  bufferedEvents,
+  isSerializedEvent,
+  parseSerializedEvent,
+  type HeldEvent,
+  type SerializedEvent,
+} from './stream-buffer.ts'
+import {
+  createRedisStoreCore,
+  FEED_PAGE_SIZE,
+  type RedisCall,
+  type RedisStreamRead,
+} from './store-redis-core.ts'
 import type { A2Store, Clock, Event, IdSource } from './store.ts'
 
 export type RedisConnection = {
@@ -32,14 +44,72 @@ type PresenceSubscription = {
   recovery?: ReturnType<typeof presenceRecovery> | undefined
 }
 
+/**
+ * One live event feed's view of its channel: wake-up messages received
+ * since it subscribed, whether it must catch up with XRANGE before trusting
+ * them, and the resolver of its park, if parked.
+ */
+type Feed = {
+  inbox: string[]
+  bytes: number
+  dirty: boolean
+  wake: (() => void) | null
+  stopRead: () => Promise<void>
+}
+
+/** A feed that falls this far behind drops its inbox and catches up. */
+const INBOX_BYTES = 512 * 1024
+
+type WakeEntry = [index: number, id: string, type: string, payload: unknown]
+
+/**
+ * Parses a wake-up message: `{"f":frontier}` or a bare frontier number
+ * announces events without carrying them; `{"f","t","e"}` carries them.
+ * Returns null for anything else, which callers treat as a hint to catch up.
+ */
+const parseWake = (
+  message: string,
+): { frontier: number; createdAt: number; entries: WakeEntry[] } | null => {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(message)
+  } catch {
+    return null
+  }
+  if (typeof parsed === 'number') {
+    return Number.isSafeInteger(parsed)
+      ? { frontier: parsed, createdAt: 0, entries: [] }
+      : null
+  }
+  if (typeof parsed !== 'object' || parsed === null) return null
+  const { f, t, e } = parsed as { f?: unknown; t?: unknown; e?: unknown }
+  if (typeof f !== 'number' || !Number.isSafeInteger(f)) return null
+  if (e === undefined) return { frontier: f, createdAt: 0, entries: [] }
+  if (!Array.isArray(e) || typeof t !== 'number' || !Number.isFinite(t))
+    return null
+  for (const entry of e) {
+    if (
+      !Array.isArray(entry) ||
+      entry.length !== 4 ||
+      !Number.isSafeInteger(entry[0]) ||
+      typeof entry[1] !== 'string' ||
+      typeof entry[2] !== 'string'
+    )
+      return null
+  }
+  return { frontier: f, createdAt: t, entries: e as WakeEntry[] }
+}
+
 export function createRedisNotifyStore(options: {
   client: () => Promise<RedisConnection>
+  callBytes?: RedisCall
   closeClient: () => Promise<void>
   clock: Clock
   ids: IdSource
   keyPrefix: string
   onReconnect?: (listener: (channel: string) => void) => void
   polling?: () => boolean
+  readStream?: RedisStreamRead
 }): A2Store & { close(): Promise<void> } {
   const { client, clock, ids, keyPrefix: prefix } = options
   const notifyChannel = (sessionId: string): string =>
@@ -56,31 +126,27 @@ export function createRedisNotifyStore(options: {
     ids,
     keyPrefix: prefix,
     presenceSource: instanceId,
+    ...(options.callBytes ? { callBytes: options.callBytes } : {}),
+    ...(options.readStream ? { readStream: options.readStream } : {}),
   })
 
   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 → live event feeds, registered before they subscribe. */
+  const feeds = new Map<string, Set<Feed>>()
   /** 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 watched = new Map<string, { at: number; ready: Promise<void> }>()
   const presenceSubscriptions = new Map<string, PresenceSubscription>()
   const pollingStreams = new Set<AsyncIterator<Event>>()
 
   options.onReconnect?.((channel) => {
-    for (const wake of wakers.get(channel) ?? []) wake()
+    for (const feed of feeds.get(channel) ?? []) {
+      feed.dirty = true
+      feed.wake?.()
+    }
     void presenceSubscriptions
       .get(channel)
       ?.recovery?.reconnect()
@@ -115,11 +181,16 @@ export function createRedisNotifyStore(options: {
     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()
+        for (const feed of feeds.get(channel) ?? []) {
+          if (feed.bytes + message.length <= INBOX_BYTES) {
+            feed.inbox.push(message)
+            feed.bytes += message.length
+          } else {
+            feed.inbox.length = 0
+            feed.bytes = 0
+            feed.dirty = true
+          }
+          feed.wake?.()
         }
         const subscription = presenceSubscriptions.get(channel)
         if (subscription) deliverRemotePresence({ subscription, message })
@@ -204,36 +275,12 @@ export function createRedisNotifyStore(options: {
     lease.refs -= 1
     if (lease.refs > 0) return
     subscriptions.delete(channel)
-    watched.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 {
+  const store: A2Store & { close(): Promise<void> } = {
     append: core.append,
     read: core.read,
     readHistory: core.readHistory!,
@@ -243,6 +290,8 @@ export function createRedisNotifyStore(options: {
     failAttempt: core.failAttempt,
     readState: core.readState,
     putSnapshots: core.putSnapshots,
+    clear: core.clear!,
+    reclaim: core.reclaim!,
 
     presence: {
       async set(ns, participant, values, meta) {
@@ -311,18 +360,68 @@ export function createRedisNotifyStore(options: {
       return {
         [Symbol.asyncIterator](): AsyncIterator<Event> {
           let last = startAfter
-          let buffer: Event[] = []
+          let buffer: HeldEvent[] = []
           let closed = false
           let subscribed = false
           let pending: Sleeper | null = null
-          let interrupt: (() => void) | null = null
           let poller: AsyncIterator<Event> | undefined
           let stopActivity: (() => void) | undefined
+          let catchup:
+            | {
+                controller: AbortController
+                iterator: AsyncGenerator<SerializedEvent[], void>
+                delivered: boolean
+              }
+            | undefined
+          let stoppingRead: Promise<void> | undefined
+          const stopRead = (): Promise<void> => {
+            const reading = catchup
+            catchup = undefined
+            if (reading) {
+              reading.controller.abort()
+              stoppingRead = reading.iterator
+                .return(undefined)
+                .then(() => undefined)
+                .catch(() => {})
+            }
+            return stoppingRead ?? Promise.resolve()
+          }
+          const nextRead = async (
+            after: number,
+          ): Promise<IteratorResult<SerializedEvent[], void>> => {
+            if (!catchup) {
+              const controller = new AbortController()
+              catchup = {
+                controller,
+                delivered: false,
+                iterator: core.streamEvents!({
+                  sessionId,
+                  afterIndex: after,
+                  signal: controller.signal,
+                })[Symbol.asyncIterator](),
+              }
+            }
+            const reading = catchup
+            const result = await reading.iterator.next()
+            if (result.done && catchup === reading) {
+              catchup = undefined
+              if (reading.delivered) feed.dirty = true
+            } else if (!result.done) reading.delivered = true
+            return result
+          }
+          const feed: Feed = {
+            inbox: [],
+            bytes: 0,
+            dirty: true,
+            wake: null,
+            stopRead,
+          }
           const activity = createStreamActivity(() => {
             if (poller) streamActivities.get(poller)?.activate()
           })
 
           const release = (): void => {
+            void stopRead()
             stopActivity?.()
             if (poller) {
               void poller.return?.()
@@ -330,9 +429,46 @@ export function createRedisNotifyStore(options: {
             }
             if (!subscribed) return
             subscribed = false
+            const set = feeds.get(channel)
+            set?.delete(feed)
+            if (set?.size === 0) feeds.delete(channel)
             releaseChannel(channel)
           }
 
+          /**
+           * Moves carried events that continue this feed's sequence into
+           * the buffer. A gap, a message without events, or an unreadable
+           * message marks the feed dirty so it catches up with XRANGE.
+           */
+          const applyInbox = (): void => {
+            feed.bytes = 0
+            for (const message of feed.inbox.splice(0)) {
+              const wake = parseWake(message)
+              if (!wake) {
+                feed.dirty = true
+                continue
+              }
+              for (const [index, id, type, payload] of wake.entries) {
+                const expected = (buffer.at(-1)?.index ?? last) + 1
+                if (index < expected) continue
+                if (index > expected) {
+                  feed.dirty = true
+                  break
+                }
+                buffer.push({
+                  id,
+                  type,
+                  payload,
+                  index,
+                  sessionId,
+                  createdAt: new Date(wake.createdAt),
+                })
+              }
+              if (wake.frontier > (buffer.at(-1)?.index ?? last))
+                feed.dirty = true
+            }
+          }
+
           const iterator: AsyncIterator<Event> = {
             async next(): Promise<IteratorResult<Event>> {
               for (;;) {
@@ -342,21 +478,41 @@ export function createRedisNotifyStore(options: {
                 }
                 const row = buffer.shift()
                 if (row) {
+                  let event: Event
+                  try {
+                    event = isSerializedEvent(row)
+                      ? parseSerializedEvent(row)
+                      : row
+                  } catch (cause) {
+                    // A retry re-reads from the last delivered event.
+                    buffer = []
+                    feed.dirty = true
+                    release()
+                    throw new A2Error(
+                      'STORE_UNAVAILABLE',
+                      'redis stream read failed',
+                      { cause },
+                    )
+                  }
                   last = row.index
-                  return { value: row, done: false }
+                  return { value: event, 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.
+                    // Register and subscribe before the first read:
+                    // anything appended after it arrives in the inbox,
+                    // so nothing slips between catch-up and park.
                     subscribed = true
+                    let set = feeds.get(channel)
+                    if (!set) {
+                      set = new Set()
+                      feeds.set(channel, set)
+                    }
+                    set.add(feed)
                     // oxlint-disable-next-line no-await-in-loop -- one-time setup
                     await acquireChannel(channel)
                     if (closed || severed) continue
@@ -385,37 +541,43 @@ export function createRedisNotifyStore(options: {
                       )
                     return result
                   }
-                  // 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.
-                  let marker = watched.get(channel)
-                  if (
-                    !marker ||
-                    Date.now() - marker.at >= NOTIFY_TIMINGS.safetyReadMs
-                  ) {
-                    marker = {
-                      at: Date.now(),
-                      ready: core.markWatched(
-                        sessionId,
-                        NOTIFY_TIMINGS.safetyReadMs * 3,
-                      ),
-                    }
-                    watched.set(channel, marker)
+                  if (catchup) {
+                    // oxlint-disable-next-line no-await-in-loop -- decode the next catch-up batch on demand
+                    const result = await nextRead(last)
+                    if (closed || severed) continue
+                    if (!result.done) buffer = result.value
+                    continue
                   }
-                  // Every viewer waits until writers can observe the marker.
-                  // oxlint-disable-next-line no-await-in-loop -- live-feed loop
-                  await marker.ready
-                  if (closed || severed) continue
-                  // 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)
+                  applyInbox()
+                  if (buffer.length > 0) continue
+                  if (feed.dirty) {
+                    feed.dirty = false
+                    if (core.streamEvents) {
+                      // oxlint-disable-next-line no-await-in-loop -- begin an incremental catch-up
+                      const result = await nextRead(last)
+                      if (closed || severed) continue
+                      if (!result.done) buffer = result.value
+                      continue
+                    }
                     // oxlint-disable-next-line no-await-in-loop -- live-feed loop
-                    await Promise.race([waker.wakeup, pending.promise])
-                    pending.cancel()
-                    pending = null
+                    buffer = await core.readFeedPage(sessionId, last)
+                    if (buffer.length >= FEED_PAGE_SIZE) feed.dirty = true
+                    continue
                   }
+                  // Caught up: park until a message, a reconnect, or the
+                  // safety read that heals a lost message.
+                  const woken = new Promise<'wake'>((resolve) => {
+                    feed.wake = () => resolve('wake')
+                  })
+                  pending = defaultSleep(NOTIFY_TIMINGS.safetyReadMs)
+                  // oxlint-disable-next-line no-await-in-loop -- live-feed loop
+                  const outcome = await Promise.race([
+                    woken,
+                    pending.promise.then(() => 'timer' as const),
+                  ])
+                  pending.cancel()
+                  pending = null
+                  if (outcome === 'timer') feed.dirty = true
                 } catch (err) {
                   release()
                   if (closed) return { value: undefined, done: true }
@@ -426,20 +588,26 @@ export function createRedisNotifyStore(options: {
                     { cause: err },
                   )
                 } finally {
-                  waker.disarm()
-                  interrupt = null
+                  feed.wake = null
                 }
               }
             },
             async return(): Promise<IteratorResult<Event>> {
               closed = true
               pending?.cancel()
-              interrupt?.() // wakes an in-flight next() immediately
+              feed.wake?.() // wakes an in-flight next() immediately
               release()
+              await stopRead()
               return { value: undefined, done: true }
             },
           }
           streamActivities.set(iterator, activity)
+          bufferedEvents.set(iterator, () => {
+            if (closed) return undefined
+            const row = buffer.shift()
+            if (row) last = row.index
+            return row
+          })
           return iterator
         },
       }
@@ -452,9 +620,14 @@ export function createRedisNotifyStore(options: {
       presenceSubscriptions.clear()
       for (const poller of pollingStreams) void poller.return?.()
       pollingStreams.clear()
-      for (const set of wakers.values()) {
-        for (const wake of set) wake()
+      const reads: Promise<void>[] = []
+      for (const set of feeds.values()) {
+        for (const feed of set) {
+          feed.wake?.()
+          reads.push(feed.stopRead())
+        }
       }
+      await Promise.allSettled(reads)
       if (subscriber) {
         const sub = await subscriber.catch(() => null)
         sub?.disconnect()
@@ -462,4 +635,6 @@ export function createRedisNotifyStore(options: {
       await options.closeClient()
     },
   }
+  stateTailReaders.set(store, core.readTail)
+  return store
 }

package/src/store-redis.ts

@@ -4,15 +4,14 @@
  * with experimental-a2/store-redis-http); this module owns the connection and
  * the live feed.
  *
- * `stream()` is notify-driven: writes to watched sessions fire a
- * disposable PUBLISH wake-up (feeds hold a TTL'd presence marker the
- * write script checks, so unwatched sessions cost no wake-up), one
- * shared subscriber connection per backend serves every local feed,
- * and each wake triggers an `XRANGE` catch-up read. The notification
- * only decides when to read, never what — a lost one is healed by a
- * safety re-read (NOTIFY_TIMINGS), so delivery never depends on
- * pub/sub. Connections scale with processes (one command client plus
- * one subscriber), not with concurrent viewers.
+ * `stream()` is notify-driven: every write publishes a wake-up that
+ * carries the appended events, one shared subscriber connection per backend
+ * serves every local feed, and a caught-up feed applies carried events that
+ * continue its sequence without reading. A gap, an oversized batch, a
+ * reconnect, or the safety re-read (NOTIFY_TIMINGS) triggers an `XRANGE`
+ * catch-up, so a lost wake-up costs latency, never delivery. Connections
+ * scale with processes (one command client plus one subscriber), not with
+ * concurrent viewers.
  *
  * Works with any Redis-protocol server on a single instance or a
  * non-cluster provider (Upstash — durable by default — Redis, Valkey).
@@ -27,6 +26,7 @@ import {
   type RedisConnection,
 } from './store-redis-notify.ts'
 import { retryableLazy } from './retryable-lazy.ts'
+import type { RedisCall } from './store-redis-core.ts'
 import {
   RANDOM_IDS,
   SYSTEM_CLOCK,
@@ -89,6 +89,16 @@ export function redis(options: RedisStoreOptions = {}): RedisStore {
 
   return createRedisNotifyStore({
     client,
+    // Only a client created from `url` is known to be ioredis, whose
+    // `callBuffer` returns bulk replies as raw bytes.
+    ...(options.client
+      ? {}
+      : {
+          callBytes: async (command, ...args) =>
+            (
+              (await client()) as RedisConnection & { callBuffer: RedisCall }
+            ).callBuffer(command, ...args),
+        }),
     clock,
     ids,
     keyPrefix: prefix,