experimental-a2 0.3.0 → 0.5.0

package/src/wire.ts

@@ -0,0 +1,454 @@
+/**
+ * The wire format shared by experimental-a2/http (server side) and experimental-a2/client
+ * (browser side): events as JSON with ISO timestamps, and the A2Error
+ * envelope. Internal module — both entry points re-export what's
+ * public.
+ */
+
+import { A2Error, type A2ErrorCode } from './errors.ts'
+import { nullProtoRecord } from './internal.ts'
+import type { Event } from './store.ts'
+import type {
+  PresenceMap,
+  PresencePatch,
+  PresenceSnapshot,
+} from './contract.ts'
+
+export type WireEvent = {
+  id: string
+  type: string
+  payload: unknown
+  index: number
+  sessionId: string
+  /** ISO 8601 — revived to a Date on the client so reducers see the
+   * same shape on both sides of the wire. */
+  createdAt: string
+}
+
+export function eventToWire(event: Event): WireEvent {
+  return {
+    id: event.id,
+    type: event.type,
+    payload: event.payload,
+    index: event.index,
+    sessionId: event.sessionId,
+    createdAt: event.createdAt.toISOString(),
+  }
+}
+
+export function eventFromWire(wire: WireEvent): Event {
+  return {
+    id: wire.id,
+    type: wire.type,
+    payload: wire.payload,
+    index: wire.index,
+    sessionId: wire.sessionId,
+    createdAt: new Date(wire.createdAt),
+  }
+}
+
+export function isWireEvent(value: unknown): value is WireEvent {
+  if (value === null || typeof value !== 'object') return false
+  const v = value as Record<string, unknown>
+  return (
+    typeof v['id'] === 'string' &&
+    typeof v['type'] === 'string' &&
+    typeof v['index'] === 'number' &&
+    typeof v['sessionId'] === 'string' &&
+    typeof v['createdAt'] === 'string'
+  )
+}
+
+// ── the presence wire pair ───────────────────────────────────────────
+
+/** The `event: presence` SSE frame body: one patch as JSON. */
+export type WirePresencePatch = {
+  participant: string
+  values: Record<string, unknown>
+  seen: number
+  /** ISO 8601 — revived to a Date on the client. */
+  at: string
+}
+
+/**
+ * The `event: presence-snapshot` SSE frame body: the in-memory
+ * `PresenceSnapshot` shape verbatim, with each per-field `at`
+ * serialized to ISO 8601.
+ */
+export type WirePresenceSnapshot = {
+  snapshot: {
+    [participant: string]: {
+      [field: string]: { value: unknown; seen: number; at: string }
+    }
+  }
+}
+
+export function presencePatchToWire(patch: PresencePatch): WirePresencePatch {
+  return {
+    participant: patch.participant,
+    values: patch.values,
+    seen: patch.seen,
+    at: patch.at.toISOString(),
+  }
+}
+
+export function presencePatchFromWire(wire: WirePresencePatch): PresencePatch {
+  return {
+    participant: wire.participant,
+    values: wire.values,
+    seen: wire.seen,
+    at: new Date(wire.at),
+  }
+}
+
+// Participant and field keys come off the wire, so every object keyed
+// by them is built null-prototype — see `nullProtoRecord`.
+export function presenceSnapshotToWire(
+  snapshot: PresenceSnapshot,
+): WirePresenceSnapshot {
+  const wire: WirePresenceSnapshot['snapshot'] = nullProtoRecord()
+  for (const [participant, fields] of Object.entries(snapshot.snapshot)) {
+    const wireFields: WirePresenceSnapshot['snapshot'][string] =
+      nullProtoRecord()
+    for (const [field, entry] of Object.entries(fields)) {
+      if (entry === undefined) continue
+      wireFields[field] = {
+        value: entry.value,
+        seen: entry.seen,
+        at: entry.at.toISOString(),
+      }
+    }
+    wire[participant] = wireFields
+  }
+  return { snapshot: wire }
+}
+
+export function presenceSnapshotFromWire(
+  wire: WirePresenceSnapshot,
+): PresenceSnapshot {
+  const map: PresenceMap = nullProtoRecord()
+  for (const [participant, fields] of Object.entries(wire.snapshot)) {
+    const revived: PresenceMap[string] = nullProtoRecord()
+    for (const [field, entry] of Object.entries(fields)) {
+      revived[field] = {
+        value: entry.value,
+        seen: entry.seen,
+        at: new Date(entry.at),
+      }
+    }
+    map[participant] = revived
+  }
+  return { snapshot: map }
+}
+
+export function isWirePresencePatch(
+  value: unknown,
+): value is WirePresencePatch {
+  if (value === null || typeof value !== 'object') return false
+  const v = value as Record<string, unknown>
+  return (
+    typeof v['participant'] === 'string' &&
+    v['values'] !== null &&
+    typeof v['values'] === 'object' &&
+    !Array.isArray(v['values']) &&
+    typeof v['seen'] === 'number' &&
+    typeof v['at'] === 'string'
+  )
+}
+
+export function isWirePresenceSnapshot(
+  value: unknown,
+): value is WirePresenceSnapshot {
+  if (value === null || typeof value !== 'object') return false
+  const v = value as Record<string, unknown>
+  return (
+    v['snapshot'] !== null &&
+    typeof v['snapshot'] === 'object' &&
+    !Array.isArray(v['snapshot'])
+  )
+}
+
+// ── the A2Error envelope ─────────────────────────────────────────────
+
+export type WireError = {
+  error: { code: A2ErrorCode; message: string; details?: unknown }
+}
+
+const ERROR_STATUS: Record<A2ErrorCode, number> = {
+  INVALID_PAYLOAD: 400,
+  UNKNOWN_EVENT_TYPE: 400,
+  PARTIAL_DUPLICATE_BATCH: 400,
+  SUPERSEDED_ATTEMPT: 409,
+  CLAIM_EXPIRED: 409,
+  STORE_UNAVAILABLE: 503,
+  STORE_NOT_CONFIGURED: 500,
+  UNKNOWN_PRESENCE_FIELD: 400,
+  PRESENCE_NOT_SUPPORTED: 500,
+}
+
+export function errorStatus(code: A2ErrorCode): number {
+  return ERROR_STATUS[code]
+}
+
+export function errorToWire(error: A2Error): WireError {
+  const body: WireError = {
+    error: { code: error.code, message: error.message },
+  }
+  if (error.details !== undefined) body.error.details = error.details
+  return body
+}
+
+/** Wrap an arbitrary thrown value for the wire: A2Errors pass through,
+ * anything else becomes STORE_UNAVAILABLE — from the client's
+ * perspective an unknown server failure is retryable-once, not a
+ * protocol contract. */
+export function asA2Error(error: unknown): A2Error {
+  return error instanceof A2Error
+    ? error
+    : new A2Error('STORE_UNAVAILABLE', 'internal error', { cause: error })
+}
+
+/** Rebuild an A2Error from a wire body; null if the body isn't one. */
+export function errorFromWire(body: unknown): A2Error | null {
+  if (body === null || typeof body !== 'object') return null
+  const err = (body as { error?: unknown }).error
+  if (err === null || typeof err !== 'object') return null
+  const { code, message, details } = err as Record<string, unknown>
+  if (typeof code !== 'string' || !Object.hasOwn(ERROR_STATUS, code))
+    return null
+  return new A2Error(code as A2ErrorCode, String(message ?? code), {
+    details,
+  })
+}
+
+// ── the ws frame layer ───────────────────────────────────────────────
+// The SSE lanes reframed for a socket (specs/a2-api.md §13): every
+// message is one JSON text frame, and a frame is its wire payload plus
+// a `kind` discriminant (plus `req` where a reply must correlate).
+// Unknown kinds are skipped by both sides — the same
+// forward-compatibility rule as named SSE frames.
+//
+// The multiplexed superset rides the same frames: `subscribe` /
+// `unsubscribe` up-frames open and close per-session lanes on one
+// socket, `sessionId` tags route everything else. Single-session
+// frames (no tags) keep parsing unchanged — a route opts into
+// multiplexing by choosing the multi-session server handler, never by
+// breaking the old protocol.
+
+/**
+ * Server → client, parsed: a live-stream item, a push ack, a
+ * subscription lifecycle notice, or the heartbeat. `parseSocketFrame`
+ * yields these; frames of unknown kind (or ones failing their shape
+ * guard) come back `null`. `sessionId` is present on frames from a
+ * multiplexed socket and absent on a single-session one.
+ */
+export type SocketDownFrame =
+  | { kind: 'event'; event: WireEvent }
+  | { kind: 'presence'; patch: WirePresencePatch; sessionId?: string }
+  | {
+      kind: 'presence-snapshot'
+      snapshot: WirePresenceSnapshot
+      sessionId?: string
+    }
+  | { kind: 'ack'; req: number; events: WireEvent[]; sessionId?: string }
+  | { kind: 'ack'; req: number; error: A2Error; sessionId?: string }
+  | { kind: 'subscribed'; sessionId: string }
+  | { kind: 'unsubscribed'; sessionId: string; reason?: string }
+  | { kind: 'ping' }
+
+/**
+ * Client → server: the push envelope's two planes. `sessionId` is
+ * implied by the socket on a single-session connection and required by
+ * the multiplexed handler. Plain JSON on the wire; the server parses
+ * and validates them through the same seams as `parsePushBody`.
+ */
+export type SocketPushFrame = {
+  kind: 'push'
+  /** Client-local ack correlator — opaque to the server. */
+  req: number
+  events: Array<{ type: string; payload: unknown; id?: string }>
+  sessionId?: string
+}
+
+export type SocketPresenceFrame = {
+  kind: 'presence'
+  participant: string
+  values: Record<string, unknown>
+  seen?: number
+  at?: number
+  sessionId?: string
+}
+
+/** Open per-session lanes on a multiplexed socket. `index` is each
+ * session's exclusive resume frontier — `stream({ startAfter })`. */
+export type SocketSubscribeFrame = {
+  kind: 'subscribe'
+  sessions: Array<{ id: string; index: number }>
+}
+
+export type SocketUnsubscribeFrame = {
+  kind: 'unsubscribe'
+  sessions: string[]
+}
+
+export type SocketUpFrame =
+  | SocketPushFrame
+  | SocketPresenceFrame
+  | SocketSubscribeFrame
+  | SocketUnsubscribeFrame
+
+export const SOCKET_PING_FRAME: string = JSON.stringify({ kind: 'ping' })
+
+/** One stream item as a socket frame — `sseResponse`'s framing over
+ * the same codecs, with `kind` instead of an SSE event name. On a
+ * multiplexed socket presence frames carry the `sessionId` tag; events
+ * already carry theirs in the wire event. */
+export function socketFrameFor(
+  item: Event | PresencePatch | PresenceSnapshot,
+  sessionId?: string,
+): string {
+  const tag = sessionId === undefined ? {} : { sessionId }
+  if ('snapshot' in item) {
+    return JSON.stringify({
+      kind: 'presence-snapshot',
+      ...presenceSnapshotToWire(item),
+      ...tag,
+    })
+  }
+  if ('participant' in item) {
+    return JSON.stringify({
+      kind: 'presence',
+      ...presencePatchToWire(item),
+      ...tag,
+    })
+  }
+  return JSON.stringify({ kind: 'event', ...eventToWire(item) })
+}
+
+export function socketAckFor(
+  req: number,
+  events: Event[],
+  sessionId?: string,
+): string {
+  return JSON.stringify({
+    kind: 'ack',
+    req,
+    events: events.map(eventToWire),
+    ...(sessionId === undefined ? {} : { sessionId }),
+  })
+}
+
+export function socketErrorAckFor(
+  req: number,
+  error: A2Error,
+  sessionId?: string,
+): string {
+  return JSON.stringify({
+    kind: 'ack',
+    req,
+    ...errorToWire(error),
+    ...(sessionId === undefined ? {} : { sessionId }),
+  })
+}
+
+export function socketSubscribedFor(sessionId: string): string {
+  return JSON.stringify({ kind: 'subscribed', sessionId })
+}
+
+/** The subscription-over notice: with a `reason` the server rejected
+ * or lost the session's stream, without one it ended cleanly. */
+export function socketUnsubscribedFor(
+  sessionId: string,
+  reason?: string,
+): string {
+  return JSON.stringify({
+    kind: 'unsubscribed',
+    sessionId,
+    ...(reason === undefined ? {} : { reason }),
+  })
+}
+
+export function parseSocketFrame(data: string): SocketDownFrame | null {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(data)
+  } catch {
+    return null
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return null
+  }
+  const frame = parsed as Record<string, unknown>
+  switch (frame['kind']) {
+    case 'ping':
+      return { kind: 'ping' }
+    case 'event': {
+      if (!isWireEvent(parsed)) return null
+      const { id, type, payload, index, sessionId, createdAt } = parsed
+      return {
+        kind: 'event',
+        event: { id, type, payload, index, sessionId, createdAt },
+      }
+    }
+    case 'presence': {
+      if (!isWirePresencePatch(parsed)) return null
+      const { participant, values, seen, at } = parsed
+      return {
+        kind: 'presence',
+        patch: { participant, values, seen, at },
+        ...sessionTag(frame),
+      }
+    }
+    case 'presence-snapshot': {
+      if (!isWirePresenceSnapshot(parsed)) return null
+      return {
+        kind: 'presence-snapshot',
+        snapshot: { snapshot: parsed.snapshot },
+        ...sessionTag(frame),
+      }
+    }
+    case 'subscribed': {
+      const sessionId = frame['sessionId']
+      if (typeof sessionId !== 'string') return null
+      return { kind: 'subscribed', sessionId }
+    }
+    case 'unsubscribed': {
+      const sessionId = frame['sessionId']
+      if (typeof sessionId !== 'string') return null
+      const reason = frame['reason']
+      return typeof reason === 'string'
+        ? { kind: 'unsubscribed', sessionId, reason }
+        : { kind: 'unsubscribed', sessionId }
+    }
+    case 'ack': {
+      const req = frame['req']
+      if (typeof req !== 'number') return null
+      const tag = sessionTag(frame)
+      const events = frame['events']
+      if (Array.isArray(events) && events.every(isWireEvent)) {
+        return { kind: 'ack', req, events, ...tag }
+      }
+      const error = errorFromWire(parsed)
+      if (error) return { kind: 'ack', req, error, ...tag }
+      // A correlatable ack must never be dropped: its waiter would hang
+      // forever behind a healthy socket (pings keep the watchdog fed).
+      // An outcome this client cannot interpret — an error code from a
+      // newer server, an event shape that fails a guard — degrades to
+      // a lost ack: retryable, and the client-generated ids make the
+      // retry idempotent even if the append actually committed.
+      return {
+        kind: 'ack',
+        req,
+        error: new A2Error('STORE_UNAVAILABLE', 'unintelligible ack'),
+        ...tag,
+      }
+    }
+    default:
+      return null
+  }
+}
+
+const sessionTag = (frame: Record<string, unknown>): { sessionId?: string } => {
+  const sessionId = frame['sessionId']
+  return typeof sessionId === 'string' ? { sessionId } : {}
+}

package/dist/internal-gCd5qMry.js

@@ -1,44 +0,0 @@
-//#region src/internal.ts
-const serverInternals = /* @__PURE__ */ new WeakMap();
-/**
-* Drain timing knobs. Mutable only as a white-box test seam. Claim
-* heartbeats run on real timers, so tests shrink these to keep suites
-* fast. Production always uses the defaults.
-*/
-const DRAIN_TIMINGS = {
-	claimTtlMs: 5e3,
-	claimHeartbeatMs: 2e3,
-	recoveryGraceMs: 1e3,
-	recoveryArmTimeoutMs: 2e3
-};
-/**
-* Stream liveness knobs — the server-side SSE heartbeat and the
-* client-side stall watchdog. Paired by design: the client declares a
-* connection dead after roughly two missed heartbeats. Mutable only as
-* a white-box test seam; production always uses the defaults.
-*/
-/**
-* Poll cadence for the poll-based log streams (sqlite, postgres) —
-* owned, not configurable: adaptive polling removed the operator's
-* reason to tune it (the floor keeps active streams smooth; the
-* ceiling bounds idle cost). Mutable only as a white-box test seam so
-* suites don't wait out real idle gaps.
-*/
-const POLL_TIMINGS = {
-	activeFloorMs: 25,
-	idleCeilingMs: 250
-};
-/**
-* Safety-read cadence for the notify-driven redis live stream. A
-* parked feed re-reads the log at this interval even without a
-* pub/sub wake-up, so a lost notification (subscriber reconnect gap,
-* dropped PUBLISH) costs latency, never an event. Mutable only as a
-* white-box test seam.
-*/
-const NOTIFY_TIMINGS = { safetyReadMs: 1e4 };
-const STREAM_TIMINGS = {
-	sseHeartbeatMs: 15e3,
-	stallTimeoutMs: 35e3
-};
-//#endregion
-export { serverInternals as a, STREAM_TIMINGS as i, NOTIFY_TIMINGS as n, POLL_TIMINGS as r, DRAIN_TIMINGS as t };

package/dist/log-memory.d.ts

@@ -1,11 +0,0 @@
-import { c as IdSource, i as Clock, t as A2Log } from "./log-ldf5g8Cx.js";
-//#region src/log-memory.d.ts
-type MemoryLogOptions = {
-  /** Injectable clock — every stored timestamp comes from here. */
-  clock?: Clock;
-  /** Injectable id source for generated event ids. */
-  ids?: IdSource;
-};
-declare function memory(options?: MemoryLogOptions): A2Log;
-//#endregion
-export { MemoryLogOptions, memory };

package/dist/recovery-vercel.js

@@ -1,119 +0,0 @@
-import { a as serverInternals, t as DRAIN_TIMINGS } from "./internal-gCd5qMry.js";
-import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
-import { n as SYSTEM_CLOCK } from "./log-yJbXUf72.js";
-//#region src/recovery-vercel.ts
-/**
-* experimental-a2/recovery-vercel — queue-backed recovery over Vercel Queues.
-*
-* `vercelQueues()` returns an `A2Recovery` (a2-implementation.md §9):
-*
-* - `arm` rounds the requested watchdog time up to a one-second slot.
-*   One message per `(contract, session, dueAt)` coalesces appends,
-*   claim renewals and racing callbacks. `DuplicateMessageError` is
-*   success because that due-time slot is already durable.
-* - `handler(...servers)` is the delivery route: look up the server for
-*   the contract named in the message and drain it. Settled drains ack;
-*   contention arms a later watchdog before acking; handler failure keeps
-*   the current message and redelivers with backoff.
-*
-* `@vercel/queue` is an optional peer dependency, imported lazily. The
-* `transport` option is the injection seam — tests run a real little
-* in-memory queue through the same interface.
-*/
-/**
-* The "not settled yet" signal for a stalled handler — an expected state,
-* not a transport failure. The default transport classifies it in
-* `@vercel/queue`'s `retry` option and reschedules the delivery quietly
-* (`{ afterSeconds }` → visibility change → 200 response, no error log)
-* instead of letting it surface as a thrown 500. Busy deliveries use a
-* fresh watchdog instead. Custom transports should treat this class the
-* same way when their protocol has a polite reschedule.
-*/
-var RecoveryUnsettled = class extends Error {};
-/** Vercel Queues rejects shorter visibility changes. */
-const MIN_VISIBILITY_SECONDS = 30;
-/** Redelivery backoff for retry states: base, 2×, 4×… bounded. */
-const unsettledBackoffSeconds = (delaySeconds, deliveryCount) => Math.min(Math.max(delaySeconds * 2 ** Math.max(deliveryCount - 1, 0), MIN_VISIBILITY_SECONDS), 60);
-const vercelQueueTransport = async (delaySeconds) => {
-	const queue = await import("@vercel/queue").catch(() => {
-		throw new Error("experimental-a2/recovery-vercel needs the '@vercel/queue' package (optional peer dependency) — install it, or inject a transport");
-	});
-	return {
-		send: (topic, message, options) => queue.send(topic, message, options),
-		handleCallback: (handler) => queue.handleCallback(handler, {
-			visibilityTimeoutSeconds: MIN_VISIBILITY_SECONDS,
-			retry: (error, metadata) => error instanceof RecoveryUnsettled ? { afterSeconds: unsettledBackoffSeconds(delaySeconds, metadata.deliveryCount) } : void 0
-		}),
-		isDuplicate: (error) => error instanceof queue.DuplicateMessageError
-	};
-};
-function vercelQueues(options = {}) {
-	const topic = options.topic ?? "a2";
-	const delaySeconds = options.delaySeconds ?? 5;
-	const clock = options.clock ?? SYSTEM_CLOCK;
-	const transport = retryableLazy(() => options.transport ? Promise.resolve(options.transport) : vercelQueueTransport(delaySeconds)).get;
-	const sendWatchdog = async (opts) => {
-		const t = await transport();
-		const nowMs = clock.now().getTime();
-		const requestedDueAt = opts.dueAt ?? nowMs + delaySeconds * 1e3;
-		const dueAt = Math.ceil(requestedDueAt / 1e3) * 1e3;
-		const recoveryId = `${opts.contract}:${opts.sessionId}:watchdog:${dueAt}`;
-		try {
-			await t.send(topic, {
-				contract: opts.contract,
-				sessionId: opts.sessionId,
-				dueAt
-			}, {
-				delaySeconds: Math.max(0, Math.ceil((dueAt - nowMs) / 1e3)),
-				idempotencyKey: recoveryId
-			});
-		} catch (err) {
-			if (t.isDuplicate(err)) return;
-			throw err;
-		}
-	};
-	const successorDueAt = (message) => {
-		const minimumDueAt = clock.now().getTime() + DRAIN_TIMINGS.claimTtlMs + DRAIN_TIMINGS.recoveryGraceMs;
-		if (message.dueAt === void 0) return minimumDueAt;
-		const beats = Math.max(1, Math.ceil((minimumDueAt - message.dueAt) / DRAIN_TIMINGS.claimHeartbeatMs));
-		return message.dueAt + beats * DRAIN_TIMINGS.claimHeartbeatMs;
-	};
-	return {
-		async arm({ contract, sessionId, dueAt }) {
-			await sendWatchdog({
-				contract,
-				sessionId,
-				...dueAt !== void 0 ? { dueAt } : {}
-			});
-		},
-		handler(...servers) {
-			const byContract = /* @__PURE__ */ new Map();
-			for (const server of servers) byContract.set(server.contract.name, server);
-			return async (req) => {
-				return (await transport()).handleCallback(async (message) => {
-					const server = byContract.get(message.contract);
-					if (!server) throw new Error(`a2 recovery: no server for contract '${message.contract}' — pass it to recovery.handler(...)`);
-					const internals = serverInternals.get(server);
-					const nextDueAt = successorDueAt(message);
-					const result = internals ? await internals.recoveryDrain(message.sessionId, { recoveryDueAt: nextDueAt }) : {
-						...await server.drain(message.sessionId),
-						outcome: "unknown"
-					};
-					if (result.settled) return;
-					if (result.outcome === "busy") {
-						if (result.recoveryArm) await result.recoveryArm;
-						else await sendWatchdog({
-							contract: message.contract,
-							sessionId: message.sessionId,
-							dueAt: nextDueAt
-						});
-						return;
-					}
-					throw new RecoveryUnsettled(`a2 recovery: session '${message.sessionId}' of '${message.contract}' not settled yet (${result.outcome}) — rescheduled for redelivery`);
-				})(req);
-			};
-		}
-	};
-}
-//#endregion
-export { RecoveryUnsettled, vercelQueues };