statewire 0.14.0 → 0.15.0

package/src/client/connection.ts

@@ -2,13 +2,20 @@ import { useEffect, useRef, useState } from "react";
 import { flushTapSync } from "@assistant-ui/tap";
 import { reviveOps, reviveValue } from "../wire/meta";
 import { backoff, timing } from "./timing";
-import type { ConnectionState, StatewireRemoteProps } from "../transports/sse";
+import type {
+  ConnectionState,
+  RemoteLink,
+  StatewireFrame,
+  StatewireRemoteProps,
+  StatewireSubmitResult,
+} from "../transports/sse";
 import type { StatewireClient } from "../statewire";
 import type { StatewireHost } from "../host";
 
 export type Episode = {
-  cause: "dropped" | "evicted" | "error" | "unauthorized";
+  cause: "dropped" | "reconnect" | "error" | "unauthorized";
   message?: string;
+  code?: string;
 };
 
 /** The terminal cmd verdict types; "applied" is the sole non-terminal type. */
@@ -90,11 +97,13 @@ export type AttemptOutcome = "stop" | "reattach" | "ended" | "idle";
 export type Conn = {
   connection: StatewireClient.Connection;
   parked: boolean;
-  hasSnapshot: boolean;
   lease: string | null;
   attempt: number;
   authDenials: number;
+  authStale: boolean;
   liveAt: number | null;
+  retryAt: number;
+  error: StatewireClient.ConnectionError | undefined;
   episode: Episode | null;
   awaitingHello: boolean;
   held: StatewireCmd[];
@@ -102,6 +111,7 @@ export type Conn = {
   abort: AbortController | null;
   lifetime: AbortController | null;
   ctx: StatewireRemoteProps;
+  onError: (error: StatewireClient.ConnectionError) => void;
   onChange: (connection: StatewireClient.Connection) => void;
   attemptOnce: (abort: AbortController) => Promise<AttemptOutcome>;
   notify: (connection: StatewireClient.Connection) => void;
@@ -110,7 +120,9 @@ export type Conn = {
 
 export const degradedOf = (state: ConnectionState): boolean =>
   (state.status === "connecting" && state.attempt > 0) ||
-  (state.status === "disconnected" && state.reason === "gone");
+  (state.status === "disconnected" &&
+    state.reason !== "idle" &&
+    state.reason !== "deferred");
 
 const sameState = (a: ConnectionState, b: ConnectionState): boolean => {
   if (a.status !== b.status) return false;
@@ -118,6 +130,7 @@ const sameState = (a: ConnectionState, b: ConnectionState): boolean => {
     return (
       a.attempt === b.attempt &&
       a.cause === b.cause &&
+      a.code === b.code &&
       a.nextRetryAt === b.nextRetryAt &&
       a.lastError === b.lastError
     );
@@ -129,9 +142,10 @@ const sameState = (a: ConnectionState, b: ConnectionState): boolean => {
 };
 
 const setStatus = (c: Conn, next: ConnectionState) => {
-  if (sameState(next, c.connection)) return;
+  if (sameState(next, c.connection) && c.connection.error === c.error) return;
   c.connection = {
     ...next,
+    ...(c.error === undefined ? {} : { error: c.error }),
     reconnect: c.reconnect,
     degraded: degradedOf(next),
   };
@@ -215,6 +229,14 @@ const validateFin = (value: unknown): value is StatewireHost.Fin => {
     protocolError("fin.reason must be a string");
   }
   validateOptionalString(value["message"], "fin.message");
+  validateOptionalString(value["code"], "fin.code");
+  if (
+    value["status"] !== undefined &&
+    !isNonnegativeSafeInteger(value["status"])
+  )
+    protocolError("fin.status must be a nonnegative safe integer");
+  if (value["retry"] !== undefined && !isNonnegativeSafeInteger(value["retry"]))
+    protocolError("fin.retry must be a nonnegative safe integer");
   return true;
 };
 
@@ -261,18 +283,7 @@ const cmdsOf = (env: StatewireEnvelope): StatewireCmd[] => {
 const snapshotOf = (env: StatewireEnvelope): unknown[] => {
   const ops = env.ops;
   if (ops === undefined) return protocolError("hello missing snapshot");
-  if (ops.length !== 1 || !isObject(ops[0])) {
-    return protocolError("hello snapshot must be one root replace op");
-  }
-  const op = ops[0];
-  if (
-    op["op"] !== "replace" ||
-    !Array.isArray(op["path"]) ||
-    op["path"].length !== 0 ||
-    !Object.hasOwn(op, "value")
-  ) {
-    return protocolError("hello snapshot must be one root replace op");
-  }
+  if (ops.length === 0) return protocolError("hello missing snapshot");
   return reviveOps(ops);
 };
 
@@ -294,7 +305,7 @@ const handleHello = (c: Conn, env: StatewireEnvelope) => {
   });
   c.ctx.onIdle(syn.idle ?? false);
   c.awaitingHello = false;
-  c.hasSnapshot = true;
+  c.error = undefined;
   c.liveAt = Date.now();
   c.authDenials = 0;
   c.episode = null;
@@ -347,51 +358,63 @@ const deliverEnvelope = (c: Conn, env: StatewireEnvelope) => {
   if (typeof env.idle === "boolean") c.ctx.onIdle(env.idle);
 };
 
-const transientCauseOf = (
-  reason: StatewireHost.Fin["reason"],
-): Episode["cause"] => {
-  switch (reason) {
-    case "evicted":
-      return "evicted";
-    case "error":
-      return "error";
-    case "unauthorized":
-      return "unauthorized";
-    default:
-      return "error";
-  }
-};
-
-const settleFin = (c: Conn, fin: StatewireHost.Fin): AttemptOutcome => {
-  let finish = fin;
-  if (finish.meta !== undefined) {
-    const { meta, ...rest } = finish;
-    finish = { ...rest, payload: reviveValue(rest.payload, meta) };
-  }
+export const settleFin = (c: Conn, fin: StatewireHost.Fin): AttemptOutcome => {
+  const finish =
+    fin.meta === undefined
+      ? fin
+      : { ...fin, payload: reviveValue(fin.payload, fin.meta) };
   releaseHeld(c);
+  c.retryAt = Date.now() + (finish.retry ?? 0);
   if (finish.reason === "idle") {
     c.ctx.onIdle(true);
     c.attempt = 0;
     c.episode = null;
+    c.error = undefined;
     setStatus(c, { status: "disconnected", reason: "idle" });
     return "idle";
   }
-  // An auth denial gets one immediate redial; a consecutive repeat parks as gone.
   const denial = finish.reason === "unauthorized";
-  const terminal = finish.reason === "gone" || (denial && c.authDenials > 0);
-  if (denial) c.authDenials += 1;
-  c.ctx.onFinish(terminal ? finish : { ...finish, reason: "error" });
+  const terminal =
+    finish.reason === "gone" ||
+    finish.reason === "forbidden" ||
+    finish.reason === "protocol-error" ||
+    (denial && c.authDenials > 0);
+  if (denial) {
+    c.authDenials += 1;
+    c.authStale = true;
+  }
+  const report =
+    finish.reason !== "reconnect" &&
+    finish.reason !== "gone" &&
+    (!denial || terminal);
+  c.error = report
+    ? Object.assign(new Error(finish.message ?? finish.reason), { fin: finish })
+    : undefined;
+  if (c.error) c.onError(c.error);
   if (!terminal) {
     c.episode = {
-      cause: transientCauseOf(finish.reason),
+      cause:
+        finish.reason === "reconnect"
+          ? "reconnect"
+          : denial
+            ? "unauthorized"
+            : "error",
       ...(finish.message !== undefined && { message: finish.message }),
+      ...(finish.code !== undefined && { code: finish.code }),
     };
     if (denial) openGate(c.gate);
     return "reattach";
   }
+  c.ctx.onFinish(finish);
   setStatus(c, {
     status: "disconnected",
-    reason: "gone",
+    reason: denial
+      ? "unauthorized"
+      : finish.reason === "forbidden"
+        ? "forbidden"
+        : finish.reason === "protocol-error"
+          ? "protocol-error"
+          : "gone",
     ...(finish.message !== undefined && { message: finish.message }),
     ...(finish.payload !== undefined && { payload: finish.payload }),
   });
@@ -432,8 +455,10 @@ const scheduleRetry = (
   c.liveAt = null;
   c.attempt += 1;
   c.episode ??= { cause: "dropped" };
-  if (immediate) return 0;
-  const delay = backoff(c.attempt);
+  const delay = Math.max(
+    immediate ? 0 : backoff(c.attempt),
+    c.retryAt - Date.now(),
+  );
   setStatus(c, {
     status: "connecting",
     attempt: c.attempt,
@@ -465,6 +490,10 @@ const run = async (c: Conn, lifetime: AbortController, gate: Gate) => {
     c.parked = false;
   }
   while (alive()) {
+    if (c.retryAt > Date.now()) {
+      await waitGate(gate, c.retryAt - Date.now());
+      continue;
+    }
     // The dial is in flight: attempt alone, no backoff fields.
     flushTapSync(() => dialing(c));
     const abort = new AbortController();
@@ -477,6 +506,27 @@ const run = async (c: Conn, lifetime: AbortController, gate: Gate) => {
       outcome = await c.attemptOnce(abort);
     } catch (error) {
       if (!abort.signal.aborted) {
+        if (
+          error instanceof SyntaxError ||
+          (error instanceof Error &&
+            /^(statewire: protocol error:|Statewire cannot apply)/.test(
+              error.message,
+            ))
+        ) {
+          outcome = flushTapSync(() =>
+            settleFin(c, { reason: "protocol-error", message: error.message }),
+          );
+        } else if (c.authStale) {
+          outcome = flushTapSync(() =>
+            settleFin(c, {
+              reason: "unauthorized",
+              message:
+                error instanceof Error
+                  ? error.message
+                  : "credential refresh failed",
+            }),
+          );
+        }
         failure =
           error instanceof Error && error.message ? error.message : "network";
       }
@@ -488,6 +538,11 @@ const run = async (c: Conn, lifetime: AbortController, gate: Gate) => {
       c.ctx.onDetach();
     });
     if (!alive()) return;
+    if (
+      c.connection.status === "disconnected" &&
+      !["deferred", "idle"].includes(c.connection.reason)
+    )
+      outcome = "stop";
     if (outcome === "stop" || outcome === "idle") {
       await waitGate(gate);
       continue;
@@ -499,24 +554,63 @@ const run = async (c: Conn, lifetime: AbortController, gate: Gate) => {
   }
 };
 
-export const useStatewireConn = (props: {
+export const unsupportedVersion = (c: Conn, version: string): AttemptOutcome =>
+  flushTapSync(() =>
+    handleEnvelope(c, {
+      fin: {
+        reason: "protocol-error",
+        message: `unsupported protocol version: ${version || '""'}`,
+      },
+    }),
+  ) ?? "stop";
+
+export const resolveHeaders = async (
+  headers: StatewireClient.HeadersOption | undefined,
+  staleAuth: boolean,
+): Promise<Headers> =>
+  new Headers(
+    typeof headers === "function" ? await headers({ staleAuth }) : headers,
+  );
+
+// The stale flag clears only once the resolver returns: a throwing refresh keeps it for the next attempt.
+export const attachFrame = async (
+  c: Conn,
+  headers: StatewireClient.HeadersOption | undefined,
+) => {
+  const resolved = await resolveHeaders(headers, c.authStale);
+  c.authStale = false;
+  const lanes = flushTapSync(() => c.ctx.takeAttachLanes());
+  return {
+    headers: resolved,
+    body: JSON.stringify({
+      headers: Object.fromEntries(resolved),
+      ...(lanes ?? {}),
+    }),
+  };
+};
+
+export const useLink = (props: {
   url: string;
   isNew?: boolean | undefined;
   onChange?: ((connection: StatewireClient.Connection) => void) | undefined;
+  onError?: ((error: StatewireClient.ConnectionError) => void) | undefined;
   ctx: StatewireRemoteProps;
   attemptOnce: (c: Conn, abort: AbortController) => Promise<AttemptOutcome>;
-}): Conn => {
+  send: (c: Conn, frame: StatewireFrame) => Promise<StatewireSubmitResult>;
+}): RemoteLink => {
   const latest = useRef(props);
   latest.current = props;
   const [, setConnection] = useState<StatewireClient.Connection | null>(null);
   const [c] = useState((): Conn => {
     const conn: Conn = {
       parked: props.isNew ?? false,
-      hasSnapshot: false,
       lease: null,
       attempt: 0,
       authDenials: 0,
+      authStale: false,
       liveAt: null,
+      retryAt: 0,
+      error: undefined,
       episode: null,
       awaitingHello: true,
       held: [],
@@ -526,6 +620,7 @@ export const useStatewireConn = (props: {
       get ctx() {
         return latest.current.ctx;
       },
+      onError: (error) => latest.current.onError?.(error),
       onChange: (connection) => latest.current.onChange?.(connection),
       attemptOnce: (abort) => latest.current.attemptOnce(conn, abort),
       notify: setConnection,
@@ -540,13 +635,25 @@ export const useStatewireConn = (props: {
     };
     return conn;
   });
+  const [link] = useState(
+    (): RemoteLink => ({
+      get connection() {
+        return c.connection;
+      },
+      get parked() {
+        return c.parked;
+      },
+      send: (frame) => latest.current.send(c, frame),
+    }),
+  );
 
   useEffect(() => {
-    c.hasSnapshot = false;
     c.lease = null;
     c.attempt = 0;
     c.authDenials = 0;
+    c.authStale = false;
     c.liveAt = null;
+    c.retryAt = 0;
     c.episode = null;
     setStatus(
       c,
@@ -566,7 +673,7 @@ export const useStatewireConn = (props: {
     };
   }, [c, props.url]);
 
-  return c;
+  return link;
 };
 
 export const classify = (timeout: AbortSignal) =>

package/src/client/core.ts

@@ -42,6 +42,7 @@ type Core = {
   notifiedPublished: unknown;
   notifiedOverlayPaths: readonly StatewirePath[];
   notifiedConnection: StatewireClient.Connection | null;
+  notifiedError: StatewireClient.ConnectionError | undefined;
   notifiedBusy: boolean;
   notifiedFailed: readonly StatewireClient.FailedCommand[];
   stale: boolean;
@@ -199,6 +200,10 @@ const flush = (c: Core, scheduled = false) => {
     const connectionChanged = connection !== c.notifiedConnection;
     c.notifiedConnection = connection;
     if (connectionChanged) options.onConnectionChange?.(connection);
+    if (connection.error !== c.notifiedError) {
+      c.notifiedError = connection.error;
+      if (connection.error) options.onError?.(connection.error);
+    }
     const busy = c.getBusy();
     const busyChanged = busy !== c.notifiedBusy;
     c.notifiedBusy = busy;
@@ -297,6 +302,7 @@ export const useStatewireCore = (
       notifiedPublished: undefined,
       notifiedOverlayPaths: [],
       notifiedConnection: null,
+      notifiedError: undefined,
       notifiedBusy: true,
       notifiedFailed: NO_FAILED,
       stale: false,

package/src/client/session.ts

@@ -1,6 +1,9 @@
+import { applyDocumentOps } from "../wire/documents";
+import type { StatewireDocuments } from "../wire/documents";
 import { useContext, useEffect, useState } from "react";
-import { applyOps } from "../wire/ops";
+
 import type { StatewirePath } from "../wire/ops";
+import { MAX_COMMANDS_PER_FRAME } from "../wire/limits";
 import { TERMINAL } from "./connection";
 import type { StatewireCmd, StatewireSyn } from "./connection";
 import {
@@ -103,6 +106,7 @@ type Session = {
   frameFailures: number;
   pending: Pending[];
   canonical: unknown;
+  documents: StatewireDocuments.State;
   lastPublished: unknown;
   changed: StatewirePath[];
   source: Statewire.StateSource;
@@ -238,7 +242,7 @@ export const failedCommands = (
   s: Session,
 ): readonly StatewireClient.FailedCommand[] => s.record.failed ?? NO_FAILED;
 
-const retainFailed = (
+const retainFailedInner = (
   s: Session,
   entry: Pending,
   failure: StatewireClient.SendFailure,
@@ -260,6 +264,18 @@ const retainFailed = (
   s.notify();
 };
 
+const retainFailed = (
+  s: Session,
+  entry: Pending,
+  failure: StatewireClient.SendFailure,
+) => {
+  if (!s.shared) {
+    retainFailedInner(s, entry, failure);
+    return;
+  }
+  void transact(s, () => retainFailedInner(s, entry, failure));
+};
+
 const settleEntry = (
   s: Session,
   entry: Pending,
@@ -481,8 +497,9 @@ const handleCmds = (s: Session, cmds: StatewireCmd[]) => {
 };
 
 const ingestOps = (s: Session, ops: unknown[]) => {
-  const applied = applyOps(s.canonical, ops);
-  s.canonical = applied.state;
+  const applied = applyDocumentOps(s.documents, ops);
+  s.documents = applied;
+  s.canonical = applied.documents.get(0)?.value;
   s.changed.push(...applied.changedPaths);
 };
 
@@ -546,6 +563,7 @@ const handleHello = (
   if (syn.record !== undefined && syn.record !== "ephemeral") {
     protocolError(`unknown record: ${String(syn.record)}`);
   }
+  s.documents = { mode: null, documents: new Map() };
   ingestOps(s, ops);
   s.attach = "attached";
   s.attachEpoch += 1;
@@ -642,7 +660,7 @@ const handleDetach = (s: Session) => {
 };
 
 const handleFinish = (s: Session, { reason }: { reason: string }) => {
-  if (reason === "evicted" || reason === "error") return;
+  if (reason === "reconnect" || reason === "error") return;
   s.attach = "finished";
   settleAll(s, "gone");
   publish(s);
@@ -663,6 +681,7 @@ const buildLanes = (s: Session): Lanes | null => {
   const ctxEntries: CtxPending[] = [];
   for (const entry of s.ctxPending) {
     if (entry.posted) continue;
+    if (ctxEntries.length >= MAX_COMMANDS_PER_FRAME) break;
     if (ctxEntries.length > 0 && entry.seq !== ctxEntries.at(-1)!.seq + 1)
       break;
     ctxEntries.push(entry);
@@ -670,6 +689,7 @@ const buildLanes = (s: Session): Lanes | null => {
   const cmdEntries: Pending[] = [];
   for (const entry of s.pending) {
     if (entry.posted) continue;
+    if (cmdEntries.length >= MAX_COMMANDS_PER_FRAME) break;
     if (cmdEntries.length > 0 && entry.seq !== cmdEntries.at(-1)!.seq + 1)
       break;
     cmdEntries.push(entry);
@@ -862,9 +882,17 @@ const enqueue = (
     void pump(s);
     return;
   }
-  void transact(s, () =>
-    enqueueInner(s, command, params, resolve, reject),
-  ).then(() => {
+  void transact(s, () => {
+    if (!s.running) {
+      reject(new StatewireSendError({ fate: "aborted", cause: "unmount" }));
+      return;
+    }
+    if (isFinished(s)) {
+      reject(new StatewireSendError({ fate: "aborted", cause: "stream-gone" }));
+      return;
+    }
+    enqueueInner(s, command, params, resolve, reject);
+  }).then(() => {
     wake(s);
     void pump(s);
   });
@@ -928,18 +956,25 @@ const sendCommand = (
   return result;
 };
 
-const takeFailed = (
+const findFailed = (
   s: Session,
   entry: StatewireClient.FailedCommand,
-): StatewireClient.FailedCommand => {
-  const failed = s.record.failed ?? [];
-  const found = failed.find(
+): StatewireClient.FailedCommand | undefined =>
+  (s.record.failed ?? []).find(
     (f) =>
       f.seq === entry.seq && f.ts === entry.ts && f.command === entry.command,
   );
-  if (found === undefined) {
-    throw new Error(`statewire: unknown failed command "${entry.command}"`);
-  }
+
+const unknownFailed = (entry: StatewireClient.FailedCommand) =>
+  new Error(`statewire: unknown failed command "${entry.command}"`);
+
+const takeFailed = (
+  s: Session,
+  entry: StatewireClient.FailedCommand,
+): StatewireClient.FailedCommand => {
+  const failed = s.record.failed ?? [];
+  const found = findFailed(s, entry);
+  if (found === undefined) throw unknownFailed(entry);
   setRecord(s, { ...s.record, failed: failed.filter((f) => f !== found) });
   s.notify();
   return found;
@@ -949,7 +984,14 @@ export const discardFailed = (
   s: Session,
   entry: StatewireClient.FailedCommand,
 ): void => {
-  takeFailed(s, entry);
+  if (!s.shared) {
+    takeFailed(s, entry);
+    return;
+  }
+  if (findFailed(s, entry) === undefined) throw unknownFailed(entry);
+  void transact(s, () => {
+    if (findFailed(s, entry) !== undefined) takeFailed(s, entry);
+  });
 };
 
 export const retryFailed = (
@@ -962,23 +1004,52 @@ export const retryFailed = (
   if (isFinished(s)) {
     return rejectedSend({ fate: "aborted", cause: "stream-gone" });
   }
-  const found = takeFailed(s, entry);
+  const found = findFailed(s, entry);
+  if (found === undefined) throw unknownFailed(entry);
   const params =
     found.meta === undefined
       ? found.params
       : (reviveValue([...found.params], found.meta) as unknown[]);
   const result = new Promise<unknown>((resolve, reject) => {
-    enqueue(
-      s,
-      {
-        method: found.command,
-        params: [...found.params],
-        ...(found.meta !== undefined && { meta: found.meta }),
-      },
-      params,
-      resolve,
-      reject,
-    );
+    const retry = () => {
+      if (!s.running) {
+        reject(new StatewireSendError({ fate: "aborted", cause: "unmount" }));
+        return;
+      }
+      if (isFinished(s)) {
+        reject(
+          new StatewireSendError({ fate: "aborted", cause: "stream-gone" }),
+        );
+        return;
+      }
+      const current = findFailed(s, entry);
+      if (current === undefined) {
+        reject(unknownFailed(entry));
+        return;
+      }
+      takeFailed(s, current);
+      enqueueInner(
+        s,
+        {
+          method: current.command,
+          params: [...current.params],
+          ...(current.meta !== undefined && { meta: current.meta }),
+        },
+        params,
+        resolve,
+        reject,
+      );
+    };
+    if (!s.shared) {
+      retry();
+      wake(s);
+      void pump(s);
+      return;
+    }
+    void transact(s, retry).then(() => {
+      wake(s);
+      void pump(s);
+    }, reject);
   });
   result.catch(() => {});
   return result;
@@ -1010,7 +1081,10 @@ const setContext = (s: Session, value: Record<string, unknown>): void => {
     void pump(s);
     return;
   }
-  void transact(s, mint).then(() => {
+  void transact(s, () => {
+    if (!s.running || isFinished(s)) return;
+    mint();
+  }).then(() => {
     wake(s);
     void pump(s);
   });
@@ -1081,6 +1155,7 @@ export const useStatewireSession = (
       frameFailures: 0,
       pending: [],
       canonical: undefined,
+      documents: { mode: null, documents: new Map() },
       lastPublished: undefined,
       changed: [],
       source: {

package/src/host/adapter.ts

@@ -1,3 +1,4 @@
+import { CLIENT_ID_RE } from "./socket";
 import type { StatewireHostInternal } from "../host-internal";
 
 export const CLIENT_QUERY_PARAM = "client";
@@ -20,14 +21,21 @@ export const clientIdFromUrl = (url: string | null | undefined): string => {
       `statewire: url is missing the "${CLIENT_QUERY_PARAM}" query parameter`,
     );
   }
+  if (!CLIENT_ID_RE.test(clientId))
+    throw new Error("statewire: invalid client id");
   return clientId;
 };
 
 export const textFrameOrClose = (
-  socket: Pick<StatewireHostInternal.Socket, "close">,
+  socket: Pick<StatewireHostInternal.Socket, "send" | "close">,
   data: unknown,
 ): string | null => {
   if (typeof data === "string") return data;
-  socket.close(1008, "text frames only");
+  socket.send(
+    JSON.stringify({
+      fin: { reason: "protocol-error", message: "malformed frame" },
+    }),
+  );
+  socket.close(1008, "malformed frame");
   return null;
 };