experimental-a2 0.9.0 → 0.11.0

package/src/store-redis-notify.ts

@@ -0,0 +1,464 @@
+import type { PresencePatch } from './contract.ts'
+import { A2Error } from './errors.ts'
+import { NOTIFY_TIMINGS } 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 type { A2Store, Clock, Event, IdSource } from './store.ts'
+
+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
+}
+
+type PresenceWireMessage = {
+  src: string
+  participant: string
+  values: Record<string, unknown>
+  seen: number
+  at: number
+}
+
+type PresenceSubscription = {
+  listeners: Set<(patch: PresencePatch) => void>
+  poll?: ReturnType<typeof pollPresence> | undefined
+  recovery?: ReturnType<typeof presenceRecovery> | undefined
+}
+
+export function createRedisNotifyStore(options: {
+  client: () => Promise<RedisConnection>
+  closeClient: () => Promise<void>
+  clock: Clock
+  ids: IdSource
+  keyPrefix: string
+  onReconnect?: (listener: (channel: string) => void) => void
+  polling?: () => boolean
+}): A2Store & { close(): Promise<void> } {
+  const { client, clock, ids, keyPrefix: prefix } = options
+  const notifyChannel = (sessionId: string): string =>
+    `${prefix}:${sessionId}:notify`
+  const presenceChannel = (ns: string): string => `${prefix}:${ns}:presence`
+
+  const instanceId = crypto.randomUUID()
+  const core = createRedisStoreCore({
+    call: async (command, ...args) => {
+      const c = await client()
+      return c.call(command, ...args)
+    },
+    clock,
+    ids,
+    keyPrefix: prefix,
+    presenceSource: instanceId,
+  })
+
+  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 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()
+    void presenceSubscriptions
+      .get(channel)
+      ?.recovery?.reconnect()
+      .catch(() => {})
+  })
+
+  const deliverRemotePresence = ({
+    subscription,
+    message,
+  }: {
+    subscription: PresenceSubscription
+    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),
+    }
+    subscription.recovery?.update(patch)
+    for (const listener of subscription.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 subscription = presenceSubscriptions.get(channel)
+        if (subscription) deliverRemotePresence({ subscription, 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: number; ready: Promise<void> } = {
+      refs: 1,
+      // Lowercase on purpose: ioredis keys its subscriber-mode
+      // bookkeeping (and reconnect resubscription) on the exact
+      // command name.
+      ready: gatedSubscriber().then(async (conn) => {
+        await conn.call('subscribe', channel)
+        if (subscriptions.get(channel) !== lease || severed) return
+        const presence = presenceSubscriptions.get(channel)
+        if (options.polling?.() && presence) {
+          presence.recovery = undefined
+          const ns = channel.slice(prefix.length + 1, -':presence'.length)
+          presence.poll = pollPresence({
+            read: () => core.presence.read(ns),
+            deliver: (patch) => {
+              for (const listener of presence.listeners) listener(patch)
+            },
+          })
+          await presence.poll.ready
+        }
+        return undefined
+      }),
+    }
+    subscriptions.set(channel, lease)
+    try {
+      await lease.ready
+    } catch (err) {
+      if (subscriptions.get(channel) === lease) {
+        subscriptions.delete(channel)
+        const presence = presenceSubscriptions.get(channel)
+        presence?.poll?.stop()
+        if (presence) presence.poll = undefined
+      }
+      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)
+    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 {
+    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 subscription = presenceSubscriptions.get(channel)
+        if (subscription) {
+          subscription.poll?.update(patch)
+          subscription.recovery?.update(patch)
+          for (const listener of subscription.listeners) listener(patch)
+        }
+      },
+
+      async read(ns) {
+        const channel = presenceChannel(ns)
+        await subscriptions.get(channel)?.ready
+        return (
+          presenceSubscriptions.get(channel)?.recovery?.read() ??
+          core.presence.read(ns)
+        )
+      },
+
+      subscribe(ns, onPatch) {
+        const channel = presenceChannel(ns)
+        let subscription = presenceSubscriptions.get(channel)
+        if (!subscription) {
+          subscription = { listeners: new Set() }
+          presenceSubscriptions.set(channel, subscription)
+          if (options.onReconnect && !options.polling?.()) {
+            const current = subscription
+            subscription.recovery = presenceRecovery({
+              read: () => core.presence.read(ns),
+              deliver: (patch) => {
+                for (const listener of current.listeners) listener(patch)
+              },
+              isActive: () =>
+                !severed && presenceSubscriptions.get(channel) === current,
+            })
+          }
+        }
+        subscription.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
+          subscription.listeners.delete(onPatch)
+          if (subscription.listeners.size === 0) {
+            subscription.poll?.stop()
+            presenceSubscriptions.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
+          let poller: AsyncIterator<Event> | undefined
+          let stopActivity: (() => void) | undefined
+          const activity = createStreamActivity(() => {
+            if (poller) streamActivities.get(poller)?.activate()
+          })
+
+          const release = (): void => {
+            stopActivity?.()
+            if (poller) {
+              void poller.return?.()
+              pollingStreams.delete(poller)
+            }
+            if (!subscribed) return
+            subscribed = false
+            releaseChannel(channel)
+          }
+
+          const iterator: AsyncIterator<Event> = {
+            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.
+                    subscribed = true
+                    // oxlint-disable-next-line no-await-in-loop -- one-time setup
+                    await acquireChannel(channel)
+                    if (closed || severed) continue
+                  }
+                  if (options.polling?.()) {
+                    if (!poller) {
+                      poller = pollingStream(
+                        (after) => core.readEvents(sessionId, after),
+                        { startAfter: last },
+                      )[Symbol.asyncIterator]()
+                      pollingStreams.add(poller)
+                      stopActivity = streamActivities
+                        .get(poller)
+                        ?.subscribe(activity.setIdle)
+                    }
+                    // oxlint-disable-next-line no-await-in-loop -- delegate the fallback to the shared poller
+                    const result = await poller.next()
+                    if (!result.done)
+                      presenceSubscriptions
+                        .get(presenceChannel(sessionId))
+                        ?.poll?.wake()
+                    if (severed)
+                      throw new A2Error(
+                        'STORE_UNAVAILABLE',
+                        'the store was closed',
+                      )
+                    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)
+                  }
+                  // 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)
+                    // 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 }
+            },
+          }
+          streamActivities.set(iterator, activity)
+          return iterator
+        },
+      }
+    },
+
+    async close() {
+      severed = true
+      for (const subscription of presenceSubscriptions.values())
+        subscription.poll?.stop()
+      presenceSubscriptions.clear()
+      for (const poller of pollingStreams) void poller.return?.()
+      pollingStreams.clear()
+      for (const set of wakers.values()) {
+        for (const wake of set) wake()
+      }
+      if (subscriber) {
+        const sub = await subscriber.catch(() => null)
+        sub?.disconnect()
+      }
+      await options.closeClient()
+    },
+  }
+}