experimental-a2 0.10.0 → 0.12.0

package/src/presence-recovery.ts

@@ -0,0 +1,120 @@
+import type { PresencePatch } from './contract.ts'
+import type { PresenceRow } from './store.ts'
+
+type Field = Pick<PresenceRow, 'participant' | 'field' | 'seen' | 'at'>
+const key = ({
+  participant,
+  field,
+}: Pick<Field, 'participant' | 'field'>): string =>
+  JSON.stringify([participant, field])
+
+export function presenceRecovery({
+  read,
+  deliver,
+  isActive,
+}: {
+  read: () => Promise<PresenceRow[]>
+  deliver: (patch: PresencePatch) => void
+  isActive: () => boolean
+}): {
+  read(): Promise<PresenceRow[]>
+  reconnect(): Promise<void>
+  update(patch: PresencePatch): void
+} {
+  const fields = new Map<string, Field>()
+  const reading = new Set<Set<string>>()
+  let generation = 0
+  let latest: Promise<PresenceRow[]> | undefined
+
+  const remember = ({ participant, field, seen, at }: Field): void => {
+    const id = key({ participant, field })
+    const previous = fields.get(id)
+    if (
+      !previous ||
+      previous.at.getTime() < at.getTime() ||
+      (previous.at.getTime() === at.getTime() && previous.seen !== seen)
+    )
+      fields.set(id, { participant, field, seen, at })
+  }
+  const snapshot = async ({
+    reconcile,
+  }: {
+    reconcile: boolean
+  }): Promise<PresenceRow[]> => {
+    const run = generation
+    const before = new Map(fields)
+    const changed = new Set<string>()
+    reading.add(changed)
+    try {
+      const rows = await read()
+      if (!isActive()) return rows
+      if (run !== generation) return latest!
+      const live = new Set<string>()
+      for (const row of rows) {
+        const id = key(row)
+        live.add(id)
+        if (changed.has(id)) continue
+        remember(row)
+        if (reconcile)
+          deliver({
+            participant: row.participant,
+            values: { [row.field]: row.value },
+            seen: row.seen,
+            at: row.at,
+          })
+      }
+      if (reconcile) {
+        for (const [id, prior] of before) {
+          if (live.has(id) || changed.has(id) || fields.get(id) !== prior)
+            continue
+          fields.delete(id)
+          deliver({
+            participant: prior.participant,
+            values: { [prior.field]: null },
+            seen: prior.seen,
+            at: prior.at,
+          })
+        }
+      }
+      return rows
+    } finally {
+      reading.delete(changed)
+      if (reading.size === 0) latest = undefined
+    }
+  }
+
+  return {
+    async read() {
+      let pending = latest
+      while (pending) {
+        // oxlint-disable-next-line no-await-in-loop -- follow replacement reconnects before starting a fresh read
+        await pending
+        if (latest === pending) break
+        pending = latest
+      }
+      return snapshot({ reconcile: false })
+    },
+    async reconnect() {
+      generation += 1
+      latest = snapshot({ reconcile: true })
+      await latest
+    },
+    update(patch) {
+      for (const [field, value] of Object.entries(patch.values)) {
+        if (value === undefined) continue
+        const id = key({ participant: patch.participant, field })
+        const previous = fields.get(id)
+        if (previous && previous.at.getTime() > patch.at.getTime()) continue
+        for (const changed of reading) changed.add(id)
+        if (value === null) fields.delete(id)
+        else
+          remember({
+            participant: patch.participant,
+            field,
+            seen: patch.seen,
+            at: patch.at,
+          })
+      }
+    },
+  }
+}

package/src/react.ts

@@ -137,6 +137,8 @@ export type UseSessionResult<
    * back. Rejects with the server's A2Error codes.
    */
   push: (...events: AppendInput<D>[]) => PushResult<D>
+  /** Restart the live subscription without resetting its state or cursor. */
+  reconnect: () => void
   /**
    * Backscroll: fetch a bounded slice of older events into `events`.
    * Defaults page backward 50 at a time from the oldest loaded event.
@@ -316,6 +318,7 @@ function useSessionResult<D extends EventDefs, S, P extends PresenceDefs>(
       index: snapshot.index,
       connection: snapshot.connection,
       push: session.push,
+      reconnect: session.reconnect,
       loadHistory: session.loadHistory,
       history: snapshot.history,
       ...(setPresence && presence ? { presence, setPresence } : {}),

package/src/redis-http-subscriptions.ts

@@ -0,0 +1,199 @@
+import { A2Error } from './errors.ts'
+import { NOTIFY_TIMINGS } from './internal.ts'
+import { defaultSleep, type Sleeper } from './store-polling.ts'
+import type { RedisConnection } from './store-redis-notify.ts'
+
+export function redisHttpSubscriptions({
+  url,
+  token,
+  onReconnect,
+  fallback,
+}: {
+  url: string
+  token: string
+  onReconnect: (channel: string) => void
+  fallback: { enabled(): boolean; enable(): Promise<void> }
+}): RedisConnection {
+  const subscriptions = new Map<
+    string,
+    { ready: Promise<void>; stop(): void }
+  >()
+  const listeners = new Set<(channel: string, message: string) => void>()
+  let closed = false
+  let supported = false
+
+  const subscribe = (channel: string): Promise<void> => {
+    if (fallback.enabled()) return Promise.resolve()
+    const existing = subscriptions.get(channel)
+    if (existing) return existing.ready
+    let resolve!: () => void
+    let reject!: (error: unknown) => void
+    const ready = new Promise<void>((yes, no) => {
+      resolve = yes
+      reject = no
+    })
+    let stopped = false
+    let connected = false
+    let request: AbortController | undefined
+    let retry: Sleeper | undefined
+    const subscription = {
+      ready,
+      stop() {
+        stopped = true
+        request?.abort()
+        retry?.cancel()
+        resolve()
+      },
+    }
+    subscriptions.set(channel, subscription)
+
+    const run = async (): Promise<void> => {
+      let delay = 100
+      for (;;) {
+        if (stopped) return
+        request = new AbortController()
+        const timeout = setTimeout(
+          () => request?.abort(),
+          NOTIFY_TIMINGS.safetyReadMs,
+        )
+        let reader: ReadableStreamDefaultReader<Uint8Array> | undefined
+        let connectedAt: number | undefined
+        try {
+          // oxlint-disable-next-line no-await-in-loop -- reconnect loop
+          const response = await fetch(
+            `${url.replace(/\/$/, '')}/subscribe/${encodeURIComponent(channel)}`,
+            {
+              method: 'POST',
+              headers: {
+                authorization: `Bearer ${token}`,
+                accept: 'text/event-stream',
+              },
+              signal: request.signal,
+            },
+          )
+          if (!supported && [404, 405, 501].includes(response.status)) {
+            // oxlint-disable-next-line no-await-in-loop -- finish capability detection before falling back
+            await response.body?.cancel()
+            // oxlint-disable-next-line no-await-in-loop -- confirm that ordinary commands work
+            await fallback.enable()
+            for (const active of subscriptions.values()) active.stop()
+            subscriptions.clear()
+            return
+          }
+          if (
+            !response.ok ||
+            !response.headers
+              .get('content-type')
+              ?.startsWith('text/event-stream') ||
+            !response.body
+          ) {
+            // oxlint-disable-next-line no-await-in-loop -- release a failed subscription attempt
+            await response.body?.cancel()
+            throw new A2Error(
+              'STORE_UNAVAILABLE',
+              `redis rest subscription failed: status ${response.status}`,
+            )
+          }
+          reader = response.body.getReader()
+          const decoder = new TextDecoder()
+          let buffer = ''
+          let data: string[] = []
+          let acknowledged = false
+          for (;;) {
+            if (stopped) break
+            // oxlint-disable-next-line no-await-in-loop -- consume SSE chunks
+            const chunk = await reader.read()
+            if (chunk.done) break
+            buffer += decoder.decode(chunk.value, { stream: true })
+            let newline: number
+            while ((newline = buffer.indexOf('\n')) !== -1) {
+              const line = buffer.slice(0, newline).replace(/\r$/, '')
+              buffer = buffer.slice(newline + 1)
+              if (line.startsWith('data:')) {
+                data.push(line.slice(5).replace(/^ /, ''))
+              } else if (line === '' && data.length > 0) {
+                const message = data.join('\n')
+                data = []
+                if (message.startsWith(`subscribe,${channel},`)) {
+                  if (acknowledged) continue
+                  acknowledged = true
+                  supported = true
+                  clearTimeout(timeout)
+                  connectedAt = Date.now()
+                  resolve()
+                  if (connected) onReconnect(channel)
+                  connected = true
+                } else if (message.startsWith(`message,${channel},`)) {
+                  const payload = message.slice(`message,${channel},`.length)
+                  for (const listener of listeners) listener(channel, payload)
+                }
+              }
+            }
+          }
+          if (!connected && !stopped) {
+            throw new A2Error(
+              'STORE_UNAVAILABLE',
+              'redis rest subscription ended before acknowledgement',
+            )
+          }
+        } catch (error) {
+          if (!connected && !stopped) {
+            reject(error)
+            if (subscriptions.get(channel) === subscription)
+              subscriptions.delete(channel)
+            return
+          }
+        } finally {
+          clearTimeout(timeout)
+          request.abort()
+          // oxlint-disable-next-line no-await-in-loop -- close this attempt before reconnecting
+          await reader?.cancel().catch(() => {})
+          reader?.releaseLock()
+        }
+        if (stopped) return
+        if (
+          connectedAt !== undefined &&
+          Date.now() - connectedAt >= NOTIFY_TIMINGS.safetyReadMs
+        )
+          delay = 100
+        retry = defaultSleep(delay)
+        // oxlint-disable-next-line no-await-in-loop -- bounded reconnect backoff
+        await retry.promise
+        delay = Math.min(delay * 2, NOTIFY_TIMINGS.safetyReadMs)
+      }
+    }
+    void run()
+    return ready
+  }
+
+  const connection: RedisConnection = {
+    call(command, ...args) {
+      if (closed)
+        return Promise.reject(
+          new A2Error('STORE_UNAVAILABLE', 'the store was closed'),
+        )
+      const channel = String(args[0])
+      if (command === 'echo') return Promise.resolve(args[0])
+      if (command === 'subscribe') return subscribe(channel)
+      if (command === 'unsubscribe') {
+        subscriptions.get(channel)?.stop()
+        subscriptions.delete(channel)
+        return Promise.resolve(null)
+      }
+      return Promise.reject(
+        new Error(`unsupported subscription command: ${command}`),
+      )
+    },
+    duplicate: () => connection,
+    on(_event, listener) {
+      listeners.add(listener)
+    },
+    disconnect() {
+      closed = true
+      for (const subscription of subscriptions.values()) subscription.stop()
+      subscriptions.clear()
+      listeners.clear()
+    },
+  }
+  return connection
+}

package/src/server.ts

@@ -31,7 +31,8 @@ import {
   type DrainOutcome,
   type DrainResult,
 } from './internal.ts'
-import { defaultSleep } from './store-polling.ts'
+import { defaultSleep, type Sleeper } from './store-polling.ts'
+import { createStreamActivity, streamActivities } from './stream-activity.ts'
 import type {
   A2Store,
   AppendEvent,
@@ -300,6 +301,17 @@ export type HandlerEntry<
       handler: Handler<D, K, P>
     }
 
+type HandlerFunction = (ctx: never) => Promise<unknown>
+
+export function handler<
+  H extends HandlerFunction | { handler: HandlerFunction },
+>(entry: H): H extends HandlerFunction ? { handler: H } : H
+export function handler(
+  entry: HandlerFunction | { handler: HandlerFunction },
+): { handler: HandlerFunction } {
+  return typeof entry === 'function' ? { handler: entry } : entry
+}
+
 export type ServerOptions<
   D extends EventDefs,
   P extends PresenceDefs = Record<never, never>,
@@ -614,8 +626,8 @@ export function createServer<
         `contract '${name}' has no event type '${type}' — cannot register a handler for it`,
       )
     }
-    const handler = typeof entry === 'function' ? entry : entry?.handler
-    if (typeof handler !== 'function') {
+    const callback = typeof entry === 'function' ? entry : entry?.handler
+    if (typeof callback !== 'function') {
       throw new TypeError(`handler for '${type}' must be a function`)
     }
     let abortOn: AbortMatcher | null = null
@@ -659,7 +671,7 @@ export function createServer<
       )
     }
     handlers.set(type, {
-      handler: handler as Handler<D>,
+      handler: callback as Handler<D>,
       abortOn,
       lane: lane as Lane<D> | null,
     })
@@ -1377,12 +1389,59 @@ export function createServer<
     id: string,
     startAfter: number,
   ): AsyncIterable<ContractEvent<D>> => {
-    const store = resolveStore()
+    let closed = false
+    let inner: AsyncIterator<Event> | undefined
+    let stopActivity: (() => void) | undefined
+    const activity = createStreamActivity(() => {
+      if (inner && !closed) streamActivities.get(inner)?.activate()
+    })
+    let closing: Promise<void> | undefined
+    const close = (): Promise<void> => {
+      closed = true
+      closing ??= (async () => {
+        stopActivity?.()
+        await inner?.return?.()
+      })()
+      return closing
+    }
     const outer = async function* (): AsyncGenerator<ContractEvent<D>> {
-      const inner = (await store).stream(nsId(id), { startAfter })
-      for await (const event of inner) yield toSessionEvent(id, event)
+      const store = await resolveStore()
+      if (closed) return
+      inner = store.stream(nsId(id), { startAfter })[Symbol.asyncIterator]()
+      const sourceActivity = streamActivities.get(inner)
+      if (sourceActivity) {
+        stopActivity = sourceActivity.subscribe(activity.setIdle)
+        activity.setIdle(sourceActivity.idle)
+      }
+      try {
+        for (;;) {
+          if (closed) return
+          const result = await inner.next()
+          if (closed || result.done) return
+          yield toSessionEvent(id, result.value)
+        }
+      } finally {
+        await close()
+      }
+    }
+    const iterator = outer()
+    return {
+      [Symbol.asyncIterator]() {
+        const stream = {
+          next: () => iterator.next(),
+          async return() {
+            await close()
+            return iterator.return(undefined)
+          },
+          async throw(error: unknown) {
+            await close()
+            return iterator.throw(error)
+          },
+        }
+        streamActivities.set(stream, activity)
+        return stream
+      },
     }
-    return outer()
   }
 
   // ── presence ──────────────────────────────────────────────
@@ -1505,10 +1564,47 @@ export function createServer<
     startAfter: number,
   ): AsyncIterable<ContractEvent<D> | PresencePatch | PresenceSnapshot> => {
     const ns = nsId(id)
+    let closed = false
+    let events: AsyncIterator<Event> | undefined
+    let unsubscribe: (() => void) | undefined
+    let sleeper: Sleeper | null = null
+    let wakeQueue: (() => void) | null = null
+    let presenceInterval = Math.min(
+      POLL_TIMINGS.activeFloorMs,
+      POLL_TIMINGS.idleCeilingMs,
+    )
+    let presenceActivityVersion = 0
+    let stopActivity: (() => void) | undefined
+    const activity = createStreamActivity(() => {
+      if (closed) return
+      presenceActivityVersion += 1
+      presenceInterval = Math.min(
+        POLL_TIMINGS.activeFloorMs,
+        POLL_TIMINGS.idleCeilingMs,
+      )
+      sleeper?.cancel()
+      if (events) streamActivities.get(events)?.activate()
+    })
+    let closing: Promise<void> | undefined
+    const close = (): Promise<void> => {
+      closed = true
+      sleeper?.cancel()
+      wakeQueue?.()
+      closing ??= (async () => {
+        try {
+          stopActivity?.()
+          unsubscribe?.()
+        } finally {
+          await events?.return?.()
+        }
+      })()
+      return closing
+    }
     const outer = async function* (): AsyncGenerator<
       ContractEvent<D> | PresencePatch | PresenceSnapshot
     > {
       const store = await resolveStore()
+      if (closed) return
       const api = requirePresence(store)
 
       const readRows = async (): Promise<PresenceRow[]> => {
@@ -1614,8 +1710,9 @@ export function createServer<
         string,
         Map<string, { value: unknown; seen: number; at: Date }>
       >()
-      let wakeQueue: (() => void) | null = null
       const enqueue = (patch: PresencePatch): void => {
+        if (closed) return
+        activity.activate()
         for (const [field, value] of Object.entries(patch.values)) {
           if (value === undefined) continue
           let fields = queue.get(patch.participant)
@@ -1650,17 +1747,22 @@ export function createServer<
         }
         return null
       }
-      // Subscribe before the snapshot read: a patch landing between
-      // the two is painted twice, never lost — repaints are idempotent.
-      const unsubscribe = api.subscribe?.(ns, enqueue)
-
-      const events = store.stream(ns, { startAfter })[Symbol.asyncIterator]()
       let pendingEvent: Promise<IteratorResult<Event>> | null = null
       try {
+        // Subscribe before the snapshot read: a patch landing between
+        // the two is painted twice, never lost — repaints are idempotent.
+        unsubscribe = api.subscribe?.(ns, enqueue)
+        events = store.stream(ns, { startAfter })[Symbol.asyncIterator]()
+        const sourceActivity = streamActivities.get(events)
+        if (sourceActivity) {
+          stopActivity = sourceActivity.subscribe(activity.setIdle)
+          activity.setIdle(sourceActivity.idle)
+        }
         // Exactly one snapshot before any live item: the pruned map,
         // per-field stamps exact — a reconnecting client replaces its
         // foreign entries wholesale from it.
         const snapshotRows = await readRows()
+        if (closed) return
         for (const row of snapshotRows) {
           let fields = painted.get(row.participant)
           if (!fields) {
@@ -1676,9 +1778,11 @@ export function createServer<
         yield { snapshot: foldPresenceRows(snapshotRows) }
 
         for (;;) {
+          if (closed) return
           for (;;) {
             const patch = dequeue()
             if (!patch) break
+            if (closed) return
             paint(patch)
             yield patch
           }
@@ -1693,35 +1797,69 @@ export function createServer<
               arrival.then(() => 'patch' as const),
             ])
             wakeQueue = null
+            if (closed) return
             if (woke === 'patch') continue
           } else {
-            const sleeper = defaultSleep(POLL_TIMINGS.idleCeilingMs)
+            sleeper = defaultSleep(presenceInterval)
             woke = await Promise.race([
               pendingEvent.then(() => 'event' as const),
               sleeper.promise.then(() => 'tick' as const),
             ])
             sleeper.cancel()
+            sleeper = null
           }
+          if (closed) return
           if (woke === 'event') {
             const result = await pendingEvent
             pendingEvent = null
-            if (result.done) return
+            if (closed || result.done) return
+            activity.activate()
             yield toSessionEvent(id, result.value)
           }
-          if (!unsubscribe) {
-            for (const patch of diffRows(await readRows())) yield patch
+          if (!closed && !unsubscribe) {
+            const version = presenceActivityVersion
+            const rows = await readRows()
+            if (closed) return
+            const patches = diffRows(rows)
+            if (patches.length > 0) activity.activate()
+            else if (version === presenceActivityVersion) {
+              presenceInterval = Math.min(
+                presenceInterval * 2,
+                POLL_TIMINGS.idleCeilingMs,
+              )
+            }
+            for (const patch of patches) {
+              if (closed) return
+              yield patch
+            }
           }
         }
       } finally {
-        wakeQueue = null
-        unsubscribe?.()
         // The consumer may close while an event read is in flight; its
         // settlement is no longer anyone's business.
         pendingEvent?.catch(() => {})
-        await events.return?.()
+        await close()
+        wakeQueue = null
       }
     }
-    return outer()
+    const iterator = outer()
+    return {
+      [Symbol.asyncIterator]() {
+        const stream = {
+          next: () => iterator.next(),
+          async return() {
+            await close()
+            return iterator.return(undefined)
+          },
+          async throw(error: unknown) {
+            await close()
+            return iterator.throw(error)
+          },
+        }
+        streamActivities.set(stream, activity)
+        return stream
+      },
+    }
   }
 
   const makeSession = <Append>(