experimental-a2 0.4.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 } : {}
+}