statewire 0.0.0-0 → 0.0.2

package/src/transports/testing.ts

@@ -0,0 +1,123 @@
+import type { ResourceElement } from "@assistant-ui/tap";
+import type { StatewireEnvelope } from "../client/connection";
+import { recordMutations } from "../util/recordMutations";
+import { StatewireSSE } from "./sse";
+import type { Statewire } from "../types";
+import { openSSEStream, sseFrame } from "./fake-sse";
+import type { FakeStreamHandle } from "./fake-sse";
+
+export * from "./fixtures";
+
+/** Let queued microtasks and op batches drain through the statewire client. */
+export const tick = () => new Promise<void>((r) => setTimeout(r, 0));
+
+/** Run a mutator against a recording draft, as the client does for `optimistic`. */
+export const applyOptimistic = <TState>(
+  state: TState,
+  mutate: (draft: TState) => void,
+): TState => recordMutations(state, mutate).state;
+
+export type MockTransport<TState> = {
+  /** Pass as the `transport:` option of useStatewire / Harness. */
+  transport: ResourceElement<Statewire<TState | undefined, any, any>>;
+  /** Captured `{ method, params }` command bodies, in POST order. */
+  commands: { method: string; params: unknown[] }[];
+  /** Replace the replicated state and broadcast it as a root snapshot op. */
+  setState: (state: TState) => Promise<void>;
+  /** Deliver an ack watermark on the stream. */
+  ack: (seq: number) => Promise<void>;
+  /** Deliver an arbitrary envelope on the stream. */
+  sendEnvelope: (envelope: StatewireEnvelope) => Promise<void>;
+  /** End the stream with a fin; further attaches fail like a dead server. */
+  finish: (reason: string, message?: string) => Promise<void>;
+  readonly clientId: string;
+  readonly attached: boolean;
+};
+
+/**
+ * A mock statewire backend: serves `initialState` as the attach snapshot,
+ * records command POSTs (receipt only — acks and results are delivered from
+ * test code), and exposes the wire as a transport ResourceElement.
+ */
+let mockCount = 0;
+
+export const createMockTransport = <TState>(
+  initialState: TState,
+): MockTransport<TState> => {
+  let state: unknown = initialState;
+  let clientId = "";
+  let finished = false;
+  const clients = new Map<string, number>();
+  const streams = new Set<FakeStreamHandle>();
+  const commands: { method: string; params: unknown[] }[] = [];
+
+  const sendEnvelope = (envelope: StatewireEnvelope) => {
+    for (const stream of streams) stream.send(sseFrame(envelope));
+    return tick();
+  };
+
+  const fakeFetch = (async (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ): Promise<Response> => {
+    if (finished) throw new TypeError("fetch failed (finished)");
+    const url = String(input);
+    const headers = new Headers(init?.headers);
+    const id = headers.get("Statewire-Client-Id") ?? "";
+    if (url.endsWith("/stream")) {
+      clientId = id;
+      const lastSeq = clients.get(id) ?? 0;
+      clients.set(id, lastSeq);
+      return openSSEStream(
+        streams,
+        id,
+        (handle) => {
+          handle.send(
+            sseFrame({
+              ops: [{ op: "replace", path: [], value: state }],
+              syn: { lastSeq, lease: "mock-lease" },
+            }),
+          );
+        },
+        init?.signal ?? undefined,
+      );
+    }
+    if (url.endsWith("/commands")) {
+      const seq = Number(headers.get("Statewire-Command-Seq"));
+      clients.set(id, Math.max(clients.get(id) ?? 0, seq));
+      commands.push(
+        JSON.parse(String(init?.body)) as { method: string; params: unknown[] },
+      );
+      return Response.json({});
+    }
+    return new Response(null, { status: 404 });
+  }) as typeof fetch;
+
+  return {
+    transport: StatewireSSE({
+      url: `http://mock-${++mockCount}/api`,
+      fetch: fakeFetch,
+    }),
+    commands,
+    setState: (next) => {
+      state = next;
+      return sendEnvelope({ ops: [{ op: "replace", path: [], value: next }] });
+    },
+    ack: (seq) => sendEnvelope({ ack: seq }),
+    sendEnvelope,
+    finish: async (reason, message) => {
+      await sendEnvelope({
+        fin: { reason, ...(message !== undefined && { message }) },
+      });
+      finished = true;
+      for (const stream of [...streams]) stream.close();
+      await tick();
+    },
+    get clientId() {
+      return clientId;
+    },
+    get attached() {
+      return streams.size > 0;
+    },
+  };
+};

package/src/transports/ws.ts

@@ -0,0 +1,256 @@
+import { useState } from "react";
+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 {
+  handleEnvelope,
+  overloadedError,
+  useStatewireConn,
+} 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 type {
+  RemoteLink,
+  StatewireSubmitResult,
+  StatewireRemoteProps,
+  StatewireWireCommand,
+} from "./sse";
+
+type PendingCommand = {
+  seq: number;
+  resolve: (result: StatewireSubmitResult) => void;
+  reject: (error: Error) => void;
+};
+
+type WsChannel = {
+  socket: WebSocket | null;
+  pending: PendingCommand[];
+};
+
+const OPEN = 1;
+
+export const WS_SUBPROTOCOL = "statewire.v1";
+
+const socketUrl = async (
+  options: StatewireClient.WSOptions,
+  clientId: string,
+) => {
+  const { url, query } = options;
+  const params = new URLSearchParams(
+    typeof query === "function" ? await query() : query,
+  );
+  params.set(CLIENT_QUERY_PARAM, clientId);
+  const base = url.replace(/\/$/, "").replace(/^http/, "ws");
+  return `${base}/ws?${params.toString()}`;
+};
+
+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,
+  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;
+    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));
+      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 };
+      };
+      try {
+        frame = JSON.parse(String(event.data)) as typeof frame;
+      } catch {
+        fail(new Error("protocol"));
+        return;
+      }
+      try {
+        if (frame.overloaded !== undefined) {
+          settleOverloaded(w, frame.overloaded);
+        } else {
+          processEnv(frame);
+        }
+      } catch (error) {
+        fail(error);
+      }
+    };
+    ws.onclose = () => {
+      closed = true;
+      clearTimeout(timer);
+      if (w.socket === ws) failPending(w, new Error("network"));
+      if (outcome) resolve(outcome);
+      else reject(new Error(timedOut ? "timeout" : "network"));
+    };
+  });
+
+const attemptSocket = async (
+  c: Conn,
+  w: WsChannel,
+  options: StatewireClient.WSOptions,
+  abort: AbortController,
+): Promise<"stop" | "reattach"> => {
+  let ws: WebSocket | null = null;
+  try {
+    const url = await socketUrl(options, c.ctx.clientId);
+    abort.signal.throwIfAborted();
+    const { protocols, webSocket } = 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]);
+    w.socket = ws;
+    return await runSocket(c, w, ws, abort);
+  } finally {
+    if (w.socket === ws) w.socket = null;
+  }
+};
+
+const sendCommand = (
+  w: WsChannel,
+  { seq, command }: { seq: number; command: StatewireWireCommand },
+): 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({
+          method: command.method,
+          ...encodeParams(command.params),
+          seq,
+        }),
+      );
+    } catch {
+      clearTimeout(timer);
+      w.pending = w.pending.filter((p) => p !== entry);
+      reject(new Error("network"));
+    }
+  });
+};
+
+const useWsLink = (
+  options: StatewireClient.WSOptions,
+  ctx: StatewireRemoteProps,
+): RemoteLink => {
+  const [w] = useState((): WsChannel => ({ socket: null, pending: [] }));
+  const c = useStatewireConn({
+    url: options.url,
+    onChange: options.onChange,
+    ctx,
+    attemptOnce: (c, abort) => attemptSocket(c, w, options, abort),
+  });
+  const [link] = useState(
+    (): RemoteLink => ({
+      get connection() {
+        return c.connection;
+      },
+      send: (args) => sendCommand(w, args),
+    }),
+  );
+  return link;
+};
+
+const useStatewireWS = (
+  options: StatewireClient.WSOptions,
+): Statewire<any, 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>>;

package/src/types.ts

@@ -0,0 +1,88 @@
+import type { StatewireClient } from "./statewire";
+import type { StatewirePath } from "./wire/ops";
+
+export namespace Statewire {
+  export type Commands = Record<string, (...args: never[]) => unknown>;
+
+  export type Command<TCommands extends Commands = Commands> = {
+    [K in keyof TCommands]: { method: K; params: Parameters<TCommands[K]> };
+  }[keyof TCommands];
+
+  export type CommandsProxy<TCommands extends Commands> = {
+    [K in keyof TCommands]: (
+      ...args: Parameters<TCommands[K]>
+    ) => Promise<Awaited<ReturnType<TCommands[K]>>>;
+  };
+
+  export type CommandUpdate<TCommands extends Commands = Commands> = {
+    [K in keyof TCommands]: {
+      method: K;
+      params: Parameters<TCommands[K]>;
+      seq: number;
+      status: "queued" | "posted" | "acked" | "settled";
+      result?: unknown;
+      failure?: StatewireClient.SendFailure;
+    };
+  }[keyof TCommands];
+
+  /** Push-based canonical state feed a statewire hands to the client core. */
+  export type StateSource = {
+    snapshot: () => 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 Op =
+    | { op: "replace"; path: StatewirePath; value: unknown }
+    | { op: "add"; path: StatewirePath; value: unknown }
+    | { op: "remove"; path: StatewirePath }
+    | { op: "event"; value: object };
+
+  export type Changes = {
+    isChangedAt(path: readonly (string | number)[]): boolean;
+    getChangedKeys(path: readonly (string | number)[]): string[];
+  };
+}
+
+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;
+}
+
+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}`;
+    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: StatewireClient.SendFailure;
+
+  constructor(failure: StatewireClient.SendFailure) {
+    super(describe(failure));
+    this.name = "StatewireSendError";
+    this.failure = failure;
+  }
+}

package/src/util/draftTraps.ts

@@ -0,0 +1,32 @@
+type SharedTraps = Pick<
+  ProxyHandler<object>,
+  | "defineProperty"
+  | "setPrototypeOf"
+  | "preventExtensions"
+  | "ownKeys"
+  | "getOwnPropertyDescriptor"
+>;
+
+export const sharedDraftTraps = (
+  current: () => object,
+  context: string,
+): SharedTraps => {
+  const unsupported = (op: string): never => {
+    throw new Error(`statewire: ${op} is not supported ${context}`);
+  };
+  return {
+    defineProperty: () => unsupported("defineProperty"),
+    setPrototypeOf: () => unsupported("setPrototypeOf"),
+    preventExtensions: () => unsupported("preventExtensions"),
+    ownKeys: () => Reflect.ownKeys(current()),
+    getOwnPropertyDescriptor: (_target, prop) => {
+      const node = current();
+      const desc = Reflect.getOwnPropertyDescriptor(node, prop);
+      if (!desc) return undefined;
+      return {
+        ...desc,
+        configurable: !Array.isArray(node) || prop !== "length",
+      };
+    },
+  };
+};

package/src/util/macrotask.ts

@@ -0,0 +1,25 @@
+// MessageChannel schedules the flush as a macrotask (tap's pattern): it runs
+// after the whole microtask drain, so every producer in the current turn
+// coalesces. The port is ref'd only while a flush is pending — an active
+// MessagePort holds the Node event loop open. ref/unref are Node-only.
+export const createMacrotaskPoster = (callback: () => void): (() => void) => {
+  if (typeof MessageChannel !== "undefined") {
+    let port1: (MessagePort & { ref?: () => void; unref?: () => void }) | null =
+      null;
+    let port2: MessagePort;
+    return () => {
+      if (!port1) {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = () => {
+          port1?.unref?.();
+          callback();
+        };
+        port1 = channel.port1;
+        port2 = channel.port2;
+      }
+      port1.ref?.();
+      port2!.postMessage(null);
+    };
+  }
+  return () => setTimeout(callback, 0);
+};

package/src/util/methodProxy.ts

@@ -0,0 +1,16 @@
+export const createMethodProxy = <T extends object>(
+  dispatch: (method: string, params: unknown[]) => Promise<unknown>,
+): T => {
+  const memo = new Map<string, (...params: unknown[]) => Promise<unknown>>();
+  return new Proxy({} as T, {
+    get: (_target, method) => {
+      if (typeof method !== "string") return undefined;
+      let fn = memo.get(method);
+      if (fn === undefined) {
+        fn = (...params: unknown[]) => dispatch(method, params);
+        memo.set(method, fn);
+      }
+      return fn;
+    },
+  });
+};

package/src/util/randomId.ts

@@ -0,0 +1,4 @@
+export const randomId = (): string =>
+  typeof crypto !== "undefined" && "randomUUID" in crypto
+    ? crypto.randomUUID()
+    : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;

package/src/util/statePath.ts

@@ -0,0 +1,61 @@
+export type StatePath = readonly (string | number)[];
+
+export const isUnsafeKey = (
+  key: string | number,
+  parent: string | number | undefined,
+) => key === "__proto__" || (key === "prototype" && parent === "constructor");
+
+export type WalkedPath = {
+  /** Container of the final key; undefined when the path is empty. */
+  parent: unknown;
+  key: string | number;
+  leaf: unknown;
+};
+
+// "read": lenient, never fails — missing steps yield an undefined leaf.
+// "parent": every step before the last must resolve; the leaf may not exist.
+// "resolve": every step including the last must resolve.
+// Strict modes require array+integer for number keys, plain object for string
+// keys, and reject unsafe (prototype-polluting) segments.
+export const walkStatePath = (
+  root: unknown,
+  path: StatePath,
+  mode: "read" | "parent" | "resolve",
+): WalkedPath | undefined => {
+  let parent: unknown = undefined;
+  let key: string | number = "";
+  let node: unknown = root;
+  for (let depth = 0; depth < path.length; depth++) {
+    const k = path[depth]!;
+    const mustResolve =
+      mode === "resolve" || (mode === "parent" && depth < path.length - 1);
+    if (mode !== "read") {
+      if (typeof k === "number") {
+        if (!Array.isArray(node) || !Number.isInteger(k) || k < 0) {
+          return undefined;
+        }
+        if (mustResolve && k >= node.length) return undefined;
+      } else {
+        if (
+          isUnsafeKey(k, path[depth - 1]) ||
+          typeof node !== "object" ||
+          node === null ||
+          Array.isArray(node)
+        ) {
+          return undefined;
+        }
+        if (mustResolve && !Object.hasOwn(node, k)) return undefined;
+      }
+    }
+    parent = node;
+    key = k;
+    node =
+      typeof node === "object" && node !== null && Object.hasOwn(node, k)
+        ? (node as Record<string | number, unknown>)[k]
+        : undefined;
+  }
+  return { parent, key, leaf: node };
+};
+
+export const readAtPath = (root: unknown, path: StatePath): unknown =>
+  walkStatePath(root, path, "read")!.leaf;