experimental-a2 0.8.1 → 0.10.0

package/src/server.ts

@@ -19,7 +19,7 @@ import type {
   PresenceSnapshot,
   WithPresence,
 } from './contract.ts'
-import { A2Error, asStoreUnavailable } from './errors.ts'
+import { A2Error, NonRetriableError, asStoreUnavailable } from './errors.ts'
 import {
   DRAIN_TIMINGS,
   POLL_TIMINGS,
@@ -1431,9 +1431,15 @@ export function createServer<
     const validated: Record<string, unknown> = nullProtoRecord()
     for (const [field, value] of Object.entries(patch.values)) {
       if (value === undefined) continue
+      // '*' is a catch-all vocabulary entry: any field name (bar
+      // object-plumbing names) validates against its schema. The
+      // actor module declares it — presence vocabularies typed by the
+      // protocol, values held to the JSON floor here.
       const schema = Object.hasOwn(presenceDefs, field)
         ? presenceDefs[field]
-        : undefined
+        : RESERVED_PARTICIPANT_IDS.has(field)
+          ? undefined
+          : presenceDefs['*']
       if (!schema) {
         throw new A2Error(
           'UNKNOWN_PRESENCE_FIELD',
@@ -2209,7 +2215,11 @@ export function createServer<
                   index: event.index,
                   attempt: event.attemptCount,
                   error: describeError(err),
-                  maxFailures: MAX_FAILURES,
+                  // A NonRetriableError is terminal on its first throw:
+                  // deterministic failures should not burn the retry
+                  // budget before dead-lettering.
+                  maxFailures:
+                    err instanceof NonRetriableError ? 1 : MAX_FAILURES,
                 })
                 eventSpan.setAttribute('a2.event.outcome', failure.outcome)
                 return {

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 => {

package/dist/contract-jIfaR085.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"contract-jIfaR085.d.ts","names":[],"sources":["../src/standard-schema.ts","../src/reducer.ts","../src/contract.ts"],"mappings":";;;;;;;;UAQiB,iBAAiB,iBAAiB,SAAS;;WAEjD,aAAa,iBAAiB,MAAM,OAAO;;kBAG7B;;mBAEN,MAAM,iBAAiB,SAAS;;aAEtC;;aAEA;;aAEA,WACP,mBACG,OAAO,UAAU,QAAQ,OAAO;;aAE5B,QAAQ,MAAM,OAAO;;;cAIpB,OAAO,UAAU,cAAc,UAAU;;mBAGpC,cAAc;;aAEpB,OAAO;;aAEP;;;mBAIM;;aAEN,QAAQ,cAAc;;;mBAIhB;;aAEN;;aAEA,OAAO,cAAc,cAAc;;;mBAI7B;;aAEN,KAAK;;;mBAIC,MAAM,iBAAiB,SAAS;;aAEtC,OAAO;;aAEP,QAAQ;;;cAIP,WAAW,eAAe,oBAAoB,YACxD;;cAIU,YAAY,eAAe,oBAAoB,YACzD;;;;;;;;;;;;;;KC5DQ,QACV,UAAU,YAAY,WACtB,aACA,UAAU,eAAe;;WAGhB;;WAEA,QAAQ,SAAS;;;;;;WAMjB,UAAU,SAAS;WACnB,OAAO,OAAO,GAAG,OAAO,cAAc,OAAO;WAC7C,cAAc;;;;;;;WAOd,aAAa,0BAA0B;;;KAItC,eACV,UAAU,WACV,GACA,UAAU,eAAe;EAEzB,KAAK,OAAO,OAAO,GAAG,OAAO,cAAc,OAAO,IAAI,QAAQ,GAAG,GAAG;;;;;KC9B1D,YAAY,eAAe;;KAG3B,eAAe,eAAe;;KAG9B,cACV,UAAU,WACV,gBAAgB,mBAAmB,iBAElC,WAAW;EACV;EACA,MAAM;EACN,SAAS,iBAAiB,YAAY,EAAE;EACxC;EACA;EACA,WAAW;KAEb;;KAGU,YAAY,UAAU,gBAC/B,WAAW;EACV,MAAM;EACN,SAAS,iBAAiB,WAAW,EAAE;EACvC;WAEI;KAEI,kBAAkB,UAAU,oBAChC,mBAAmB,YAAY,SAElC,QAAQ,MACR;;;;;;KAOO,cAAc,UAAU,eAAe;EACjD;EACA,WACG,WAAW,cAAc,iBAAiB,YAAY,EAAE;EAE3D;EACA,IAAI;;;;;;;;KASM,YAAY,UAAU,eAAe;GAE5C,yBAAA,WAAW;IACV,OAAO,iBAAiB,YAAY,EAAE;IACtC;IACA,IAAI;;;;;;;;KAUE,iBAAiB,UAAU,eAAe;EACpD,UAAU,YAAY;;;;;;;KAQZ,aACV,UAAU,cACV,iBACQ,4BAA4B;KAE1B,eAAe,MAAM;;;;;EAK/B;;;;;;EAMA,cAAc;;;;;;EAMd,cAAc,iBAAiB,MAAM;;KAG3B,SACV,UAAU,YAAY,WACtB,UAAU,eAAe;;WAGhB;;WAEA,QAAQ,SAAS;;WAEjB,UAAU,SAAS;;WAEnB,OAAO,kBAAkB;;;;;;;;;;;EAWlC,QAAQ,MAAM,IAAI,MAChB,SAAS,eAAe,MAAM,KAC7B,eAAe,GAAG,GAAG;;;;;;;iBAQV,SACd,UAAU,WACV,UAAU,eAAe,sBACzB;;EAEA;;EAEA,QAAQ;;;;;;EAMR,WAAW;IACT,SAAS,GAAG"}