experimental-a2 0.6.0 → 0.7.0

package/src/server.ts

@@ -28,11 +28,9 @@ import {
   markSchedulerSendFailure,
   nullProtoRecord,
   serverInternals,
-  serverSchedulerBindings,
   type DrainOutcome,
   type DrainResult,
 } from './internal.ts'
-import { InspectionUnsupportedError, serverInspection } from './inspection.ts'
 import { defaultSleep } from './store-polling.ts'
 import type {
   A2Store,
@@ -46,6 +44,14 @@ import type {
   StoredEvent,
 } from './store.ts'
 import type { Reducer } from './reducer.ts'
+import {
+  createServerFetch,
+  type A2Operation,
+  type A2PushEvent,
+  type A2PushPresence,
+  type ServerFetchOptions,
+  type UpgradeWebSocket,
+} from './server-fetch.ts'
 import { validateSync } from './validate.ts'
 import {
   deterministicEventId,
@@ -66,45 +72,6 @@ import {
   type A2Telemetry,
 } from './telemetry.ts'
 
-/**
- * Events that arrived over the wire through `parsePushBody` — already
- * envelope-validated, headed for schema validation inside `append`.
- * The brand lets the documented push route hand them straight to
- * `session.append` without weakening typed appends for app code: a
- * hand-written `{ type: string }` literal still fails to compile.
- */
-export type PushedEvent = {
-  type: string
-  payload: unknown
-  id?: string
-  readonly '~a2.pushed': true
-}
-
-/**
- * A presence patch that arrived over the wire through `parsePushBody`
- * — same provenance brand as `PushedEvent`, so the documented route
- * hands it whole to `session.setPresence` while a hand-written
- * untyped patch still fails to compile. Field validation happens
- * inside `setPresence`.
- */
-export type PushedPresence = {
-  participant: string
-  values: Record<string, unknown>
-  seen?: number
-  /** The sender's LWW stamp in epoch ms; receipt time when absent. */
-  at?: number
-  readonly '~a2.pushed': true
-}
-
-export type PushValidationContext = {
-  sessionId: string
-  events: readonly PushedEvent[]
-  /** The whole pushed patch — present exactly on the presence-plane
-   * invocation, so the callback authorizes the participant id and can
-   * apply size or cardinality policy. */
-  presence?: PushedPresence
-}
-
 /** What every handler receives. */
 export type HandlerContext<
   D extends EventDefs,
@@ -142,11 +109,9 @@ export type Lane<
   K extends keyof D & string = keyof D & string,
 > = string | ((context: LaneContext<D, K>) => string)
 
-export type SessionDispatch<D extends EventDefs> = {
-  (...events: AppendInput<D>[]): Promise<ContractEvent<D>[]>
-  /** The push-route path: events from `parsePushBody`. */
-  (...events: PushedEvent[]): Promise<ContractEvent<D>[]>
-}
+export type SessionDispatch<D extends EventDefs> = (
+  ...events: AppendInput<D>[]
+) => Promise<ContractEvent<D>[]>
 
 export type SessionAppend<D extends EventDefs> = SessionDispatch<D> & {
   /** Commit, then hand pending work directly to configured scheduler. */
@@ -192,16 +157,12 @@ export type SessionPresence<D extends EventDefs, P extends PresenceDefs> = {
    * is the sender's LWW stamp in epoch ms; omitted, receipt time
    * stands in (single writer, so receipt order is sender order).
    */
-  setPresence(
-    patch:
-      | {
-          participant: string
-          values: PresencePatch<P>['values']
-          seen?: number
-          at?: number
-        }
-      | PushedPresence,
-  ): Promise<void>
+  setPresence(patch: {
+    participant: string
+    values: PresencePatch<P>['values']
+    seen?: number
+    at?: number
+  }): Promise<void>
   /** The current map, expired values pruned — a point-in-time read. */
   presence(): Promise<PresenceMap<P>>
 }
@@ -219,8 +180,7 @@ export type Session<
   state<S>(reducer: Reducer<D, S>): Promise<{ state: S; index: number }>
   /**
    * A live feed of this session's events, starting after `startAfter`
-   * (exclusive). Server-side only — `handle` from experimental-a2/http
-   * exposes it over SSE as the route's stream lane.
+   * (exclusive). Server-side only. `server.fetch` exposes it over SSE.
    */
   stream(opts?: { startAfter?: number }): AsyncIterable<ContractEvent<D>>
 }
@@ -255,6 +215,10 @@ export type A2Server<
 > = {
   /** The contract this server implements. */
   readonly contract: Contract<D, P>
+  readonly fetch: {
+    (request: Request): Promise<Response>
+    (request: Request, options: ServerFetchOptions<D, P>): Promise<Response>
+  }
   session(id: string): Session<D, SessionAppend<D>, P>
   /**
    * Process every currently eligible event. `settled` means nothing
@@ -263,6 +227,15 @@ export type A2Server<
   drain(sessionId: string): Promise<{ settled: boolean }>
 }
 
+export type {
+  A2Operation,
+  A2PushEvent,
+  A2PushPresence,
+  ServerFetchOptions,
+  UpgradeWebSocket,
+}
+export type { A2Socket } from './session-socket.ts'
+
 /**
  * Deliver one authenticated scheduler append through an A2 server's ordinary
  * top-level append path. Custom scheduler adapters call this after validating
@@ -336,8 +309,6 @@ export type ServerOptions<
   scheduler?: A2Scheduler
   /** Optional instrumentation — e.g. `otel()` from `experimental-a2/otel`. */
   telemetry?: A2Telemetry
-  /** Validate events that came through `parsePushBody` before writing them. */
-  validatePush?: (context: PushValidationContext) => void | PromiseLike<void>
   /**
    * Presence-plane policy — valid only when the contract declares
    * presence fields (TypeError at construction otherwise). `ttlMs` is
@@ -1295,22 +1266,6 @@ export function createServer<
     },
     fallbackSeen: number,
   ): Promise<void> => {
-    // The push-route provenance seam, mirroring appendExternal: a
-    // branded patch came from the wire, so `validatePush` runs before
-    // field validation and the broadcast — with `events: []`, the
-    // documented presence-only shape.
-    if (Reflect.get(patch, '~a2.pushed') === true) {
-      // Frozen before the callback: this is the authorization seam,
-      // and an authorization hook must not be able to rewrite
-      // authorship or values on its way through (assignment throws
-      // under strict mode, failing the push loudly).
-      Object.freeze(patch.values)
-      await options.validatePush?.({
-        sessionId,
-        events: [],
-        presence: Object.freeze(patch as PushedPresence),
-      })
-    }
     if (
       typeof patch.participant !== 'string' ||
       patch.participant.length === 0
@@ -2240,16 +2195,38 @@ export function createServer<
                 shouldClaim = false
               }
             }
+            if (
+              claim?.outcome === 'claimed' &&
+              [...active.values()].some((entry) => entry.lapsed)
+            ) {
+              shouldClaim = true
+              continue
+            }
             if (active.size > 0) {
               const wake = signal?.wait(signalVersion)
-              await Promise.race([
-                ...[...active.values()].map((entry) => entry.execution),
-                ...(wake ? [wake.promise] : []),
+              const hasLapsed = [...active.values()].some(
+                (entry) => entry.lapsed,
+              )
+              const retry =
+                claim?.outcome === 'busy' && hasLapsed
+                  ? defaultSleep(
+                      Math.max(0, claim.retryAt.getTime() - Date.now()),
+                    )
+                  : undefined
+              const retryDue = await Promise.race([
+                ...[...active.values()].map((entry) =>
+                  entry.execution.then(() => false),
+                ),
+                ...(wake ? [wake.promise.then(() => false)] : []),
+                ...(retry ? [retry.promise.then(() => true)] : []),
               ])
               wake?.cancel()
+              retry?.cancel()
               shouldClaim =
+                retryDue ||
                 claimAgain ||
                 active.size === 0 ||
+                hasLapsed ||
                 (signal !== undefined && signal.version !== signalVersion)
               claimAgain = false
               continue
@@ -2298,19 +2275,12 @@ export function createServer<
   const appendExternal = async (
     sessionId: string,
     mode: 'inline' | 'dispatch',
-    events: Array<AppendInput<D> | PushedEvent>,
+    events: AppendInput<D>[],
     requireDurableInitialArm = false,
   ): Promise<ContractEvent<D>[]> => {
-    const pushed = events.filter(
-      (event): event is PushedEvent =>
-        Reflect.get(event, '~a2.pushed') === true,
-    )
-    if (pushed.length > 0) {
-      await options.validatePush?.({ sessionId, events: pushed })
-    }
     return appendCore(
       sessionId,
-      events as AppendInput<D>[],
+      events,
       'external',
       mode,
       (_rows, watchdogDueAt) => scheduleDrain(sessionId, watchdogDueAt),
@@ -2320,21 +2290,23 @@ export function createServer<
     )
   }
 
+  const session = (id: string): Session<D, SessionAppend<D>, P> => {
+    assertSessionId(id)
+    const appendInline = async (...events: AppendInput<D>[]) =>
+      appendExternal(id, 'inline', events)
+    const appendDispatch = async (...events: AppendInput<D>[]) =>
+      appendExternal(id, 'dispatch', events)
+    const append = Object.assign(appendInline, {
+      dispatch: appendDispatch,
+    }) as SessionAppend<D>
+    return makeSession(id, append, null)
+  }
+
+  const fetch = createServerFetch({ contract: serverContract, session })
   const self: A2Server<D, P> = {
     contract: serverContract,
-    session(id) {
-      assertSessionId(id)
-      const appendInline = async (
-        ...events: Array<AppendInput<D> | PushedEvent>
-      ) => appendExternal(id, 'inline', events)
-      const appendDispatch = async (
-        ...events: Array<AppendInput<D> | PushedEvent>
-      ) => appendExternal(id, 'dispatch', events)
-      const append = Object.assign(appendInline, {
-        dispatch: appendDispatch,
-      }) as SessionAppend<D>
-      return makeSession(id, append, null)
-    },
+    fetch,
+    session,
 
     async drain(sessionId) {
       assertSessionId(sessionId)
@@ -2363,126 +2335,6 @@ export function createServer<
       await appendExternal(sessionId, 'inline', [...events], true)
     },
   })
-  serverSchedulerBindings.set(self, { scheduler })
-
-  serverInspection.set(self, {
-    async listSessions(inspectionOptions) {
-      const store = await resolveStore()
-      if (!store.inspect) {
-        throw new InspectionUnsupportedError(
-          'this store backend does not support inspection',
-        )
-      }
-      const page = await store.inspect.listSessions({
-        prefix: `${name}${NS}`,
-        limit: inspectionOptions.limit,
-        ...(inspectionOptions.cursor !== undefined
-          ? { cursor: inspectionOptions.cursor }
-          : {}),
-      })
-      return {
-        cursor: page.cursor,
-        // oxlint-disable-next-line oxc/no-map-spread -- inspection results remain adapter-owned
-        sessions: page.sessions.map((session) => {
-          const publicSession = { ...session }
-          publicSession.sessionId = stripNs(session.sessionId)
-          return publicSession
-        }),
-      }
-    },
-    async readSessionPage(sessionId, inspectionOptions) {
-      assertSessionId(sessionId)
-      if (
-        !Number.isSafeInteger(inspectionOptions.afterIndex) ||
-        inspectionOptions.afterIndex < 0 ||
-        !Number.isSafeInteger(inspectionOptions.limit) ||
-        inspectionOptions.limit < 1 ||
-        (inspectionOptions.throughIndex !== undefined &&
-          (!Number.isSafeInteger(inspectionOptions.throughIndex) ||
-            inspectionOptions.throughIndex < 0))
-      ) {
-        throw new TypeError('invalid inspection event page bounds')
-      }
-      const store = await resolveStore()
-      if (!store.inspect) {
-        throw new InspectionUnsupportedError(
-          'this store backend does not support inspection',
-        )
-      }
-      const ns = nsId(sessionId)
-      const snapshots =
-        inspectionOptions.afterIndex === 0
-          ? await store.inspect.listSnapshots(ns)
-          : []
-      const page = store.inspect.readEvents
-        ? await store.inspect.readEvents(ns, inspectionOptions)
-        : await (async () => {
-            const all = await store.read(ns)
-            const currentFrontier = all.at(-1)?.index ?? 0
-            const throughIndex = Math.min(
-              inspectionOptions.throughIndex ?? currentFrontier,
-              currentFrontier,
-            )
-            return {
-              events: all
-                .filter(
-                  (event) =>
-                    event.index > inspectionOptions.afterIndex &&
-                    event.index <= throughIndex,
-                )
-                .slice(0, inspectionOptions.limit),
-              throughIndex,
-            }
-          })()
-      const { events, throughIndex } = page
-      if (
-        !Number.isSafeInteger(throughIndex) ||
-        throughIndex < 0 ||
-        events.length > inspectionOptions.limit ||
-        (inspectionOptions.throughIndex !== undefined &&
-          inspectionOptions.afterIndex > 0 &&
-          throughIndex !== inspectionOptions.throughIndex)
-      ) {
-        throw new A2Error(
-          'STORE_UNAVAILABLE',
-          `inspection event page for session '${sessionId}' has invalid bounds`,
-        )
-      }
-      for (let position = 0; position < events.length; position += 1) {
-        if (
-          events[position]!.index !==
-            inspectionOptions.afterIndex + position + 1 ||
-          events[position]!.index > throughIndex
-        ) {
-          throw new A2Error(
-            'STORE_UNAVAILABLE',
-            `inspection event page for session '${sessionId}' is not contiguous`,
-          )
-        }
-      }
-      if (inspectionOptions.afterIndex < throughIndex && events.length === 0) {
-        throw new A2Error(
-          'STORE_UNAVAILABLE',
-          `inspection event page for session '${sessionId}' ended before index ${throughIndex}`,
-        )
-      }
-      const lastIndex = events.at(-1)?.index ?? inspectionOptions.afterIndex
-      return {
-        // oxlint-disable-next-line oxc/no-map-spread -- inspection results remain adapter-owned
-        events: events.map((event) => {
-          const publicEvent = { ...event }
-          publicEvent.sessionId = sessionId
-          return publicEvent
-        }),
-        snapshots: snapshots.filter(
-          (snapshot) => snapshot.index <= throughIndex,
-        ),
-        throughIndex,
-        nextIndex: lastIndex < throughIndex ? lastIndex : null,
-      }
-    },
-  })
-
   return self
 }
 
@@ -2666,7 +2518,6 @@ function cloneInitial<S>(initial: S): S {
 // transports — re-exported so experimental-a2/server is self-sufficient.
 export type {
   A2Store,
-  A2StoreInspection,
   AppendEvent,
   Clock,
   Event,
@@ -2678,9 +2529,6 @@ export type {
   StoreStateRead,
   PresenceRow,
   StoredEvent,
-  StoredSessionPage,
-  StoredSessionSummary,
-  StoredSnapshot,
 } from './store.ts'
 export type {
   ScheduledEvent,

package/src/session-socket.ts

@@ -11,7 +11,8 @@ 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 type { ParsedPushEvent, ParsedPushPresence } from './push-envelope.ts'
+import type { Session } from './server.ts'
 import { parsePresenceSibling, parsePushEvents } from './push-envelope.ts'
 import {
   SOCKET_PING_FRAME,
@@ -71,16 +72,15 @@ 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`.
+ * runtime (`setPresence` present). The cast stays inside the transport.
  */
 export type SocketSession = {
   stream(opts: {
     startAfter: number
     presence?: boolean
   }): AsyncIterable<Event | PresencePatch | PresenceSnapshot>
-  append(...events: PushedEvent[]): Promise<Event[]>
-  setPresence?(patch: PushedPresence): Promise<void>
+  append(...events: ParsedPushEvent[]): Promise<Event[]>
+  setPresence?(patch: ParsedPushPresence): Promise<void>
 }
 
 /**
@@ -238,7 +238,8 @@ export type SessionsSocketResolve<D extends EventDefs> = (
   sessionId: string,
   /** The entry's resume frontier — `stream({ startAfter })`. */
   startAfter: number,
-) => Session<D> | null | Promise<Session<D> | null>
+) =>
+  Pick<Session<D>, 'stream'> | null | Promise<Pick<Session<D>, 'stream'> | null>
 
 export type SessionsSocketOptions = {
   /** The `stream()` presence opt-in for every session on the socket —
@@ -247,17 +248,11 @@ export type SessionsSocketOptions = {
   /** 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.
-   */
+  /** Runs after frame parsing and before append or presence I/O. */
   gatePush?(
     sessionId: string,
-    events: PushedEvent[],
+    events: ParsedPushEvent[],
+    presence?: ParsedPushPresence,
   ): A2Error | null | Promise<A2Error | null>
 }
 
@@ -359,11 +354,14 @@ export function sessionsSocket<D extends EventDefs>(
     id: string,
     index: number,
   ): Promise<void> => {
-    let session: Session<D> | null
+    let session: Pick<Session<D>, 'stream'> | null
     try {
       session = await resolve(id, index)
     } catch {
-      session = null
+      if (!shell.torn()) {
+        shell.send(socketUnsubscribedFor(id, 'stream failed'))
+      }
+      return
     }
     if (shell.torn()) return
     if (session === null) {
@@ -419,7 +417,8 @@ export function sessionsSocket<D extends EventDefs>(
     }
     try {
       const events = parsePushEvents(frame['events'])
-      const denial = (await options?.gatePush?.(sessionId, events)) ?? null
+      const denial =
+        (await options?.gatePush?.(sessionId, events, undefined)) ?? null
       if (denial !== null) {
         shell.send(socketErrorAckFor(req, denial, sessionId))
         return
@@ -442,11 +441,28 @@ export function sessionsSocket<D extends EventDefs>(
       shell.malformedFrame('presence frame on a presence-less session')
       return
     }
+    let patch: ParsedPushPresence | undefined
     try {
-      const patch = parsePresenceSibling(frame)
-      if (patch) await subscription.target.setPresence(patch)
+      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')
     }
   }
 

package/src/sse.ts

@@ -1,7 +1,7 @@
 /**
  * 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
+ * teardown for the live stream lane. Internal module: `server.fetch` is
+ * the sanctioned caller; the framing rules stay
  * documented on `sseResponse` because the client's parser (and the
  * stall watchdog) depend on them.
  */

package/src/store-memory.ts

@@ -21,7 +21,6 @@ import {
   type IdSource,
   type PresenceRow,
   type StoredEvent,
-  type StoredSessionSummary,
   type StoreStateRead,
 } from './store.ts'
 
@@ -648,86 +647,6 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       },
     },
 
-    inspect: {
-      async listSessions(inspectionOptions) {
-        const ids = [...sessions.keys()]
-          .filter(
-            (sessionId) =>
-              sessionId.startsWith(inspectionOptions.prefix) &&
-              (inspectionOptions.cursor === undefined ||
-                sessionId > inspectionOptions.cursor),
-          )
-          .toSorted()
-        const visible = ids.slice(0, inspectionOptions.limit)
-        const summaries = visible.map((sessionId): StoredSessionSummary => {
-          const rows = sessions.get(sessionId)!
-          const first = rows[0]!
-          let updatedAt = first.createdAt
-          let pendingCount = 0
-          let failedCount = 0
-          let attemptCount = 0
-          let failureCount = 0
-          for (const row of rows) {
-            attemptCount += row.attemptCount
-            failureCount += row.failureCount
-            if (row.processedAt === null && row.failedAt === null) {
-              pendingCount += 1
-            }
-            if (row.failedAt !== null) failedCount += 1
-            for (const timestamp of [
-              row.createdAt,
-              row.firstClaimedAt,
-              row.lastClaimedAt,
-              row.lastFailedAt,
-              row.processedAt,
-              row.failedAt,
-            ]) {
-              if (timestamp && timestamp > updatedAt) updatedAt = timestamp
-            }
-          }
-          return {
-            sessionId,
-            eventCount: rows.length,
-            pendingCount,
-            failedCount,
-            attemptCount,
-            failureCount,
-            firstEventAt: new Date(first.createdAt),
-            updatedAt: new Date(updatedAt),
-          }
-        })
-        return {
-          sessions: summaries,
-          cursor: ids.length > visible.length ? (visible.at(-1) ?? null) : null,
-        }
-      },
-      async readEvents(sessionId, pageOptions) {
-        const rows = sessions.get(sessionId) ?? []
-        const throughIndex = Math.min(
-          pageOptions.throughIndex ?? rows.length,
-          rows.length,
-        )
-        return {
-          events: rows
-            .slice(pageOptions.afterIndex, throughIndex)
-            .slice(0, pageOptions.limit)
-            .map(toStored),
-          throughIndex,
-        }
-      },
-      async listSnapshots(sessionId) {
-        const prefix = `${sessionId}\u0000`
-        return [...snapshots.entries()]
-          .filter(([key]) => key.startsWith(prefix))
-          .map(([key, snapshot]) => ({
-            reducerName: key.slice(prefix.length),
-            index: snapshot.index,
-            updatedAt: new Date(snapshot.updatedAt),
-          }))
-          .toSorted((a, b) => a.reducerName.localeCompare(b.reducerName))
-      },
-    },
-
     stream(sessionId, opts) {
       const startAfter = opts?.startAfter ?? 0
       return {