statewire 0.14.0 → 0.15.0

package/src/host/work.ts

@@ -0,0 +1,50 @@
+import { useEffect, useState } from "react";
+import type { StatewireHost } from "../host";
+
+/** Track background tasks and scheduled callbacks in the host's idle status. */
+export const useStatewireWork = (): StatewireHost.Work => {
+  const [, notify] = useState(0);
+  const [cell] = useState(() => ({
+    tasks: new Set<Promise<unknown>>(),
+    scheduled: new Set<() => void>(),
+    active: true,
+  }));
+  useEffect(() => {
+    cell.active = true;
+    return () => {
+      cell.active = false;
+      cell.scheduled.clear();
+    };
+  }, [cell]);
+  const [work] = useState<StatewireHost.Work>(() => ({
+    get isIdle() {
+      return cell.tasks.size === 0 && cell.scheduled.size === 0;
+    },
+    track: (task) => {
+      if (!cell.active) throw new Error("statewire: work called after unmount");
+      cell.tasks.add(task);
+      notify((n) => n + 1);
+      const release = () => {
+        cell.tasks.delete(task);
+        if (cell.active) notify((n) => n + 1);
+      };
+      void task.then(release, release);
+      return task;
+    },
+    schedule: (callback) => {
+      if (!cell.active) throw new Error("statewire: work called after unmount");
+      if (cell.scheduled.has(callback)) return;
+      cell.scheduled.add(callback);
+      notify((n) => n + 1);
+      queueMicrotask(() => {
+        if (!cell.scheduled.delete(callback)) return;
+        try {
+          callback();
+        } finally {
+          if (cell.active) notify((n) => n + 1);
+        }
+      });
+    },
+  }));
+  return work;
+};

package/src/host-internal.ts

@@ -1,7 +1,9 @@
 import type { StatewireHost } from "./host";
+import type { StatewireCmd } from "./client/connection";
 
 export { StatewireSocketHost } from "./host/socket";
 export { clientIdFromUrl, textFrameOrClose } from "./host/adapter";
+export { WS_SUBPROTOCOL } from "./wire/version";
 export namespace StatewireHostInternal {
   export type Socket = {
     send: (data: string) => void;
@@ -17,8 +19,10 @@ export namespace StatewireHostInternal {
   export type SocketConnectOptions = {
     /** The adapter restored this socket from an already-authorized session. */
     authorized?: boolean;
-    /** Persist authorization before the first snapshot is released. */
-    onAuthorized?: () => void;
+    /** The restored session's captured auth value; it must satisfy the client record's principal binding. */
+    auth?: unknown;
+    /** Persist authorization (and the captured auth value) before the first snapshot is released. */
+    onAuthorized?: (auth: unknown) => void;
   };
 
   export type SocketHost = {
@@ -34,17 +38,41 @@ export namespace StatewireHostInternal {
     dispose: () => void;
   };
 
-  export type SocketHostOptions = {
+  export type ClientRecord = {
+    id: string;
+    lastSeq: number;
+    ctxSeq: number;
+    touched: number;
+    context: Record<string, unknown> | null;
+    results: readonly { seq: number; ts: number; cmd: StatewireCmd }[];
+    principal: unknown;
+  };
+
+  export type SocketHostPersistence = {
+    clientRecords?: readonly ClientRecord[];
+    onClientRecordsChange?: (records: readonly ClientRecord[]) => void;
+  };
+
+  export type SocketHostOptions<TAuth = unknown> = {
+    /** Gates every attach; the awaited return value is the attach's auth, exposed to command handlers as `this.caller.auth`. The first attach binds the client id's record to this value; a later attach whose value is not structurally equal is refused (HTTP 403, socket close 1008). */
     authorize?: (ctx: {
       headers: Record<string, string>;
-    }) => void | Promise<void>;
+    }) => TAuth | Promise<TAuth>;
     /** Time allowed to complete WebSocket initialization and authorization. */
     wsInitTimeoutMs?: number;
     heartbeatIntervalMs?: number;
+    /** Maximum number of concurrently attached WebSocket and SSE streams. */
+    maxSubscribers?: number;
+    /** Maximum number of admitted commands still running across all clients. */
+    maxInflightCommands?: number;
+    /** Maximum number of queued SSE packets before a lagging stream is closed. */
+    streamQueueSize?: number;
     /** LRU cap on stored client records; live or in-flight records are exempt. */
     clientRecordLimit?: number;
     /** Hang every attach up with `fin: idle` at the idle flag's rising edge. */
     finOnIdle?: boolean;
+    /** Milliseconds to defer admission, or null to admit. */
+    pushback?: () => number | null;
   };
 
   export type Fin = StatewireHost.Fin;

package/src/host.ts

@@ -1,6 +1,7 @@
 import type { Statewire } from "./types";
 
 export { StatewireReject } from "./host/engine";
+export { useStatewireWork } from "./host/work";
 export { append } from "./host/draft";
 export {
   getStateHost,
@@ -9,6 +10,12 @@ export {
 } from "./host/host";
 
 export namespace StatewireHost {
+  export type Work = {
+    readonly isIdle: boolean;
+    track: <T>(task: Promise<T>) => Promise<T>;
+    schedule: (callback: () => void) => void;
+  };
+
   export type StateCtl<TState = unknown> = {
     /** Apply server-vocabulary ops (root replace = whole-state swap). */
     apply: (ops: readonly Statewire.Op[]) => void;
@@ -30,18 +37,22 @@ export namespace StatewireHost {
    */
   export type Ctx = {
     readonly caller: Caller;
+    readonly signal: AbortSignal;
     readonly applied: () => void;
   };
 
   /**
    * The submitting client (`this.caller` in a command handler). Holdable
    * across a long run: `clientId` is the client's `Statewire-Client-Id`
-   * (in-process dispatch has none — reading it throws), `context` reads the
+   * (in-process dispatch has none — reading it throws), `auth` is the value
+   * `authorize` returned for the attach that admitted the command (undefined
+   * for a void `authorize` and for in-process dispatch), `context` reads the
    * client's current ambient context live (null until the client sends one),
    * `isConnected` reports whether the client has an active stream attachment.
    */
   export type Caller = {
     readonly clientId: string;
+    readonly auth: unknown;
     readonly context: Record<string, unknown> | null;
     readonly isConnected: boolean;
   };
@@ -54,13 +65,18 @@ export namespace StatewireHost {
 
   export type Fin = {
     reason:
-      | "evicted"
+      | "reconnect"
       | "error"
+      | "protocol-error"
+      | "forbidden"
       | "unauthorized"
       | "gone"
       | "idle"
       | (string & {});
     message?: string;
+    code?: string;
+    status?: number;
+    retry?: number;
     payload?: unknown;
     meta?: unknown;
   };

package/src/statewire.ts

@@ -1,3 +1,4 @@
+import type { StatewireHost } from "./host";
 import { useMemo, useRef, useState, useSyncExternalStore } from "react";
 import {
   createTapRoot,
@@ -182,6 +183,7 @@ export namespace StatewireClient {
       ctx: { state: NonNullable<TState> },
     ) => void;
     onConnectionChange?: (connection: Connection) => void;
+    onError?: (error: ConnectionError) => void;
     /** Drops a retained failed entry once a canonical snapshot shows its effect landed; checked against each new snapshot. */
     failureCovered?: (
       state: NonNullable<TState>,
@@ -215,7 +217,13 @@ export namespace StatewireClient {
   export type ConnectionState =
     | {
         status: "disconnected";
-        reason: "deferred" | "idle" | "gone";
+        reason:
+          | "deferred"
+          | "idle"
+          | "gone"
+          | "forbidden"
+          | "protocol-error"
+          | "unauthorized";
         message?: string;
         payload?: unknown;
       }
@@ -223,13 +231,15 @@ export namespace StatewireClient {
         status: "connecting";
         /** 0 = the episode's first dial, >0 = retry. */
         attempt: number;
-        cause?: "dropped" | "evicted" | "error" | "unauthorized";
+        cause?: "dropped" | "reconnect" | "error" | "unauthorized";
+        code?: string;
         nextRetryAt?: number;
         lastError?: string;
         message?: string;
       }
     | { status: "connected" };
   export type Connection = ConnectionState & {
+    error?: ConnectionError;
     reconnect: () => void;
     /** True while retrying (`connecting` with `attempt > 0`) or parked `gone`. */
     degraded: boolean;
@@ -357,6 +367,8 @@ export namespace StatewireClient {
   };
 
   /** Static headers, or a resolver invoked per request/attach; `staleAuth` is true right after an auth rejection. */
+  export type ConnectionError = Error & { fin: StatewireHost.Fin };
+
   export type HeadersOption =
     | HeadersInit
     | ((ctx: { staleAuth: boolean }) => HeadersInit | Promise<HeadersInit>);
@@ -370,6 +382,7 @@ export namespace StatewireClient {
     fetch?: typeof globalThis.fetch;
     onSessionLost?: OnSessionLost;
     onChange?: (connection: Connection) => void;
+    onError?: (error: ConnectionError) => void;
     /** The broadcast idle flag's rising edge: the instance went quiet. */
     onDone?: () => void;
   };
@@ -387,6 +400,7 @@ export namespace StatewireClient {
     webSocket?: new (url: string, protocols?: string | string[]) => WebSocket;
     onSessionLost?: OnSessionLost;
     onChange?: (connection: Connection) => void;
+    onError?: (error: ConnectionError) => void;
     /** The broadcast idle flag's rising edge: the instance went quiet. */
     onDone?: () => void;
   };

package/src/transports/sse.ts

@@ -1,12 +1,14 @@
-import { useRef, useState } from "react";
 import { flushTapSync, resource } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
 import { createSseParser } from "./sse-parser";
 import { timing } from "../client/timing";
 import {
+  settleFin,
   classify,
   handleEnvelope,
-  useStatewireConn,
+  resolveHeaders,
+  unsupportedVersion,
+  useLink,
   validateRefusalSyn,
 } from "../client/connection";
 import type {
@@ -20,6 +22,7 @@ import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
 import type { StatewireHost } from "../host";
 import { useStatewireRemote } from "./remote";
+import { PROTOCOL_VERSION, VERSION_HEADER } from "../wire/version";
 
 /** A client frame's lanes: stamped statements, strictly consecutive per lane. */
 export type StatewireFrame = {
@@ -61,18 +64,6 @@ const LEASE_HEADER = "Statewire-Lease";
 const baseUrl = (options: StatewireClient.SSEOptions) =>
   options.url.replace(/\/$/, "");
 
-export type AuthState = { stale: boolean };
-
-const resolveHeaders = async (
-  options: StatewireClient.SSEOptions,
-  ctx: { staleAuth: boolean },
-): Promise<Headers> => {
-  const { headers } = options;
-  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);
@@ -126,18 +117,13 @@ const consume = async (
 const attemptStream = async (
   c: Conn,
   options: StatewireClient.SSEOptions,
-  auth: AuthState,
   abort: AbortController,
 ): Promise<AttemptOutcome> => {
-  const stale = auth.stale;
-  auth.stale = false;
   c.lease = null;
-  const userHeaders = await resolveHeaders(options, { staleAuth: stale });
+  const headers = await resolveHeaders(options.headers, c.authStale);
+  c.authStale = false;
   const lanes = flushTapSync(() => c.ctx.takeAttachLanes());
-  const frame = {
-    headers: Object.fromEntries(userHeaders),
-    ...(lanes ?? {}),
-  };
+  const body = lanes === null ? undefined : JSON.stringify(lanes);
   const heartbeat = new AbortController();
   const headerTimer = setTimeout(
     () => heartbeat.abort(),
@@ -149,13 +135,13 @@ const attemptStream = async (
       options,
       `${baseUrl(options)}/stream`,
       {
-        method: "POST",
-        headers: withExtra(userHeaders, {
+        method: body === undefined ? "GET" : "POST",
+        headers: withExtra(headers, {
           "content-type": "application/json",
           "Statewire-Client-Id": c.ctx.clientId,
           accept: "text/event-stream",
         }),
-        body: JSON.stringify(frame),
+        ...(body === undefined ? {} : { body }),
         cache: "no-store",
         signal: AbortSignal.any([abort.signal, heartbeat.signal]),
       },
@@ -164,12 +150,14 @@ const attemptStream = async (
   } finally {
     clearTimeout(headerTimer);
   }
-  if (res.status === 401) {
-    c.episode = { cause: "unauthorized" };
-    auth.stale = true;
-    throw new Error("unauthorized");
+  if (!res.ok) return flushTapSync(() => settleFin(c, httpFin(res)));
+  if (!res.body)
+    throw new Error("statewire: protocol error: stream response has no body");
+  const version = res.headers.get(VERSION_HEADER)?.trim();
+  if (version !== undefined && version !== PROTOCOL_VERSION) {
+    res.body.cancel().catch(() => {});
+    return unsupportedVersion(c, version);
   }
-  if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
   c.lease = res.headers.get(LEASE_HEADER);
   const reader = res.body.getReader();
   try {
@@ -185,16 +173,14 @@ const postFrame = async (
   lease: string,
   frame: StatewireFrame,
   timeout: AbortSignal,
-  stale: boolean,
 ): Promise<Response> =>
   timedFetch(
     options,
     `${baseUrl(options)}/frames`,
     {
       method: "POST",
-      headers: withExtra(await resolveHeaders(options, { staleAuth: stale }), {
+      headers: withExtra(new Headers(), {
         "content-type": "application/json",
-        "Statewire-Client-Id": c.ctx.clientId,
         [LEASE_HEADER]: lease,
       }),
       body: JSON.stringify(frame),
@@ -214,6 +200,23 @@ const retryAfterMs = (res: Response): number | null => {
   return Number.isSafeInteger(retry) ? retry : null;
 };
 
+const httpFin = (res: Response): StatewireHost.Fin => ({
+  reason:
+    res.status === 401
+      ? "unauthorized"
+      : res.status === 403
+        ? "forbidden"
+        : res.status === 429 || res.status === 503
+          ? "reconnect"
+          : res.status >= 400 && res.status < 500
+            ? "protocol-error"
+            : "error",
+  status: res.status,
+  message: `HTTP ${res.status}`,
+  ...(res.status === 429 || res.status === 503 ? { code: "overloaded" } : {}),
+  ...(retryAfterMs(res) !== null ? { retry: retryAfterMs(res)! } : {}),
+});
+
 const refusalSyn = async (res: Response): Promise<StatewireSyn> => {
   const body = (await res.json().catch(() => null)) as {
     syn?: StatewireSyn;
@@ -228,16 +231,12 @@ const refusalSyn = async (res: Response): Promise<StatewireSyn> => {
 const sendFrame = async (
   c: Conn,
   options: StatewireClient.SSEOptions,
-  auth: AuthState,
   frame: StatewireFrame,
 ): Promise<StatewireSubmitResult> => {
   const lease = c.lease;
   if (lease === null) return { type: "no-lease" };
   const timeout = AbortSignal.timeout(timing.heartbeatTimeoutMs);
-  let res = await postFrame(c, options, lease, frame, timeout, false);
-  if (res.status === 401 && typeof options.headers === "function") {
-    res = await postFrame(c, options, lease, frame, timeout, true);
-  }
+  const res = await postFrame(c, options, lease, frame, timeout);
   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.
@@ -251,44 +250,37 @@ const sendFrame = async (
     return { type: "refusal", syn };
   }
   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.
-    auth.stale = true;
-    c.episode = { cause: "unauthorized" };
-    c.connection.reconnect();
-    throw new Error("unauthorized");
-  }
+  flushTapSync(() => settleFin(c, httpFin(res)));
+  c.abort?.abort();
   throw new Error(`HTTP ${res.status}`);
 };
 
 const useSseLink = (
   options: StatewireClient.SSEOptions,
   ctx: StatewireRemoteProps,
-): RemoteLink => {
-  const latest = useRef(options);
-  latest.current = options;
-  const [auth] = useState((): AuthState => ({ stale: false }));
-  const c = useStatewireConn({
-    url: options.url,
-    isNew: options.isNew,
-    onChange: options.onChange,
+): RemoteLink =>
+  useLink({
+    ...options,
     ctx,
-    attemptOnce: (c, abort) => attemptStream(c, options, auth, abort),
+    attemptOnce: (c, abort) => attemptStream(c, options, abort),
+    send: async (c, frame) => {
+      try {
+        return await sendFrame(c, options, frame);
+      } catch (error) {
+        if (
+          error instanceof SyntaxError ||
+          (error instanceof Error &&
+            error.message.startsWith("statewire: protocol error:"))
+        ) {
+          flushTapSync(() =>
+            settleFin(c, { reason: "protocol-error", message: error.message }),
+          );
+          c.abort?.abort();
+        }
+        throw error;
+      }
+    },
   });
-  const [link] = useState(
-    (): RemoteLink => ({
-      get connection() {
-        return c.connection;
-      },
-      get parked() {
-        return c.parked;
-      },
-      send: (frame) => sendFrame(c, latest.current, auth, frame),
-    }),
-  );
-  return link;
-};
 
 const useStatewireSSE = (
   options: StatewireClient.SSEOptions,

package/src/transports/testing.ts

@@ -79,7 +79,7 @@ export const createMockTransport = <TState>(
       clientId = id;
       if (!clients.has(id)) clients.set(id, { seq: 0, ctxSeq: 0 });
       const rec = clients.get(id)!;
-      const frame = JSON.parse(String(init?.body)) as StatewireFrame;
+      const frame = JSON.parse(String(init?.body ?? "{}")) as StatewireFrame;
       admit(id, frame);
       return openSSEStream(
         streams,
@@ -97,7 +97,7 @@ export const createMockTransport = <TState>(
       );
     }
     if (url.endsWith("/frames")) {
-      admit(id, JSON.parse(String(init?.body)) as StatewireFrame);
+      admit(clientId, JSON.parse(String(init?.body ?? "{}")) as StatewireFrame);
       return Response.json({});
     }
     return new Response(null, { status: 404 });

package/src/transports/ws.ts

@@ -2,7 +2,12 @@ import { useState } from "react";
 import { flushTapSync, resource } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
 import { timing } from "../client/timing";
-import { handleEnvelope, useStatewireConn } from "../client/connection";
+import {
+  attachFrame,
+  handleEnvelope,
+  unsupportedVersion,
+  useLink,
+} from "../client/connection";
 import type {
   AttemptOutcome,
   Conn,
@@ -12,6 +17,7 @@ import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
 import { useStatewireRemote } from "./remote";
 import { CLIENT_QUERY_PARAM } from "../host/adapter";
+import { WS_SUBPROTOCOL } from "../wire/version";
 import type {
   RemoteLink,
   StatewireFrame,
@@ -21,12 +27,11 @@ import type {
 
 type WsChannel = {
   socket: WebSocket | null;
-  authStale: boolean;
 };
 
 const OPEN = 1;
 
-export const WS_SUBPROTOCOL = "statewire.v1";
+export { WS_SUBPROTOCOL };
 
 const socketUrl = async (
   options: StatewireClient.WSOptions,
@@ -37,30 +42,15 @@ const socketUrl = async (
     typeof query === "function" ? await query() : query,
   );
   params.set(CLIENT_QUERY_PARAM, clientId);
-  const base = url.replace(/\/$/, "").replace(/^http/, "ws");
-  return `${base}/ws?${params.toString()}`;
-};
-
-const firstFrame = async (
-  options: StatewireClient.WSOptions,
-  stale: boolean,
-  lanes: StatewireFrame | null,
-): Promise<string> => {
-  const { headers } = options;
-  const resolved = new Headers(
-    typeof headers === "function"
-      ? await headers({ staleAuth: stale })
-      : headers,
-  );
-  return JSON.stringify({
-    headers: Object.fromEntries(resolved),
-    ...(lanes ?? {}),
-  });
+  const resolved = new URL(url, globalThis.location?.href);
+  resolved.protocol = resolved.protocol.replace(/^http/, "ws");
+  resolved.pathname = `${resolved.pathname.replace(/\/$/, "")}/ws`;
+  resolved.search = params.toString();
+  return resolved.href;
 };
 
 const runSocket = (
   c: Conn,
-  w: WsChannel,
   ws: WebSocket,
   frame: string,
   abort: AbortController,
@@ -80,7 +70,15 @@ const runSocket = (
     arm();
     abort.signal.addEventListener("abort", () => ws.close());
     ws.onerror = () => {};
-    ws.onopen = () => ws.send(frame);
+    ws.onopen = () => {
+      const negotiated = ws.protocol.trim();
+      if (negotiated !== "" && negotiated !== WS_SUBPROTOCOL) {
+        outcome = unsupportedVersion(c, negotiated);
+        ws.close();
+        return;
+      }
+      ws.send(frame);
+    };
     const stale = () => Boolean(outcome) || closed || abort.signal.aborted;
     const fail = (error: unknown) => {
       clearTimeout(timer);
@@ -94,7 +92,7 @@ const runSocket = (
       try {
         env = JSON.parse(String(event.data)) as StatewireEnvelope;
       } catch {
-        fail(new Error("protocol"));
+        fail(new SyntaxError("invalid JSON packet"));
         return;
       }
       // {} heartbeats live below the packet layer: invisible to handlers.
@@ -108,7 +106,6 @@ const runSocket = (
       try {
         const done = flushTapSync(() => handleEnvelope(c, env));
         if (done) {
-          if (env.fin?.reason === "unauthorized") w.authStale = true;
           outcome = done;
           ws.close();
         }
@@ -133,10 +130,7 @@ const attemptSocket = async (
   let ws: WebSocket | null = null;
   try {
     const url = await socketUrl(options, c.ctx.clientId);
-    const stale = w.authStale;
-    w.authStale = false;
-    const lanes = flushTapSync(() => c.ctx.takeAttachLanes());
-    const frame = await firstFrame(options, stale, lanes);
+    const { body } = await attachFrame(c, options.headers);
     abort.signal.throwIfAborted();
     const { protocols, webSocket } = options;
     const WS = webSocket ?? globalThis.WebSocket;
@@ -149,7 +143,7 @@ const attemptSocket = async (
           : protocols;
     ws = new WS(url, [WS_SUBPROTOCOL, ...extra]);
     w.socket = ws;
-    return await runSocket(c, w, ws, frame, abort);
+    return await runSocket(c, ws, body, abort);
   } finally {
     if (w.socket === ws) w.socket = null;
   }
@@ -175,26 +169,13 @@ const useWsLink = (
   options: StatewireClient.WSOptions,
   ctx: StatewireRemoteProps,
 ): RemoteLink => {
-  const [w] = useState((): WsChannel => ({ socket: null, authStale: false }));
-  const c = useStatewireConn({
-    url: options.url,
-    isNew: options.isNew,
-    onChange: options.onChange,
+  const [w] = useState((): WsChannel => ({ socket: null }));
+  return useLink({
+    ...options,
     ctx,
     attemptOnce: (c, abort) => attemptSocket(c, w, options, abort),
+    send: (_, frame) => sendFrame(w, frame),
   });
-  const [link] = useState(
-    (): RemoteLink => ({
-      get connection() {
-        return c.connection;
-      },
-      get parked() {
-        return c.parked;
-      },
-      send: (frame) => sendFrame(w, frame),
-    }),
-  );
-  return link;
 };
 
 const useStatewireWS = (

package/src/types.ts

@@ -57,6 +57,7 @@ export interface Statewire<
   durableSeq?: number;
   /** Negation of the server's broadcast idle level; absent means always busy. */
   isBusy?: boolean;
+  work?: { readonly isIdle: boolean };
   /** Replace this client's ambient context on the server; it rides the ctx lane (no verdict). */
   setContext?: (value: Record<string, unknown>) => void;
   /** The retained failed-send lane; present on transports with a durable session. */