statewire 0.0.0-0 → 0.0.1

package/src/transports/ws.ts

@@ -0,0 +1,272 @@
+import { flushTapSync, resource } from "@assistant-ui/tap";
+import type { ResourceElement } from "@assistant-ui/tap";
+import { encodeParams } from "../wire/meta";
+import { timing } from "../client/timing";
+import {
+  createGate,
+  handleEnvelope,
+  overloadedError,
+  reconnectConn,
+} from "../client/connection";
+import type { ConnBase, StatewireEnvelope } from "../client/connection";
+import type { StatewireTransport } from "../types";
+import { useStatewireRemote } from "./remote";
+import type { StatewireSessionStore } from "../client/sessionStore";
+import type { StatewireCommands } from "../types";
+import type {
+  RemoteLink,
+  StatewireSubmitResult,
+  StatewireConnection,
+  StatewireTransportProps,
+  StatewireWireCommand,
+} from "./sse";
+
+export type StatewireWSOptions = {
+  url: string;
+  protocols?: string | string[];
+  query?:
+    | Record<string, string>
+    | (() => Record<string, string> | Promise<Record<string, string>>);
+  webSocket?: new (url: string, protocols?: string | string[]) => WebSocket;
+  onChange?: (connection: StatewireConnection) => void;
+  sessionStore?: StatewireSessionStore;
+};
+
+type Latest = {
+  options: StatewireWSOptions;
+  ctx: StatewireTransportProps;
+};
+
+type PendingCommand = {
+  seq: number;
+  resolve: (result: StatewireSubmitResult) => void;
+  reject: (error: Error) => void;
+};
+
+type Conn = ConnBase & {
+  socket: WebSocket | null;
+  pending: PendingCommand[];
+  latest: { readonly current: Latest };
+  send: RemoteLink["send"];
+};
+
+const OPEN = 1;
+
+export const WS_SUBPROTOCOL = "statewire.v1";
+
+const createConn = (
+  latest: { readonly current: Latest },
+  notify: (connection: StatewireConnection) => void,
+): Conn => {
+  const c: Conn = {
+    hasSnapshot: false,
+    lease: null,
+    attempt: 0,
+    episode: null,
+    abort: null,
+    socket: null,
+    pending: [],
+    gate: createGate(),
+    lifetime: null,
+    latest,
+    notify,
+    reconnect: () => reconnectConn(c),
+    attemptOnce: (abort) => attemptSocket(c, abort),
+    send: (args) => sendCommand(c, args),
+    connection: { status: "connecting", reconnect: () => c.reconnect() },
+  };
+  return c;
+};
+
+const socketUrl = async (c: Conn) => {
+  const { url, query } = c.latest.current.options;
+  const params = new URLSearchParams(
+    typeof query === "function" ? await query() : query,
+  );
+  params.set("client", c.latest.current.ctx.clientId);
+  const base = url.replace(/\/$/, "").replace(/^http/, "ws");
+  return `${base}/ws?${params.toString()}`;
+};
+
+const settleOverloaded = (
+  c: Conn,
+  { seq, retryAfterMs }: { seq?: number; retryAfterMs?: number },
+) => {
+  if (seq === undefined) throw overloadedError(retryAfterMs);
+  const entry = c.pending.find((p) => p.seq === seq);
+  if (!entry) return;
+  c.pending = c.pending.filter((p) => p !== entry);
+  entry.reject(overloadedError(retryAfterMs));
+};
+
+const resolveReceipts = (c: Conn, ack: number) => {
+  while (c.pending[0] && c.pending[0].seq <= ack) {
+    c.pending.shift()!.resolve({ type: "receipt" });
+  }
+};
+
+const resolveResponded = (c: Conn, seqs: Set<number>) => {
+  const remaining: PendingCommand[] = [];
+  for (const entry of c.pending) {
+    if (seqs.has(entry.seq)) entry.resolve({ type: "receipt" });
+    else remaining.push(entry);
+  }
+  c.pending = remaining;
+};
+
+const failPending = (c: Conn, error: Error) => {
+  const pending = c.pending;
+  c.pending = [];
+  for (const entry of pending) entry.reject(error);
+};
+
+const runSocket = (
+  c: Conn,
+  ws: WebSocket,
+  abort: AbortController,
+): Promise<"stop" | "reattach"> =>
+  new Promise((resolve, reject) => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let timedOut = false;
+    let outcome: "stop" | "reattach" | null = null;
+    let closed = false;
+    let attached = false;
+    const arm = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        timedOut = true;
+        ws.close();
+      }, timing.heartbeatTimeoutMs);
+    };
+    arm();
+    abort.signal.addEventListener("abort", () => ws.close());
+    ws.onerror = () => {};
+    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, attached));
+      attached = true;
+      if (env.ack !== undefined) resolveReceipts(c, env.ack);
+      if (env.res !== undefined) {
+        resolveResponded(c, new Set(env.res.map((r) => r.seq)));
+      }
+      if (done) {
+        outcome = done;
+        ws.close();
+      }
+    };
+    ws.onmessage = (event) => {
+      if (stale()) return;
+      arm();
+      let frame: StatewireEnvelope & {
+        overloaded?: { seq?: number; retryAfterMs?: number };
+      };
+      try {
+        frame = JSON.parse(String(event.data)) as typeof frame;
+      } catch {
+        fail(new Error("protocol"));
+        return;
+      }
+      try {
+        if (frame.overloaded !== undefined) {
+          settleOverloaded(c, frame.overloaded);
+        } else {
+          processEnv(frame);
+        }
+      } catch (error) {
+        fail(error);
+      }
+    };
+    ws.onclose = () => {
+      closed = true;
+      clearTimeout(timer);
+      if (c.socket === ws) failPending(c, new Error("network"));
+      if (outcome) resolve(outcome);
+      else reject(new Error(timedOut ? "timeout" : "network"));
+    };
+  });
+
+const attemptSocket = async (
+  c: Conn,
+  abort: AbortController,
+): Promise<"stop" | "reattach"> => {
+  let ws: WebSocket | null = null;
+  try {
+    const url = await socketUrl(c);
+    abort.signal.throwIfAborted();
+    const { protocols, webSocket } = c.latest.current.options;
+    const WS = webSocket ?? globalThis.WebSocket;
+    if (!WS) throw new Error("no WebSocket implementation");
+    const extra =
+      protocols === undefined
+        ? []
+        : typeof protocols === "string"
+          ? [protocols]
+          : protocols;
+    ws = new WS(url, [WS_SUBPROTOCOL, ...extra]);
+    c.socket = ws;
+    return await runSocket(c, ws, abort);
+  } finally {
+    if (c.socket === ws) c.socket = null;
+  }
+};
+
+const sendCommand = (
+  c: Conn,
+  { seq, command }: { seq: number; command: StatewireWireCommand },
+): Promise<StatewireSubmitResult> => {
+  const ws = c.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(() => {
+      c.pending = c.pending.filter((p) => p !== entry);
+      reject(new Error("timeout"));
+      ws.close();
+    }, timing.heartbeatTimeoutMs);
+    c.pending.push(entry);
+    try {
+      ws.send(
+        JSON.stringify({
+          method: command.method,
+          ...encodeParams(command.params),
+          seq,
+        }),
+      );
+    } catch {
+      clearTimeout(timer);
+      c.pending = c.pending.filter((p) => p !== entry);
+      reject(new Error("network"));
+    }
+  });
+};
+
+const useStatewireWS = (
+  options: StatewireWSOptions,
+): StatewireTransport<any, any, any> => useStatewireRemote(options, createConn);
+
+export const StatewireWS = resource(useStatewireWS) as <
+  TState = any,
+  TCommands extends StatewireCommands = StatewireCommands,
+  TEvent = any,
+>(
+  options: StatewireWSOptions,
+) => ResourceElement<StatewireTransport<TState | undefined, TCommands, TEvent>>;

package/src/types.ts

@@ -0,0 +1,169 @@
+import type { ResourceElement } from "@assistant-ui/tap";
+import type { StatewireConnection } from "./transports/sse";
+import type { StatewirePath } from "./wire/ops";
+
+export type StatewireCommands = Record<string, (...args: never[]) => unknown>;
+
+/** Push-based canonical state feed a transport hands to the client core. */
+export type StatewireStateSource = {
+  root: () => unknown;
+  /** Drain the paths changed since the last take (`[]` entry = whole state). */
+  takeChanged: () => StatewirePath[];
+  /** Synchronous, per change; the consumer owns coalescing. */
+  setOnChange: (listener: (() => void) | null) => void;
+};
+
+export type StatewireTransport<
+  TState,
+  TCommands extends StatewireCommands = StatewireCommands,
+  TEvent = any,
+> = {
+  state: TState;
+  commands: StatewireCommandsProxy<TCommands>;
+  emit: (event: TEvent) => void;
+  connection?: StatewireConnection;
+  source?: StatewireStateSource;
+};
+
+export type StatewireCommand<
+  TCommands extends StatewireCommands = StatewireCommands,
+> = {
+  [K in keyof TCommands]: { method: K; params: Parameters<TCommands[K]> };
+}[keyof TCommands];
+
+export type StatewireCommandsProxy<TCommands extends StatewireCommands> = {
+  [K in keyof TCommands]: (
+    ...args: Parameters<TCommands[K]>
+  ) => Promise<Awaited<ReturnType<TCommands[K]>>>;
+};
+
+export type StatewireCommandUpdate<
+  TCommands extends StatewireCommands = StatewireCommands,
+> = {
+  [K in keyof TCommands]: {
+    method: K;
+    params: Parameters<TCommands[K]>;
+    seq: number;
+    status: "queued" | "posted" | "acked" | "settled";
+    result?: unknown;
+    failure?: SendFailure;
+  };
+}[keyof TCommands];
+
+export type StatewireOptimisticContext = {
+  ts: number;
+  seq: number;
+  clientId?: string;
+};
+
+/**
+ * Mutate the draft in place; the client records the next state plus the exact
+ * changed paths. Re-run against the new base on every rebase.
+ */
+export type StatewireOptimistic<
+  TState,
+  TCommands extends StatewireCommands = StatewireCommands,
+> = (
+  draft: TState,
+  command: StatewireCommand<TCommands>,
+  ctx: StatewireOptimisticContext,
+) => void;
+
+export type StatewireChanges = {
+  isChangedAt(path: readonly (string | number)[]): boolean;
+  getChangedKeys(path: readonly (string | number)[]): string[];
+};
+
+export type StatewireOptions<
+  TState,
+  TCommands extends StatewireCommands = StatewireCommands,
+  TEvent = any,
+> = {
+  transport: ResourceElement<StatewireTransport<TState, TCommands, TEvent>>;
+  optimistic?: StatewireOptimistic<NonNullable<TState>, TCommands>;
+  onEvent?: (event: TEvent, ctx: { state: NonNullable<TState> }) => void;
+  onStateChange?: (
+    state: NonNullable<TState>,
+    ctx: { changes: StatewireChanges },
+  ) => void;
+  onCommandChange?: (
+    update: StatewireCommandUpdate<TCommands>,
+    ctx: { state: NonNullable<TState> },
+  ) => void;
+};
+
+export type StatewireHelpers<
+  TState,
+  TCommands extends StatewireCommands = StatewireCommands,
+> = {
+  /** The transport's state type — remote transports include `undefined` until the first attach snapshot applies. */
+  state: TState;
+  connection: StatewireConnection;
+  commands: StatewireCommandsProxy<TCommands>;
+};
+
+/**
+ * fate: "aborted" = never sent, "rejected" = the handler refused,
+ * "unknown-command" = no such command, "invalid-params" = the args did not
+ * match the command's schema, "lost" = sent but never covered by an ack,
+ * "crashed" = acked but the processing died, "result-unavailable" = acked
+ * but the result is gone.
+ * cause is which channel settled it: "server" = the server's answer;
+ * the rest are channel deaths the client settled locally.
+ */
+export type SendFailure =
+  | { fate: "rejected"; cause: "server"; message: string; payload?: unknown }
+  | { fate: "unknown-command"; cause: "server" }
+  | { fate: "invalid-params"; cause: "server"; message: string }
+  | { fate: "crashed"; cause: "server" }
+  | {
+      fate: "result-unavailable";
+      cause:
+        | "server"
+        | "unmount"
+        | "stream-gone"
+        | "session-lost"
+        | "superseded";
+    }
+  | {
+      fate: "aborted";
+      cause:
+        | "cascade"
+        | "unmount"
+        | "stream-gone"
+        | "session-lost"
+        | "superseded";
+    }
+  | {
+      fate: "lost";
+      cause: "unmount" | "stream-gone" | "session-lost" | "superseded";
+    };
+
+const describe = (failure: 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}`;
+    case "aborted":
+      return `statewire: command aborted (${failure.cause})`;
+    case "lost":
+      return `statewire: command lost (${failure.cause})`;
+    case "crashed":
+      return "statewire: command crashed";
+    case "result-unavailable":
+      return `statewire: command result unavailable (${failure.cause})`;
+  }
+};
+
+export class StatewireSendError extends Error {
+  readonly failure: SendFailure;
+
+  constructor(failure: SendFailure) {
+    super(describe(failure));
+    this.name = "StatewireSendError";
+    this.failure = failure;
+  }
+}

package/src/wire/meta.ts

@@ -0,0 +1,106 @@
+export type StatewireMetaEntry = {
+  path: (string | number)[];
+  type: string;
+};
+
+const fault = (message: string): never => {
+  throw new Error(`statewire: protocol error: ${message}`);
+};
+
+const isPath = (path: unknown): path is (string | number)[] =>
+  Array.isArray(path) &&
+  path.every(
+    (seg) =>
+      typeof seg === "string" ||
+      (typeof seg === "number" && Number.isInteger(seg)),
+  );
+
+/** Revive meta-typed locations inside a wire value (in place). Unknown types
+ * are skipped; a path that does not resolve to a valid target faults. */
+export const reviveValue = (value: unknown, meta: unknown): unknown => {
+  if (!Array.isArray(meta)) return fault("meta must be an array");
+  for (const entry of meta as { path?: unknown; type?: unknown }[]) {
+    const path =
+      typeof entry === "object" && entry !== null ? entry.path : null;
+    if (!isPath(path)) return fault("meta entry must carry a path array");
+    if (entry.type !== "date") continue;
+    let parent: unknown = null;
+    let key: string | number = "";
+    let node = value;
+    for (const seg of path) {
+      parent = node;
+      key = seg;
+      if (
+        typeof seg === "string" &&
+        typeof node === "object" &&
+        node !== null &&
+        !Array.isArray(node) &&
+        Object.hasOwn(node, seg)
+      ) {
+        node = (node as Record<string, unknown>)[seg];
+      } else if (
+        typeof seg === "number" &&
+        Array.isArray(node) &&
+        seg >= 0 &&
+        seg < node.length
+      ) {
+        node = node[seg];
+      } else {
+        return fault(`meta path ${path.join(".")} does not resolve`);
+      }
+    }
+    if (typeof node !== "string") {
+      return fault(`meta path ${path.join(".")} must name a string`);
+    }
+    const date = new Date(node);
+    if (Number.isNaN(date.getTime())) {
+      return fault(`invalid date at meta path ${path.join(".")}`);
+    }
+    if (parent === null) return date;
+    (parent as Record<string | number, unknown>)[key] = date;
+  }
+  return value;
+};
+
+export const reviveOps = (ops: unknown[]): unknown[] =>
+  ops.map((op) => {
+    if (typeof op !== "object" || op === null || !("meta" in op)) return op;
+    const { meta, ...rest } = op as { meta: unknown; value?: unknown };
+    return { ...rest, value: reviveValue(rest.value, meta) };
+  });
+
+export const reviveResponse = <T extends { payload?: unknown; meta?: unknown }>(
+  response: T,
+): T => {
+  if (response.meta === undefined) return response;
+  const { meta, ...rest } = response;
+  return { ...rest, payload: reviveValue(rest.payload, meta) } as T;
+};
+
+/** Encode Date instances inside command params as canonical ISO strings,
+ * recording their paths (starting at the param index) in meta. */
+export const encodeParams = (
+  params: readonly unknown[],
+): { params: unknown[]; meta?: StatewireMetaEntry[] } => {
+  const meta: StatewireMetaEntry[] = [];
+  const walk = (node: unknown, path: (string | number)[]): unknown => {
+    if (node instanceof Date) {
+      meta.push({ path, type: "date" });
+      return node.toISOString();
+    }
+    if (Array.isArray(node)) {
+      return node.map((item, i) => walk(item, [...path, i]));
+    }
+    if (typeof node === "object" && node !== null) {
+      return Object.fromEntries(
+        Object.keys(node).map((key) => [
+          key,
+          walk((node as Record<string, unknown>)[key], [...path, key]),
+        ]),
+      );
+    }
+    return node;
+  };
+  const encoded = params.map((param, i) => walk(param, [i]));
+  return meta.length > 0 ? { params: encoded, meta } : { params: encoded };
+};