experimental-a2 0.9.0 → 0.11.0

package/src/session-socket.ts

@@ -1,14 +1,14 @@
 /**
  * The A2 socket protocol's server half (specs/a2-api.md §13): the
  * per-socket shell — teardown, backpressure, heartbeat, the malformed
- * budget, the in-flight bound — and `sessionsSocket`, the multiplexed
- * frame handler riding it. Internal module: `handle`'s upgrade lane is
- * the sanctioned mount; only `A2Socket` (the structural socket the
- * platform hands over) is re-exported as public surface.
+ * budget, and the in-flight bound. `sessionSocket` binds one session to
+ * one socket; `sessionsSocket` is the opt-in multiplexed handler. Only
+ * `A2Socket`, the structural socket the platform hands over, is public.
  */
 
 import { A2Error } from './errors.ts'
 import { SOCKET_TIMINGS, STREAM_TIMINGS } from './internal.ts'
+import { streamActivities } from './stream-activity.ts'
 import type { Event } from './store.ts'
 import type { EventDefs, PresencePatch, PresenceSnapshot } from './contract.ts'
 import type { ParsedPushEvent, ParsedPushPresence } from './push-envelope.ts'
@@ -256,17 +256,214 @@ export type SessionsSocketOptions = {
   ): A2Error | null | Promise<A2Error | null>
 }
 
+export type SessionSocketOptions = SessionsSocketOptions & {
+  startAfter?: number
+}
+
 type SocketSubscription = {
   target: SocketSession
   iterator: AsyncIterator<Event | PresencePatch | PresenceSnapshot>
   stopped: boolean
 }
 
+const socketSubscription = (
+  target: SocketSession,
+  startAfter: number,
+  presence: boolean,
+): SocketSubscription => ({
+  target,
+  iterator: (presence
+    ? target.stream({ startAfter, presence: true })
+    : target.stream({ startAfter }))[Symbol.asyncIterator](),
+  stopped: false,
+})
+
 const stopSubscription = (subscription: SocketSubscription): void => {
   subscription.stopped = true
   void subscription.iterator.return?.()?.catch(() => {})
 }
 
+const pumpSubscription = async (
+  shell: SocketShell,
+  subscription: SocketSubscription,
+  frameFor: (item: Event | PresencePatch | PresenceSnapshot) => string,
+): Promise<void> => {
+  for (;;) {
+    while (
+      !shell.torn() &&
+      !subscription.stopped &&
+      shell.buffered() > SOCKET_TIMINGS.highWaterMarkBytes
+    ) {
+      // oxlint-disable-next-line no-await-in-loop -- backpressure park
+      await new Promise((wake) => setTimeout(wake, SOCKET_TIMINGS.resumePollMs))
+    }
+    if (shell.torn() || subscription.stopped) return
+    // oxlint-disable-next-line no-await-in-loop -- stream pump
+    const { value, done } = await subscription.iterator.next()
+    if (shell.torn() || subscription.stopped || done) return
+    shell.send(frameFor(value))
+  }
+}
+
+const handleSocketPush = async (
+  shell: SocketShell,
+  target: SocketSession,
+  sessionId: string,
+  frame: Record<string, unknown>,
+  req: number,
+  ackSessionId: string | undefined,
+  gatePush: SessionsSocketOptions['gatePush'],
+  activate: () => void,
+): Promise<void> => {
+  try {
+    const events = parsePushEvents(frame['events'])
+    const denial = (await gatePush?.(sessionId, events, undefined)) ?? null
+    if (denial !== null) {
+      shell.send(socketErrorAckFor(req, denial, ackSessionId))
+      return
+    }
+    activate()
+    // oxlint-disable-next-line a2/await-handler-append -- this transport append is awaited before its ack
+    const appended = await target.append(...events)
+    activate()
+    shell.send(socketAckFor(req, appended, ackSessionId))
+  } catch (error) {
+    shell.send(socketErrorAckFor(req, asA2Error(error), ackSessionId))
+  }
+}
+
+const applySocketPresence = async (
+  shell: SocketShell,
+  target: SocketSession,
+  sessionId: string,
+  frame: Record<string, unknown>,
+  gatePush: SessionsSocketOptions['gatePush'],
+): Promise<void> => {
+  if (typeof target.setPresence !== 'function') {
+    shell.malformedFrame('presence frame on a presence-less session')
+    return
+  }
+  let patch: ParsedPushPresence | undefined
+  try {
+    patch = parsePresenceSibling(frame)
+  } catch {
+    shell.malformedFrame('invalid presence frame')
+    return
+  }
+  if (!patch) return
+  try {
+    const denial = (await gatePush?.(sessionId, [], patch)) ?? null
+    if (denial !== null) return
+    await target.setPresence(patch)
+  } catch (error) {
+    const failure = asA2Error(error)
+    if (
+      failure.code === 'INVALID_PAYLOAD' ||
+      failure.code === 'UNKNOWN_PRESENCE_FIELD'
+    ) {
+      shell.malformedFrame('invalid presence frame')
+      return
+    }
+    shell.shutdown(1011, 'internal error')
+  }
+}
+
+export function sessionSocket<D extends EventDefs>(
+  sessionId: string,
+  session: Pick<Session<D>, 'stream'>,
+  socket: A2Socket,
+  options?: SessionSocketOptions,
+): void {
+  const target = session as unknown as SocketSession
+  const subscription = socketSubscription(
+    target,
+    options?.startAfter ?? 0,
+    options?.presence === true,
+  )
+
+  const handleFrame = (frame: Record<string, unknown>): void => {
+    switch (frame['kind']) {
+      case 'push': {
+        const req = frame['req']
+        if (typeof req !== 'number') {
+          shell.malformedFrame('push frame without a numeric req')
+          return
+        }
+        if (frame['sessionId'] !== undefined) {
+          shell.send(
+            socketErrorAckFor(
+              req,
+              new A2Error(
+                'INVALID_PAYLOAD',
+                'sessionId is not allowed on a single-session socket',
+              ),
+            ),
+          )
+          return
+        }
+        if (shell.overCap()) {
+          shell.send(
+            socketErrorAckFor(
+              req,
+              new A2Error(
+                'STORE_UNAVAILABLE',
+                'push shed: too many in flight on this socket',
+              ),
+            ),
+          )
+          return
+        }
+        shell.track(
+          handleSocketPush(
+            shell,
+            target,
+            sessionId,
+            frame,
+            req,
+            undefined,
+            options?.gatePush,
+            () => streamActivities.get(subscription.iterator)?.activate(),
+          ),
+        )
+        return
+      }
+      case 'presence':
+        if (frame['sessionId'] !== undefined) {
+          shell.malformedFrame(
+            'sessionId is not allowed on a single-session socket',
+          )
+          return
+        }
+        if (!shell.overCap()) {
+          shell.track(
+            applySocketPresence(
+              shell,
+              target,
+              sessionId,
+              frame,
+              options?.gatePush,
+            ),
+          )
+        }
+        return
+      default:
+        return
+    }
+  }
+
+  const shell = socketShell(
+    socket,
+    () => stopSubscription(subscription),
+    handleFrame,
+    options?.deadline,
+  )
+
+  void pumpSubscription(shell, subscription, socketFrameFor).then(
+    () => shell.shutdown(1000),
+    () => shell.shutdown(1011, 'stream failed'),
+  )
+}
+
 const parseSubscribeEntries = (
   value: unknown,
 ): Array<{ id: string; index: number }> | null => {
@@ -308,45 +505,21 @@ export function sessionsSocket<D extends EventDefs>(
     if (subscriptions.get(id) === subscription) subscriptions.delete(id)
   }
 
-  const pump = async (
-    id: string,
-    subscription: SocketSubscription,
-  ): Promise<void> => {
-    for (;;) {
-      for (;;) {
-        if (
-          shell.torn() ||
-          subscription.stopped ||
-          shell.buffered() <= SOCKET_TIMINGS.highWaterMarkBytes
-        )
-          break
-        // oxlint-disable-next-line no-await-in-loop -- backpressure park
-        await new Promise((wake) =>
-          setTimeout(wake, SOCKET_TIMINGS.resumePollMs),
-        )
-      }
-      if (shell.torn() || subscription.stopped) return
-      // oxlint-disable-next-line no-await-in-loop -- stream pump
-      const { value, done } = await subscription.iterator.next()
-      if (shell.torn() || subscription.stopped) return
-      if (done) return
-      shell.send(socketFrameFor(value, id))
-    }
-  }
-
   const runSubscription = async (
     id: string,
     subscription: SocketSubscription,
   ): Promise<void> => {
     try {
-      await pump(id, subscription)
+      await pumpSubscription(shell, subscription, (item) =>
+        socketFrameFor(item, id),
+      )
       if (shell.torn() || subscription.stopped) return
       retire(id, subscription)
       shell.send(socketUnsubscribedFor(id))
-    } catch {
+    } catch (error) {
       if (shell.torn() || subscription.stopped) return
       retire(id, subscription)
-      shell.send(socketUnsubscribedFor(id, 'stream failed'))
+      shell.send(socketUnsubscribedFor(id, 'stream failed', asA2Error(error)))
     }
   }
 
@@ -354,33 +527,33 @@ export function sessionsSocket<D extends EventDefs>(
     id: string,
     index: number,
   ): Promise<void> => {
+    const existing = subscriptions.get(id)
+    if (existing) {
+      stopSubscription(existing)
+      subscriptions.delete(id)
+    }
     let session: Pick<Session<D>, 'stream'> | null
     try {
       session = await resolve(id, index)
-    } catch {
+    } catch (error) {
       if (!shell.torn()) {
-        shell.send(socketUnsubscribedFor(id, 'stream failed'))
+        shell.send(socketUnsubscribedFor(id, 'stream failed', asA2Error(error)))
       }
       return
     }
     if (shell.torn()) return
     if (session === null) {
-      shell.send(socketUnsubscribedFor(id, 'subscribe rejected'))
+      shell.send(
+        socketUnsubscribedFor(
+          id,
+          'subscribe rejected',
+          new A2Error('FORBIDDEN', 'the subscription is not authorized'),
+        ),
+      )
       return
     }
     const target = session as unknown as SocketSession
-    const existing = subscriptions.get(id)
-    if (existing) stopSubscription(existing)
-    const iterator = (
-      presence
-        ? target.stream({ startAfter: index, presence: true })
-        : target.stream({ startAfter: index })
-    )[Symbol.asyncIterator]()
-    const subscription: SocketSubscription = {
-      target,
-      iterator,
-      stopped: false,
-    }
+    const subscription = socketSubscription(target, index, presence)
     subscriptions.set(id, subscription)
     shell.send(socketSubscribedFor(id))
     void runSubscription(id, subscription)
@@ -415,19 +588,19 @@ export function sessionsSocket<D extends EventDefs>(
       )
       return
     }
-    try {
-      const events = parsePushEvents(frame['events'])
-      const denial =
-        (await options?.gatePush?.(sessionId, events, undefined)) ?? null
-      if (denial !== null) {
-        shell.send(socketErrorAckFor(req, denial, sessionId))
-        return
-      }
-      const appended = await subscription.target.append(...events)
-      shell.send(socketAckFor(req, appended, sessionId))
-    } catch (err) {
-      shell.send(socketErrorAckFor(req, asA2Error(err), sessionId))
-    }
+    await handleSocketPush(
+      shell,
+      subscription.target,
+      sessionId,
+      frame,
+      req,
+      sessionId,
+      options?.gatePush,
+      () => {
+        const current = subscriptions.get(sessionId)
+        if (current) streamActivities.get(current.iterator)?.activate()
+      },
+    )
   }
 
   const handlePresence = async (
@@ -437,33 +610,13 @@ export function sessionsSocket<D extends EventDefs>(
     const subscription = subscriptions.get(sessionId)
     // An unsubscribe race, not malformedness — the plane repaints.
     if (subscription === undefined) return
-    if (typeof subscription.target.setPresence !== 'function') {
-      shell.malformedFrame('presence frame on a presence-less session')
-      return
-    }
-    let patch: ParsedPushPresence | undefined
-    try {
-      patch = parsePresenceSibling(frame)
-    } catch {
-      shell.malformedFrame('invalid presence frame')
-      return
-    }
-    if (!patch) return
-    try {
-      const denial = (await options?.gatePush?.(sessionId, [], patch)) ?? null
-      if (denial !== null) return
-      await subscription.target.setPresence(patch)
-    } catch (error) {
-      const failure = asA2Error(error)
-      if (
-        failure.code === 'INVALID_PAYLOAD' ||
-        failure.code === 'UNKNOWN_PRESENCE_FIELD'
-      ) {
-        shell.malformedFrame('invalid presence frame')
-        return
-      }
-      shell.shutdown(1011, 'internal error')
-    }
+    await applySocketPresence(
+      shell,
+      subscription.target,
+      sessionId,
+      frame,
+      options?.gatePush,
+    )
   }
 
   const handleFrame = (frame: Record<string, unknown>): void => {

package/src/sse.ts

@@ -10,6 +10,7 @@ import { STREAM_TIMINGS } from './internal.ts'
 import type { Event } from './store.ts'
 import type { PresencePatch, PresenceSnapshot } from './contract.ts'
 import { invocationDeadlineMs } from './platform.ts'
+import { streamActivities } from './stream-activity.ts'
 import {
   eventToWire,
   presencePatchToWire,
@@ -41,7 +42,10 @@ export function sseResponse(
   let deadlineTimer: ReturnType<typeof setTimeout> | undefined
   let closed = false
   let iteratorReturned = false
+  let stopActivity: (() => void) | undefined
   const stopTimers = (): void => {
+    stopActivity?.()
+    stopActivity = undefined
     if (heartbeat !== undefined) clearInterval(heartbeat)
     if (deadlineTimer !== undefined) clearTimeout(deadlineTimer)
     heartbeat = undefined
@@ -61,6 +65,19 @@ export function sseResponse(
       // early proof this is a stream. Comment frames are invisible to
       // SSE consumers.
       controller.enqueue(encoder.encode(': connected\n\n'))
+      const activity = streamActivities.get(iterator)
+      if (activity) {
+        const announce = (idle: boolean): void => {
+          if (closed) return
+          controller.enqueue(
+            encoder.encode(
+              `event: a2-activity\ndata: ${idle ? 'idle' : 'active'}\n\n`,
+            ),
+          )
+        }
+        stopActivity = activity.subscribe(announce)
+        if (activity.idle) announce(true)
+      }
       // Heartbeat: comment frames are ignored by SSE parsers but are
       // bytes on the wire — liveness proof for the client's watchdog
       // and for idle-timeout-happy intermediaries.

package/src/store-polling.ts

@@ -14,7 +14,8 @@
  */
 
 import { POLL_TIMINGS } from './internal.ts'
-import type { StoredEvent } from './store.ts'
+import type { Event } from './store.ts'
+import { createStreamActivity, streamActivities } from './stream-activity.ts'
 
 /** One cancellable sleep — the injection seam for cadence tests. */
 export type Sleeper = { promise: Promise<void>; cancel: () => void }
@@ -56,47 +57,66 @@ export type PollingStreamOptions = {
  * SSE client), waking any pending sleep immediately.
  */
 export function pollingStream(
-  readAfter: (afterIndex: number) => StoredEvent[] | Promise<StoredEvent[]>,
+  readAfter: (afterIndex: number) => Event[] | Promise<Event[]>,
   options: PollingStreamOptions,
-): AsyncIterable<StoredEvent> {
+): AsyncIterable<Event> {
   const startAfter = options.startAfter ?? 0
   const sleep = options.sleep ?? defaultSleep
 
   return {
-    [Symbol.asyncIterator](): AsyncIterator<StoredEvent> {
+    [Symbol.asyncIterator](): AsyncIterator<Event> {
       let last = startAfter
-      let buffer: StoredEvent[] = []
+      let buffer: Event[] = []
       let closed = false
       let pending: Sleeper | null = null
       let interval = floor()
+      let activityVersion = 0
+      const activity = createStreamActivity(() => {
+        if (closed) return
+        activityVersion += 1
+        interval = floor()
+        pending?.cancel()
+      })
 
-      return {
-        async next(): Promise<IteratorResult<StoredEvent>> {
+      const iterator: AsyncIterator<Event> = {
+        async next(): Promise<IteratorResult<Event>> {
           for (;;) {
             if (closed) return { value: undefined, done: true }
-            // oxlint-disable-next-line no-await-in-loop -- poll loop
-            if (buffer.length === 0) buffer = await readAfter(last)
+            try {
+              // oxlint-disable-next-line no-await-in-loop -- poll loop
+              if (buffer.length === 0) buffer = await readAfter(last)
+            } catch (error) {
+              if (closed) return { value: undefined, done: true }
+              throw error
+            }
+            if (closed) return { value: undefined, done: true }
             const row = buffer.shift()
             if (row) {
               // Activity: tighten back to the floor.
-              interval = floor()
+              activity.activate()
               last = row.index
               return { value: row, done: false }
             }
             // Empty poll: wait, then back off toward the idle ceiling.
+            activity.setIdle(interval === ceiling())
+            const version = activityVersion
             pending = sleep(interval)
             // oxlint-disable-next-line no-await-in-loop -- poll loop
             await pending.promise
             pending = null
-            interval = Math.min(interval * 2, ceiling())
+            if (version === activityVersion) {
+              interval = Math.min(interval * 2, ceiling())
+            }
           }
         },
-        async return(): Promise<IteratorResult<StoredEvent>> {
+        async return(): Promise<IteratorResult<Event>> {
           closed = true
           pending?.cancel()
           return { value: undefined, done: true }
         },
       }
+      streamActivities.set(iterator, activity)
+      return iterator
     },
   }
 }