experimental-a2 0.6.0 → 0.7.0

package/src/http.ts

@@ -1,394 +0,0 @@
-/**
- * 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/inspection.ts

@@ -1,39 +0,0 @@
-/**
- * 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,
-}

package/src/testing.browser.ts

@@ -1,5 +0,0 @@
-/** experimental-a2/testing loads local capture files and is Node-only. */
-throw new Error(
-  'experimental-a2/testing is Node-only. Load captures in a local test or script.',
-)
-export {}

package/src/testing.ts

@@ -1,185 +0,0 @@
-/**
- * Offline helpers for loading a captured A2 session and replaying its events
- * through the application's current reducers. This module never constructs a
- * server or dispatches handlers.
- */
-
-import { readFile } from 'node:fs/promises'
-import { fileURLToPath } from 'node:url'
-import type { Contract, ContractEvent, EventDefs } from './contract.ts'
-import {
-  parseDevtoolsCapture,
-  verifyDevtoolsCapture,
-  type DevtoolsCapture,
-  type DevtoolsCaptureEvent,
-} from './devtools.ts'
-import type { Reducer } from './reducer.ts'
-import { validateSync } from './validate.ts'
-
-export type CaptureSource = string | URL
-
-export type LoadedCapture<D extends EventDefs> = {
-  /** The verified capture, including its footer and operational records. */
-  readonly capture: DevtoolsCapture
-  /** The contract used to validate and type the captured event history. */
-  readonly contract: Contract<D>
-  /** Contract-typed public events with `createdAt` revived to `Date`. */
-  readonly events: readonly ContractEvent<D>[]
-  /** Unmodified wire events, including dispatch and failure metadata. */
-  readonly rawEvents: readonly DevtoolsCaptureEvent[]
-}
-
-export type ReplayCaptureOptions = {
-  /** Fold events through this log index, inclusive. Zero means no events. */
-  throughIndex?: number
-}
-
-export type CaptureReplay<S> = {
-  readonly state: S
-  /** The last event index actually folded, or zero for the initial state. */
-  readonly index: number
-}
-
-const captureError = (message: string): TypeError =>
-  new TypeError(`invalid A2 capture: ${message}`)
-
-const typedEvents = <D extends EventDefs>(
-  capture: DevtoolsCapture,
-  contract: Contract<D>,
-): ContractEvent<D>[] => {
-  const events: ContractEvent<D>[] = []
-  for (const event of capture.events) {
-    const schema = Object.hasOwn(contract.events, event.type)
-      ? contract.events[event.type]
-      : undefined
-    if (schema === undefined) {
-      throw captureError(
-        `contract '${contract.name}' has no event type '${event.type}' at index ${event.index}`,
-      )
-    }
-    const result = validateSync(
-      schema,
-      structuredClone(event.payload),
-      `captured event '${event.type}'`,
-    )
-    if (result.issues !== undefined) {
-      throw captureError(
-        `event #${event.index} '${event.type}' has an invalid payload: ${result.issues
-          .map((issue) => issue.message)
-          .join('; ')}`,
-      )
-    }
-    events.push({
-      id: event.id,
-      type: event.type,
-      payload: result.value,
-      index: event.index,
-      sessionId: event.sessionId,
-      createdAt: new Date(event.createdAt),
-    } as ContractEvent<D>)
-  }
-  return events
-}
-
-/** Validate an already-parsed capture against an application's contract. */
-export async function prepareCapture<D extends EventDefs>(
-  capture: DevtoolsCapture,
-  contract: Contract<D>,
-): Promise<LoadedCapture<D>> {
-  await verifyDevtoolsCapture(capture)
-  if (capture.contract !== contract.name) {
-    throw captureError(
-      `expected contract '${contract.name}', received '${capture.contract}'`,
-    )
-  }
-  return {
-    capture,
-    contract,
-    events: typedEvents(capture, contract),
-    rawEvents: capture.events,
-  }
-}
-
-const displayUrl = (url: URL): string => {
-  if (url.protocol === 'data:') return 'data: URL'
-  const safe = new URL(url)
-  safe.username = ''
-  safe.password = ''
-  safe.search = ''
-  safe.hash = ''
-  return safe.href
-}
-
-const fetchCapture = async (url: URL): Promise<Uint8Array> => {
-  const location = displayUrl(url)
-  let response: Response
-  try {
-    response = await fetch(url)
-  } catch {
-    throw new Error(`failed to load A2 capture from '${location}'`)
-  }
-  if (!response.ok) {
-    throw new Error(
-      `failed to load A2 capture from '${location}': ${response.status} ${response.statusText}`,
-    )
-  }
-  return new Uint8Array(await response.arrayBuffer())
-}
-
-const readCapture = async (source: CaptureSource): Promise<Uint8Array> => {
-  if (source instanceof URL) {
-    return source.protocol === 'file:'
-      ? readFile(fileURLToPath(source))
-      : fetchCapture(source)
-  }
-  if (/^[a-z]:[\\/]/i.test(source)) return readFile(source)
-  let url: URL | undefined
-  try {
-    url = new URL(source)
-  } catch {
-    return readFile(source)
-  }
-  return readCapture(url)
-}
-
-/** Load, integrity-check, and contract-type a `.a2log` file or URL. */
-export async function loadCapture<D extends EventDefs>(
-  source: CaptureSource,
-  contract: Contract<D>,
-): Promise<LoadedCapture<D>> {
-  const encoded = await readCapture(source)
-  const capture = parseDevtoolsCapture(encoded)
-  return prepareCapture(capture, contract)
-}
-
-const cloneInitial = <S>(initialState: S): S => {
-  try {
-    return structuredClone(initialState)
-  } catch {
-    return initialState
-  }
-}
-
-/** Purely fold captured events through a reducer, optionally to a cutpoint. */
-export function replayCapture<D extends EventDefs, S>(
-  loaded: LoadedCapture<D>,
-  reducer: Reducer<D, S>,
-  options: ReplayCaptureOptions = {},
-): CaptureReplay<S> {
-  const { throughIndex } = options
-  if (
-    throughIndex !== undefined &&
-    (!Number.isInteger(throughIndex) || throughIndex < 0)
-  ) {
-    throw new TypeError('throughIndex must be a non-negative integer')
-  }
-
-  let state = cloneInitial(reducer.initialState)
-  let index = 0
-  for (const event of loaded.events) {
-    if (throughIndex !== undefined && event.index > throughIndex) break
-    state = reducer.fold(state, event)
-    index = event.index
-  }
-  return { state, index }
-}