statewire 0.4.0 → 0.5.0

package/src/statewire.ts

@@ -119,6 +119,7 @@ export namespace StatewireClient {
       update: Statewire.CommandUpdate<TCommands>,
       ctx: { state: NonNullable<TState> },
     ) => void;
+    onConnectionChange?: (connection: Connection) => void;
   };
 
   export type Helpers<
@@ -140,7 +141,7 @@ export namespace StatewireClient {
     | { status: "live" }
     | {
         status: "reconnecting";
-        cause: "dropped" | "evicted" | "error";
+        cause: "dropped" | "evicted" | "error" | "unauthorized";
         attempt: number;
         nextRetryAt: number;
         lastError?: string;
@@ -202,33 +203,26 @@ export namespace StatewireClient {
         cause: "unmount" | "stream-gone" | "session-lost" | "superseded";
       };
 
-  /**
-   * A pending command offered for replay while the session is being evicted.
-   * Return "replay" to re-enqueue it under the rotated client id instead of
-   * settling it as a session-lost failure.
-   */
-  export type SessionLostCommand = {
-    method: string;
-    params: unknown[];
-    seq: number;
-  };
+  /** 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 & {
     url: string;
-    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    headers?: HeadersOption;
     fetch?: typeof globalThis.fetch;
     onChange?: (connection: Connection) => void;
-    onCommandSessionLost?: (command: SessionLostCommand) => "replay" | void;
   };
 
   export type WSOptions = StatewireSessionStoreOptions & {
     url: string;
+    headers?: HeadersOption;
     protocols?: string | string[];
     query?:
       | Record<string, string>
       | (() => Record<string, string> | Promise<Record<string, string>>);
     webSocket?: new (url: string, protocols?: string | string[]) => WebSocket;
     onChange?: (connection: Connection) => void;
-    onCommandSessionLost?: (command: SessionLostCommand) => "replay" | void;
   };
 }

package/src/transports/remote.ts

@@ -20,13 +20,7 @@ export const useStatewireRemote = <
   useLink: (options: TOptions, ctx: StatewireRemoteProps) => RemoteLink,
 ): Statewire<any, any, any> => {
   const emit = useStatewireEmit<any>();
-  const s = useStatewireSession(
-    {
-      sessionStore: options.sessionStore,
-      onCommandSessionLost: options.onCommandSessionLost,
-    },
-    emit,
-  );
+  const s = useStatewireSession({ sessionStore: options.sessionStore }, emit);
   const conn = useLink(options, s.ctx);
   useEffect(() => setTransport(s, conn), [s, conn]);
 

package/src/transports/sse.ts

@@ -72,13 +72,16 @@ export type RemoteLink = {
 const baseUrl = (options: StatewireClient.SSEOptions) =>
   options.url.replace(/\/$/, "");
 
+export type AuthState = { stale: boolean };
+
 const requestHeaders = async (
   options: StatewireClient.SSEOptions,
   extra: Record<string, string>,
+  ctx: { staleAuth: boolean },
 ) => {
   const { headers } = options;
   const merged = new Headers(
-    typeof headers === "function" ? await headers() : headers,
+    typeof headers === "function" ? await headers(ctx) : headers,
   );
   for (const [name, value] of Object.entries(extra)) merged.set(name, value);
   return merged;
@@ -131,12 +134,19 @@ const consume = async (
 const attemptStream = async (
   c: Conn,
   options: StatewireClient.SSEOptions,
+  auth: AuthState,
   abort: AbortController,
 ): Promise<"stop" | "reattach" | "ended"> => {
-  const headers = await requestHeaders(options, {
-    "Statewire-Client-Id": c.ctx.clientId,
-    accept: "text/event-stream",
-  });
+  const stale = auth.stale;
+  auth.stale = false;
+  const headers = await requestHeaders(
+    options,
+    {
+      "Statewire-Client-Id": c.ctx.clientId,
+      accept: "text/event-stream",
+    },
+    { staleAuth: stale },
+  );
   const heartbeat = new AbortController();
   const headerTimer = setTimeout(
     () => heartbeat.abort(),
@@ -158,6 +168,11 @@ const attemptStream = async (
     clearTimeout(headerTimer);
   }
   if (res.status === 429 || res.status === 503) throw overloaded(res);
+  if (res.status === 401) {
+    if (stale) c.episode = { cause: "unauthorized" };
+    auth.stale = true;
+    throw new Error("unauthorized");
+  }
   if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
   const reader = res.body.getReader();
   try {
@@ -170,23 +185,28 @@ const attemptStream = async (
 const overloaded = (res: Response) =>
   overloadedError(parseRetryAfter(res.headers.get("Retry-After")));
 
-const sendCommand = async (
+const postCommand = async (
   c: Conn,
   options: StatewireClient.SSEOptions,
   { seq, command }: { seq: number; command: StatewireWireCommand },
-): Promise<StatewireSubmitResult> => {
-  const timeout = AbortSignal.timeout(timing.heartbeatTimeoutMs);
-  const res = await timedFetch(
+  timeout: AbortSignal,
+  stale: boolean,
+): Promise<Response> =>
+  timedFetch(
     options,
     `${baseUrl(options)}/commands`,
     {
       method: "POST",
-      headers: await requestHeaders(options, {
-        "content-type": "application/json",
-        "Statewire-Client-Id": c.ctx.clientId,
-        "Statewire-Command-Seq": String(seq),
-        ...(c.lease !== null && { "Statewire-Lease": c.lease }),
-      }),
+      headers: await requestHeaders(
+        options,
+        {
+          "content-type": "application/json",
+          "Statewire-Client-Id": c.ctx.clientId,
+          "Statewire-Command-Seq": String(seq),
+          ...(c.lease !== null && { "Statewire-Lease": c.lease }),
+        },
+        { staleAuth: stale },
+      ),
       body: JSON.stringify(encodeWireCommand(command)),
       signal: AbortSignal.any([
         c.lifetime?.signal ?? AbortSignal.abort(),
@@ -195,6 +215,18 @@ const sendCommand = async (
     },
     timeout,
   );
+
+const sendCommand = async (
+  c: Conn,
+  options: StatewireClient.SSEOptions,
+  auth: AuthState,
+  args: { seq: number; command: StatewireWireCommand },
+): Promise<StatewireSubmitResult> => {
+  const timeout = AbortSignal.timeout(timing.heartbeatTimeoutMs);
+  let res = await postCommand(c, options, args, timeout, false);
+  if (res.status === 401 && typeof options.headers === "function") {
+    res = await postCommand(c, options, args, timeout, true);
+  }
   if (res.ok) {
     let body: { res?: StatewireResponse } | null;
     try {
@@ -209,24 +241,35 @@ const sendCommand = async (
       ? { type: "receipt", response: reviveResponse(body.res) }
       : { type: "receipt" };
   }
+  if (res.status === 429 || res.status === 503) throw overloaded(res);
+  if (res.status === 401) {
+    // Fresh credentials did not clear the 401: signal auth-failed on the
+    // connection and let the send retry as a transport fault.
+    auth.stale = true;
+    c.episode = { cause: "unauthorized" };
+    c.connection.reconnect();
+    throw new Error("unauthorized");
+  }
+  // Bodies settle, statuses pace: only a statewire-shaped body carries a
+  // verdict; any bare status is middleware noise — a transport fault, retried.
+  const body = (await res.json().catch(() => null)) as {
+    error?: string;
+    rejections?: { message?: string }[];
+  } | null;
+  if (body?.error === "rejected") {
+    return {
+      type: "rejected",
+      message: body.rejections?.[0]?.message ?? `HTTP ${res.status}`,
+    };
+  }
   if (res.status === 409 || res.status === 412 || res.status === 423) {
-    // Only a body naming the same verdict as the status is statewire's own;
-    // a bare status is middleware noise — a transport fault, retried.
     const verdict =
       res.status === 409
         ? ("seq-gap" as const)
         : res.status === 412
           ? ("unknown-client" as const)
           : ("stale-lease" as const);
-    const body = (await res.json().catch(() => null)) as {
-      error?: string;
-    } | null;
     if (body?.error === verdict) return { type: verdict };
-    throw new Error(`HTTP ${res.status}`);
-  }
-  if (res.status === 429 || res.status === 503) throw overloaded(res);
-  if (res.status >= 400 && res.status < 500) {
-    return { type: "rejected", message: `HTTP ${res.status}` };
   }
   throw new Error(`HTTP ${res.status}`);
 };
@@ -237,18 +280,19 @@ const useSseLink = (
 ): RemoteLink => {
   const latest = useRef(options);
   latest.current = options;
+  const [auth] = useState((): AuthState => ({ stale: false }));
   const c = useStatewireConn({
     url: options.url,
     onChange: options.onChange,
     ctx,
-    attemptOnce: (c, abort) => attemptStream(c, options, abort),
+    attemptOnce: (c, abort) => attemptStream(c, options, auth, abort),
   });
   const [link] = useState(
     (): RemoteLink => ({
       get connection() {
         return c.connection;
       },
-      send: (args) => sendCommand(c, latest.current, args),
+      send: (args) => sendCommand(c, latest.current, auth, args),
     }),
   );
   return link;

package/src/transports/ws.ts

@@ -29,11 +29,13 @@ type PendingCommand = {
 type WsChannel = {
   socket: WebSocket | null;
   pending: PendingCommand[];
+  authStale: boolean;
 };
 
 const OPEN = 1;
 
 export const WS_SUBPROTOCOL = "statewire.v1";
+export const UNAUTHORIZED_CLOSE = 4401;
 
 const socketUrl = async (
   options: StatewireClient.WSOptions,
@@ -48,6 +50,23 @@ const socketUrl = async (
   return `${base}/ws?${params.toString()}`;
 };
 
+const headersFrame = async (
+  options: StatewireClient.WSOptions,
+  stale: boolean,
+): Promise<string | null> => {
+  const { headers } = options;
+  if (headers === undefined) return null;
+  const resolved = new Headers(
+    typeof headers === "function"
+      ? await headers({ staleAuth: stale })
+      : headers,
+  );
+  return JSON.stringify({
+    type: "headers",
+    headers: Object.fromEntries(resolved),
+  });
+};
+
 const settleOverloaded = (
   w: WsChannel,
   { seq, retryAfterMs }: { seq?: number; retryAfterMs?: number },
@@ -81,6 +100,8 @@ const runSocket = (
   c: Conn,
   w: WsChannel,
   ws: WebSocket,
+  frame: string | null,
+  staleAuth: boolean,
   abort: AbortController,
 ): Promise<"stop" | "reattach"> =>
   new Promise((resolve, reject) => {
@@ -98,6 +119,7 @@ const runSocket = (
     arm();
     abort.signal.addEventListener("abort", () => ws.close());
     ws.onerror = () => {};
+    if (frame !== null) ws.onopen = () => ws.send(frame);
     const stale = () => Boolean(outcome) || closed || abort.signal.aborted;
     const fail = (error: unknown) => {
       clearTimeout(timer);
@@ -141,12 +163,16 @@ const runSocket = (
         fail(error);
       }
     };
-    ws.onclose = () => {
+    ws.onclose = (event?: { code?: number }) => {
       closed = true;
       clearTimeout(timer);
       if (w.socket === ws) failPending(w, new Error("network"));
       if (outcome) resolve(outcome);
-      else reject(new Error(timedOut ? "timeout" : "network"));
+      else if (event?.code === UNAUTHORIZED_CLOSE) {
+        if (staleAuth) c.episode = { cause: "unauthorized" };
+        w.authStale = true;
+        reject(new Error("unauthorized"));
+      } else reject(new Error(timedOut ? "timeout" : "network"));
     };
   });
 
@@ -159,6 +185,9 @@ const attemptSocket = async (
   let ws: WebSocket | null = null;
   try {
     const url = await socketUrl(options, c.ctx.clientId);
+    const stale = w.authStale;
+    w.authStale = false;
+    const frame = await headersFrame(options, stale);
     abort.signal.throwIfAborted();
     const { protocols, webSocket } = options;
     const WS = webSocket ?? globalThis.WebSocket;
@@ -171,7 +200,7 @@ const attemptSocket = async (
           : protocols;
     ws = new WS(url, [WS_SUBPROTOCOL, ...extra]);
     w.socket = ws;
-    return await runSocket(c, w, ws, abort);
+    return await runSocket(c, w, ws, frame, stale, abort);
   } finally {
     if (w.socket === ws) w.socket = null;
   }
@@ -219,7 +248,9 @@ const useWsLink = (
   options: StatewireClient.WSOptions,
   ctx: StatewireRemoteProps,
 ): RemoteLink => {
-  const [w] = useState((): WsChannel => ({ socket: null, pending: [] }));
+  const [w] = useState(
+    (): WsChannel => ({ socket: null, pending: [], authStale: false }),
+  );
   const c = useStatewireConn({
     url: options.url,
     onChange: options.onChange,