experimental-a2 0.3.0 → 0.5.0

package/src/errors.ts

@@ -0,0 +1,50 @@
+/**
+ * a2 errors — one class, discriminated by `code`.
+ *
+ * See specs/a2-implementation.md §10 and docs/reference/02-errors.mdx.
+ * A single class serializes cleanly across the push-route boundary and
+ * keeps `instanceof` checks working after bundling.
+ */
+
+export type A2ErrorCode =
+  | 'INVALID_PAYLOAD' // schema validation failed — thrown before anything is written
+  | 'UNKNOWN_EVENT_TYPE' // event type not in the machine's `events` map
+  | 'PARTIAL_DUPLICATE_BATCH' // batch mixed already-appended and fresh events
+  | 'SUPERSEDED_ATTEMPT' // handler append from an attempt a recovery claim replaced
+  | 'CLAIM_EXPIRED' // ctx.signal abort reason: the attempt's lease lapsed without renewal
+  | 'STORE_UNAVAILABLE' // store backend failure — retryable, nothing was written
+  | 'STORE_NOT_CONFIGURED' // production boot with no `store` passed
+  | 'UNKNOWN_PRESENCE_FIELD' // presence field not in the contract's `presence` map
+  | 'PRESENCE_NOT_SUPPORTED' // contract declares presence but the store lacks the capability
+
+export class A2Error extends Error {
+  readonly code: A2ErrorCode
+  /** e.g. the Standard Schema issues for INVALID_PAYLOAD */
+  readonly details: unknown
+
+  constructor(
+    code: A2ErrorCode,
+    message: string,
+    options?: { details?: unknown; cause?: unknown },
+  ) {
+    super(
+      message,
+      options && 'cause' in options ? { cause: options.cause } : undefined,
+    )
+    this.name = 'A2Error'
+    this.code = code
+    this.details = options?.details
+  }
+}
+
+/**
+ * Wrap an arbitrary thrown value as STORE_UNAVAILABLE, preserving the
+ * original as `cause`. A2Errors pass through untouched — they already
+ * carry their own meaning.
+ */
+export function asStoreUnavailable(err: unknown): A2Error {
+  if (err instanceof A2Error) return err
+  return new A2Error('STORE_UNAVAILABLE', 'the store backend failed', {
+    cause: err,
+  })
+}

package/src/http.ts

@@ -0,0 +1,394 @@
+/**
+ * experimental-a2/http — the wire's server half (specs/a2-api.md §9–10, §13).
+ *
+ * A thin public assembly. The surface: `handle` — GET, POST, and the
+ * socket's frames parsed into intents (stream, history, push,
+ * ws-upgrade) with `before`/`after` hooks around them for policy —
+ * plus `A2Intent`/`A2Outcome`/`UpgradeFn`/`A2Socket` (its argument
+ * types), `errorResponse`/`deserializeError` (the A2Error wire pair
+ * both sides branch on), and `schedulerHandler` (the scheduler
+ * callback mount). The machinery lives in internal modules — the SSE
+ * framing in sse.ts, the push-envelope trust boundary in
+ * push-envelope.ts, the socket shell and multiplexed handler in
+ * session-socket.ts — because nothing outside `handle` is sanctioned
+ * to compose them. Policy — auth, caching, quotas — never enters this
+ * module: the hooks own it.
+ */
+
+import { A2Error } from './errors.ts'
+import {
+  assertServerSchedulerBindings,
+  assertSchedulerTargets,
+  schedulerForServer,
+} from './internal.ts'
+import type { ContractEvent, EventDefs, PresenceDefs } from './contract.ts'
+import type {
+  A2Server,
+  DrainableServer,
+  PushedEvent,
+  PushedPresence,
+} from './server.ts'
+import { sseResponse } from './sse.ts'
+import { invalidPushBody, parsePushBody } from './push-envelope.ts'
+import {
+  sessionsSocket,
+  type A2Socket,
+  type SocketSession,
+} from './session-socket.ts'
+import {
+  asA2Error,
+  errorFromWire,
+  errorStatus,
+  errorToWire,
+  eventToWire,
+} from './wire.ts'
+
+export type { A2Socket } from './session-socket.ts'
+
+/**
+ * Create one scheduler callback route for servers sharing the same configured
+ * scheduler. Configuration mistakes throw immediately while the route module
+ * is evaluated, before a delivery can be acknowledged by the wrong adapter.
+ */
+export function schedulerHandler(
+  firstServer: DrainableServer,
+  ...servers: DrainableServer[]
+): (req: Request) => Promise<Response> {
+  if (firstServer === undefined) {
+    throw new TypeError('schedulerHandler() requires at least one A2 server')
+  }
+  const scheduler = schedulerForServer(firstServer)
+  const targets = [firstServer, ...servers]
+  assertSchedulerTargets(targets, { allowStructural: false })
+  assertServerSchedulerBindings(scheduler, targets)
+  return scheduler.handler(...targets)
+}
+
+/**
+ * Serialize an error into the documented wire shape,
+ * `{ error: { code, message, details } }`, with the mapped status
+ * (400 for caller bugs, 503 for STORE_UNAVAILABLE). Non-A2Errors become a
+ * 503 STORE_UNAVAILABLE — from the client's perspective an unknown server
+ * failure is retryable-once, not a protocol contract. The natural
+ * return value of a `before` hook that wants the wire's own error
+ * shapes.
+ */
+export function errorResponse(error: unknown): Response {
+  const a2error = asA2Error(error)
+  return Response.json(errorToWire(a2error), {
+    status: errorStatus(a2error.code),
+  })
+}
+
+/**
+ * The other half of the wire pair: rebuild an `A2Error` from a response
+ * body, or null if the body isn't one. Client `push` uses it so both
+ * sides branch on identical codes.
+ */
+export function deserializeError(body: unknown): A2Error | null {
+  return errorFromWire(body)
+}
+
+// ── handle: the request protocol, parsed ────────────────────────
+
+/**
+ * What a request (or socket frame) asks of a session, parsed — the
+ * argument policy hooks branch on. `stream` covers the SSE GET and the
+ * socket's subscribe frames; `push` covers the HTTP POST and the
+ * socket's push frames; `history` is the bounded cold read the
+ * client's `loadHistory` rides; `ws-upgrade` is the upgrade GET before
+ * any frame flows.
+ */
+export type A2Intent<D extends EventDefs = EventDefs> =
+  | { type: 'ws-upgrade' }
+  | {
+      type: 'stream'
+      sessionId: string
+      startAfter: number
+      transport: 'sse' | 'ws'
+    }
+  | { type: 'history'; sessionId: string; gte: number; lte: number }
+  | {
+      type: 'push'
+      sessionId: string
+      /** Parsed and branded, payloads not yet validated — `type`
+       * autocompletes the contract's names but is any string off the
+       * wire; `append` rejects unknown types after the hooks run. */
+      events: Array<PushedEvent & { type: SuggestedEventType<D> }>
+      presence?: PushedPresence
+      transport: 'http' | 'ws'
+    }
+
+/** The contract's event names for editor completion, without excluding
+ * the wire's reality (any string can arrive; validation is later). */
+type SuggestedEventType<D extends EventDefs> =
+  (keyof D & string) | (string & Record<never, never>)
+
+/** What the library did with an allowed intent — `after`'s view.
+ * `covered` = the closed range is fully present (an immutable slice of
+ * the append-only log), the one caching-relevant fact the library
+ * owns; policy over it belongs to the app's `after`. */
+export type A2Outcome<D extends EventDefs = EventDefs> =
+  | { type: 'stream' }
+  | { type: 'history'; covered: boolean; events: ContractEvent<D>[] }
+  | { type: 'push'; appended: ContractEvent<D>[] }
+
+/**
+ * The platform's socket-upgrade seam: given the attach callback, return
+ * the 101 response. On Vercel:
+ * `upgrade: (attach) => experimental_upgradeWebSocket(attach)`.
+ */
+export type UpgradeFn = (
+  attach: (socket: A2Socket) => void,
+) => Response | Promise<Response>
+
+const parseHistoryBounds = (
+  gte: string | null,
+  lte: string | null,
+): { gte: number; lte: number } => {
+  if (gte === null || lte === null) {
+    throw new A2Error(
+      'INVALID_PAYLOAD',
+      'a history read takes both gte and lte',
+    )
+  }
+  const bounds = { gte: Number(gte), lte: Number(lte) }
+  for (const [name, value] of Object.entries(bounds)) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new A2Error(
+        'INVALID_PAYLOAD',
+        `history ${name} must be a non-negative safe integer`,
+      )
+    }
+  }
+  if (bounds.gte > bounds.lte) {
+    throw new A2Error(
+      'INVALID_PAYLOAD',
+      'history gte must be less than or equal to lte',
+    )
+  }
+  return bounds
+}
+
+const parseResumeIndex = (raw: string | null): number => {
+  if (raw === null) return 0
+  const index = Number(raw)
+  if (!Number.isSafeInteger(index) || index < 0) {
+    throw new A2Error(
+      'INVALID_PAYLOAD',
+      'stream index must be a non-negative safe integer',
+    )
+  }
+  return index
+}
+
+/** One bag: the policy hooks and the capability options — the names
+ * distinguish them, so `handle(server, { presence: true })` and
+ * `handle(server, { before, upgrade })` both read naturally. */
+export type HandleOptions<D extends EventDefs = EventDefs> = {
+  /** Return a Response to deny; thrown errors are treated as
+   * infrastructure failures and answer with the retryable wire shape. */
+  before?(args: {
+    request: Request
+    intent: A2Intent<D>
+  }): Response | undefined | void | Promise<Response | undefined | void>
+  after?(args: {
+    request: Request
+    intent: A2Intent<D>
+    outcome: A2Outcome<D>
+    response: Response
+  }): Response | undefined | void | Promise<Response | undefined | void>
+  upgrade?: UpgradeFn
+  presence?: boolean
+  deadline?: number
+}
+
+/**
+ * The session route pair as one call: `export const { GET, POST } =
+ * handle(server, options?)` serves the live stream (SSE GET, resumed
+ * at `index`), the history slice (GET with `gte`/`lte`), the push
+ * envelope (POST), and — with `options.upgrade` — the multiplexed
+ * WebSocket, all through one pair of policy hooks.
+ *
+ * Parsing is protocol, hooks are policy: a request that fails to parse
+ * (missing sessionId, malformed bounds, bad push envelope) answers
+ * INVALID_PAYLOAD on the wire before any hook runs. `before` sees
+ * every parsed intent — HTTP requests and socket frames alike, with
+ * `request` always the original (for socket frames: upgrade) Request —
+ * and short-circuits by returning a Response: over HTTP it is the
+ * response verbatim; over the socket it is translated to the wire's
+ * own vocabulary (subscribe → `unsubscribed { reason: 'subscribe
+ * rejected' }`, push → an INVALID_PAYLOAD error ack), because a
+ * Response body cannot cross a socket. `after` runs only where the
+ * library produced an HTTP response — never after a short-circuit,
+ * never for socket frames — and may mutate `response.headers` in place
+ * or return a replacement (history caching policy lives here, on
+ * `outcome.covered`). `options.deadline` (epoch ms) closes sockets
+ * cleanly ahead of a known platform deadline, so clients reconnect on
+ * our schedule.
+ */
+export function handle<
+  D extends EventDefs,
+  P extends PresenceDefs = Record<never, never>,
+>(
+  server: A2Server<D, P>,
+  options?: HandleOptions<D>,
+): {
+  GET(req: Request): Promise<Response>
+  POST(req: Request): Promise<Response>
+} {
+  const presence = options?.presence === true
+
+  const before = async (
+    request: Request,
+    intent: A2Intent<D>,
+  ): Promise<Response | null> => {
+    const result = await options?.before?.({ request, intent })
+    return result instanceof Response ? result : null
+  }
+
+  const decorate = async (
+    request: Request,
+    intent: A2Intent<D>,
+    outcome: A2Outcome<D>,
+    response: Response,
+  ): Promise<Response> => {
+    const replaced = await options?.after?.({
+      request,
+      intent,
+      outcome,
+      response,
+    })
+    return replaced instanceof Response ? replaced : response
+  }
+
+  // Socket frames re-enter `before` with the upgrade Request — one
+  // policy point for both wires, and the fix for pushes that were
+  // gated only at subscribe time.
+  const attach =
+    (request: Request) =>
+    (socket: A2Socket): void => {
+      sessionsSocket<D>(
+        async (sessionId, startAfter) => {
+          const short = await before(request, {
+            type: 'stream',
+            sessionId,
+            startAfter,
+            transport: 'ws',
+          })
+          return short === null ? server.session(sessionId) : null
+        },
+        socket,
+        {
+          presence,
+          ...(options?.deadline === undefined
+            ? {}
+            : { deadline: options.deadline }),
+          gatePush: async (sessionId, events) => {
+            const short = await before(request, {
+              type: 'push',
+              sessionId,
+              events,
+              transport: 'ws',
+            })
+            // The denial Response cannot cross the socket; INVALID_PAYLOAD
+            // is the one caller-fault code the client never retries — a
+            // retryable code would spin retries against a standing denial.
+            return short === null
+              ? null
+              : new A2Error('INVALID_PAYLOAD', 'push rejected')
+          },
+        },
+      )
+    }
+
+  return {
+    async GET(req: Request): Promise<Response> {
+      try {
+        if (req.headers.get('upgrade')?.toLowerCase() === 'websocket') {
+          const short = await before(req, { type: 'ws-upgrade' })
+          if (short !== null) return short
+          if (options?.upgrade === undefined) {
+            return new Response(
+              "WebSocket upgrade requested, but handle() has no upgrade implementation — pass options.upgrade, e.g. { upgrade: (attach) => experimental_upgradeWebSocket(attach) } from '@vercel/functions'",
+              { status: 426 },
+            )
+          }
+          return await options.upgrade(attach(req))
+        }
+        const { searchParams } = new URL(req.url)
+        const sessionId = searchParams.get('sessionId')
+        if (sessionId === null || sessionId.length === 0) {
+          throw new A2Error('INVALID_PAYLOAD', 'missing sessionId')
+        }
+        const gteRaw = searchParams.get('gte')
+        const lteRaw = searchParams.get('lte')
+        if (gteRaw !== null || lteRaw !== null) {
+          const bounds = parseHistoryBounds(gteRaw, lteRaw)
+          const intent: A2Intent<D> = { type: 'history', sessionId, ...bounds }
+          const short = await before(req, intent)
+          if (short !== null) return short
+          const events = await server.session(sessionId).history(bounds)
+          const covered = events.length === bounds.lte - bounds.gte + 1
+          return await decorate(
+            req,
+            intent,
+            { type: 'history', covered, events },
+            Response.json(events.map(eventToWire)),
+          )
+        }
+        const startAfter = parseResumeIndex(searchParams.get('index'))
+        const intent: A2Intent<D> = {
+          type: 'stream',
+          sessionId,
+          startAfter,
+          transport: 'sse',
+        }
+        const short = await before(req, intent)
+        if (short !== null) return short
+        const target = server.session(sessionId) as unknown as SocketSession
+        const response = sseResponse(
+          presence
+            ? target.stream({ startAfter, presence: true })
+            : target.stream({ startAfter }),
+        )
+        return await decorate(req, intent, { type: 'stream' }, response)
+      } catch (err) {
+        return errorResponse(err)
+      }
+    },
+
+    async POST(req: Request): Promise<Response> {
+      try {
+        const body = await parsePushBody(req)
+        const intent: A2Intent<D> = {
+          type: 'push',
+          sessionId: body.sessionId,
+          events: body.events,
+          ...(body.presence === undefined ? {} : { presence: body.presence }),
+          transport: 'http',
+        }
+        const short = await before(req, intent)
+        if (short !== null) return short
+        const session = server.session(body.sessionId)
+        if (body.presence !== undefined) {
+          const target = session as unknown as SocketSession
+          if (typeof target.setPresence !== 'function') {
+            throw invalidPushBody('presence is not declared by this contract')
+          }
+          await target.setPresence(body.presence)
+        }
+        const appended =
+          body.events.length === 0 ? [] : await session.append(...body.events)
+        return await decorate(
+          req,
+          intent,
+          { type: 'push', appended },
+          Response.json(appended),
+        )
+      } catch (err) {
+        return errorResponse(err)
+      }
+    },
+  }
+}

package/src/idempotent-replay.ts

@@ -0,0 +1,53 @@
+import { A2Error } from './errors.ts'
+import type { AppendEvent, StoredEvent } from './store.ts'
+
+const canonicalJson = (value: unknown): string =>
+  JSON.stringify(value, (_key, candidate: unknown) => {
+    if (
+      candidate === null ||
+      typeof candidate !== 'object' ||
+      Array.isArray(candidate)
+    ) {
+      return candidate
+    }
+    return Object.fromEntries(
+      Object.entries(candidate).toSorted(([left], [right]) =>
+        left < right ? -1 : left > right ? 1 : 0,
+      ),
+    )
+  }) ?? 'null'
+
+export const idempotentReplay = (
+  events: readonly AppendEvent[],
+  existing: readonly StoredEvent[],
+): StoredEvent[] => {
+  const byId = new Map(existing.map((event) => [event.id, event]))
+  const ordered = events.map((event) =>
+    event.id === undefined ? undefined : byId.get(event.id),
+  )
+  const firstIndex = ordered[0]?.index
+  const batchSize = events[0]?.cause?.batchSize
+
+  if (
+    firstIndex === undefined ||
+    (batchSize !== undefined && batchSize !== events.length) ||
+    ordered.some((stored, index) => {
+      const event = events[index]!
+      return (
+        stored === undefined ||
+        stored.index !== firstIndex + index ||
+        stored.type !== event.type ||
+        stored.lane !== (event.lane ?? null) ||
+        stored.cause?.batchSize !== event.cause?.batchSize ||
+        canonicalJson(stored.payload) !== canonicalJson(event.payload)
+      )
+    })
+  ) {
+    throw new A2Error(
+      'PARTIAL_DUPLICATE_BATCH',
+      'already-appended events do not match the retried batch',
+    )
+  }
+
+  return ordered as StoredEvent[]
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * a2 — a durable event log for serverless apps.
+ *
+ * This entry point is isomorphic by construction: the contract (the
+ * vocabulary everything shares), reducers derived from it, and the
+ * error type. Implementing a contract — storage, handlers, sessions —
+ * lives in experimental-a2/server, which never enters a browser bundle.
+ */
+
+export { contract } from './contract.ts'
+export type {
+  AppendInput,
+  Contract,
+  ContractEvent,
+  EventDefs,
+  EventBatchFactory,
+  PresenceDefs,
+  PresenceMap,
+  PresencePatch,
+  PresenceSnapshot,
+  ReducerOptions,
+} from './contract.ts'
+
+export type { Reducer, ReducerBuilder } from './reducer.ts'
+
+export { A2Error } from './errors.ts'
+export type { A2ErrorCode } from './errors.ts'
+
+export type {
+  A2AttributeValue,
+  A2SpanHandle,
+  A2SpanName,
+  A2Telemetry,
+} from './telemetry.ts'
+
+export type { Event } from './store.ts'
+export type { StandardSchemaV1 } from './standard-schema.ts'

package/src/inspection.ts

@@ -0,0 +1,39 @@
+/**
+ * Private bridge between `createServer` and `experimental-a2/devtools/server`.
+ * Servers keep their store closure private; the WeakMap grants A2's own
+ * read-only devtools entry point access without adding public methods to
+ * application server handles.
+ */
+
+import type { StoredEvent, StoredSessionPage, StoredSnapshot } from './store.ts'
+
+export class InspectionUnsupportedError extends Error {}
+
+export type ServerInspection = {
+  listSessions(options: {
+    cursor?: string
+    limit: number
+  }): Promise<StoredSessionPage>
+  readSessionPage(
+    sessionId: string,
+    options: { afterIndex: number; throughIndex?: number; limit: number },
+  ): Promise<{
+    events: StoredEvent[]
+    snapshots: StoredSnapshot[]
+    throughIndex: number
+    nextIndex: number | null
+  }>
+}
+
+export const serverInspection: WeakMap<object, ServerInspection> = new WeakMap()
+
+/** Owned live-inspection cadence; mutable only for white-box tests. */
+export const DEVTOOLS_TIMINGS: {
+  activeMs: number
+  idleMs: number
+  heartbeatMs: number
+} = {
+  activeMs: 250,
+  idleMs: 1_000,
+  heartbeatMs: 15_000,
+}