experimental-a2 0.4.0 → 0.5.0

package/src/session-socket.ts

@@ -0,0 +1,548 @@
+/**
+ * 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.
+ */
+
+import { A2Error } from './errors.ts'
+import { SOCKET_TIMINGS, STREAM_TIMINGS } from './internal.ts'
+import type { Event } from './store.ts'
+import type { EventDefs, PresencePatch, PresenceSnapshot } from './contract.ts'
+import type { PushedEvent, PushedPresence, Session } from './server.ts'
+import { parsePresenceSibling, parsePushEvents } from './push-envelope.ts'
+import {
+  SOCKET_PING_FRAME,
+  asA2Error,
+  socketAckFor,
+  socketErrorAckFor,
+  socketFrameFor,
+  socketSubscribedFor,
+  socketUnsubscribedFor,
+} from './wire.ts'
+
+// ── the ws wire ───────────────────────────────────────────────────────
+
+/**
+ * The structural socket `sessionsSocket` speaks against — satisfied
+ * by `ws` and by `@vercel/functions`' upgraded socket alike, so the
+ * platform upgrade API stays out of the library. `message` data
+ * arrives as whatever the platform delivers (string, Buffer,
+ * ArrayBuffer, or fragments); the handler normalizes defensively.
+ */
+export type A2Socket = {
+  send(data: string): void
+  on(event: 'message', listener: (data: unknown) => void): void
+  on(event: 'close', listener: () => void): void
+  on(event: 'error', listener: (error: unknown) => void): void
+  close(code?: number, reason?: string): void
+  /** Bytes queued but not yet transmitted — when exposed, the down
+   * pump uses it for backpressure (`SOCKET_TIMINGS`). */
+  bufferedAmount?: number
+}
+
+const messageText = (data: unknown): string | null => {
+  if (typeof data === 'string') return data
+  if (data instanceof ArrayBuffer) return new TextDecoder().decode(data)
+  if (ArrayBuffer.isView(data)) return new TextDecoder().decode(data)
+  if (Array.isArray(data) && data.every(ArrayBuffer.isView)) {
+    // ws delivers fragmented messages as a Buffer array; stream-decode
+    // so multi-byte characters can span fragment boundaries.
+    const decoder = new TextDecoder()
+    let text = ''
+    for (const part of data) text += decoder.decode(part, { stream: true })
+    return text + decoder.decode()
+  }
+  return null
+}
+
+/**
+ * How many unparseable or invalid frames a socket may send before it
+ * is closed (1008): the budget absorbs isolated client bugs without
+ * letting a broken peer spin the validation path forever. Push frames
+ * with a usable `req` never count — their failures are answered with
+ * error acks, exactly like the POST path's 4xx bodies.
+ */
+const MAX_MALFORMED_FRAMES = 5
+
+/**
+ * The pump's runtime view of a session. The presence members are
+ * conditional on the public surface (`WithPresence`) and therefore
+ * invisible on a generic `Session<D>`, so capability is checked at
+ * runtime (`setPresence` present) — the same resolution as the docs'
+ * route sample. The casts live in `sessionsSocket` and `handle`.
+ */
+export type SocketSession = {
+  stream(opts: {
+    startAfter: number
+    presence?: boolean
+  }): AsyncIterable<Event | PresencePatch | PresenceSnapshot>
+  append(...events: PushedEvent[]): Promise<Event[]>
+  setPresence?(patch: PushedPresence): Promise<void>
+}
+
+/**
+ * The per-socket machinery `sessionsSocket` builds on: the torn flag
+ * with a release-once teardown, the backpressure-aware send with its
+ * non-reader ceiling, the malformed budget, the in-flight bound, the
+ * message normalization, the heartbeat, and the optional deadline.
+ */
+type SocketShell = {
+  torn(): boolean
+  send(data: string): void
+  shutdown(code: number, reason?: string): void
+  malformedFrame(reason: string): void
+  buffered(): number
+  overCap(): boolean
+  track(work: Promise<void>): void
+}
+
+function socketShell(
+  socket: A2Socket,
+  release: () => void,
+  onFrame: (frame: Record<string, unknown>) => void,
+  deadlineAt: number | undefined,
+): SocketShell {
+  let torn = false
+  let malformed = 0
+  let heartbeat: ReturnType<typeof setInterval> | undefined
+  let deadline: ReturnType<typeof setTimeout> | undefined
+
+  const teardown = (): void => {
+    if (torn) return
+    torn = true
+    if (heartbeat !== undefined) clearInterval(heartbeat)
+    if (deadline !== undefined) clearTimeout(deadline)
+    release()
+  }
+
+  const shutdown = (code: number, reason?: string): void => {
+    if (torn) return
+    teardown()
+    try {
+      socket.close(code, reason)
+    } catch {
+      // Already closed underneath us — teardown has run either way.
+    }
+  }
+
+  const send = (data: string): void => {
+    if (torn) return
+    // The pump parks at the high-water mark, but acks and pings are
+    // exempt (small, correctness-relevant) — so a peer that never
+    // reads while it keeps uploading grows the buffer through its own
+    // acks. The ceiling closes the class: past it, the peer is not a
+    // slow reader, it is a non-reader (adversarial F4).
+    if (
+      typeof socket.bufferedAmount === 'number' &&
+      socket.bufferedAmount > SOCKET_TIMINGS.disconnectWaterMarkBytes
+    ) {
+      shutdown(1008, 'backpressure: peer not reading')
+      return
+    }
+    try {
+      socket.send(data)
+    } catch {
+      // The platform closed the socket without an event; closing it
+      // again would throw the same way, so just tear down.
+      teardown()
+    }
+  }
+
+  const malformedFrame = (reason: string): void => {
+    malformed += 1
+    if (malformed >= MAX_MALFORMED_FRAMES) {
+      shutdown(1008, `too many malformed frames (last: ${reason})`)
+    }
+  }
+
+  // The up-lane bound (adversarial F3): one socket must not hold
+  // unbounded concurrent appends. Shedding is per-plane semantics —
+  // pushes are TOLD (retryable error ack, ids make the retry safe),
+  // presence is silently dropped (a lost update is repainted by the
+  // next one). Sheds are our load decision, never the peer's
+  // malformedness, so they spend no budget.
+  let inFlight = 0
+  const track = (work: Promise<void>): void => {
+    inFlight += 1
+    void work.finally(() => {
+      inFlight -= 1
+    })
+  }
+
+  const handleMessage = (data: unknown): void => {
+    if (torn) return
+    const text = messageText(data)
+    if (text === null) {
+      malformedFrame('non-text frame')
+      return
+    }
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(text)
+    } catch {
+      malformedFrame('frame is not valid JSON')
+      return
+    }
+    if (
+      parsed === null ||
+      typeof parsed !== 'object' ||
+      Array.isArray(parsed)
+    ) {
+      malformedFrame('frame is not an object')
+      return
+    }
+    onFrame(parsed as Record<string, unknown>)
+  }
+
+  socket.on('message', handleMessage)
+  socket.on('close', teardown)
+  socket.on('error', teardown)
+
+  heartbeat = setInterval(
+    () => send(SOCKET_PING_FRAME),
+    STREAM_TIMINGS.sseHeartbeatMs,
+  )
+  ;(heartbeat as { unref?: () => void }).unref?.()
+
+  if (deadlineAt !== undefined) {
+    deadline = setTimeout(
+      () => shutdown(1000, 'deadline'),
+      Math.max(0, deadlineAt - Date.now()),
+    )
+    ;(deadline as { unref?: () => void }).unref?.()
+  }
+
+  return {
+    torn: () => torn,
+    send,
+    shutdown,
+    malformedFrame,
+    buffered: () =>
+      typeof socket.bufferedAmount === 'number' ? socket.bufferedAmount : 0,
+    overCap: () => inFlight >= SOCKET_TIMINGS.maxInFlightMessages,
+    track,
+  }
+}
+
+/**
+ * The per-session authorization seam of `sessionsSocket`: called once
+ * per `subscribe` entry (and never for the pushes and presence that
+ * ride an accepted subscription). `null` rejects that session — the
+ * socket answers `unsubscribed` with a rejection reason and every
+ * other session on it is untouched.
+ */
+export type SessionsSocketResolve<D extends EventDefs> = (
+  sessionId: string,
+  /** The entry's resume frontier — `stream({ startAfter })`. */
+  startAfter: number,
+) => Session<D> | null | Promise<Session<D> | null>
+
+export type SessionsSocketOptions = {
+  /** The `stream()` presence opt-in for every session on the socket —
+   * the server decides, same rule as the SSE route. */
+  presence?: boolean
+  /** Epoch ms: close cleanly (code 1000) at this time, ahead of a known
+   * platform deadline, so clients reconnect on our schedule. */
+  deadline?: number
+  /**
+   * Per-frame push gate — policy's seam on the up lane, the socket
+   * counterpart of a POST route's checks (`handle`'s `before` rides
+   * it). Runs after the frame parses and before `append`: return an
+   * `A2Error` to answer the push with that error ack (nothing
+   * appended), `null` to allow. Absent, every push on an accepted
+   * subscription is allowed — the prior behavior, unchanged.
+   */
+  gatePush?(
+    sessionId: string,
+    events: PushedEvent[],
+  ): A2Error | null | Promise<A2Error | null>
+}
+
+type SocketSubscription = {
+  target: SocketSession
+  iterator: AsyncIterator<Event | PresencePatch | PresenceSnapshot>
+  stopped: boolean
+}
+
+const stopSubscription = (subscription: SocketSubscription): void => {
+  subscription.stopped = true
+  void subscription.iterator.return?.()?.catch(() => {})
+}
+
+const parseSubscribeEntries = (
+  value: unknown,
+): Array<{ id: string; index: number }> | null => {
+  if (!Array.isArray(value) || value.length === 0) return null
+  const entries: Array<{ id: string; index: number }> = []
+  for (const entry of value) {
+    if (entry === null || typeof entry !== 'object') return null
+    const { id, index } = entry as Record<string, unknown>
+    if (typeof id !== 'string' || id.length === 0) return null
+    if (typeof index !== 'number' || !Number.isInteger(index) || index < 0) {
+      return null
+    }
+    entries.push({ id, index })
+  }
+  return entries
+}
+
+/**
+ * Speak the multiplexed A2 socket protocol (specs/a2-api.md §13)
+ * against many sessions on one socket. `subscribe` frames open a
+ * per-session pump at that session's own resume frontier; push and
+ * presence frames route by `sessionId` through the same validation
+ * seams as the POST lane; every down frame carries the `sessionId` it
+ * belongs to. One heartbeat, one
+ * malformed budget, one in-flight bound, one backpressure gauge — per
+ * socket, shared by all sessions. A session's stream ending or failing
+ * answers `unsubscribed` for that session; only the peer, the
+ * deadline, the malformed budget, or backpressure closes the socket.
+ */
+export function sessionsSocket<D extends EventDefs>(
+  resolve: SessionsSocketResolve<D>,
+  socket: A2Socket,
+  options?: SessionsSocketOptions,
+): void {
+  const presence = options?.presence === true
+  const subscriptions = new Map<string, SocketSubscription>()
+
+  const retire = (id: string, subscription: SocketSubscription): void => {
+    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)
+      if (shell.torn() || subscription.stopped) return
+      retire(id, subscription)
+      shell.send(socketUnsubscribedFor(id))
+    } catch {
+      if (shell.torn() || subscription.stopped) return
+      retire(id, subscription)
+      shell.send(socketUnsubscribedFor(id, 'stream failed'))
+    }
+  }
+
+  const startSubscription = async (
+    id: string,
+    index: number,
+  ): Promise<void> => {
+    let session: Session<D> | null
+    try {
+      session = await resolve(id, index)
+    } catch {
+      session = null
+    }
+    if (shell.torn()) return
+    if (session === null) {
+      shell.send(socketUnsubscribedFor(id, 'subscribe rejected'))
+      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,
+    }
+    subscriptions.set(id, subscription)
+    shell.send(socketSubscribedFor(id))
+    void runSubscription(id, subscription)
+  }
+
+  // Control frames (subscribe/unsubscribe) run in arrival order — an
+  // unsubscribe can never overtake the subscribe it targets while the
+  // resolve hook is still pending.
+  let controlTail: Promise<void> = Promise.resolve()
+  const control = (work: () => Promise<void> | void): void => {
+    controlTail = controlTail.then(work).catch(() => {})
+  }
+
+  const handlePush = async (
+    frame: Record<string, unknown>,
+    req: number,
+    sessionId: string,
+  ): Promise<void> => {
+    const subscription = subscriptions.get(sessionId)
+    if (subscription === undefined) {
+      // Retryable: the client re-subscribes on reconnect and the retry
+      // rides the same client-generated event ids.
+      shell.send(
+        socketErrorAckFor(
+          req,
+          new A2Error(
+            'STORE_UNAVAILABLE',
+            'session is not subscribed on this socket',
+          ),
+          sessionId,
+        ),
+      )
+      return
+    }
+    try {
+      const events = parsePushEvents(frame['events'])
+      const denial = (await options?.gatePush?.(sessionId, events)) ?? 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))
+    }
+  }
+
+  const handlePresence = async (
+    frame: Record<string, unknown>,
+    sessionId: string,
+  ): Promise<void> => {
+    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
+    }
+    try {
+      const patch = parsePresenceSibling(frame)
+      if (patch) await subscription.target.setPresence(patch)
+    } catch {
+      shell.malformedFrame('invalid presence frame')
+    }
+  }
+
+  const handleFrame = (frame: Record<string, unknown>): void => {
+    switch (frame['kind']) {
+      case 'subscribe': {
+        const entries = parseSubscribeEntries(frame['sessions'])
+        if (entries === null) {
+          shell.malformedFrame('malformed subscribe frame')
+          return
+        }
+        for (const entry of entries) {
+          control(() => startSubscription(entry.id, entry.index))
+        }
+        return
+      }
+      case 'unsubscribe': {
+        const ids = frame['sessions']
+        if (
+          !Array.isArray(ids) ||
+          ids.length === 0 ||
+          !ids.every((id) => typeof id === 'string')
+        ) {
+          shell.malformedFrame('malformed unsubscribe frame')
+          return
+        }
+        for (const id of ids as string[]) {
+          control(() => {
+            const subscription = subscriptions.get(id)
+            if (subscription === undefined) return
+            stopSubscription(subscription)
+            subscriptions.delete(id)
+          })
+        }
+        return
+      }
+      case 'push': {
+        const req = frame['req']
+        const sessionId = frame['sessionId']
+        if (shell.overCap()) {
+          if (typeof req === 'number') {
+            shell.send(
+              socketErrorAckFor(
+                req,
+                new A2Error(
+                  'STORE_UNAVAILABLE',
+                  'push shed: too many in flight on this socket',
+                ),
+                typeof sessionId === 'string' ? sessionId : undefined,
+              ),
+            )
+          } else {
+            shell.malformedFrame('push frame without a numeric req')
+          }
+          return
+        }
+        if (typeof req !== 'number') {
+          shell.malformedFrame('push frame without a numeric req')
+          return
+        }
+        if (typeof sessionId !== 'string' || sessionId.length === 0) {
+          shell.send(
+            socketErrorAckFor(
+              req,
+              new A2Error('INVALID_PAYLOAD', 'push frame without a sessionId'),
+            ),
+          )
+          return
+        }
+        shell.track(handlePush(frame, req, sessionId))
+        return
+      }
+      case 'presence': {
+        if (shell.overCap()) return
+        const sessionId = frame['sessionId']
+        if (typeof sessionId !== 'string' || sessionId.length === 0) {
+          shell.malformedFrame('presence frame without a sessionId')
+          return
+        }
+        shell.track(handlePresence(frame, sessionId))
+        return
+      }
+      default:
+        return // unknown kinds are skipped — the forward-compatibility rule
+    }
+  }
+
+  const shell = socketShell(
+    socket,
+    () => {
+      for (const subscription of subscriptions.values()) {
+        stopSubscription(subscription)
+      }
+      subscriptions.clear()
+    },
+    (frame) => handleFrame(frame),
+    options?.deadline,
+  )
+}

package/src/sse.ts

@@ -0,0 +1,141 @@
+/**
+ * The SSE response protocol — framing, heartbeat, deadline, and
+ * teardown for the live stream lane. Internal module: `handle`'s
+ * stream branch is the one sanctioned caller; the framing rules stay
+ * documented on `sseResponse` because the client's parser (and the
+ * stall watchdog) depend on them.
+ */
+
+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 {
+  eventToWire,
+  presencePatchToWire,
+  presenceSnapshotToWire,
+} from './wire.ts'
+
+/**
+ * Pipe a live event iterable into an SSE `Response`. Each event is one
+ * frame — `id:` carries the event-log index, `data:` the JSON event. A
+ * `stream({ presence: true })` iterable also yields presence items,
+ * which ride as named frames old clients skip: `event:
+ * presence-snapshot` first (the map, ISO dates), then `event: presence`
+ * per patch — no `id:`, presence never advances the resume frontier. A
+ * disconnecting client cancels the stream, which closes the underlying
+ * subscription. Two kinds of comment frames ride along: a `: connected`
+ * prelude that flushes headers immediately, and a `: ping` heartbeat
+ * every 15 seconds so clients (and proxies) can tell a quiet stream
+ * from a dead connection — the session client's stall watchdog counts
+ * on it. When the platform exposes an invocation deadline, the response
+ * closes cleanly one second before it so the client reconnects without
+ * a platform-timeout failure.
+ */
+export function sseResponse(
+  iterable: AsyncIterable<Event | PresencePatch | PresenceSnapshot>,
+): Response {
+  const iterator = iterable[Symbol.asyncIterator]()
+  const encoder = new TextEncoder()
+  let heartbeat: ReturnType<typeof setInterval> | undefined
+  let deadlineTimer: ReturnType<typeof setTimeout> | undefined
+  let closed = false
+  let iteratorReturned = false
+  const stopTimers = (): void => {
+    if (heartbeat !== undefined) clearInterval(heartbeat)
+    if (deadlineTimer !== undefined) clearTimeout(deadlineTimer)
+    heartbeat = undefined
+    deadlineTimer = undefined
+  }
+  const returnIterator = async (): Promise<void> => {
+    if (iteratorReturned) return
+    iteratorReturned = true
+    await iterator.return?.()
+  }
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      // Prelude comment frame: flushes headers immediately (a fresh
+      // session may otherwise send nothing for a long time — some
+      // servers buffer headers until the first byte, and clients can't
+      // report "live" until they see the response), and gives proxies
+      // early proof this is a stream. Comment frames are invisible to
+      // SSE consumers.
+      controller.enqueue(encoder.encode(': connected\n\n'))
+      // 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.
+      heartbeat = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(': ping\n\n'))
+        } catch {
+          // The stream closed underneath the timer.
+          stopTimers()
+        }
+      }, STREAM_TIMINGS.sseHeartbeatMs)
+      ;(heartbeat as { unref?: () => void }).unref?.()
+
+      const invocationDeadline = invocationDeadlineMs()
+      if (invocationDeadline !== null) {
+        const delay = Math.max(
+          0,
+          invocationDeadline - Date.now() - STREAM_TIMINGS.sseDeadlineGraceMs,
+        )
+        deadlineTimer = setTimeout(() => {
+          if (closed) return
+          closed = true
+          stopTimers()
+          void returnIterator().catch(() => {})
+          try {
+            controller.close()
+          } catch {
+            // The response already closed underneath the timer.
+          }
+        }, delay)
+        ;(deadlineTimer as { unref?: () => void }).unref?.()
+      }
+    },
+    async pull(controller) {
+      try {
+        const { value, done } = await iterator.next()
+        if (closed) return
+        if (done) {
+          closed = true
+          stopTimers()
+          controller.close()
+          return
+        }
+        controller.enqueue(encoder.encode(frameFor(value)))
+      } catch (error) {
+        if (closed) return
+        closed = true
+        stopTimers()
+        void returnIterator().catch(() => {})
+        throw error
+      }
+    },
+    async cancel() {
+      if (closed) return
+      closed = true
+      stopTimers()
+      await returnIterator()
+    },
+  })
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      'content-type': 'text/event-stream',
+      'cache-control': 'no-cache, no-transform',
+      connection: 'keep-alive',
+    },
+  })
+}
+
+function frameFor(item: Event | PresencePatch | PresenceSnapshot): string {
+  if ('snapshot' in item) {
+    return `event: presence-snapshot\ndata: ${JSON.stringify(presenceSnapshotToWire(item))}\n\n`
+  }
+  if ('participant' in item) {
+    return `event: presence\ndata: ${JSON.stringify(presencePatchToWire(item))}\n\n`
+  }
+  return `id: ${item.index}\ndata: ${JSON.stringify(eventToWire(item))}\n\n`
+}