statewire 0.13.1 → 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,17 +111,46 @@ 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;
   reconnect: () => void;
 };
 
+export const degradedOf = (state: ConnectionState): boolean =>
+  (state.status === "connecting" && state.attempt > 0) ||
+  (state.status === "disconnected" &&
+    state.reason !== "idle" &&
+    state.reason !== "deferred");
+
+const sameState = (a: ConnectionState, b: ConnectionState): boolean => {
+  if (a.status !== b.status) return false;
+  if (a.status === "connecting" && b.status === "connecting") {
+    return (
+      a.attempt === b.attempt &&
+      a.cause === b.cause &&
+      a.code === b.code &&
+      a.nextRetryAt === b.nextRetryAt &&
+      a.lastError === b.lastError
+    );
+  }
+  if (a.status === "disconnected" && b.status === "disconnected") {
+    return a.reason === b.reason;
+  }
+  return true;
+};
+
 const setStatus = (c: Conn, next: ConnectionState) => {
-  const changed = next.status !== c.connection.status;
-  c.connection = { ...next, reconnect: c.reconnect };
+  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),
+  };
   c.notify(c.connection);
-  if (changed) c.onChange(c.connection);
+  c.onChange(c.connection);
 };
 
 const protocolError = (message: string): never => {
@@ -191,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;
 };
 
@@ -237,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);
 };
 
@@ -270,11 +305,11 @@ 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;
-  setStatus(c, { status: "live" });
+  setStatus(c, { status: "connected" });
 };
 
 let warnedUnknownSynFact = false;
@@ -323,50 +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;
-    setStatus(c, { status: "idle" });
+    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: "gone",
+    status: "disconnected",
+    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 }),
   });
@@ -385,14 +433,17 @@ export const handleEnvelope = (
   }
   deliverEnvelope(c, env);
   if (env.fin !== undefined) return settleFin(c, env.fin);
-  if (c.connection.status !== "live") {
+  if (c.connection.status !== "connected") {
     c.attempt = 0;
     c.episode = null;
-    setStatus(c, { status: "live" });
+    setStatus(c, { status: "connected" });
   }
   return null;
 };
 
+const dialing = (c: Conn) =>
+  setStatus(c, { status: "connecting", attempt: c.attempt });
+
 const scheduleRetry = (
   c: Conn,
   failure: string | undefined,
@@ -404,11 +455,14 @@ const scheduleRetry = (
   c.liveAt = null;
   c.attempt += 1;
   c.episode ??= { cause: "dropped" };
-  const delay = immediate ? 0 : backoff(c.attempt);
+  const delay = Math.max(
+    immediate ? 0 : backoff(c.attempt),
+    c.retryAt - Date.now(),
+  );
   setStatus(c, {
-    status: "reconnecting",
-    ...c.episode,
+    status: "connecting",
     attempt: c.attempt,
+    ...c.episode,
     nextRetryAt: Date.now() + delay,
     ...(failure !== undefined && { lastError: failure }),
   });
@@ -417,13 +471,12 @@ const scheduleRetry = (
 
 const reconnectConn = (c: Conn) => {
   if (!c.lifetime) return;
-  if (c.connection.status === "gone" || c.connection.status === "idle") {
+  if (c.connection.status === "disconnected") {
+    // A reconnect out of a park starts a fresh episode: first dial, attempt 0.
     c.attempt = 0;
     c.authDenials = 0;
-    c.episode = { cause: "dropped" };
-    flushTapSync(() => {
-      scheduleRetry(c, undefined, true);
-    });
+    c.episode = null;
+    flushTapSync(() => dialing(c));
   }
   openGate(c.gate);
   c.abort?.abort();
@@ -437,6 +490,12 @@ 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();
     c.abort = abort;
     c.awaitingHello = true;
@@ -447,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";
       }
@@ -458,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;
@@ -469,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: [],
@@ -496,25 +620,47 @@ 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,
       reconnect: () => reconnectConn(conn),
-      connection: { status: "connecting", reconnect: () => conn.reconnect() },
+      connection: {
+        ...((props.isNew ?? false)
+          ? { status: "disconnected", reason: "deferred" }
+          : { status: "connecting", attempt: 0 }),
+        degraded: false,
+        reconnect: () => conn.reconnect(),
+      },
     };
     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;
-    if (c.connection.status !== "connecting") {
-      setStatus(c, { status: "connecting" });
-    }
+    setStatus(
+      c,
+      c.parked
+        ? { status: "disconnected", reason: "deferred" }
+        : { status: "connecting", attempt: 0 },
+    );
     const lifetime = new AbortController();
     c.lifetime = lifetime;
     c.gate = newGate();
@@ -527,7 +673,7 @@ export const useStatewireConn = (props: {
     };
   }, [c, props.url]);
 
-  return c;
+  return link;
 };
 
 export const classify = (timeout: AbortSignal) =>

package/src/client/core.ts

@@ -10,8 +10,9 @@ import { StatewireSendError } from "../types";
 import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
 
-export const LIVE_CONNECTION: StatewireClient.Connection = {
-  status: "live",
+export const CONNECTED_CONNECTION: StatewireClient.Connection = {
+  status: "connected",
+  degraded: false,
   reconnect: () => {},
 };
 
@@ -41,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;
@@ -160,7 +162,7 @@ const recompute = (c: Core) => {
 };
 
 const getConnection = (c: Core): StatewireClient.Connection =>
-  c.value?.connection ?? LIVE_CONNECTION;
+  c.value?.connection ?? CONNECTED_CONNECTION;
 
 const flush = (c: Core, scheduled = false) => {
   if (!c.value) return;
@@ -198,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;
@@ -296,6 +302,7 @@ export const useStatewireCore = (
       notifiedPublished: undefined,
       notifiedOverlayPaths: [],
       notifiedConnection: null,
+      notifiedError: undefined,
       notifiedBusy: true,
       notifiedFailed: NO_FAILED,
       stale: false,