statewire 0.14.0 → 0.15.0

package/src/host/socket.ts

@@ -8,6 +8,14 @@ import type { Statewire } from "../types";
 import type { StatewireHost } from "../host";
 import type { StatewireHostInternal } from "../host-internal";
 import { encodeValue, reviveValue } from "../wire/meta";
+import {
+  COMMAND_CAPACITY_RETRY_MS,
+  MAX_COMMANDS_PER_FRAME,
+  MAX_CONTEXT_VALUE_BYTES,
+  MAX_FRAME_BODY_BYTES,
+  MAX_INFLIGHT_COMMANDS_PER_CLIENT,
+  MAX_INFLIGHT_COMMANDS_PER_HOST,
+} from "../wire/limits";
 import { createMacrotaskPoster } from "../util/macrotask";
 import type { StatewireMetaEntry } from "../wire/meta";
 import type { StatewirePath } from "../wire/ops";
@@ -15,9 +23,49 @@ import type { StatewireCmd, StatewireEnvelope } from "../client/connection";
 import { frames as serveFrames, stream as serveStream } from "./http";
 
 export const CLIENT_ID_RE = /^[A-Za-z0-9._~-]{1,256}$/;
+export const PRINCIPAL_MISMATCH_MESSAGE =
+  "client id is bound to another principal";
+
+/** Structural equality over auth values: primitives, Dates, arrays, and plain
+ * objects compare by value; anything else by identity. */
+export const authEquals = (a: unknown, b: unknown): boolean => {
+  if (Object.is(a, b)) return true;
+  if (a instanceof Date && b instanceof Date)
+    return a.getTime() === b.getTime();
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => authEquals(v, b[i]));
+  }
+  if (
+    typeof a === "object" &&
+    typeof b === "object" &&
+    a !== null &&
+    b !== null &&
+    Object.getPrototypeOf(a) === Object.prototype &&
+    Object.getPrototypeOf(b) === Object.prototype
+  ) {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    return (
+      keysA.length === keysB.length &&
+      keysA.every(
+        (key) =>
+          key in b &&
+          authEquals(
+            (a as Record<string, unknown>)[key],
+            (b as Record<string, unknown>)[key],
+          ),
+      )
+    );
+  }
+  return false;
+};
+
 const RESULT_TTL_MS = 30_000;
 const RESULT_LIMIT = 256;
 const CLIENT_RECORD_LIMIT = 1024;
+const MAX_SUBSCRIBERS = 1024;
+export const SUBSCRIBER_LIMIT_MESSAGE = "stream subscriber limit reached";
+const STREAM_QUEUE_SIZE = 256;
 
 type WireOp = {
   op: string;
@@ -42,6 +90,8 @@ export type ClientRec = {
   context: Record<string, unknown> | null;
   results: Map<number, { ts: number; cmd: StatewireCmd }>;
   inflight: Map<number, Admission>;
+  /** The auth captured at the record's first attach; later attaches must match. */
+  principal: unknown;
 };
 
 export type Conn = {
@@ -51,12 +101,15 @@ export type Conn = {
   sawFrame: boolean;
   lastSentAt: number;
   lease: string | null;
+  /** The awaited `authorize` return captured at this attach's authorization. */
+  auth: unknown;
 };
 
 type PendingConn = {
   socket: StatewireHostInternal.Socket;
   open: boolean;
   authorizing: boolean;
+  queued: string[];
   timer: ReturnType<typeof setTimeout> | null;
   connection: StatewireHostInternal.SocketConnection | null;
 };
@@ -81,7 +134,6 @@ type CmdStatement = {
 };
 
 export type ParsedFrame = {
-  headers: Record<string, string> | null;
   ctx: CtxStatement[];
   cmd: CmdStatement[];
 };
@@ -107,6 +159,8 @@ const parseLane = (value: unknown): Record<string, unknown>[] => {
   return statements;
 };
 
+const frameEncoder = new TextEncoder();
+
 /** v1 ctx statements state the context whole: one root replace with an object value. */
 const contextValue = (ops: unknown): Record<string, unknown> => {
   if (!Array.isArray(ops) || ops.length !== 1) {
@@ -131,46 +185,42 @@ const contextValue = (ops: unknown): Record<string, unknown> => {
   return value;
 };
 
-export const parseFrameValue = (
-  frame: unknown,
-  first: boolean,
-): ParsedFrame => {
+export const parseFrameValue = (frame: unknown): ParsedFrame => {
   if (!isPlainObject(frame)) return violation("malformed frame");
   const keys = Object.keys(frame);
   if (keys.length === 0) return violation("malformed frame");
-  const unknown = keys
-    .filter((key) => key !== "headers" && key !== "ctx" && key !== "cmd")
-    .sort();
+  const unknown = keys.filter((key) => key !== "ctx" && key !== "cmd").sort();
   if (unknown.length > 0)
     return violation(`unknown frame key: '${unknown[0]}'`);
-  let headers: Record<string, string> | null = null;
-  if (frame["headers"] !== undefined) {
-    if (!first) return violation("mid-session headers");
-    const raw = frame["headers"];
-    if (
-      !isPlainObject(raw) ||
-      Object.values(raw).some((value) => typeof value !== "string")
-    ) {
-      return violation("malformed headers");
-    }
-    headers = raw as Record<string, string>;
-  }
   const ctx: CtxStatement[] = [];
   if (frame["ctx"] !== undefined) {
-    for (const statement of parseLane(frame["ctx"])) {
+    const lane = frame["ctx"];
+    if (Array.isArray(lane) && lane.length > MAX_COMMANDS_PER_FRAME) {
+      return violation("too many context statements");
+    }
+    for (const statement of parseLane(lane)) {
+      let value: Record<string, unknown>;
       try {
-        ctx.push({
-          seq: statement["seq"] as number,
-          value: contextValue(statement["ops"]),
-        });
+        value = contextValue(statement["ops"]);
       } catch {
         return violation("invalid-context");
       }
+      if (
+        frameEncoder.encode(JSON.stringify(value)).byteLength >
+        MAX_CONTEXT_VALUE_BYTES
+      ) {
+        return violation("oversized-context");
+      }
+      ctx.push({ seq: statement["seq"] as number, value });
     }
   }
   const cmd: CmdStatement[] = [];
   if (frame["cmd"] !== undefined) {
-    for (const statement of parseLane(frame["cmd"])) {
+    const lane = frame["cmd"];
+    if (Array.isArray(lane) && lane.length > MAX_COMMANDS_PER_FRAME) {
+      return violation("too many commands");
+    }
+    for (const statement of parseLane(lane)) {
       const method = statement["method"];
       if (typeof method !== "string" || !("params" in statement)) {
         return violation("malformed statement");
@@ -183,19 +233,23 @@ export const parseFrameValue = (
       });
     }
   }
-  return { headers, ctx, cmd };
+  return { ctx, cmd };
 };
 
-export const parseFrame = (raw: string, first: boolean): ParsedFrame => {
+export const parseFrame = (raw: string): ParsedFrame => {
   let frame: unknown;
   try {
     frame = JSON.parse(raw);
   } catch {
     return violation("malformed frame");
   }
-  return parseFrameValue(frame, first);
+  return parseFrameValue(frame);
 };
 
+const frameIsOversized = (raw: string): boolean =>
+  raw.length > MAX_FRAME_BODY_BYTES ||
+  frameEncoder.encode(raw).byteLength > MAX_FRAME_BODY_BYTES;
+
 // ─── verdict encoding ───────────────────────────────────
 
 const encodePayload = (
@@ -213,6 +267,8 @@ const cmdOf = (adm: Admission, outcome: CommandsOutcome): StatewireCmd => {
   const failure =
     outcome.error instanceof StatewireSendError ? outcome.error.failure : null;
   switch (failure?.fate) {
+    case "crashed":
+      return { seq: adm.seq, type: "crashed" };
     case "failed":
       return {
         seq: adm.seq,
@@ -251,13 +307,41 @@ const cmdOf = (adm: Admission, outcome: CommandsOutcome): StatewireCmd => {
   }
 };
 
+const parseInitialFrame = (raw: string) => {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return violation("malformed frame");
+  }
+  if (!isPlainObject(value)) return violation("malformed frame");
+  const { headers, ...lanes } = value;
+  if (headers === undefined) throw new Response(null, { status: 401 });
+  if (
+    !isPlainObject(headers) ||
+    Object.values(headers).some((v) => typeof v !== "string")
+  ) {
+    return violation("malformed headers");
+  }
+  return {
+    headers: headers as Record<string, string>,
+    frame: Object.keys(lanes).length
+      ? parseFrameValue(lanes)
+      : { ctx: [], cmd: [] },
+  };
+};
+
 // ─── host ───────────────────────────────────────────────
 
 export type SocketHostState = {
   heartbeatMs: number;
   wsInitTimeoutMs: number;
+  maxSubscribers: number;
+  maxInflightCommands: number;
+  streamQueueSize: number;
   clientRecordLimit: number;
   finOnIdle: boolean;
+  pushback: (() => number | null) | undefined;
   authorize: StatewireHostInternal.SocketHostOptions["authorize"];
   clients: Map<string, ClientRec>;
   conns: Set<Conn>;
@@ -273,6 +357,7 @@ export type SocketHostState = {
   stateHost: StatewireHost.StateHost | null;
   commandsHost: CommandsHost | null;
   current: Statewire<unknown> | null;
+  persistence: StatewireHostInternal.SocketHostPersistence | undefined;
   post: () => void;
   connect: (
     clientId: string,
@@ -358,6 +443,11 @@ export const sendTo = (h: SocketHostState, conn: Conn, data: string) => {
   }
 };
 
+export const atSubscriberLimit = (h: SocketHostState): boolean =>
+  h.conns.size +
+    [...h.pendingConns].filter((conn) => conn.authorizing).length >=
+  h.maxSubscribers;
+
 const ensureHeartbeat = (h: SocketHostState) => {
   if (h.heartbeatTimer !== null || h.heartbeatMs <= 0) return;
   h.heartbeatTimer = setInterval(() => {
@@ -380,6 +470,7 @@ const setHeartbeatMs = (h: SocketHostState, ms: number) => {
 };
 
 const idleLevel = (h: SocketHostState): boolean => {
+  if (h.current?.work?.isIdle === false) return false;
   for (const rec of h.clients.values()) {
     if (rec.inflight.size > 0) return false;
   }
@@ -463,6 +554,24 @@ const queueCmd = (h: SocketHostState, clientId: string, cmd: StatewireCmd) => {
   scheduleFlush(h);
 };
 
+const notifyClientRecords = (h: SocketHostState) => {
+  h.persistence?.onClientRecordsChange?.(
+    [...h.clients.values()].map((rec) => ({
+      id: rec.id,
+      lastSeq: admittedThrough(rec),
+      ctxSeq: rec.ctxSeq,
+      touched: rec.touched,
+      context: rec.context,
+      results: [...rec.results].map(([seq, entry]) => ({
+        seq,
+        ts: entry.ts,
+        cmd: entry.cmd,
+      })),
+      principal: rec.principal,
+    })),
+  );
+};
+
 const retain = (rec: ClientRec, cmd: StatewireCmd) => {
   const now = Date.now();
   rec.results.set(cmd.seq, { ts: now, cmd });
@@ -493,6 +602,7 @@ const reemit = (h: SocketHostState, rec: ClientRec, seq: number) => {
       return;
     }
     rec.results.delete(seq);
+    notifyClientRecords(h);
   }
   const adm = rec.inflight.get(seq);
   if (adm) {
@@ -515,6 +625,7 @@ const settleCmd = (
   rec.lastSeq = Math.max(rec.lastSeq, adm.seq);
   adm.applied = true;
   queueCmd(h, rec.id, cmd);
+  notifyClientRecords(h);
 };
 
 const settleWire = (
@@ -527,8 +638,10 @@ const settleWire = (
 const callerOf = (
   h: SocketHostState,
   rec: ClientRec,
+  auth: unknown,
 ): StatewireHost.Caller => ({
   clientId: rec.id,
+  auth,
   get context() {
     return rec.context;
   },
@@ -558,6 +671,7 @@ const admitCmd = (
   h: SocketHostState,
   rec: ClientRec,
   statement: CmdStatement,
+  auth: unknown,
 ) => {
   const adm: Admission = {
     seq: statement.seq,
@@ -567,6 +681,7 @@ const admitCmd = (
     settled: false,
   };
   rec.inflight.set(statement.seq, adm);
+  notifyClientRecords(h);
   if (!Array.isArray(statement.params)) {
     rejectStatement(h, rec, adm, "params must be an array");
     return;
@@ -603,11 +718,12 @@ const admitCmd = (
     method: statement.method,
     params,
     clientId: rec.id,
-    caller: callerOf(h, rec),
+    caller: callerOf(h, rec, auth),
     onApplied: () => {
       if (adm.settled || adm.applied) return;
       adm.applied = true;
       rec.lastSeq = Math.max(rec.lastSeq, adm.seq);
+      notifyClientRecords(h);
       scheduleFlush(h);
     },
     onSettle: (outcome) => settleWire(h, rec, adm, outcome),
@@ -621,12 +737,18 @@ const admitCmd = (
 // {syn} stating both watermarks, nothing consumed. A gap is never a close.
 export type FrameAdmission =
   | { type: "ok" }
-  | { type: "refused"; syn: { syn: { seq: number; ctxSeq: number } } };
+  | {
+      type: "refused";
+      syn: {
+        syn: { seq: number; ctxSeq: number; retry?: number };
+      };
+    };
 
 export const admitFrame = (
   h: SocketHostState,
   rec: ClientRec,
   frame: ParsedFrame,
+  auth: unknown,
 ): FrameAdmission => {
   rec.touched = Date.now();
   const through = admittedThrough(rec);
@@ -639,40 +761,100 @@ export const admitFrame = (
     (ctxNew.length > 0 && ctxNew[0]!.seq !== rec.ctxSeq + 1) ||
     (cmdNew.length > 0 && cmdNew[0]!.seq !== through + 1)
   ) {
+    notifyClientRecords(h);
     return {
       type: "refused",
       syn: { syn: { seq: through, ctxSeq: rec.ctxSeq } },
     };
   }
+  if (cmdNew.length > 0) {
+    let hostCommandLoad = 0;
+    for (const client of h.clients.values()) {
+      hostCommandLoad += client.inflight.size;
+    }
+    if (
+      rec.inflight.size + cmdNew.length > MAX_INFLIGHT_COMMANDS_PER_CLIENT ||
+      hostCommandLoad + cmdNew.length > h.maxInflightCommands
+    ) {
+      return {
+        type: "refused",
+        syn: {
+          syn: {
+            seq: through,
+            ctxSeq: rec.ctxSeq,
+            retry: COMMAND_CAPACITY_RETRY_MS,
+          },
+        },
+      };
+    }
+  }
+  if ((ctxNew.length || cmdNew.length) && h.pushback) {
+    const retry = h.pushback();
+    if (retry !== null) {
+      if (!Number.isSafeInteger(retry) || retry < 0)
+        throw new TypeError(
+          "pushback must return a nonnegative safe integer or null",
+        );
+      return {
+        type: "refused",
+        syn: { syn: { seq: through, ctxSeq: rec.ctxSeq, retry } },
+      };
+    }
+  }
   for (const statement of ctxNew) {
     rec.context = statement.value;
     rec.ctxSeq = statement.seq;
   }
-  for (const statement of cmdNew) admitCmd(h, rec, statement);
+  for (const statement of cmdNew) admitCmd(h, rec, statement, auth);
   if (cmdNew.length > 0) {
     // Memory host: admitted means retained — dur rides the admitting flush.
     queueCmd(h, rec.id, { seq: cmdNew.at(-1)!.seq, dur: true });
   }
+  notifyClientRecords(h);
   scheduleFlush(h);
   return { type: "ok" };
 };
 
 const message = (h: SocketHostState, conn: Conn, data: string) => {
   if (!conn.open || h.disposed || h.finished !== null) return;
+  if (frameIsOversized(data)) {
+    sendTo(
+      h,
+      conn,
+      JSON.stringify({
+        fin: {
+          reason: "protocol-error",
+          message: "frame too large",
+        },
+      }),
+    );
+    closeConn(h, conn, 1009, "frame too large");
+    return;
+  }
   const first = !conn.sawFrame;
   conn.sawFrame = true;
   let frame: ParsedFrame;
   try {
-    frame = parseFrame(data, first);
+    frame = first ? parseInitialFrame(data).frame : parseFrame(data);
   } catch (error) {
     const reason = violationReason(error);
     if (reason === null) throw error;
+    sendTo(
+      h,
+      conn,
+      JSON.stringify({
+        fin: {
+          reason: "protocol-error",
+          message: reason,
+        },
+      }),
+    );
     closeConn(h, conn, 1008, reason);
     return;
   }
   if (frame.ctx.length === 0 && frame.cmd.length === 0) return;
   const rec = h.clients.get(conn.clientId)!;
-  const admission = admitFrame(h, rec, frame);
+  const admission = admitFrame(h, rec, frame, conn.auth);
   if (admission.type === "refused") {
     sendTo(h, conn, JSON.stringify(admission.syn));
   }
@@ -705,6 +887,28 @@ const sendPending = (pending: PendingConn, data: string): boolean => {
   }
 };
 
+const refuseSubscriberLimit = (socket: StatewireHostInternal.Socket): null => {
+  try {
+    socket.send(
+      JSON.stringify({
+        fin: {
+          reason: "reconnect",
+          code: "overloaded",
+          message: SUBSCRIBER_LIMIT_MESSAGE,
+        },
+      }),
+    );
+  } catch {
+    /* peer already gone */
+  }
+  try {
+    socket.close(1013, SUBSCRIBER_LIMIT_MESSAGE);
+  } catch {
+    /* peer already gone */
+  }
+  return null;
+};
+
 const rejectPendingAuthorization = (
   h: SocketHostState,
   pending: PendingConn,
@@ -721,7 +925,12 @@ const rejectPendingAuthorization = (
     pending,
     JSON.stringify({
       fin: {
-        reason: unauthorized ? "unauthorized" : "error",
+        reason:
+          status === 403
+            ? "forbidden"
+            : unauthorized
+              ? "unauthorized"
+              : "error",
         message,
         ...(status !== undefined && { status }),
       },
@@ -732,7 +941,15 @@ const rejectPendingAuthorization = (
 
 const normalizedHeaders = (
   headers: Record<string, string>,
-): Record<string, string> => Object.fromEntries(new Headers(headers));
+): Record<string, string> => {
+  const seen = new Set<string>();
+  for (const name of Object.keys(headers)) {
+    const key = name.toLowerCase();
+    if (seen.has(key)) throw new TypeError("duplicate header name");
+    seen.add(key);
+  }
+  return Object.fromEntries(new Headers(headers));
+};
 
 const connectAuthorized = (
   h: SocketHostState,
@@ -741,12 +958,13 @@ const connectAuthorized = (
   options: StatewireHostInternal.SocketConnectOptions,
 ): StatewireHostInternal.SocketConnection | null => {
   const authorize = h.authorize;
-  if (authorize === undefined || options.authorized === true) {
+  if (options.authorized === true) {
     const registration = register(
       h,
       clientId,
       socket,
       options.authorized === true,
+      options.auth,
     );
     return registration?.connection ?? null;
   }
@@ -773,6 +991,7 @@ const connectAuthorized = (
     socket,
     open: true,
     authorizing: false,
+    queued: [],
     timer: null,
     connection: null,
   };
@@ -795,69 +1014,95 @@ const connectAuthorized = (
         return;
       }
       if (!pending.open || h.disposed || h.finished !== null) return;
+      if (frameIsOversized(data)) {
+        sendPending(
+          pending,
+          JSON.stringify({
+            fin: {
+              reason: "protocol-error",
+              message: "frame too large",
+            },
+          }),
+        );
+        closePending(h, pending, 1009, "frame too large");
+        return;
+      }
       if (pending.authorizing) {
-        closePending(h, pending, 1008, "authorization pending");
+        pending.queued.push(data);
         return;
       }
-      let frame: ParsedFrame;
+      let initial: ReturnType<typeof parseInitialFrame>;
       try {
-        frame = parseFrame(data, true);
+        initial = parseInitialFrame(data);
       } catch (error) {
+        if (error instanceof Response) {
+          rejectPendingAuthorization(h, pending, error);
+          return;
+        }
         const reason = violationReason(error);
         if (reason === null) throw error;
         sendPending(
           pending,
           JSON.stringify({
             fin: {
-              reason: "error",
-              message: `protocol violation: ${reason}`,
+              reason: "protocol-error",
+              message: reason,
             },
           }),
         );
         closePending(h, pending, 1008, reason);
         return;
       }
-      if (frame.headers === null) {
-        rejectPendingAuthorization(
-          h,
-          pending,
-          new Response(null, { status: 401 }),
-        );
-        return;
-      }
+      const frame = initial.frame;
       let headers: Record<string, string>;
       try {
-        headers = normalizedHeaders(frame.headers);
+        headers = normalizedHeaders(initial.headers);
       } catch {
         sendPending(
           pending,
           JSON.stringify({
             fin: {
-              reason: "error",
-              message: "protocol violation: malformed headers",
+              reason: "protocol-error",
+              message: "malformed headers",
             },
           }),
         );
         closePending(h, pending, 1008, "malformed headers");
         return;
       }
+      if (atSubscriberLimit(h)) {
+        sendPending(
+          pending,
+          JSON.stringify({
+            fin: {
+              reason: "reconnect",
+              code: "overloaded",
+              message: SUBSCRIBER_LIMIT_MESSAGE,
+            },
+          }),
+        );
+        closePending(h, pending, 1013, SUBSCRIBER_LIMIT_MESSAGE);
+        return;
+      }
       pending.authorizing = true;
       Promise.resolve()
-        .then(() => authorize({ headers }))
-        .then(() => {
+        .then(() => authorize?.({ headers }))
+        .then((auth) => {
           if (!pending.open || h.disposed || h.finished !== null) return;
-          options.onAuthorized?.();
+          options.onAuthorized?.(auth);
           pending.open = false;
           h.pendingConns.delete(pending);
           if (pending.timer !== null) clearTimeout(pending.timer);
-          const registration = register(h, clientId, socket, true);
+          const registration = register(h, clientId, socket, true, auth);
           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));
+          if (frame.ctx.length || frame.cmd.length) {
+            const admission = admitFrame(h, registration.rec, frame, auth);
+            if (admission.type === "refused")
+              sendTo(h, registration.conn, JSON.stringify(admission.syn));
           }
+          for (const data of pending.queued.splice(0))
+            registration.connection.message(data);
         })
         .catch((error: unknown) => {
           if (pending.open) rejectPendingAuthorization(h, pending, error);
@@ -873,14 +1118,17 @@ const connectAuthorized = (
 const gcClients = (h: SocketHostState) => {
   let excess = h.clients.size - h.clientRecordLimit;
   if (excess <= 0) return;
+  let changed = false;
   const live = new Set([...h.conns].map((conn) => conn.clientId));
   const oldest = [...h.clients.values()].sort((a, b) => a.touched - b.touched);
   for (const rec of oldest) {
-    if (excess <= 0) return;
+    if (excess <= 0) break;
     if (live.has(rec.id) || rec.inflight.size > 0) continue;
     h.clients.delete(rec.id);
+    changed = true;
     excess -= 1;
   }
+  if (changed) notifyClientRecords(h);
 };
 
 export type Registration = {
@@ -894,6 +1142,7 @@ export const register = (
   clientId: string,
   socket: StatewireHostInternal.Socket,
   sawFrame = false,
+  auth: unknown = undefined,
 ): Registration | null => {
   const refuse = (code: number, reason: string) => {
     try {
@@ -915,22 +1164,42 @@ export const register = (
     refuse(1000, "finished");
     return null;
   }
-  const known = h.clients.has(clientId);
-  const rec = known
-    ? h.clients.get(clientId)!
-    : (() => {
-        const created: ClientRec = {
-          id: clientId,
-          lastSeq: 0,
-          ctxSeq: 0,
-          touched: Date.now(),
-          context: null,
-          results: new Map(),
-          inflight: new Map(),
-        };
-        h.clients.set(clientId, created);
-        return created;
-      })();
+  if (atSubscriberLimit(h)) {
+    return refuseSubscriberLimit(socket);
+  }
+  const known = h.clients.get(clientId);
+  if (known !== undefined && !authEquals(known.principal, auth)) {
+    try {
+      socket.send(
+        JSON.stringify({
+          fin: {
+            reason: "forbidden",
+            message: PRINCIPAL_MISMATCH_MESSAGE,
+            status: 403,
+          },
+        }),
+      );
+    } catch {
+      /* peer already gone */
+    }
+    return refuse(1008, PRINCIPAL_MISMATCH_MESSAGE);
+  }
+  const rec =
+    known ??
+    (() => {
+      const created: ClientRec = {
+        id: clientId,
+        lastSeq: 0,
+        ctxSeq: 0,
+        touched: Date.now(),
+        context: null,
+        results: new Map(),
+        inflight: new Map(),
+        principal: auth,
+      };
+      h.clients.set(clientId, created);
+      return created;
+    })();
   rec.touched = Date.now();
   const conn: Conn = {
     clientId,
@@ -939,9 +1208,11 @@ export const register = (
     sawFrame,
     lastSentAt: 0,
     lease: null,
+    auth,
   };
   h.conns.add(conn);
   gcClients(h);
+  notifyClientRecords(h);
   ensureHeartbeat(h);
   const { value, meta } = encodeValue(h.stateHost!.snapshot());
   const hello: StatewireEnvelope = {
@@ -978,7 +1249,14 @@ const connect = (
 };
 
 const finish = (h: SocketHostState, fin: StatewireHost.Fin) => {
+  if (
+    fin.retry !== undefined &&
+    (!Number.isSafeInteger(fin.retry) || fin.retry < 0)
+  ) {
+    throw new Error("statewire: retry must be a nonnegative safe integer");
+  }
   if (h.finished !== null || h.disposed) return;
+  h.commandsHost?.abort?.();
   h.finished = fin;
   for (const pending of [...h.pendingConns]) {
     sendPending(pending, JSON.stringify({ fin }));
@@ -1001,9 +1279,26 @@ const suspend = (h: SocketHostState) => {
   h.stateHost?.setOnOp(null);
 };
 
+const restoreClientRecords = (
+  records: readonly StatewireHostInternal.ClientRecord[] = [],
+): Map<string, ClientRec> =>
+  new Map(
+    records.map((record) => [
+      record.id,
+      {
+        ...record,
+        results: new Map(
+          record.results.map(({ seq, ts, cmd }) => [seq, { ts, cmd }]),
+        ),
+        inflight: new Map(),
+      },
+    ]),
+  );
+
 const useSocketHost = (
   transport: ResourceElement<Statewire>,
   options?: StatewireHostInternal.SocketHostOptions,
+  persistence?: StatewireHostInternal.SocketHostPersistence,
 ): Pick<
   StatewireHostInternal.SocketHost,
   "connect" | "finish" | "stream" | "frames"
@@ -1012,10 +1307,14 @@ const useSocketHost = (
     const host: SocketHostState = {
       heartbeatMs: 15_000,
       wsInitTimeoutMs: 5_000,
+      maxSubscribers: MAX_SUBSCRIBERS,
+      maxInflightCommands: MAX_INFLIGHT_COMMANDS_PER_HOST,
+      streamQueueSize: STREAM_QUEUE_SIZE,
       clientRecordLimit: CLIENT_RECORD_LIMIT,
       finOnIdle: false,
+      pushback: undefined,
       authorize: undefined,
-      clients: new Map(),
+      clients: restoreClientRecords(persistence?.clientRecords),
       conns: new Set(),
       pendingConns: new Set(),
       pendingOps: [],
@@ -1029,6 +1328,7 @@ const useSocketHost = (
       stateHost: null,
       commandsHost: null,
       current: null,
+      persistence,
       post: createMacrotaskPoster(() => {
         host.flushScheduled = false;
         flush(host);
@@ -1042,7 +1342,32 @@ const useSocketHost = (
     return host;
   });
   setHeartbeatMs(h, options?.heartbeatIntervalMs ?? 15_000);
+  h.pushback = options?.pushback;
   h.wsInitTimeoutMs = options?.wsInitTimeoutMs ?? 5_000;
+  const maxSubscribers =
+    options?.maxSubscribers === undefined
+      ? MAX_SUBSCRIBERS
+      : options.maxSubscribers;
+  if (!Number.isInteger(maxSubscribers) || maxSubscribers < 1) {
+    throw new TypeError("maxSubscribers must be a positive integer");
+  }
+  h.maxSubscribers = maxSubscribers;
+  const maxInflightCommands =
+    options?.maxInflightCommands === undefined
+      ? MAX_INFLIGHT_COMMANDS_PER_HOST
+      : options.maxInflightCommands;
+  if (!Number.isInteger(maxInflightCommands) || maxInflightCommands < 1) {
+    throw new TypeError("maxInflightCommands must be a positive integer");
+  }
+  h.maxInflightCommands = maxInflightCommands;
+  const streamQueueSize =
+    options?.streamQueueSize === undefined
+      ? STREAM_QUEUE_SIZE
+      : options.streamQueueSize;
+  if (!Number.isInteger(streamQueueSize) || streamQueueSize < 1) {
+    throw new TypeError("streamQueueSize must be a positive integer");
+  }
+  h.streamQueueSize = streamQueueSize;
   h.clientRecordLimit = options?.clientRecordLimit ?? CLIENT_RECORD_LIMIT;
   h.finOnIdle = options?.finOnIdle ?? false;
   h.authorize = options?.authorize;
@@ -1050,6 +1375,7 @@ const useSocketHost = (
   attach(h, value);
   useEffect(() => {
     attach(h, value);
+    scheduleFlush(h);
   });
   useEffect(() => {
     resume(h);
@@ -1069,8 +1395,9 @@ const useSocketHost = (
 export const StatewireSocketHost = (
   transport: ResourceElement<Statewire>,
   options?: StatewireHostInternal.SocketHostOptions,
+  persistence?: StatewireHostInternal.SocketHostPersistence,
 ): StatewireHostInternal.SocketHost => {
-  const SocketHostRoot = () => useSocketHost(transport, options);
+  const SocketHostRoot = () => useSocketHost(transport, options, persistence);
   const root = createTapRoot(SocketHostRoot);
   let disposed = false;
   return {
@@ -1084,7 +1411,9 @@ export const StatewireSocketHost = (
     dispose: () => {
       if (disposed) return;
       disposed = true;
-      flushTapSync(() => root.getValue().finish({ reason: "evicted" }));
+      flushTapSync(() =>
+        root.getValue().finish({ reason: "reconnect", code: "evicted" }),
+      );
       root.unmount();
     },
   };