statewire 0.13.1 → 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;
@@ -14,24 +16,63 @@ export namespace StatewireHostInternal {
     close: () => void;
   };
 
+  export type SocketConnectOptions = {
+    /** The adapter restored this socket from an already-authorized session. */
+    authorized?: boolean;
+    /** 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 = {
     /** Null means refused: the socket was told (fin and/or close) and is dead. */
-    connect: (clientId: string, socket: Socket) => SocketConnection | null;
+    connect: (
+      clientId: string,
+      socket: Socket,
+      options?: SocketConnectOptions,
+    ) => SocketConnection | null;
     stream: (request: Request) => Promise<Response>;
     frames: (request: Request) => Promise<Response>;
     finish: (fin: StatewireHost.Fin) => void;
     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,
@@ -9,7 +10,7 @@ import {
   withKey,
 } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
-import { LIVE_CONNECTION, useStatewireCore } from "./client/core";
+import { CONNECTED_CONNECTION, useStatewireCore } from "./client/core";
 import type { Statewire } from "./types";
 import type { TERMINAL } from "./client/connection";
 import { SessionStorageContext } from "./client/sessionStore";
@@ -64,7 +65,7 @@ export const useStatewire = <
     core.getFailed,
     core.getFailed,
   );
-  const connection = value.connection ?? LIVE_CONNECTION;
+  const connection = value.connection ?? CONNECTED_CONNECTION;
 
   return useMemo(() => {
     const failures = (): NonNullable<typeof value.failures> => {
@@ -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>,
@@ -211,20 +213,37 @@ export namespace StatewireClient {
     discardFailed: (entry: FailedCommand) => void;
   };
 
+  /** `cause`/`nextRetryAt`/`lastError` are present only while waiting out the backoff timer; a dial in flight carries `attempt` alone. */
   export type ConnectionState =
-    | { status: "connecting" }
-    | { status: "live" }
-    | { status: "idle" }
     | {
-        status: "reconnecting";
-        cause: "dropped" | "evicted" | "error" | "unauthorized";
+        status: "disconnected";
+        reason:
+          | "deferred"
+          | "idle"
+          | "gone"
+          | "forbidden"
+          | "protocol-error"
+          | "unauthorized";
+        message?: string;
+        payload?: unknown;
+      }
+    | {
+        status: "connecting";
+        /** 0 = the episode's first dial, >0 = retry. */
         attempt: number;
-        nextRetryAt: number;
+        cause?: "dropped" | "reconnect" | "error" | "unauthorized";
+        code?: string;
+        nextRetryAt?: number;
         lastError?: string;
         message?: string;
       }
-    | { status: "gone"; message?: string; payload?: unknown };
-  export type Connection = ConnectionState & { reconnect: () => void };
+    | { status: "connected" };
+  export type Connection = ConnectionState & {
+    error?: ConnectionError;
+    reconnect: () => void;
+    /** True while retrying (`connecting` with `attempt > 0`) or parked `gone`. */
+    degraded: boolean;
+  };
   export type ConnectionStatus = Connection["status"];
 
   /**
@@ -348,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>);
@@ -361,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;
   };
@@ -378,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 });