statewire 0.8.1 → 0.9.0

package/src/transports/sse.ts

@@ -1,88 +1,77 @@
 import { useRef, useState } from "react";
 import { flushTapSync, resource } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
-import { encodeParams, reviveResponse } from "../wire/meta";
 import { createSseParser } from "./sse-parser";
 import { timing } from "../client/timing";
 import {
   classify,
   handleEnvelope,
-  overloadedError,
-  parseRetryAfter,
   useStatewireConn,
 } from "../client/connection";
 import type {
+  AttemptOutcome,
   Conn,
+  StatewireCmd,
   StatewireEnvelope,
-  StatewireResponse,
+  StatewireSyn,
 } from "../client/connection";
 import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
 import type { StatewireHost } from "../host";
 import { useStatewireRemote } from "./remote";
 
+/** A client frame's lanes: stamped statements, strictly consecutive per lane. */
+export type StatewireFrame = {
+  ctx?: { ops: unknown[]; seq: number }[];
+  cmd?: { method: string; params: unknown[]; meta?: unknown; seq: number }[];
+};
+
 export type StatewireRemoteProps = {
   clientId: string;
-  onSnapshot: (args: { ops: unknown[]; lastSeq: number }) => void;
-  onOps: (args: {
-    ops: unknown[];
-    res?: StatewireResponse[];
-    ack?: number;
-  }) => void;
+  /** Lanes to ride the attach frame (no-lease supersession only); records the included seqs. */
+  takeAttachLanes: () => StatewireFrame | null;
+  onHello: (args: { ops: unknown[]; syn: StatewireSyn }) => void;
+  onOps: (args: { ops: unknown[]; cmds: StatewireCmd[] }) => void;
+  onCmds: (cmds: StatewireCmd[]) => void;
+  onRefusal: (syn: StatewireSyn) => void;
+  onIdle: (level: boolean) => void;
+  onDetach: () => void;
   onFinish: (args: StatewireHost.Fin) => void;
 };
 
-export type StatewireWireCommand =
-  | { method: string; params: readonly unknown[]; context?: never }
-  | { method?: never; params?: never; context: Record<string, unknown> };
-
-/** The wire shape of a client context submission: one root replace op. */
-export const contextOps = (value: Record<string, unknown>) => [
-  { op: "replace", path: [], value },
-];
-
-export const encodeWireCommand = (command: StatewireWireCommand) => ({
-  ...(command.method !== undefined && {
-    method: command.method,
-    ...encodeParams(command.params),
-  }),
-  ...(command.context !== undefined && {
-    context: contextOps(command.context),
-  }),
-});
-
 export type StatewireSubmitResult =
-  | { type: "receipt"; response?: StatewireResponse }
-  | { type: "rejected"; message: string }
-  | { type: "seq-gap" }
-  | { type: "unknown-client" }
-  | { type: "stale-lease" };
+  | { type: "ok" }
+  | { type: "refusal"; syn: StatewireSyn }
+  | { type: "stale-lease" }
+  | { type: "no-lease" };
 
 export type ConnectionState = StatewireClient.ConnectionState;
 
-/** The live wire a remote session drives: connection status plus command POST. */
+/** The live wire a remote session drives: connection status plus frame submission. */
 export type RemoteLink = {
   connection: StatewireClient.Connection;
-  send: (args: {
-    seq: number;
-    command: StatewireWireCommand;
-  }) => Promise<StatewireSubmitResult>;
+  send: (frame: StatewireFrame) => Promise<StatewireSubmitResult>;
 };
 
+const LEASE_HEADER = "Statewire-Lease";
+
 const baseUrl = (options: StatewireClient.SSEOptions) =>
   options.url.replace(/\/$/, "");
 
 export type AuthState = { stale: boolean };
 
-const requestHeaders = async (
+const resolveHeaders = async (
   options: StatewireClient.SSEOptions,
-  extra: Record<string, string>,
   ctx: { staleAuth: boolean },
-) => {
+): Promise<Headers> => {
   const { headers } = options;
-  const merged = new Headers(
+  return new Headers(
     typeof headers === "function" ? await headers(ctx) : headers,
   );
+};
+
+const withExtra = (headers: Headers, extra: Record<string, string>) => {
+  const merged = new Headers(headers);
   for (const [name, value] of Object.entries(extra)) merged.set(name, value);
   return merged;
 };
@@ -105,7 +94,7 @@ const consume = async (
   reader: ReadableStreamDefaultReader<Uint8Array>,
   heartbeat: AbortController,
   dead: () => boolean,
-): Promise<"stop" | "reattach" | "ended"> => {
+): Promise<AttemptOutcome> => {
   const decoder = new TextDecoder();
   const parse = createSseParser();
   for (;;) {
@@ -136,17 +125,16 @@ const attemptStream = async (
   options: StatewireClient.SSEOptions,
   auth: AuthState,
   abort: AbortController,
-): Promise<"stop" | "reattach" | "ended"> => {
+): Promise<AttemptOutcome> => {
   const stale = auth.stale;
   auth.stale = false;
-  const headers = await requestHeaders(
-    options,
-    {
-      "Statewire-Client-Id": c.ctx.clientId,
-      accept: "text/event-stream",
-    },
-    { staleAuth: stale },
-  );
+  c.lease = null;
+  const userHeaders = await resolveHeaders(options, { staleAuth: stale });
+  const lanes = flushTapSync(() => c.ctx.takeAttachLanes());
+  const frame = {
+    headers: Object.fromEntries(userHeaders),
+    ...(lanes ?? {}),
+  };
   const heartbeat = new AbortController();
   const headerTimer = setTimeout(
     () => heartbeat.abort(),
@@ -158,7 +146,13 @@ const attemptStream = async (
       options,
       `${baseUrl(options)}/stream`,
       {
-        headers,
+        method: "POST",
+        headers: withExtra(userHeaders, {
+          "content-type": "application/json",
+          "Statewire-Client-Id": c.ctx.clientId,
+          accept: "text/event-stream",
+        }),
+        body: JSON.stringify(frame),
         cache: "no-store",
         signal: AbortSignal.any([abort.signal, heartbeat.signal]),
       },
@@ -167,13 +161,13 @@ const attemptStream = async (
   } finally {
     clearTimeout(headerTimer);
   }
-  if (res.status === 429 || res.status === 503) throw overloaded(res);
   if (res.status === 401) {
     if (stale) c.episode = { cause: "unauthorized" };
     auth.stale = true;
     throw new Error("unauthorized");
   }
   if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
+  c.lease = res.headers.get(LEASE_HEADER);
   const reader = res.body.getReader();
   try {
     return await consume(c, reader, heartbeat, () => abort.signal.aborted);
@@ -182,32 +176,25 @@ const attemptStream = async (
   }
 };
 
-const overloaded = (res: Response) =>
-  overloadedError(parseRetryAfter(res.headers.get("Retry-After")));
-
-const postCommand = async (
+const postFrame = async (
   c: Conn,
   options: StatewireClient.SSEOptions,
-  { seq, command }: { seq: number; command: StatewireWireCommand },
+  lease: string,
+  frame: StatewireFrame,
   timeout: AbortSignal,
   stale: boolean,
 ): Promise<Response> =>
   timedFetch(
     options,
-    `${baseUrl(options)}/commands`,
+    `${baseUrl(options)}/frames`,
     {
       method: "POST",
-      headers: await requestHeaders(
-        options,
-        {
-          "content-type": "application/json",
-          "Statewire-Client-Id": c.ctx.clientId,
-          "Statewire-Command-Seq": String(seq),
-          ...(c.lease !== null && { "Statewire-Lease": c.lease }),
-        },
-        { staleAuth: stale },
-      ),
-      body: JSON.stringify(encodeWireCommand(command)),
+      headers: withExtra(await resolveHeaders(options, { staleAuth: stale }), {
+        "content-type": "application/json",
+        "Statewire-Client-Id": c.ctx.clientId,
+        [LEASE_HEADER]: lease,
+      }),
+      body: JSON.stringify(frame),
       signal: AbortSignal.any([
         c.lifetime?.signal ?? AbortSignal.abort(),
         timeout,
@@ -216,32 +203,51 @@ const postCommand = async (
     timeout,
   );
 
-const sendCommand = async (
+// Delta-seconds only; anything else reads as absent.
+const retryAfterMs = (res: Response): number | null => {
+  const header = res.headers.get("retry-after")?.trim();
+  return header !== undefined && /^\d+$/.test(header)
+    ? Number(header) * 1000
+    : null;
+};
+
+const refusalSyn = async (res: Response): Promise<StatewireSyn> => {
+  const body = (await res.json().catch(() => null)) as {
+    syn?: StatewireSyn;
+  } | null;
+  const syn = body?.syn;
+  if (typeof syn !== "object" || syn === null) {
+    throw new Error(`HTTP ${res.status}`);
+  }
+  return syn;
+};
+
+const sendFrame = async (
   c: Conn,
   options: StatewireClient.SSEOptions,
   auth: AuthState,
-  args: { seq: number; command: StatewireWireCommand },
+  frame: StatewireFrame,
 ): Promise<StatewireSubmitResult> => {
+  const lease = c.lease;
+  if (lease === null) return { type: "no-lease" };
   const timeout = AbortSignal.timeout(timing.heartbeatTimeoutMs);
-  let res = await postCommand(c, options, args, timeout, false);
+  let res = await postFrame(c, options, lease, frame, timeout, false);
   if (res.status === 401 && typeof options.headers === "function") {
-    res = await postCommand(c, options, args, timeout, true);
+    res = await postFrame(c, options, lease, frame, timeout, true);
   }
-  if (res.ok) {
-    let body: { res?: StatewireResponse } | null;
-    try {
-      body = (await res.json()) as { res?: StatewireResponse } | null;
-    } catch {
-      return {
-        type: "rejected",
-        message: "statewire: protocol error: malformed /commands receipt body",
-      };
-    }
-    return body?.res !== undefined
-      ? { type: "receipt", response: reviveResponse(body.res) }
-      : { type: "receipt" };
+  if (res.ok) return { type: "ok" };
+  if (res.status === 429 || res.status === 409) {
+    // The syn body retry wins; Retry-After covers 429s minted below the host.
+    const headerRetry = res.status === 429 ? retryAfterMs(res) : null;
+    const syn: StatewireSyn = await refusalSyn(res).catch((error: unknown) => {
+      if (headerRetry === null) throw error;
+      return { retry: headerRetry };
+    });
+    if (syn.retry === undefined && headerRetry !== null)
+      syn.retry = headerRetry;
+    return { type: "refusal", syn };
   }
-  if (res.status === 429 || res.status === 503) throw overloaded(res);
+  if (res.status === 423) return { type: "stale-lease" };
   if (res.status === 401) {
     // Fresh credentials did not clear the 401: signal auth-failed on the
     // connection and let the send retry as a transport fault.
@@ -250,27 +256,6 @@ const sendCommand = async (
     c.connection.reconnect();
     throw new Error("unauthorized");
   }
-  // Bodies settle, statuses pace: only a statewire-shaped body carries a
-  // verdict; any bare status is middleware noise — a transport fault, retried.
-  const body = (await res.json().catch(() => null)) as {
-    error?: string;
-    rejections?: { message?: string }[];
-  } | null;
-  if (body?.error === "rejected") {
-    return {
-      type: "rejected",
-      message: body.rejections?.[0]?.message ?? `HTTP ${res.status}`,
-    };
-  }
-  if (res.status === 409 || res.status === 412 || res.status === 423) {
-    const verdict =
-      res.status === 409
-        ? ("seq-gap" as const)
-        : res.status === 412
-          ? ("unknown-client" as const)
-          : ("stale-lease" as const);
-    if (body?.error === verdict) return { type: verdict };
-  }
   throw new Error(`HTTP ${res.status}`);
 };
 
@@ -292,7 +277,7 @@ const useSseLink = (
       get connection() {
         return c.connection;
       },
-      send: (args) => sendCommand(c, latest.current, auth, args),
+      send: (frame) => sendFrame(c, latest.current, auth, frame),
     }),
   );
   return link;
@@ -300,12 +285,11 @@ const useSseLink = (
 
 const useStatewireSSE = (
   options: StatewireClient.SSEOptions,
-): Statewire<any, any, any> => useStatewireRemote(options, useSseLink);
+): Statewire<any, any> => useStatewireRemote(options, useSseLink);
 
 export const StatewireSSE = resource(useStatewireSSE) as <
   TState = any,
   TCommands extends Statewire.Commands = Statewire.Commands,
-  TEvent = any,
 >(
   options: StatewireClient.SSEOptions,
-) => ResourceElement<Statewire<TState | undefined, TCommands, TEvent>>;
+) => ResourceElement<Statewire<TState | undefined, TCommands>>;

package/src/transports/testing.ts

@@ -1,6 +1,7 @@
 import type { ResourceElement } from "@assistant-ui/tap";
 import type { StatewireEnvelope } from "../client/connection";
 import { StatewireSSE } from "./sse";
+import type { StatewireFrame } from "./sse";
 import type { Statewire } from "../types";
 import { openSSEStream, sseFrame } from "./fake-sse";
 import type { FakeStreamHandle } from "./fake-sse";
@@ -14,13 +15,15 @@ export { applyOptimistic } from "../util/recordMutations";
 
 export type MockTransport<TState> = {
   /** Pass as the `transport:` option of useStatewire / Harness. */
-  transport: ResourceElement<Statewire<TState | undefined, any, any>>;
-  /** Captured `/commands` POST bodies, in POST order. */
+  transport: ResourceElement<Statewire<TState | undefined, any>>;
+  /** Captured statements in arrival order: cmd as `{method, params}`, ctx as `{context}`. */
   commands: { method?: string; params?: unknown[]; context?: unknown }[];
   /** Replace the replicated state and broadcast it as a root snapshot op. */
   setState: (state: TState) => Promise<void>;
-  /** Deliver an ack watermark on the stream. */
-  ack: (seq: number) => Promise<void>;
+  /** Deliver a bare ack cmd packet on the stream. */
+  applied: (seq: number) => Promise<void>;
+  /** Deliver a terminal result cmd packet on the stream. */
+  settle: (seq: number, payload?: unknown) => Promise<void>;
   /** Deliver an arbitrary envelope on the stream. */
   sendEnvelope: (envelope: StatewireEnvelope) => Promise<void>;
   /** End the stream with a fin; further attaches fail like a dead server. */
@@ -31,8 +34,8 @@ export type MockTransport<TState> = {
 
 /**
  * A mock statewire backend: serves `initialState` as the attach snapshot,
- * records command POSTs (receipt only — acks and results are delivered from
- * test code), and exposes the wire as a transport ResourceElement.
+ * records submitted frames (receipt only — acks and results are delivered
+ * from test code), and exposes the wire as a transport ResourceElement.
  */
 let mockCount = 0;
 
@@ -42,7 +45,7 @@ export const createMockTransport = <TState>(
   let state: unknown = initialState;
   let clientId = "";
   let finished = false;
-  const clients = new Map<string, number>();
+  const clients = new Map<string, { seq: number; ctxSeq: number }>();
   const streams = new Set<FakeStreamHandle>();
   const commands: MockTransport<unknown>["commands"] = [];
 
@@ -51,6 +54,19 @@ export const createMockTransport = <TState>(
     return tick();
   };
 
+  const admit = (id: string, frame: StatewireFrame) => {
+    const rec = clients.get(id)!;
+    for (const statement of frame.ctx ?? []) {
+      rec.ctxSeq = Math.max(rec.ctxSeq, statement.seq);
+      const root = statement.ops[0] as { value?: unknown } | undefined;
+      commands.push({ context: root?.value });
+    }
+    for (const statement of frame.cmd ?? []) {
+      rec.seq = Math.max(rec.seq, statement.seq);
+      commands.push({ method: statement.method, params: statement.params });
+    }
+  };
+
   const fakeFetch = (async (
     input: RequestInfo | URL,
     init?: RequestInit,
@@ -61,8 +77,11 @@ export const createMockTransport = <TState>(
     const id = headers.get("Statewire-Client-Id") ?? "";
     if (url.endsWith("/stream")) {
       clientId = id;
-      const lastSeq = clients.get(id) ?? 0;
-      clients.set(id, lastSeq);
+      const known = clients.has(id);
+      if (!known) clients.set(id, { seq: 0, ctxSeq: 0 });
+      const rec = clients.get(id)!;
+      const frame = JSON.parse(String(init?.body)) as StatewireFrame;
+      admit(id, frame);
       return openSSEStream(
         streams,
         id,
@@ -70,21 +89,20 @@ export const createMockTransport = <TState>(
           handle.send(
             sseFrame({
               ops: [{ op: "replace", path: [], value: state }],
-              syn: { lastSeq, lease: "mock-lease" },
+              syn: {
+                seq: rec.seq,
+                ctxSeq: rec.ctxSeq,
+                record: known ? "resumed" : "fresh",
+              },
             }),
           );
         },
         init?.signal ?? undefined,
+        { "Statewire-Lease": "mock-lease" },
       );
     }
-    if (url.endsWith("/commands")) {
-      const seq = Number(headers.get("Statewire-Command-Seq"));
-      clients.set(id, Math.max(clients.get(id) ?? 0, seq));
-      commands.push(
-        JSON.parse(
-          String(init?.body),
-        ) as MockTransport<unknown>["commands"][number],
-      );
+    if (url.endsWith("/frames")) {
+      admit(id, JSON.parse(String(init?.body)) as StatewireFrame);
       return Response.json({});
     }
     return new Response(null, { status: 404 });
@@ -100,7 +118,17 @@ export const createMockTransport = <TState>(
       state = next;
       return sendEnvelope({ ops: [{ op: "replace", path: [], value: next }] });
     },
-    ack: (seq) => sendEnvelope({ ack: seq }),
+    applied: (seq) => sendEnvelope({ cmd: [{ seq, type: "applied" }] }),
+    settle: (seq, payload) =>
+      sendEnvelope({
+        cmd: [
+          {
+            seq,
+            type: "result",
+            ...(payload !== undefined && { payload }),
+          },
+        ],
+      }),
     sendEnvelope,
     finish: async (reason, message) => {
       await sendEnvelope({