statewire 0.8.1 → 0.9.0

package/src/transports/ws.ts

@@ -2,40 +2,32 @@ import { useState } from "react";
 import { flushTapSync, resource } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
 import { timing } from "../client/timing";
-import {
-  handleEnvelope,
-  overloadedError,
-  useStatewireConn,
+import { handleEnvelope, useStatewireConn } from "../client/connection";
+import type {
+  AttemptOutcome,
+  Conn,
+  StatewireEnvelope,
 } from "../client/connection";
-import type { Conn, StatewireEnvelope } from "../client/connection";
 import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
 import { useStatewireRemote } from "./remote";
 import { CLIENT_QUERY_PARAM } from "../host/adapter";
-import { encodeWireCommand } from "./sse";
 import type {
   RemoteLink,
+  StatewireFrame,
   StatewireSubmitResult,
   StatewireRemoteProps,
-  StatewireWireCommand,
 } from "./sse";
 
-type PendingCommand = {
-  seq: number;
-  resolve: (result: StatewireSubmitResult) => void;
-  reject: (error: Error) => void;
-};
-
 type WsChannel = {
   socket: WebSocket | null;
-  pending: PendingCommand[];
   authStale: boolean;
 };
 
 const OPEN = 1;
 
 export const WS_SUBPROTOCOL = "statewire.v1";
-export const UNAUTHORIZED_CLOSE = 4401;
+const UNAUTHORIZED_CLOSE = 4401;
 
 const socketUrl = async (
   options: StatewireClient.WSOptions,
@@ -50,64 +42,35 @@ const socketUrl = async (
   return `${base}/ws?${params.toString()}`;
 };
 
-const headersFrame = async (
+const firstFrame = async (
   options: StatewireClient.WSOptions,
   stale: boolean,
-): Promise<string | null> => {
+  lanes: StatewireFrame | null,
+): Promise<string> => {
   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),
+    ...(lanes ?? {}),
   });
 };
 
-const settleOverloaded = (
-  w: WsChannel,
-  { seq, retryAfterMs }: { seq?: number; retryAfterMs?: number },
-) => {
-  if (seq === undefined) throw overloadedError(retryAfterMs);
-  const entry = w.pending.find((p) => p.seq === seq);
-  if (!entry) return;
-  w.pending = w.pending.filter((p) => p !== entry);
-  entry.reject(overloadedError(retryAfterMs));
-};
-
-const resolvePending = (
-  w: WsChannel,
-  matches: (entry: PendingCommand) => boolean,
-) => {
-  const remaining: PendingCommand[] = [];
-  for (const entry of w.pending) {
-    if (matches(entry)) entry.resolve({ type: "receipt" });
-    else remaining.push(entry);
-  }
-  w.pending = remaining;
-};
-
-const failPending = (w: WsChannel, error: Error) => {
-  const pending = w.pending;
-  w.pending = [];
-  for (const entry of pending) entry.reject(error);
-};
-
 const runSocket = (
   c: Conn,
   w: WsChannel,
   ws: WebSocket,
-  frame: string | null,
+  frame: string,
   staleAuth: boolean,
   abort: AbortController,
-): Promise<"stop" | "reattach"> =>
+): Promise<AttemptOutcome> =>
   new Promise((resolve, reject) => {
     let timer: ReturnType<typeof setTimeout> | undefined;
     let timedOut = false;
-    let outcome: "stop" | "reattach" | null = null;
+    let outcome: AttemptOutcome | null = null;
     let closed = false;
     const arm = () => {
       clearTimeout(timer);
@@ -119,45 +82,36 @@ const runSocket = (
     arm();
     abort.signal.addEventListener("abort", () => ws.close());
     ws.onerror = () => {};
-    if (frame !== null) ws.onopen = () => ws.send(frame);
+    ws.onopen = () => ws.send(frame);
     const stale = () => Boolean(outcome) || closed || abort.signal.aborted;
     const fail = (error: unknown) => {
       clearTimeout(timer);
       reject(error instanceof Error ? error : new Error("protocol"));
       ws.close();
     };
-    const processEnv = (env: StatewireEnvelope) => {
-      const done = flushTapSync(() => handleEnvelope(c, env));
-      if (env.ack !== undefined) {
-        const ack = env.ack;
-        resolvePending(w, (entry) => entry.seq <= ack);
-      }
-      if (env.res !== undefined) {
-        const seqs = new Set(env.res.map((r) => r.seq));
-        resolvePending(w, (entry) => seqs.has(entry.seq));
-      }
-      if (done) {
-        outcome = done;
-        ws.close();
-      }
-    };
     ws.onmessage = (event) => {
       if (stale()) return;
       arm();
-      let frame: StatewireEnvelope & {
-        overloaded?: { seq?: number; retryAfterMs?: number };
-      };
+      let env: StatewireEnvelope;
       try {
-        frame = JSON.parse(String(event.data)) as typeof frame;
+        env = JSON.parse(String(event.data)) as StatewireEnvelope;
       } catch {
         fail(new Error("protocol"));
         return;
       }
+      // {} heartbeats live below the packet layer: invisible to handlers.
+      if (
+        typeof env === "object" &&
+        env !== null &&
+        Object.keys(env).length === 0
+      ) {
+        return;
+      }
       try {
-        if (frame.overloaded !== undefined) {
-          settleOverloaded(w, frame.overloaded);
-        } else {
-          processEnv(frame);
+        const done = flushTapSync(() => handleEnvelope(c, env));
+        if (done) {
+          outcome = done;
+          ws.close();
         }
       } catch (error) {
         fail(error);
@@ -166,7 +120,6 @@ const runSocket = (
     ws.onclose = (event?: { code?: number }) => {
       closed = true;
       clearTimeout(timer);
-      if (w.socket === ws) failPending(w, new Error("network"));
       if (outcome) resolve(outcome);
       else if (event?.code === UNAUTHORIZED_CLOSE) {
         if (staleAuth) c.episode = { cause: "unauthorized" };
@@ -181,13 +134,14 @@ const attemptSocket = async (
   w: WsChannel,
   options: StatewireClient.WSOptions,
   abort: AbortController,
-): Promise<"stop" | "reattach"> => {
+): Promise<AttemptOutcome> => {
   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);
+    const lanes = flushTapSync(() => c.ctx.takeAttachLanes());
+    const frame = await firstFrame(options, stale, lanes);
     abort.signal.throwIfAborted();
     const { protocols, webSocket } = options;
     const WS = webSocket ?? globalThis.WebSocket;
@@ -206,51 +160,27 @@ const attemptSocket = async (
   }
 };
 
-const sendCommand = (
+const sendFrame = (
   w: WsChannel,
-  { seq, command }: { seq: number; command: StatewireWireCommand },
+  frame: StatewireFrame,
 ): Promise<StatewireSubmitResult> => {
   const ws = w.socket;
   if (!ws || ws.readyState !== OPEN) {
     return Promise.reject(new Error("network"));
   }
-  return new Promise((resolve, reject) => {
-    const entry: PendingCommand = {
-      seq,
-      resolve: (result) => {
-        clearTimeout(timer);
-        resolve(result);
-      },
-      reject: (error) => {
-        clearTimeout(timer);
-        reject(error);
-      },
-    };
-    // A timed-out command fails the socket: the retry then rides reconnect +
-    // attach-seq arbitration.
-    const timer = setTimeout(() => {
-      w.pending = w.pending.filter((p) => p !== entry);
-      reject(new Error("timeout"));
-      ws.close();
-    }, timing.heartbeatTimeoutMs);
-    w.pending.push(entry);
-    try {
-      ws.send(JSON.stringify({ ...encodeWireCommand(command), seq }));
-    } catch {
-      clearTimeout(timer);
-      w.pending = w.pending.filter((p) => p !== entry);
-      reject(new Error("network"));
-    }
-  });
+  try {
+    ws.send(JSON.stringify(frame));
+  } catch {
+    return Promise.reject(new Error("network"));
+  }
+  return Promise.resolve({ type: "ok" });
 };
 
 const useWsLink = (
   options: StatewireClient.WSOptions,
   ctx: StatewireRemoteProps,
 ): RemoteLink => {
-  const [w] = useState(
-    (): WsChannel => ({ socket: null, pending: [], authStale: false }),
-  );
+  const [w] = useState((): WsChannel => ({ socket: null, authStale: false }));
   const c = useStatewireConn({
     url: options.url,
     onChange: options.onChange,
@@ -262,7 +192,7 @@ const useWsLink = (
       get connection() {
         return c.connection;
       },
-      send: (args) => sendCommand(w, args),
+      send: (frame) => sendFrame(w, frame),
     }),
   );
   return link;
@@ -270,12 +200,11 @@ const useWsLink = (
 
 const useStatewireWS = (
   options: StatewireClient.WSOptions,
-): Statewire<any, any, any> => useStatewireRemote(options, useWsLink);
+): Statewire<any, any> => useStatewireRemote(options, useWsLink);
 
 export const StatewireWS = resource(useStatewireWS) as <
   TState = any,
   TCommands extends Statewire.Commands = Statewire.Commands,
-  TEvent = any,
 >(
   options: StatewireClient.WSOptions,
-) => ResourceElement<Statewire<TState | undefined, TCommands, TEvent>>;
+) => ResourceElement<Statewire<TState | undefined, TCommands>>;

package/src/types.ts

@@ -19,7 +19,7 @@ export namespace Statewire {
       method: K;
       params: Parameters<TCommands[K]>;
       seq: number;
-      status: "queued" | "posted" | "acked" | "settled";
+      status: "queued" | "posted" | "applied" | "settled";
       result?: unknown;
       failure?: StatewireClient.SendFailure;
     };
@@ -37,8 +37,7 @@ export namespace Statewire {
   export type Op =
     | { op: "replace"; path: StatewirePath; value: unknown }
     | { op: "add"; path: StatewirePath; value: unknown }
-    | { op: "remove"; path: StatewirePath }
-    | { op: "event"; value: object };
+    | { op: "remove"; path: StatewirePath };
 
   export type Changes = {
     isChangedAt(path: readonly (string | number)[]): boolean;
@@ -49,33 +48,35 @@ export namespace Statewire {
 export interface Statewire<
   TState = any,
   TCommands extends Statewire.Commands = Statewire.Commands,
-  TEvent = any,
 > {
   state: TState;
   commands: Statewire.CommandsProxy<TCommands>;
-  emit?: (event: TEvent) => void;
   connection?: StatewireClient.Connection;
   source?: Statewire.StateSource;
-  /** Replace this client's ambient context on the server; absent on transports without a client context channel. */
-  setContext?: (value: Record<string, unknown>) => Promise<unknown>;
+  /** Highest command seq released from the resend queue by the server's dur flag. */
+  durableSeq?: number;
+  /** Negation of the server's broadcast idle level; absent means always busy. */
+  isBusy?: boolean;
+  /** Replace this client's ambient context on the server; it rides the ctx lane (no verdict). */
+  setContext?: (value: Record<string, unknown>) => void;
 }
 
 const describe = (failure: StatewireClient.SendFailure): string => {
   switch (failure.fate) {
     case "rejected":
-      return `statewire: command rejected: ${failure.message}`;
-    case "unknown-command":
-      return "statewire: unknown command";
-    case "invalid-params":
-      return `statewire: invalid params: ${failure.message}`;
+      return `statewire: command rejected${failure.code ? ` (${failure.code})` : ""}${failure.message ? `: ${failure.message}` : ""}`;
     case "aborted":
       return `statewire: command aborted (${failure.cause})`;
     case "lost":
       return `statewire: command lost (${failure.cause})`;
+    case "failed":
+      return failure.message
+        ? `statewire: command failed: ${failure.message}`
+        : "statewire: command failed";
     case "crashed":
       return "statewire: command crashed";
-    case "result-unavailable":
-      return `statewire: command result unavailable (${failure.cause})`;
+    case "expired":
+      return `statewire: command result expired (${failure.cause})`;
   }
 };
 

package/src/wire/ops.ts

@@ -61,14 +61,12 @@ const sanitizeAt = (
 export const sanitizeValue = (value: unknown, parent?: string): unknown =>
   sanitizeAt(value, parent, parent === undefined ? [] : [parent]);
 
-type MutableOp = Extract<Statewire.Op, { op: "replace" | "add" | "remove" }>;
-
-const invalid = (op: MutableOp) =>
+const invalid = (op: Statewire.Op) =>
   new Error(`Statewire cannot apply ${op.op} at path: ${op.path.join(".")}`);
 
 const insertedText = (
   current: string,
-  op: Extract<MutableOp, { op: "add" }>,
+  op: Extract<Statewire.Op, { op: "add" }>,
   offset: number,
 ): string => {
   if (typeof op.value !== "string" || offset > current.length) {
@@ -79,7 +77,7 @@ const insertedText = (
 
 const applyAdd = (
   box: { state: unknown },
-  op: Extract<MutableOp, { op: "add" }>,
+  op: Extract<Statewire.Op, { op: "add" }>,
 ) => {
   const offset = op.path[op.path.length - 1];
   const walked = walkStatePath(box.state, op.path.slice(0, -1), "resolve");
@@ -107,7 +105,7 @@ const applyAdd = (
   }
 };
 
-const applyInList = (list: unknown[], index: number, op: MutableOp) => {
+const applyInList = (list: unknown[], index: number, op: Statewire.Op) => {
   if (index >= list.length) throw invalid(op);
   if (op.op === "replace") {
     list[index] = sanitizeValue(op.value);
@@ -119,7 +117,7 @@ const applyInList = (list: unknown[], index: number, op: MutableOp) => {
 const applyInObject = (
   obj: Record<string, unknown>,
   key: string,
-  op: MutableOp,
+  op: Statewire.Op,
 ) => {
   if (op.op === "replace") {
     obj[key] = sanitizeValue(op.value, key);
@@ -129,7 +127,7 @@ const applyInObject = (
   }
 };
 
-const applyOpToDraft = (box: { state: unknown }, op: MutableOp): void => {
+const applyOpToDraft = (box: { state: unknown }, op: Statewire.Op): void => {
   if (op.op === "add") {
     if (op.path.length === 0) throw invalid(op);
     applyAdd(box, op);
@@ -161,7 +159,7 @@ const unboxPaths = (paths: readonly StatewirePath[]): StatewirePath[] =>
 
 export const applyOp = (
   root: unknown,
-  op: MutableOp,
+  op: Statewire.Op,
 ): { state: unknown; changedPaths: StatewirePath[] } => {
   const recorded = recordMutations({ state: root }, (draft) =>
     applyOpToDraft(draft, op),
@@ -177,15 +175,11 @@ export const applyOps = (
   ops: readonly unknown[],
 ): {
   state: unknown;
-  events: unknown[];
   changedPaths: StatewirePath[];
 } => {
-  const events: unknown[] = [];
-  const mutable: MutableOp[] = [];
+  const mutable: Statewire.Op[] = [];
   for (const op of ops as Statewire.Op[]) {
-    if (op.op === "event") {
-      events.push(sanitizeValue(op.value));
-    } else if (op.op === "replace" || op.op === "add" || op.op === "remove") {
+    if (op.op === "replace" || op.op === "add" || op.op === "remove") {
       mutable.push(op);
     } else {
       warnUnknownOp((op as { op: unknown }).op);
@@ -196,7 +190,6 @@ export const applyOps = (
   });
   return {
     state: recorded.state.state,
-    events,
     changedPaths: unboxPaths(recorded.changedPaths),
   };
 };