statewire 0.0.1 → 0.0.3

package/src/host/socket.ts

@@ -0,0 +1,618 @@
+import { useEffect, useState } from "react";
+import { createTapRoot, flushTapSync, useResource } from "@assistant-ui/tap";
+import type { ResourceElement } from "@assistant-ui/tap";
+import { getCommandsHost, getEmitHost, getStateHost } from "./host";
+import type { CommandsHost, CommandsOutcome } from "./host";
+import { StatewireSendError } from "../types";
+import type { Statewire } from "../types";
+import type { StatewireHost } from "../host";
+import type { StatewireHostInternal } from "../host-internal";
+import { encodeValue, reviveValue } from "../wire/meta";
+import { createMacrotaskPoster } from "../util/macrotask";
+import { randomId } from "../util/randomId";
+import type { StatewireMetaEntry } from "../wire/meta";
+import type { StatewirePath } from "../wire/ops";
+import type {
+  StatewireEnvelope,
+  StatewireResponse,
+} from "../client/connection";
+
+const CLIENT_ID_RE = /^[A-Za-z0-9._~-]{1,256}$/;
+const RESULT_TTL_MS = 30_000;
+const RESULT_LIMIT = 256;
+
+type WireOp = {
+  op: string;
+  path?: StatewirePath;
+  value?: unknown;
+  meta?: StatewireMetaEntry[];
+};
+
+type Admission = {
+  seq: number;
+  method: string;
+  acked: boolean;
+  pendingSent: boolean;
+  settled: boolean;
+  release: () => void;
+};
+
+type ClientRec = {
+  id: string;
+  lastSeq: number;
+  context: Record<string, unknown> | null;
+  results: Map<number, { ts: number; res: StatewireResponse }>;
+  inflight: Map<number, Admission>;
+};
+
+type Conn = {
+  clientId: string;
+  socket: StatewireHostInternal.Socket;
+  open: boolean;
+  lastSentAt: number;
+};
+
+type Frame = {
+  method?: string;
+  seq: number;
+  params: unknown[];
+  context?: unknown;
+};
+
+const parseFrame = (raw: string): Frame | null => {
+  let frame: unknown;
+  try {
+    frame = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof frame !== "object" || frame === null || Array.isArray(frame)) {
+    return null;
+  }
+  const { method, seq, params, meta, context } = frame as Record<
+    string,
+    unknown
+  >;
+  if (method === undefined && context === undefined) return null;
+  if (typeof seq !== "number" || !Number.isInteger(seq) || seq < 1) return null;
+  if (method === undefined) {
+    return { seq, params: [], ...(context !== undefined && { context }) };
+  }
+  if (typeof method !== "string") return null;
+  if (!Array.isArray(params)) return null;
+  if (meta !== undefined) {
+    try {
+      reviveValue(params, meta);
+    } catch {
+      return null;
+    }
+  }
+  return { method, seq, params, ...(context !== undefined && { context }) };
+};
+
+/** v1 context submissions are exactly one root replace with an object value. */
+const contextValue = (context: unknown): Record<string, unknown> => {
+  if (!Array.isArray(context) || context.length !== 1) {
+    throw new Error("context must be a single-op array");
+  }
+  const op = context[0] as Record<string, unknown> | null;
+  if (
+    typeof op !== "object" ||
+    op === null ||
+    op["op"] !== "replace" ||
+    !Array.isArray(op["path"]) ||
+    op["path"].length !== 0
+  ) {
+    throw new Error("context op must be a root replace");
+  }
+  const value = op["value"];
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("context value must be an object");
+  }
+  return value as Record<string, unknown>;
+};
+
+const encodePayload = (
+  payload: unknown,
+): { payload?: unknown; meta?: StatewireMetaEntry[] } => {
+  if (payload === undefined) return {};
+  const { value, meta } = encodeValue(payload);
+  return { payload: value, ...(meta !== undefined && { meta }) };
+};
+
+const responseOf = (
+  adm: Admission,
+  outcome: CommandsOutcome,
+): StatewireResponse => {
+  if (outcome.type === "accepted") {
+    return {
+      seq: adm.seq,
+      type: "accepted",
+      ...encodePayload(outcome.payload),
+    };
+  }
+  const failure =
+    outcome.error instanceof StatewireSendError ? outcome.error.failure : null;
+  switch (failure?.fate) {
+    case "unknown-command":
+      return {
+        seq: adm.seq,
+        type: "rejected",
+        code: "unknown-command",
+        message: `unknown method: '${adm.method}'`,
+      };
+    case "invalid-params":
+      return {
+        seq: adm.seq,
+        type: "rejected",
+        code: "invalid-params",
+        message: failure.message,
+      };
+    case "crashed":
+      return { seq: adm.seq, type: "crashed" };
+    case "rejected":
+      return {
+        seq: adm.seq,
+        type: "rejected",
+        message: failure.message,
+        ...encodePayload(failure.payload),
+      };
+    default:
+      return {
+        seq: adm.seq,
+        type: "rejected",
+        message:
+          outcome.error instanceof Error
+            ? outcome.error.message
+            : String(outcome.error),
+      };
+  }
+};
+
+const createSocketHost = (
+  options?: StatewireHostInternal.SocketHostOptions,
+) => {
+  const heartbeatMs = options?.heartbeatIntervalMs ?? 15_000;
+
+  const clients = new Map<string, ClientRec>();
+  const conns = new Set<Conn>();
+  let pendingOps: WireOp[] = [];
+  let dirtyAcks = new Set<string>();
+  let pendingRes = new Map<string, StatewireResponse[]>();
+  let inbox: Promise<void> = Promise.resolve();
+  let finished: StatewireHost.Fin | null = null;
+  let disposed = false;
+  let flushScheduled = false;
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+  let stateHost: StatewireHost.StateHost | null = null;
+  let commandsHost: CommandsHost | null = null;
+  let emitHost: ReturnType<typeof getEmitHost> | null = null;
+  let current: Statewire<unknown> | null = null;
+
+  const post = createMacrotaskPoster(() => {
+    flushScheduled = false;
+    flush();
+  });
+  const scheduleFlush = () => {
+    if (flushScheduled || disposed) return;
+    flushScheduled = true;
+    post();
+  };
+
+  const recordOp = (op: {
+    op: string;
+    path?: StatewirePath;
+    value?: unknown;
+  }) => {
+    if (op.op === "replace" || op.op === "add" || op.op === "event") {
+      const { value, meta } = encodeValue(op.value);
+      pendingOps.push({ ...op, value, ...(meta !== undefined && { meta }) });
+    } else {
+      pendingOps.push(op);
+    }
+    scheduleFlush();
+  };
+
+  const attach = (next: Statewire<unknown>) => {
+    if (next === current) return;
+    current = next;
+    const nextState =
+      typeof next.state === "object" && next.state !== null
+        ? getStateHost(next.state)
+        : undefined;
+    const nextCommands = getCommandsHost(next.commands);
+    const nextEmit = getEmitHost(next.emit);
+    if (!nextState || !nextCommands?.submit || !nextEmit) {
+      throw new Error(
+        "StatewireSocketHost requires a statewire/host transport (useStatewireState with object state, useStatewireCommands, useStatewireEmit)",
+      );
+    }
+    if (nextState !== stateHost) {
+      stateHost?.setOnOp(null);
+      stateHost = nextState;
+      stateHost.setOnOp(recordOp);
+    }
+    commandsHost = nextCommands;
+    if (nextEmit !== emitHost) {
+      emitHost?.setSink(null);
+      emitHost = nextEmit;
+      emitHost.setSink((event) => recordOp({ op: "event", value: event }));
+    }
+  };
+
+  const closeConn = (conn: Conn, code?: number, reason?: string) => {
+    if (!conn.open) return;
+    conn.open = false;
+    conns.delete(conn);
+    try {
+      conn.socket.close(code, reason);
+    } catch {
+      /* peer already gone */
+    }
+    if (conns.size === 0 && heartbeatTimer !== null) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+  };
+
+  const sendTo = (conn: Conn, data: string) => {
+    if (!conn.open) return;
+    conn.lastSentAt = Date.now();
+    try {
+      conn.socket.send(data);
+    } catch {
+      closeConn(conn);
+    }
+  };
+
+  const ensureHeartbeat = () => {
+    if (heartbeatTimer !== null || heartbeatMs <= 0) return;
+    heartbeatTimer = setInterval(() => {
+      const now = Date.now();
+      for (const conn of [...conns]) {
+        if (now - conn.lastSentAt >= heartbeatMs) sendTo(conn, "{}");
+      }
+    }, heartbeatMs);
+    (heartbeatTimer as unknown as { unref?: () => void }).unref?.();
+  };
+
+  const flush = (fin?: StatewireHost.Fin) => {
+    flushTapSync(() => {});
+    stateHost?.takeChanged();
+    for (const rec of clients.values()) {
+      for (const adm of rec.inflight.values()) {
+        if (adm.acked && !adm.settled && !adm.pendingSent) {
+          adm.pendingSent = true;
+          queueRes(rec.id, { seq: adm.seq, type: "pending" });
+        }
+      }
+    }
+    if (
+      pendingOps.length === 0 &&
+      dirtyAcks.size === 0 &&
+      pendingRes.size === 0 &&
+      fin === undefined
+    ) {
+      return;
+    }
+    const ops = pendingOps;
+    const acks = dirtyAcks;
+    const res = pendingRes;
+    pendingOps = [];
+    dirtyAcks = new Set();
+    pendingRes = new Map();
+    for (const conn of [...conns]) {
+      const envelope: StatewireEnvelope = {};
+      if (ops.length > 0) envelope.ops = ops;
+      const clientRes = res.get(conn.clientId);
+      if (clientRes !== undefined) envelope.res = clientRes;
+      if (acks.has(conn.clientId)) {
+        const rec = clients.get(conn.clientId);
+        if (rec !== undefined) envelope.ack = rec.lastSeq;
+      }
+      if (fin !== undefined) envelope.fin = fin;
+      if (Object.keys(envelope).length === 0) continue;
+      sendTo(conn, JSON.stringify(envelope));
+      if (fin !== undefined) closeConn(conn);
+    }
+  };
+
+  const queueRes = (clientId: string, response: StatewireResponse) => {
+    const list = pendingRes.get(clientId);
+    if (list) list.push(response);
+    else pendingRes.set(clientId, [response]);
+  };
+
+  const advance = (rec: ClientRec, seq: number) => {
+    rec.lastSeq = seq;
+    dirtyAcks.add(rec.id);
+  };
+
+  const retain = (rec: ClientRec, response: StatewireResponse) => {
+    const now = Date.now();
+    rec.results.set(response.seq, { ts: now, res: response });
+    const newest = Math.max(...rec.results.keys());
+    for (const [seq, entry] of rec.results) {
+      if (seq !== newest && now - entry.ts > RESULT_TTL_MS) {
+        rec.results.delete(seq);
+      }
+    }
+    while (rec.results.size > RESULT_LIMIT) {
+      rec.results.delete(Math.min(...rec.results.keys()));
+    }
+  };
+
+  const duplicateAnswer = (rec: ClientRec, seq: number): StatewireResponse => {
+    const cached = rec.results.get(seq);
+    if (cached) {
+      const newest = Math.max(...rec.results.keys());
+      if (seq === newest || Date.now() - cached.ts <= RESULT_TTL_MS) {
+        return cached.res;
+      }
+      rec.results.delete(seq);
+    }
+    if (rec.inflight.has(seq)) return { seq, type: "pending" };
+    return { seq, type: "result-unavailable" };
+  };
+
+  const settleResponse = (
+    rec: ClientRec,
+    adm: Admission,
+    response: StatewireResponse,
+  ) => {
+    if (adm.settled) return;
+    adm.settled = true;
+    rec.inflight.delete(adm.seq);
+    retain(rec, response);
+    if (!adm.acked) {
+      adm.acked = true;
+      advance(rec, adm.seq);
+    }
+    if (
+      adm.pendingSent ||
+      response.type !== "accepted" ||
+      response.payload !== undefined
+    ) {
+      queueRes(rec.id, response);
+    }
+    scheduleFlush();
+    adm.release();
+  };
+
+  const settleWire = (
+    rec: ClientRec,
+    adm: Admission,
+    outcome: CommandsOutcome,
+  ) => settleResponse(rec, adm, responseOf(adm, outcome));
+
+  const callerOf = (rec: ClientRec): StatewireHost.Caller => ({
+    get context() {
+      return rec.context;
+    },
+    get isConnected() {
+      if (clients.get(rec.id) !== rec) return false;
+      for (const conn of conns) {
+        if (conn.clientId === rec.id && conn.open) return true;
+      }
+      return false;
+    },
+  });
+
+  const admit = (conn: Conn, frame: Frame): Promise<void> | void => {
+    if (!conn.open || disposed || finished !== null) return;
+    const rec = clients.get(conn.clientId)!;
+    if (frame.seq <= rec.lastSeq || rec.inflight.has(frame.seq)) {
+      queueRes(rec.id, duplicateAnswer(rec, frame.seq));
+      scheduleFlush();
+      return;
+    }
+    if (frame.seq > rec.lastSeq + 1) {
+      closeConn(
+        conn,
+        1008,
+        `seq gap: expected ${rec.lastSeq + 1}, got ${frame.seq}`,
+      );
+      return;
+    }
+    const adm: Admission = {
+      seq: frame.seq,
+      method: frame.method ?? "",
+      acked: false,
+      pendingSent: false,
+      settled: false,
+      release: () => {},
+    };
+    if (frame.context !== undefined) {
+      let value: Record<string, unknown>;
+      try {
+        value = contextValue(frame.context);
+      } catch (error) {
+        rec.inflight.set(frame.seq, adm);
+        settleResponse(rec, adm, {
+          seq: frame.seq,
+          type: "rejected",
+          code: "invalid-context",
+          message: `invalid context: ${(error as Error).message}`,
+        });
+        return;
+      }
+      rec.context = value;
+      if (frame.method === undefined) {
+        rec.inflight.set(frame.seq, adm);
+        settleResponse(rec, adm, { seq: frame.seq, type: "accepted" });
+        return;
+      }
+    }
+    const released = new Promise<void>((resolve) => {
+      adm.release = resolve;
+    });
+    rec.inflight.set(frame.seq, adm);
+    commandsHost!.submit!({
+      method: frame.method!,
+      params: frame.params,
+      clientId: rec.id,
+      caller: callerOf(rec),
+      onAck: () => {
+        if (adm.settled || adm.acked) return;
+        adm.acked = true;
+        advance(rec, adm.seq);
+        scheduleFlush();
+        adm.release();
+      },
+      onSettle: (outcome) => settleWire(rec, adm, outcome),
+    }).catch((error: unknown) => {
+      if (!adm.settled) settleWire(rec, adm, { type: "rejected", error });
+    });
+    return released;
+  };
+
+  const message = (conn: Conn, data: string) => {
+    if (!conn.open || disposed || finished !== null) return;
+    const frame = parseFrame(data);
+    if (frame === null) {
+      closeConn(conn, 1008, "invalid frame");
+      return;
+    }
+    inbox = inbox.then(() => admit(conn, frame));
+  };
+
+  const connect = (
+    clientId: string,
+    socket: StatewireHostInternal.Socket,
+  ): StatewireHostInternal.SocketConnection => {
+    const dead: StatewireHostInternal.SocketConnection = {
+      clientId,
+      message: () => {},
+      close: () => {},
+    };
+    const refuse = (code: number, reason: string) => {
+      try {
+        socket.close(code, reason);
+      } catch {
+        /* peer already gone */
+      }
+      return dead;
+    };
+    if (disposed) return refuse(1001, "disposed");
+    if (!CLIENT_ID_RE.test(clientId)) return refuse(1008, "invalid client id");
+    flush();
+    if (finished !== null) {
+      try {
+        socket.send(JSON.stringify({ fin: finished }));
+      } catch {
+        /* peer already gone */
+      }
+      return refuse(1000, "finished");
+    }
+    const known = clients.has(clientId);
+    const rec = known
+      ? clients.get(clientId)!
+      : (() => {
+          const created: ClientRec = {
+            id: clientId,
+            lastSeq: 0,
+            context: null,
+            results: new Map(),
+            inflight: new Map(),
+          };
+          clients.set(clientId, created);
+          return created;
+        })();
+    for (const other of [...conns]) {
+      if (other.clientId !== clientId) continue;
+      sendTo(other, JSON.stringify({ fin: { reason: "superseded" } }));
+      closeConn(other);
+    }
+    const conn: Conn = { clientId, socket, open: true, lastSentAt: 0 };
+    conns.add(conn);
+    ensureHeartbeat();
+    const { value, meta } = encodeValue(stateHost!.snapshot());
+    const snapshot: StatewireEnvelope = {
+      ops: [
+        {
+          op: "replace",
+          path: [],
+          value,
+          ...(meta !== undefined && { meta }),
+        },
+      ],
+      syn: { lastSeq: known ? rec.lastSeq : -1, lease: randomId() },
+    };
+    sendTo(conn, JSON.stringify(snapshot));
+    return {
+      clientId,
+      message: (data) => message(conn, data),
+      close: () => closeConn(conn),
+    };
+  };
+
+  const finish = (fin: StatewireHost.Fin) => {
+    if (finished !== null || disposed) return;
+    finished = fin;
+    flush(fin);
+  };
+
+  return {
+    connect,
+    finish,
+    attach,
+    resume: () => {
+      disposed = false;
+      stateHost?.setOnOp(recordOp);
+      emitHost?.setSink((event) => recordOp({ op: "event", value: event }));
+    },
+    suspend: () => {
+      disposed = true;
+      if (heartbeatTimer !== null) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+      }
+      stateHost?.setOnOp(null);
+      emitHost?.setSink(null);
+    },
+  };
+};
+
+const useSocketHost = (
+  transport: ResourceElement<Statewire>,
+  options?: StatewireHostInternal.SocketHostOptions,
+): Pick<StatewireHostInternal.SocketHost, "connect" | "finish"> => {
+  const [h] = useState(() => createSocketHost(options));
+  const value = useResource(transport) as Statewire<unknown>;
+  h.attach(value);
+  useEffect(() => {
+    h.attach(value);
+  });
+  useEffect(() => {
+    h.resume();
+    return () => h.suspend();
+  }, [h]);
+  return h;
+};
+
+/**
+ * Transport-agnostic WS binding over a statewire/host transport:
+ * feed it sockets (anything with `send`/`close`) and raw text frames, and it
+ * speaks the Statewire envelope protocol — snapshot-first attach with `syn`,
+ * delta/ack/res envelopes, per-client-id supersede, and `fin` on finish.
+ */
+export const StatewireSocketHost = (
+  transport: ResourceElement<Statewire>,
+  options?: StatewireHostInternal.SocketHostOptions,
+): StatewireHostInternal.SocketHost => {
+  const SocketHostRoot = () => useSocketHost(transport, options);
+  const root = createTapRoot(SocketHostRoot);
+  let disposed = false;
+  return {
+    connect: (clientId, socket) =>
+      flushTapSync(() => root.getValue().connect(clientId, socket)),
+    finish: (fin) => flushTapSync(() => root.getValue().finish(fin)),
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      flushTapSync(() => root.getValue().finish({ reason: "evicted" }));
+      root.unmount();
+    },
+  };
+};

package/src/host-internal.ts

@@ -0,0 +1,28 @@
+import type { StatewireHost } from "./host";
+
+export { StatewireSocketHost } from "./host/socket";
+export { clientIdFromUrl, textFrameOrClose } from "./host/adapter";
+export namespace StatewireHostInternal {
+  export type Socket = {
+    send: (data: string) => void;
+    close: (code?: number, reason?: string) => void;
+  };
+
+  export type SocketConnection = {
+    readonly clientId: string;
+    message: (data: string) => void;
+    close: () => void;
+  };
+
+  export type SocketHost = {
+    connect: (clientId: string, socket: Socket) => SocketConnection;
+    finish: (fin: StatewireHost.Fin) => void;
+    dispose: () => void;
+  };
+
+  export type SocketHostOptions = {
+    heartbeatIntervalMs?: number;
+  };
+
+  export type Fin = StatewireHost.Fin;
+}

package/src/host.ts

@@ -0,0 +1,72 @@
+import type { Statewire } from "./types";
+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). */
+    apply: (ops: readonly Statewire.Op[]) => void;
+    /** The committed plain state — immutably replaced per op, so a captured value is a stable snapshot. */
+    snapshot: () => TState;
+  };
+
+  export type StateHost = Statewire.StateSource & {
+    /** Synchronous, per locally-recorded op; the host owns batching. */
+    setOnOp: (listener: ((op: ServerOp) => void) | null) => void;
+  };
+
+  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.
+   */
+  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;
+  };
+
+  /**
+   * The submitting client, bound as `this` of a command handler. Holdable
+   * across a long run: `context` reads the client's current ambient context
+   * live (null until the client sends one), `isConnected` reports whether the
+   * client has an active stream attachment.
+   */
+  export type Caller = {
+    readonly context: Record<string, unknown> | null;
+    readonly isConnected: boolean;
+  };
+
+  export type HandledCommands<THandlers extends Statewire.Commands> = {
+    [K in keyof THandlers]: (
+      ...args: Parameters<THandlers[K]>
+    ) => UnwrapExecution<Awaited<ReturnType<THandlers[K]>>>;
+  };
+
+  export type Fin = {
+    reason: "evicted" | "error" | "gone" | "superseded" | (string & {});
+    message?: string;
+    payload?: unknown;
+    meta?: unknown;
+  };
+}