statewire 0.9.2 → 0.11.0

package/src/host/socket.ts

@@ -12,8 +12,9 @@ import { createMacrotaskPoster } from "../util/macrotask";
 import type { StatewireMetaEntry } from "../wire/meta";
 import type { StatewirePath } from "../wire/ops";
 import type { StatewireCmd, StatewireEnvelope } from "../client/connection";
+import { frames as serveFrames, stream as serveStream } from "./http";
 
-const CLIENT_ID_RE = /^[A-Za-z0-9._~-]{1,256}$/;
+export const CLIENT_ID_RE = /^[A-Za-z0-9._~-]{1,256}$/;
 const RESULT_TTL_MS = 30_000;
 const RESULT_LIMIT = 256;
 const CLIENT_RECORD_LIMIT = 1024;
@@ -33,17 +34,18 @@ type Admission = {
   settled: boolean;
 };
 
-type ClientRec = {
+export type ClientRec = {
   id: string;
   lastSeq: number;
   ctxSeq: number;
+  lease: string | null;
   touched: number;
   context: Record<string, unknown> | null;
   results: Map<number, { ts: number; cmd: StatewireCmd }>;
   inflight: Map<number, Admission>;
 };
 
-type Conn = {
+export type Conn = {
   clientId: string;
   socket: StatewireHostInternal.Socket;
   open: boolean;
@@ -70,7 +72,7 @@ type CmdStatement = {
   meta?: unknown;
 };
 
-type ParsedFrame = {
+export type ParsedFrame = {
   headers: Record<string, string> | null;
   ctx: CtxStatement[];
   cmd: CmdStatement[];
@@ -121,13 +123,10 @@ const contextValue = (ops: unknown): Record<string, unknown> => {
   return value;
 };
 
-const parseFrame = (raw: string, first: boolean): ParsedFrame => {
-  let frame: unknown;
-  try {
-    frame = JSON.parse(raw);
-  } catch {
-    return violation("malformed frame");
-  }
+export const parseFrameValue = (
+  frame: unknown,
+  first: boolean,
+): ParsedFrame => {
   if (!isPlainObject(frame)) return violation("malformed frame");
   if (
     frame["headers"] === undefined &&
@@ -179,6 +178,16 @@ const parseFrame = (raw: string, first: boolean): ParsedFrame => {
   return { headers, ctx, cmd };
 };
 
+export const parseFrame = (raw: string, first: boolean): ParsedFrame => {
+  let frame: unknown;
+  try {
+    frame = JSON.parse(raw);
+  } catch {
+    return violation("malformed frame");
+  }
+  return parseFrameValue(frame, first);
+};
+
 // ─── verdict encoding ───────────────────────────────────
 
 const encodePayload = (
@@ -236,10 +245,11 @@ const cmdOf = (adm: Admission, outcome: CommandsOutcome): StatewireCmd => {
 
 // ─── host ───────────────────────────────────────────────
 
-type Host = {
+export type SocketHostState = {
   heartbeatMs: number;
   clientRecordLimit: number;
   finOnIdle: boolean;
+  authorize: StatewireHostInternal.SocketHostOptions["authorize"];
   clients: Map<string, ClientRec>;
   conns: Set<Conn>;
   pendingOps: WireOp[];
@@ -259,16 +269,18 @@ type Host = {
     socket: StatewireHostInternal.Socket,
   ) => StatewireHostInternal.SocketConnection;
   finish: (fin: StatewireHost.Fin) => void;
+  stream: (request: Request) => Promise<Response>;
+  frames: (request: Request) => Promise<Response>;
 };
 
-const scheduleFlush = (h: Host) => {
+const scheduleFlush = (h: SocketHostState) => {
   if (h.flushScheduled || h.disposed) return;
   h.flushScheduled = true;
   h.post();
 };
 
 const recordOp = (
-  h: Host,
+  h: SocketHostState,
   op: {
     op: string;
     path?: StatewirePath;
@@ -284,7 +296,7 @@ const recordOp = (
   scheduleFlush(h);
 };
 
-const attach = (h: Host, next: Statewire<unknown>) => {
+const attach = (h: SocketHostState, next: Statewire<unknown>) => {
   if (next === h.current) return;
   h.current = next;
   const nextState =
@@ -305,7 +317,12 @@ const attach = (h: Host, next: Statewire<unknown>) => {
   h.commandsHost = nextCommands;
 };
 
-const closeConn = (h: Host, conn: Conn, code?: number, reason?: string) => {
+export const closeConn = (
+  h: SocketHostState,
+  conn: Conn,
+  code?: number,
+  reason?: string,
+) => {
   if (!conn.open) return;
   conn.open = false;
   h.conns.delete(conn);
@@ -320,7 +337,7 @@ const closeConn = (h: Host, conn: Conn, code?: number, reason?: string) => {
   }
 };
 
-const sendTo = (h: Host, conn: Conn, data: string) => {
+export const sendTo = (h: SocketHostState, conn: Conn, data: string) => {
   if (!conn.open) return;
   conn.lastSentAt = Date.now();
   try {
@@ -330,7 +347,7 @@ const sendTo = (h: Host, conn: Conn, data: string) => {
   }
 };
 
-const ensureHeartbeat = (h: Host) => {
+const ensureHeartbeat = (h: SocketHostState) => {
   if (h.heartbeatTimer !== null || h.heartbeatMs <= 0) return;
   h.heartbeatTimer = setInterval(() => {
     const now = Date.now();
@@ -341,7 +358,7 @@ const ensureHeartbeat = (h: Host) => {
   (h.heartbeatTimer as unknown as { unref?: () => void }).unref?.();
 };
 
-const setHeartbeatMs = (h: Host, ms: number) => {
+const setHeartbeatMs = (h: SocketHostState, ms: number) => {
   if (ms === h.heartbeatMs) return;
   h.heartbeatMs = ms;
   if (h.heartbeatTimer !== null) {
@@ -351,14 +368,14 @@ const setHeartbeatMs = (h: Host, ms: number) => {
   }
 };
 
-const idleLevel = (h: Host): boolean => {
+const idleLevel = (h: SocketHostState): boolean => {
   for (const rec of h.clients.values()) {
     if (rec.inflight.size > 0) return false;
   }
   return true;
 };
 
-const flush = (h: Host, fin?: StatewireHost.Fin) => {
+export const flush = (h: SocketHostState, fin?: StatewireHost.Fin) => {
   flushTapSync(() => {});
   h.stateHost?.takeChanged();
   for (const rec of h.clients.values()) {
@@ -421,14 +438,14 @@ const flush = (h: Host, fin?: StatewireHost.Fin) => {
   }
 };
 
-const queueApplied = (h: Host, clientId: string, seq: number) => {
+const queueApplied = (h: SocketHostState, clientId: string, seq: number) => {
   const list = h.pendingApplied.get(clientId);
   if (list) list.push(seq);
   else h.pendingApplied.set(clientId, [seq]);
   scheduleFlush(h);
 };
 
-const queueCmd = (h: Host, clientId: string, cmd: StatewireCmd) => {
+const queueCmd = (h: SocketHostState, clientId: string, cmd: StatewireCmd) => {
   const list = h.pendingCmds.get(clientId);
   if (list) list.push(cmd);
   else h.pendingCmds.set(clientId, [cmd]);
@@ -456,7 +473,7 @@ const admittedThrough = (rec: ClientRec): number =>
 // A re-asked seq never re-runs: the stored verdict re-emits, an applied
 // inflight run re-answers applied; one not yet applied answers nothing (its
 // answers ride the stream when ready), an evicted verdict answers expired.
-const reemit = (h: Host, rec: ClientRec, seq: number) => {
+const reemit = (h: SocketHostState, rec: ClientRec, seq: number) => {
   const cached = rec.results.get(seq);
   if (cached) {
     const newest = Math.max(...rec.results.keys());
@@ -475,7 +492,7 @@ const reemit = (h: Host, rec: ClientRec, seq: number) => {
 };
 
 const settleCmd = (
-  h: Host,
+  h: SocketHostState,
   rec: ClientRec,
   adm: Admission,
   cmd: StatewireCmd,
@@ -490,13 +507,16 @@ const settleCmd = (
 };
 
 const settleWire = (
-  h: Host,
+  h: SocketHostState,
   rec: ClientRec,
   adm: Admission,
   outcome: CommandsOutcome,
 ) => settleCmd(h, rec, adm, cmdOf(adm, outcome));
 
-const callerOf = (h: Host, rec: ClientRec): StatewireHost.Caller => ({
+const callerOf = (
+  h: SocketHostState,
+  rec: ClientRec,
+): StatewireHost.Caller => ({
   clientId: rec.id,
   get context() {
     return rec.context;
@@ -511,7 +531,7 @@ const callerOf = (h: Host, rec: ClientRec): StatewireHost.Caller => ({
 });
 
 const rejectStatement = (
-  h: Host,
+  h: SocketHostState,
   rec: ClientRec,
   adm: Admission,
   message: string,
@@ -523,7 +543,11 @@ const rejectStatement = (
     message,
   });
 
-const admitCmd = (h: Host, rec: ClientRec, statement: CmdStatement) => {
+const admitCmd = (
+  h: SocketHostState,
+  rec: ClientRec,
+  statement: CmdStatement,
+) => {
   const adm: Admission = {
     seq: statement.seq,
     method: statement.method,
@@ -582,8 +606,15 @@ const admitCmd = (h: Host, rec: ClientRec, statement: CmdStatement) => {
 // One admission law, both lanes: absorbed statements answer from the record,
 // then the new suffix is admitted whole or the frame is refused whole via a
 // {syn} stating both watermarks, nothing consumed. A gap is never a close.
-const admitFrame = (h: Host, conn: Conn, frame: ParsedFrame) => {
-  const rec = h.clients.get(conn.clientId)!;
+export type FrameAdmission =
+  | { type: "ok" }
+  | { type: "refused"; syn: { syn: { seq: number; ctxSeq: number } } };
+
+export const admitFrame = (
+  h: SocketHostState,
+  rec: ClientRec,
+  frame: ParsedFrame,
+): FrameAdmission => {
   rec.touched = Date.now();
   const through = admittedThrough(rec);
   for (const statement of frame.cmd) {
@@ -595,12 +626,10 @@ const admitFrame = (h: Host, conn: Conn, frame: ParsedFrame) => {
     (ctxNew.length > 0 && ctxNew[0]!.seq !== rec.ctxSeq + 1) ||
     (cmdNew.length > 0 && cmdNew[0]!.seq !== through + 1)
   ) {
-    sendTo(
-      h,
-      conn,
-      JSON.stringify({ syn: { seq: through, ctxSeq: rec.ctxSeq } }),
-    );
-    return;
+    return {
+      type: "refused",
+      syn: { syn: { seq: through, ctxSeq: rec.ctxSeq } },
+    };
   }
   for (const statement of ctxNew) {
     rec.context = statement.value;
@@ -612,9 +641,10 @@ const admitFrame = (h: Host, conn: Conn, frame: ParsedFrame) => {
     queueCmd(h, rec.id, { seq: cmdNew.at(-1)!.seq, dur: true });
   }
   scheduleFlush(h);
+  return { type: "ok" };
 };
 
-const message = (h: Host, conn: Conn, data: string) => {
+const message = (h: SocketHostState, conn: Conn, data: string) => {
   if (!conn.open || h.disposed || h.finished !== null) return;
   const first = !conn.sawFrame;
   conn.sawFrame = true;
@@ -628,10 +658,14 @@ const message = (h: Host, conn: Conn, data: string) => {
     return;
   }
   if (frame.ctx.length === 0 && frame.cmd.length === 0) return;
-  admitFrame(h, conn, frame);
+  const rec = h.clients.get(conn.clientId)!;
+  const admission = admitFrame(h, rec, frame);
+  if (admission.type === "refused") {
+    sendTo(h, conn, JSON.stringify(admission.syn));
+  }
 };
 
-const gcClients = (h: Host) => {
+const gcClients = (h: SocketHostState) => {
   let excess = h.clients.size - h.clientRecordLimit;
   if (excess <= 0) return;
   const live = new Set([...h.conns].map((conn) => conn.clientId));
@@ -644,23 +678,24 @@ const gcClients = (h: Host) => {
   }
 };
 
-const connect = (
-  h: Host,
+export type Registration = {
+  rec: ClientRec;
+  conn: Conn;
+  connection: StatewireHostInternal.SocketConnection;
+};
+
+export const register = (
+  h: SocketHostState,
   clientId: string,
   socket: StatewireHostInternal.Socket,
-): StatewireHostInternal.SocketConnection => {
-  const dead: StatewireHostInternal.SocketConnection = {
-    clientId,
-    message: () => {},
-    close: () => {},
-  };
+): Registration | null => {
   const refuse = (code: number, reason: string) => {
     try {
       socket.close(code, reason);
     } catch {
       /* peer already gone */
     }
-    return dead;
+    return null;
   };
   if (h.disposed) return refuse(1001, "disposed");
   if (!CLIENT_ID_RE.test(clientId)) return refuse(1008, "invalid client id");
@@ -671,7 +706,8 @@ const connect = (
     } catch {
       /* peer already gone */
     }
-    return refuse(1000, "finished");
+    refuse(1000, "finished");
+    return null;
   }
   const known = h.clients.has(clientId);
   const rec = known
@@ -681,6 +717,7 @@ const connect = (
           id: clientId,
           lastSeq: 0,
           ctxSeq: 0,
+          lease: null,
           touched: Date.now(),
           context: null,
           results: new Map(),
@@ -690,6 +727,7 @@ const connect = (
         return created;
       })();
   rec.touched = Date.now();
+  rec.lease = null;
   for (const other of [...h.conns]) {
     if (other.clientId !== clientId) continue;
     sendTo(h, other, JSON.stringify({ fin: { reason: "superseded" } }));
@@ -723,25 +761,41 @@ const connect = (
     },
   };
   sendTo(h, conn, JSON.stringify(hello));
-  return {
+  const connection: StatewireHostInternal.SocketConnection = {
     clientId,
     message: (data) => message(h, conn, data),
     close: () => closeConn(h, conn),
   };
+  return { rec, conn, connection };
+};
+
+const connect = (
+  h: SocketHostState,
+  clientId: string,
+  socket: StatewireHostInternal.Socket,
+): StatewireHostInternal.SocketConnection => {
+  const registration = register(h, clientId, socket);
+  return (
+    registration?.connection ?? {
+      clientId,
+      message: () => {},
+      close: () => {},
+    }
+  );
 };
 
-const finish = (h: Host, fin: StatewireHost.Fin) => {
+const finish = (h: SocketHostState, fin: StatewireHost.Fin) => {
   if (h.finished !== null || h.disposed) return;
   h.finished = fin;
   flush(h, fin);
 };
 
-const resume = (h: Host) => {
+const resume = (h: SocketHostState) => {
   h.disposed = false;
   h.stateHost?.setOnOp((op) => recordOp(h, op));
 };
 
-const suspend = (h: Host) => {
+const suspend = (h: SocketHostState) => {
   h.disposed = true;
   if (h.heartbeatTimer !== null) {
     clearInterval(h.heartbeatTimer);
@@ -753,12 +807,16 @@ const suspend = (h: Host) => {
 const useSocketHost = (
   transport: ResourceElement<Statewire>,
   options?: StatewireHostInternal.SocketHostOptions,
-): Pick<StatewireHostInternal.SocketHost, "connect" | "finish"> => {
-  const [h] = useState((): Host => {
-    const host: Host = {
+): Pick<
+  StatewireHostInternal.SocketHost,
+  "connect" | "finish" | "stream" | "frames"
+> => {
+  const [h] = useState((): SocketHostState => {
+    const host: SocketHostState = {
       heartbeatMs: 15_000,
       clientRecordLimit: CLIENT_RECORD_LIMIT,
       finOnIdle: false,
+      authorize: undefined,
       clients: new Map(),
       conns: new Set(),
       pendingOps: [],
@@ -778,12 +836,15 @@ const useSocketHost = (
       }),
       connect: (clientId, socket) => connect(host, clientId, socket),
       finish: (fin) => finish(host, fin),
+      stream: (request) => serveStream(host, request),
+      frames: (request) => serveFrames(host, request),
     };
     return host;
   });
   setHeartbeatMs(h, options?.heartbeatIntervalMs ?? 15_000);
   h.clientRecordLimit = options?.clientRecordLimit ?? CLIENT_RECORD_LIMIT;
   h.finOnIdle = options?.finOnIdle ?? false;
+  h.authorize = options?.authorize;
   const value = useResource(transport) as Statewire<unknown>;
   attach(h, value);
   useEffect(() => {
@@ -813,6 +874,8 @@ export const StatewireSocketHost = (
   return {
     connect: (clientId, socket) =>
       flushTapSync(() => root.getValue().connect(clientId, socket)),
+    stream: (request) => flushTapSync(() => root.getValue().stream(request)),
+    frames: (request) => flushTapSync(() => root.getValue().frames(request)),
     finish: (fin) => flushTapSync(() => root.getValue().finish(fin)),
     dispose: () => {
       if (disposed) return;

package/src/host-internal.ts

@@ -16,11 +16,16 @@ export namespace StatewireHostInternal {
 
   export type SocketHost = {
     connect: (clientId: string, socket: Socket) => SocketConnection;
+    stream: (request: Request) => Promise<Response>;
+    frames: (request: Request) => Promise<Response>;
     finish: (fin: StatewireHost.Fin) => void;
     dispose: () => void;
   };
 
   export type SocketHostOptions = {
+    authorize?: (ctx: {
+      headers: Record<string, string>;
+    }) => void | Promise<void>;
     heartbeatIntervalMs?: number;
     /** LRU cap on stored client records; live or in-flight records are exempt. */
     clientRecordLimit?: number;

package/src/statewire.ts

@@ -3,12 +3,31 @@ import {
   createTapRoot,
   flushTapSync,
   resource,
+  useContextProvider,
   useResource,
+  useResources,
+  withKey,
 } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
 import { LIVE_CONNECTION, useStatewireCore } from "./client/core";
 import type { Statewire } from "./types";
-import type { StatewireSessionStoreOptions } from "./client/sessionStore";
+import { SessionStorageContext } from "./client/sessionStore";
+
+const useSessionTransport = ({
+  transport,
+  session,
+}: {
+  transport: ResourceElement<Statewire<any, any>>;
+  session: StatewireClient.SessionStorage | undefined;
+}): Statewire<unknown> =>
+  useContextProvider(SessionStorageContext, session, () =>
+    // oxlint-disable-next-line react-hooks/rules-of-hooks
+    useResource(transport),
+  );
+
+// The transport owns the session; it reads the storage off the context this
+// wrapper's own fiber provides, so plain-React callers get a provider too.
+const SessionTransport = resource(useSessionTransport);
 
 export const useStatewire = <
   TState,
@@ -19,7 +38,14 @@ export const useStatewire = <
   const latest = useRef(options);
   latest.current = options;
 
-  const value = useResource(options.transport) as Statewire<unknown>;
+  const session = useResources(
+    options.storage?.session !== undefined
+      ? [withKey("session", options.storage.session)]
+      : [],
+  )[0];
+  const value = useResource(
+    SessionTransport({ transport: options.transport, session }),
+  );
   const core = useStatewireCore(() => latest.current, value);
   const [subscribe] = useState(
     () => (listener: () => void) =>
@@ -111,6 +137,10 @@ export namespace StatewireClient {
     TCommands extends Statewire.Commands = Statewire.Commands,
   > = {
     transport: ResourceElement<Statewire<TState, TCommands>>;
+    /** Durable session: the mounted storage holds this client's lane identity and its un-durable commands, which resend on the next attach. */
+    storage?:
+      | { session?: ResourceElement<SessionStorage> | undefined }
+      | undefined;
     /** Served as the canonical state until the attach snapshot; own commands fold over it. */
     initialState?: TState;
     optimistic?: Optimistic<NonNullable<TState>, TCommands>;
@@ -187,10 +217,12 @@ export namespace StatewireClient {
   /**
    * fate: "aborted" = never sent, "rejected" = the server refused it
    * (`code` "unknown-command" | "invalid-params" for the static rejects,
-   * code-less for handler rejects), "lost" = sent but never covered by an
-   * applied, "failed" = the handler ran and threw, "crashed" = the handler
-   * died involuntarily, "expired" = concluded but the outcome is
-   * unavailable.
+   * code-less for handler rejects), "lost" = sent but no verdict will ever
+   * arrive — the record is gone (`record: "fresh"`) or the channel died: it
+   * may or may not have run, "failed" = the handler ran and threw,
+   * "crashed" = the handler died involuntarily, "expired" = settled —
+   * result, rejected, failed, or crashed — but the verdict outlived the
+   * server's retention.
    * cause is which channel settled it: "server" = the server's answer;
    * the rest are channel deaths the client settled locally.
    */
@@ -215,12 +247,51 @@ export namespace StatewireClient {
         cause: "unmount" | "stream-gone" | "session-lost" | "superseded";
       };
 
+  /** A command as persisted while un-durable: its lane seq plus the wire statement. */
+  export type SessionCommand = {
+    seq: number;
+    method: string;
+    params: unknown[];
+    meta?: unknown;
+  };
+
+  /** The persisted session: the lane identity, the lane clocks, and the commands the server has not marked durable. */
+  export type SessionRecord = {
+    clientId: string;
+    nextSeq: number;
+    ctxNextSeq: number;
+    commands: readonly SessionCommand[];
+    /** Terminal verdicts parked for the sharer that minted the seq (shared storage only). */
+    verdicts?: readonly SessionVerdict[];
+  };
+
+  /** A terminal verdict one sharer's connection carried, parked for the sharer awaiting the seq. */
+  export type SessionVerdict = {
+    seq: number;
+    type: "result" | "rejected" | "failed" | "crashed" | "expired";
+    code?: string;
+    message?: string;
+    payload?: unknown;
+    meta?: unknown;
+  };
+
+  /** Session storage seam; `save` must persist synchronously in the caller's flow. */
+  export type SessionStorage = {
+    load: () => SessionRecord | null;
+    save: (record: SessionRecord) => void;
+    /** Serializes record mutations across sharers; presence marks the storage shared. */
+    lock?: <T>(fn: () => T | Promise<T>) => Promise<T>;
+    /** Notifies of record saves by other sharers; returns unsubscribe. Required alongside `lock`. */
+    subscribe?: (listener: () => void) => () => void;
+  };
+
   /** Static headers, or a resolver invoked per request/attach; `staleAuth` is true right after an auth rejection. */
   export type HeadersOption =
     | HeadersInit
     | ((ctx: { staleAuth: boolean }) => HeadersInit | Promise<HeadersInit>);
 
-  export type SSEOptions = StatewireSessionStoreOptions & {
+  export type SSEOptions = {
+    sessionStore?: SessionStorage | undefined;
     url: string;
     headers?: HeadersOption;
     fetch?: typeof globalThis.fetch;
@@ -229,7 +300,8 @@ export namespace StatewireClient {
     onDone?: () => void;
   };
 
-  export type WSOptions = StatewireSessionStoreOptions & {
+  export type WSOptions = {
+    sessionStore?: SessionStorage | undefined;
     url: string;
     headers?: HeadersOption;
     protocols?: string | string[];

package/src/types.ts

@@ -53,7 +53,7 @@ export interface Statewire<
   commands: Statewire.CommandsProxy<TCommands>;
   connection?: StatewireClient.Connection;
   source?: Statewire.StateSource;
-  /** Highest command seq released from the resend queue by the server's dur flag. */
+  /** Highest command seq the server's dur flag states durably admitted — never lost, never run again — and released from the resend queue. */
   durableSeq?: number;
   /** Negation of the server's broadcast idle level; absent means always busy. */
   isBusy?: boolean;