statewire 0.0.5 → 0.5.0

package/src/host/host.ts

@@ -102,82 +102,10 @@ export const useStatewireState = <TState>(
 
 // ─── commands ───────────────────────────────────────────
 
-type ExecutionSettled =
+type Settled =
   | { type: "resolved"; value: unknown }
   | { type: "rejected"; error: unknown };
 
-type ExecutionBind = {
-  onAck: () => void;
-  onSettle: (settled: ExecutionSettled) => void;
-};
-
-type ExecutionState = {
-  acked: boolean;
-  settled: ExecutionSettled | null;
-  bind: ExecutionBind | null;
-};
-
-const executionStates = new WeakMap<object, ExecutionState>();
-
-/**
- * `CommandExecution(executor)` runs the (possibly async) `executor({ ack })`
- * immediately: its return value resolves the execution, a throw/rejection
- * rejects it; `ack()` releases the client's ack watermark before the executor
- * finishes. `CommandExecution.withResolvers()` returns `[execution,
- * { ack, resolve, reject }]` instead — settle them from your own spawned work.
- */
-export const CommandExecution = Object.assign(
-  <T = void>(
-    executor: (resolvers: {
-      ack: () => void;
-    }) => T | void | PromiseLike<T | void>,
-  ): StatewireHost.Execution<T> => {
-    const state: ExecutionState = { acked: false, settled: null, bind: null };
-    const execution = Object.freeze(
-      {},
-    ) as unknown as StatewireHost.Execution<T>;
-    executionStates.set(execution, state);
-    const settle = (settled: ExecutionSettled) => {
-      if (state.settled) return;
-      state.settled = settled;
-      state.acked = true;
-      state.bind?.onSettle(settled);
-    };
-    const ack = () => {
-      if (state.acked) return;
-      state.acked = true;
-      state.bind?.onAck();
-    };
-    void (async () => {
-      try {
-        settle({ type: "resolved", value: await executor({ ack }) });
-      } catch (error) {
-        settle({ type: "rejected", error });
-      }
-    })();
-    return execution;
-  },
-  {
-    withResolvers: <T = void>(): [
-      StatewireHost.Execution<T>,
-      StatewireHost.ExecutionResolvers<T>,
-    ] => {
-      let resolve!: (value: T) => void;
-      let reject!: (error: unknown) => void;
-      const promise = new Promise<T>((res, rej) => {
-        resolve = res;
-        reject = rej;
-      });
-      let ack!: () => void;
-      const execution = CommandExecution<T>(({ ack: a }) => {
-        ack = a;
-        return promise;
-      });
-      return [execution, { ack: () => ack(), resolve, reject }];
-    },
-  },
-);
-
 export type CommandsInvocation = {
   readonly method: string;
   readonly params: readonly unknown[];
@@ -279,7 +207,7 @@ const settleInvocation = (
   cell: CommandsCell,
   inv: ActiveInvocation,
   call: QueuedCall,
-  settled: ExecutionSettled,
+  settled: Settled,
 ) => {
   ackInvocation(cell, inv);
   if (settled.type === "resolved") {
@@ -299,14 +227,13 @@ const settleInvocation = (
   }
 };
 
-const pump = (cell: CommandsCell) => {
-  if (cell.running || !cell.handlers) {
-    watchStall(cell);
-    return;
-  }
-  const call = cell.queue.shift();
-  if (!call) return;
-  const handler = cell.handlers[call.method];
+const isThenable = (value: unknown): value is PromiseLike<unknown> =>
+  typeof value === "object" &&
+  value !== null &&
+  typeof (value as { then?: unknown }).then === "function";
+
+const dispatch = (cell: CommandsCell, call: QueuedCall) => {
+  const handler = cell.handlers![call.method];
   if (handler === undefined) {
     const error = new StatewireSendError({
       fate: "unknown-command",
@@ -314,7 +241,6 @@ const pump = (cell: CommandsCell) => {
     });
     call.origin?.onSettle?.({ type: "rejected", error });
     call.reject(error);
-    pump(cell);
     return;
   }
   const inv: ActiveInvocation = {
@@ -328,39 +254,55 @@ const pump = (cell: CommandsCell) => {
       clientId: call.origin.clientId,
     }),
   };
-  cell.running = true;
   cell.listener?.onStart(inv);
   cell.listener?.onPosted?.(inv);
   cell.listener?.onCovered?.(inv);
-  void (async () => {
-    try {
-      const value = await (
-        handler as (...args: readonly unknown[]) => unknown
-      ).call(call.origin?.caller ?? LOCAL_CALLER, ...call.params);
-      const execution =
-        typeof value === "object" && value !== null
-          ? executionStates.get(value)
-          : undefined;
-      if (execution) {
-        if (execution.acked) ackInvocation(cell, inv);
-        if (execution.settled) {
-          settleInvocation(cell, inv, call, execution.settled);
-        } else {
-          execution.bind = {
-            onAck: () => ackInvocation(cell, inv),
-            onSettle: (settled) => settleInvocation(cell, inv, call, settled),
-          };
-        }
-      } else {
-        settleInvocation(cell, inv, call, { type: "resolved", value });
-      }
-    } catch (error) {
-      settleInvocation(cell, inv, call, { type: "rejected", error });
-    } finally {
-      cell.running = false;
-      pump(cell);
+  const ctx: StatewireHost.Ctx = {
+    caller: call.origin?.caller ?? LOCAL_CALLER,
+    ack: () => ackInvocation(cell, inv),
+  };
+  try {
+    const value = (
+      handler as (
+        this: StatewireHost.Ctx,
+        ...args: readonly unknown[]
+      ) => unknown
+    ).call(ctx, ...call.params);
+    if (isThenable(value)) {
+      value.then(
+        (resolved) =>
+          settleInvocation(cell, inv, call, {
+            type: "resolved",
+            value: resolved,
+          }),
+        (error: unknown) =>
+          settleInvocation(cell, inv, call, { type: "rejected", error }),
+      );
+    } else {
+      settleInvocation(cell, inv, call, { type: "resolved", value });
     }
-  })();
+  } catch (error) {
+    settleInvocation(cell, inv, call, { type: "rejected", error });
+  }
+};
+
+// Prefix-only advancement: each handler runs synchronously to its first
+// await, then the pump moves on; settlement rides the returned promise.
+const pump = (cell: CommandsCell) => {
+  if (cell.running || !cell.handlers) {
+    watchStall(cell);
+    return;
+  }
+  cell.running = true;
+  try {
+    while (cell.handlers) {
+      const call = cell.queue.shift();
+      if (!call) break;
+      dispatch(cell, call);
+    }
+  } finally {
+    cell.running = false;
+  }
 };
 
 const watchStall = (cell: CommandsCell) => {
@@ -378,7 +320,7 @@ const watchStall = (cell: CommandsCell) => {
 
 export const useStatewireCommands = <THandlers extends Statewire.Commands>(
   commands:
-    | (THandlers & ThisType<StatewireHost.Caller>)
+    | (THandlers & ThisType<StatewireHost.Ctx>)
     | undefined
     | null
     | false,

package/src/host.ts

@@ -4,17 +4,12 @@ import type { ServerOp } from "./host/draft";
 export { StatewireReject } from "./host/engine";
 export { append } from "./host/draft";
 export {
-  CommandExecution,
   getStateHost,
   useStatewireState,
   useStatewireCommands,
   useStatewireEmit,
 } from "./host/host";
 
-declare const executionResult: unique symbol;
-
-type UnwrapExecution<V> = V extends StatewireHost.Execution<infer T> ? T : V;
-
 export namespace StatewireHost {
   export type StateCtl<TState = unknown> = {
     /** Apply server-vocabulary ops (root replace = whole-state swap). */
@@ -31,23 +26,18 @@ export namespace StatewireHost {
   export type StateSource = Statewire.StateSource;
 
   /**
-   * Handle a command handler returns to keep the command open past its own
-   * return: `ack()` releases the client's optimistic overlay / ack watermark,
-   * `resolve`/`reject` settle the command (and imply ack). `ack` is idempotent
-   * and a no-op after settle.
+   * Per-invocation handle bound as `this` of a command handler: `caller` is
+   * the submitting client, `ack()` releases the client's optimistic overlay /
+   * ack watermark before the handler settles (idempotent, a no-op after
+   * settle). The command settles when the handler's returned promise does.
    */
-  export type Execution<T = void> = {
-    readonly [executionResult]: (value: T) => void;
-  };
-
-  export type ExecutionResolvers<T = void> = {
-    ack: () => void;
-    resolve: (value: T) => void;
-    reject: (error: unknown) => void;
+  export type Ctx = {
+    readonly caller: Caller;
+    readonly ack: () => void;
   };
 
   /**
-   * The submitting client, bound as `this` of a command handler. Holdable
+   * The submitting client (`this.caller` in a command handler). Holdable
    * across a long run: `clientId` is the client's `Statewire-Client-Id`
    * (in-process dispatch has none — reading it throws), `context` reads the
    * client's current ambient context live (null until the client sends one),
@@ -62,7 +52,7 @@ export namespace StatewireHost {
   export type HandledCommands<THandlers extends Statewire.Commands> = {
     [K in keyof THandlers]: (
       ...args: Parameters<THandlers[K]>
-    ) => UnwrapExecution<Awaited<ReturnType<THandlers[K]>>>;
+    ) => Awaited<ReturnType<THandlers[K]>>;
   };
 
   export type Fin = {

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,