experimental-a2 0.9.0 → 0.10.0

package/src/session-socket.ts

@@ -1,10 +1,9 @@
 /**
  * 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'
@@ -256,17 +255,210 @@ 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'],
+): 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
+    }
+    // oxlint-disable-next-line a2/await-handler-append -- this transport append is awaited before its ack
+    const appended = await target.append(...events)
+    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,
+          ),
+        )
+        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,38 +500,14 @@ 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))
@@ -371,16 +539,7 @@ export function sessionsSocket<D extends EventDefs>(
     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 +574,15 @@ 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 handlePresence = async (
@@ -437,33 +592,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 => {