statewire 0.13.0 → 0.14.0

package/src/host/socket.ts

@@ -53,6 +53,14 @@ export type Conn = {
   lease: string | null;
 };
 
+type PendingConn = {
+  socket: StatewireHostInternal.Socket;
+  open: boolean;
+  authorizing: boolean;
+  timer: ReturnType<typeof setTimeout> | null;
+  connection: StatewireHostInternal.SocketConnection | null;
+};
+
 // ─── frame parsing ──────────────────────────────────────
 
 const violation = (reason: string): never => {
@@ -247,11 +255,13 @@ const cmdOf = (adm: Admission, outcome: CommandsOutcome): StatewireCmd => {
 
 export type SocketHostState = {
   heartbeatMs: number;
+  wsInitTimeoutMs: number;
   clientRecordLimit: number;
   finOnIdle: boolean;
   authorize: StatewireHostInternal.SocketHostOptions["authorize"];
   clients: Map<string, ClientRec>;
   conns: Set<Conn>;
+  pendingConns: Set<PendingConn>;
   pendingOps: WireOp[];
   pendingApplied: Map<string, number[]>;
   pendingCmds: Map<string, StatewireCmd[]>;
@@ -267,6 +277,7 @@ export type SocketHostState = {
   connect: (
     clientId: string,
     socket: StatewireHostInternal.Socket,
+    options?: StatewireHostInternal.SocketConnectOptions,
   ) => StatewireHostInternal.SocketConnection | null;
   finish: (fin: StatewireHost.Fin) => void;
   stream: (request: Request) => Promise<Response>;
@@ -667,6 +678,198 @@ const message = (h: SocketHostState, conn: Conn, data: string) => {
   }
 };
 
+const closePending = (
+  h: SocketHostState,
+  pending: PendingConn,
+  code?: number,
+  reason?: string,
+) => {
+  if (!pending.open) return;
+  pending.open = false;
+  h.pendingConns.delete(pending);
+  if (pending.timer !== null) clearTimeout(pending.timer);
+  try {
+    pending.socket.close(code, reason);
+  } catch {
+    /* peer already gone */
+  }
+};
+
+const sendPending = (pending: PendingConn, data: string): boolean => {
+  if (!pending.open) return false;
+  try {
+    pending.socket.send(data);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const rejectPendingAuthorization = (
+  h: SocketHostState,
+  pending: PendingConn,
+  error: unknown,
+) => {
+  const response = error instanceof Response ? error : null;
+  const unauthorized = response?.status === 401 || response?.status === 403;
+  const status = response?.status;
+  const message = unauthorized
+    ? "unauthorized"
+    : response?.statusText ||
+      (status === undefined ? "authorization failed" : `HTTP ${status}`);
+  sendPending(
+    pending,
+    JSON.stringify({
+      fin: {
+        reason: unauthorized ? "unauthorized" : "error",
+        message,
+        ...(status !== undefined && { status }),
+      },
+    }),
+  );
+  closePending(h, pending, unauthorized ? 1008 : 1011, message);
+};
+
+const normalizedHeaders = (
+  headers: Record<string, string>,
+): Record<string, string> => Object.fromEntries(new Headers(headers));
+
+const connectAuthorized = (
+  h: SocketHostState,
+  clientId: string,
+  socket: StatewireHostInternal.Socket,
+  options: StatewireHostInternal.SocketConnectOptions,
+): StatewireHostInternal.SocketConnection | null => {
+  const authorize = h.authorize;
+  if (authorize === undefined || options.authorized === true) {
+    const registration = register(
+      h,
+      clientId,
+      socket,
+      options.authorized === true,
+    );
+    return registration?.connection ?? null;
+  }
+  const refuse = (code: number, reason: string) => {
+    try {
+      socket.close(code, reason);
+    } catch {
+      /* peer already gone */
+    }
+    return null;
+  };
+  if (h.disposed) return refuse(1001, "disposed");
+  if (!CLIENT_ID_RE.test(clientId)) return refuse(1008, "invalid client id");
+  flush(h);
+  if (h.finished !== null) {
+    try {
+      socket.send(JSON.stringify({ fin: h.finished }));
+    } catch {
+      /* peer already gone */
+    }
+    return refuse(1000, "finished");
+  }
+  const pending: PendingConn = {
+    socket,
+    open: true,
+    authorizing: false,
+    timer: null,
+    connection: null,
+  };
+  h.pendingConns.add(pending);
+  pending.timer = setTimeout(
+    () =>
+      rejectPendingAuthorization(
+        h,
+        pending,
+        new Response(null, { status: 401 }),
+      ),
+    h.wsInitTimeoutMs,
+  );
+  (pending.timer as unknown as { unref?: () => void }).unref?.();
+  return {
+    clientId,
+    message: (data) => {
+      if (pending.connection !== null) {
+        pending.connection.message(data);
+        return;
+      }
+      if (!pending.open || h.disposed || h.finished !== null) return;
+      if (pending.authorizing) {
+        closePending(h, pending, 1008, "authorization pending");
+        return;
+      }
+      let frame: ParsedFrame;
+      try {
+        frame = parseFrame(data, true);
+      } catch (error) {
+        const reason = violationReason(error);
+        if (reason === null) throw error;
+        sendPending(
+          pending,
+          JSON.stringify({
+            fin: {
+              reason: "error",
+              message: `protocol violation: ${reason}`,
+            },
+          }),
+        );
+        closePending(h, pending, 1008, reason);
+        return;
+      }
+      if (frame.headers === null) {
+        rejectPendingAuthorization(
+          h,
+          pending,
+          new Response(null, { status: 401 }),
+        );
+        return;
+      }
+      let headers: Record<string, string>;
+      try {
+        headers = normalizedHeaders(frame.headers);
+      } catch {
+        sendPending(
+          pending,
+          JSON.stringify({
+            fin: {
+              reason: "error",
+              message: "protocol violation: malformed headers",
+            },
+          }),
+        );
+        closePending(h, pending, 1008, "malformed headers");
+        return;
+      }
+      pending.authorizing = true;
+      Promise.resolve()
+        .then(() => authorize({ headers }))
+        .then(() => {
+          if (!pending.open || h.disposed || h.finished !== null) return;
+          options.onAuthorized?.();
+          pending.open = false;
+          h.pendingConns.delete(pending);
+          if (pending.timer !== null) clearTimeout(pending.timer);
+          const registration = register(h, clientId, socket, true);
+          if (registration === null) return;
+          pending.connection = registration.connection;
+          if (frame.ctx.length === 0 && frame.cmd.length === 0) return;
+          const admission = admitFrame(h, registration.rec, frame);
+          if (admission.type === "refused") {
+            sendTo(h, registration.conn, JSON.stringify(admission.syn));
+          }
+        })
+        .catch((error: unknown) => {
+          if (pending.open) rejectPendingAuthorization(h, pending, error);
+        });
+    },
+    close: () => {
+      if (pending.connection !== null) pending.connection.close();
+      else closePending(h, pending);
+    },
+  };
+};
+
 const gcClients = (h: SocketHostState) => {
   let excess = h.clients.size - h.clientRecordLimit;
   if (excess <= 0) return;
@@ -690,6 +893,7 @@ export const register = (
   h: SocketHostState,
   clientId: string,
   socket: StatewireHostInternal.Socket,
+  sawFrame = false,
 ): Registration | null => {
   const refuse = (code: number, reason: string) => {
     try {
@@ -732,7 +936,7 @@ export const register = (
     clientId,
     socket,
     open: true,
-    sawFrame: false,
+    sawFrame,
     lastSentAt: 0,
     lease: null,
   };
@@ -768,14 +972,18 @@ const connect = (
   h: SocketHostState,
   clientId: string,
   socket: StatewireHostInternal.Socket,
+  options: StatewireHostInternal.SocketConnectOptions = {},
 ): StatewireHostInternal.SocketConnection | null => {
-  const registration = register(h, clientId, socket);
-  return registration?.connection ?? null;
+  return connectAuthorized(h, clientId, socket, options);
 };
 
 const finish = (h: SocketHostState, fin: StatewireHost.Fin) => {
   if (h.finished !== null || h.disposed) return;
   h.finished = fin;
+  for (const pending of [...h.pendingConns]) {
+    sendPending(pending, JSON.stringify({ fin }));
+    closePending(h, pending, 1000, fin.reason);
+  }
   flush(h, fin);
 };
 
@@ -803,11 +1011,13 @@ const useSocketHost = (
   const [h] = useState((): SocketHostState => {
     const host: SocketHostState = {
       heartbeatMs: 15_000,
+      wsInitTimeoutMs: 5_000,
       clientRecordLimit: CLIENT_RECORD_LIMIT,
       finOnIdle: false,
       authorize: undefined,
       clients: new Map(),
       conns: new Set(),
+      pendingConns: new Set(),
       pendingOps: [],
       pendingApplied: new Map(),
       pendingCmds: new Map(),
@@ -823,7 +1033,8 @@ const useSocketHost = (
         host.flushScheduled = false;
         flush(host);
       }),
-      connect: (clientId, socket) => connect(host, clientId, socket),
+      connect: (clientId, socket, connectOptions) =>
+        connect(host, clientId, socket, connectOptions),
       finish: (fin) => finish(host, fin),
       stream: (request) => serveStream(host, request),
       frames: (request) => serveFrames(host, request),
@@ -831,6 +1042,7 @@ const useSocketHost = (
     return host;
   });
   setHeartbeatMs(h, options?.heartbeatIntervalMs ?? 15_000);
+  h.wsInitTimeoutMs = options?.wsInitTimeoutMs ?? 5_000;
   h.clientRecordLimit = options?.clientRecordLimit ?? CLIENT_RECORD_LIMIT;
   h.finOnIdle = options?.finOnIdle ?? false;
   h.authorize = options?.authorize;
@@ -862,8 +1074,10 @@ export const StatewireSocketHost = (
   const root = createTapRoot(SocketHostRoot);
   let disposed = false;
   return {
-    connect: (clientId, socket) =>
-      flushTapSync(() => root.getValue().connect(clientId, socket)),
+    connect: (clientId, socket, connectOptions) =>
+      flushTapSync(() =>
+        root.getValue().connect(clientId, socket, connectOptions),
+      ),
     stream: (request) => flushTapSync(() => root.getValue().stream(request)),
     frames: (request) => flushTapSync(() => root.getValue().frames(request)),
     finish: (fin) => flushTapSync(() => root.getValue().finish(fin)),

package/src/host-internal.ts

@@ -14,9 +14,20 @@ export namespace StatewireHostInternal {
     close: () => void;
   };
 
+  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;
+  };
+
   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;
@@ -27,6 +38,8 @@ export namespace StatewireHostInternal {
     authorize?: (ctx: {
       headers: Record<string, string>;
     }) => void | Promise<void>;
+    /** Time allowed to complete WebSocket initialization and authorization. */
+    wsInitTimeoutMs?: number;
     heartbeatIntervalMs?: number;
     /** LRU cap on stored client records; live or in-flight records are exempt. */
     clientRecordLimit?: number;

package/src/statewire.ts

@@ -9,7 +9,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 +64,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> => {
@@ -211,20 +211,29 @@ 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";
+        message?: string;
+        payload?: unknown;
+      }
+    | {
+        status: "connecting";
+        /** 0 = the episode's first dial, >0 = retry. */
         attempt: number;
-        nextRetryAt: number;
+        cause?: "dropped" | "evicted" | "error" | "unauthorized";
+        nextRetryAt?: number;
         lastError?: string;
         message?: string;
       }
-    | { status: "gone"; message?: string; payload?: unknown };
-  export type Connection = ConnectionState & { reconnect: () => void };
+    | { status: "connected" };
+  export type Connection = ConnectionState & {
+    reconnect: () => void;
+    /** True while retrying (`connecting` with `attempt > 0`) or parked `gone`. */
+    degraded: boolean;
+  };
   export type ConnectionStatus = Connection["status"];
 
   /**
@@ -355,6 +364,8 @@ export namespace StatewireClient {
   export type SSEOptions = {
     sessionStore?: SessionStorage | undefined;
     url: string;
+    /** The session does not exist on the server yet: the first attach waits for the first command send (or an explicit `reconnect()`). */
+    isNew?: boolean;
     headers?: HeadersOption;
     fetch?: typeof globalThis.fetch;
     onSessionLost?: OnSessionLost;
@@ -366,6 +377,8 @@ export namespace StatewireClient {
   export type WSOptions = {
     sessionStore?: SessionStorage | undefined;
     url: string;
+    /** The session does not exist on the server yet: the first attach waits for the first command send (or an explicit `reconnect()`). */
+    isNew?: boolean;
     headers?: HeadersOption;
     protocols?: string | string[];
     query?:

package/src/transports/sse.ts

@@ -51,6 +51,8 @@ export type ConnectionState = StatewireClient.ConnectionState;
 /** The live wire a remote session drives: connection status plus frame submission. */
 export type RemoteLink = {
   connection: StatewireClient.Connection;
+  /** A deferred first attach still waiting; `reconnect()` releases it. */
+  parked: boolean;
   send: (frame: StatewireFrame) => Promise<StatewireSubmitResult>;
 };
 
@@ -269,6 +271,7 @@ const useSseLink = (
   const [auth] = useState((): AuthState => ({ stale: false }));
   const c = useStatewireConn({
     url: options.url,
+    isNew: options.isNew,
     onChange: options.onChange,
     ctx,
     attemptOnce: (c, abort) => attemptStream(c, options, auth, abort),
@@ -278,6 +281,9 @@ const useSseLink = (
       get connection() {
         return c.connection;
       },
+      get parked() {
+        return c.parked;
+      },
       send: (frame) => sendFrame(c, latest.current, auth, frame),
     }),
   );

package/src/transports/ws.ts

@@ -178,6 +178,7 @@ const useWsLink = (
   const [w] = useState((): WsChannel => ({ socket: null, authStale: false }));
   const c = useStatewireConn({
     url: options.url,
+    isNew: options.isNew,
     onChange: options.onChange,
     ctx,
     attemptOnce: (c, abort) => attemptSocket(c, w, options, abort),
@@ -187,6 +188,9 @@ const useWsLink = (
       get connection() {
         return c.connection;
       },
+      get parked() {
+        return c.parked;
+      },
       send: (frame) => sendFrame(w, frame),
     }),
   );