statewire 0.0.1 → 0.0.2

package/src/client/connection.ts

@@ -1,26 +1,16 @@
 import { useEffect, useRef, useState } from "react";
 import { flushTapSync } from "@assistant-ui/tap";
 import { reviveOps, reviveResponse, reviveValue } from "../wire/meta";
-import { backoff } from "./timing";
-import type {
-  ConnectionState,
-  RemoteLink,
-  StatewireConnection,
-  StatewireTransportProps,
-} from "../transports/sse";
+import { retryDelay } from "./timing";
+import type { ConnectionState, StatewireRemoteProps } from "../transports/sse";
+import type { StatewireClient } from "../statewire";
+import type { StatewireHost } from "../host";
 
 export type Episode = {
-  cause: "dropped" | "ended" | "error";
+  cause: "dropped" | "evicted" | "error";
   message?: string;
 };
 
-export type StatewireFinish = {
-  reason: "ended" | "error" | "gone" | "superseded" | (string & {});
-  message?: string;
-  payload?: unknown;
-  meta?: unknown;
-};
-
 export type StatewireResponse = {
   seq: number;
   type: "accepted" | "rejected" | "pending" | "crashed" | "result-unavailable";
@@ -40,10 +30,10 @@ export type StatewireEnvelope = {
   res?: StatewireResponse[];
   ack?: number;
   syn?: StatewireSyn;
-  fin?: StatewireFinish;
+  fin?: StatewireHost.Fin;
 };
 
-export const createGate = () => {
+const createGate = () => {
   let latched = false;
   let wake: (() => void) | undefined;
   return {
@@ -81,8 +71,8 @@ export const createGate = () => {
 
 export type Gate = ReturnType<typeof createGate>;
 
-export type ConnBase = {
-  connection: StatewireConnection;
+export type Conn = {
+  connection: StatewireClient.Connection;
   hasSnapshot: boolean;
   lease: string | null;
   attempt: number;
@@ -90,37 +80,33 @@ export type ConnBase = {
   gate: Gate;
   abort: AbortController | null;
   lifetime: AbortController | null;
-  latest: {
-    readonly current: {
-      options: { onChange?: (connection: StatewireConnection) => void };
-      ctx: StatewireTransportProps;
-    };
-  };
-  notify: (connection: StatewireConnection) => void;
-  reconnect: () => void;
+  ctx: StatewireRemoteProps;
+  onChange: (connection: StatewireClient.Connection) => void;
   attemptOnce: (
     abort: AbortController,
   ) => Promise<"stop" | "reattach" | "ended">;
+  notify: (connection: StatewireClient.Connection) => void;
+  reconnect: () => void;
 };
 
-export const setStatus = (c: ConnBase, next: ConnectionState) => {
+const setStatus = (c: Conn, next: ConnectionState) => {
   const changed = next.status !== c.connection.status;
   c.connection = { ...next, reconnect: c.reconnect };
   c.notify(c.connection);
-  if (changed) c.latest.current.options.onChange?.(c.connection);
+  if (changed) c.onChange(c.connection);
 };
 
-export const deliverEnvelope = (
-  c: ConnBase,
+const deliverEnvelope = (
+  c: Conn,
   env: Pick<StatewireEnvelope, "ops" | "res" | "ack" | "syn">,
-  attached: boolean,
 ) => {
   if (env.syn?.lease !== undefined) c.lease = env.syn.lease;
-  const ctx = c.latest.current.ctx;
+  const ctx = c.ctx;
   const ops = env.ops === undefined ? [] : reviveOps(env.ops);
   const res = env.res?.map(reviveResponse);
-  if (!attached) {
-    ctx.onSnapshot({ ops, lastSeq: env.syn?.lastSeq ?? -1 });
+  if (env.syn !== undefined) {
+    ctx.onSnapshot({ ops, lastSeq: env.syn.lastSeq });
+    c.hasSnapshot = true;
   } else if (
     env.ops !== undefined ||
     env.res !== undefined ||
@@ -132,15 +118,14 @@ export const deliverEnvelope = (
       ...(env.ack !== undefined && { ack: env.ack }),
     });
   }
-  c.hasSnapshot = true;
 };
 
-export const isTransientFinish = (
-  reason: StatewireFinish["reason"],
-): reason is "ended" | "error" => reason === "ended" || reason === "error";
+const isTransientFinish = (
+  reason: StatewireHost.Fin["reason"],
+): reason is "evicted" | "error" => reason === "evicted" || reason === "error";
 
-export const settleEnvelope = (
-  c: ConnBase,
+const settleEnvelope = (
+  c: Conn,
   env: StatewireEnvelope,
 ): "stop" | "reattach" | null => {
   let finish = env.fin;
@@ -149,7 +134,7 @@ export const settleEnvelope = (
       const { meta, ...rest } = finish;
       finish = { ...rest, payload: reviveValue(rest.payload, meta) };
     }
-    c.latest.current.ctx.onFinish(finish);
+    c.ctx.onFinish(finish);
     if (isTransientFinish(finish.reason)) {
       c.episode = {
         cause: finish.reason,
@@ -173,23 +158,22 @@ export const settleEnvelope = (
 };
 
 export const handleEnvelope = (
-  c: ConnBase,
+  c: Conn,
   env: StatewireEnvelope,
-  attached: boolean,
 ): "stop" | "reattach" | null => {
-  deliverEnvelope(c, env, attached);
+  deliverEnvelope(c, env);
   return settleEnvelope(c, env);
 };
 
-export const scheduleRetry = (
-  c: ConnBase,
+const scheduleRetry = (
+  c: Conn,
   failure: string | undefined,
   immediate: boolean,
-  retryAfterMs?: number,
+  cause?: unknown,
 ) => {
   c.attempt += 1;
   c.episode ??= { cause: "dropped" };
-  const delay = immediate ? 0 : (retryAfterMs ?? backoff(c.attempt));
+  const delay = immediate ? 0 : retryDelay(cause, c.attempt);
   if (c.hasSnapshot) {
     setStatus(c, {
       status: "reconnecting",
@@ -202,7 +186,7 @@ export const scheduleRetry = (
   return delay;
 };
 
-export const reconnectConn = (c: ConnBase) => {
+const reconnectConn = (c: Conn) => {
   if (!c.lifetime) return;
   if (c.connection.status === "gone") {
     c.attempt = 0;
@@ -216,13 +200,13 @@ export const reconnectConn = (c: ConnBase) => {
   c.abort?.abort();
 };
 
-const run = async (c: ConnBase, lifetime: AbortController, gate: Gate) => {
+const run = async (c: Conn, lifetime: AbortController, gate: Gate) => {
   const alive = () => c.lifetime === lifetime;
   while (alive()) {
     const abort = new AbortController();
     c.abort = abort;
     let failure: string | undefined;
-    let retryAfterMs: number | undefined;
+    let cause: unknown;
     let gone = false;
     try {
       gone = (await c.attemptOnce(abort)) === "stop";
@@ -230,13 +214,7 @@ const run = async (c: ConnBase, lifetime: AbortController, gate: Gate) => {
       if (!abort.signal.aborted) {
         failure =
           error instanceof Error && error.message ? error.message : "network";
-        if (
-          error instanceof Error &&
-          "retryAfterMs" in error &&
-          typeof error.retryAfterMs === "number"
-        ) {
-          retryAfterMs = error.retryAfterMs;
-        }
+        cause = error;
       }
     }
     abort.abort();
@@ -247,69 +225,65 @@ const run = async (c: ConnBase, lifetime: AbortController, gate: Gate) => {
     }
     const immediate = gate.take();
     const delay = flushTapSync(() =>
-      scheduleRetry(c, failure, immediate, retryAfterMs),
+      scheduleRetry(c, failure, immediate, cause),
     );
     if (delay === 0) continue;
     await gate.wait(delay);
   }
 };
 
-const startConn = (c: ConnBase) => {
-  c.hasSnapshot = false;
-  c.lease = null;
-  c.attempt = 0;
-  c.episode = null;
-  if (c.connection.status !== "connecting") {
-    setStatus(c, { status: "connecting" });
-  }
-  c.lifetime = new AbortController();
-  c.gate = createGate();
-  void run(c, c.lifetime, c.gate);
-};
-
-const stopConn = (c: ConnBase) => {
-  c.abort?.abort();
-  c.lifetime?.abort();
-  c.lifetime = null;
-  c.gate.open();
-};
-
-export const useStatewireConn = <
-  TOptions extends {
-    url: string;
-    onChange?: (connection: StatewireConnection) => void;
-  },
->(
-  options: TOptions,
-  ctx: StatewireTransportProps,
-  create: (
-    latest: {
-      readonly current: {
-        options: TOptions;
-        ctx: StatewireTransportProps;
-      };
-    },
-    notify: (connection: StatewireConnection) => void,
-  ) => ConnBase & { send: RemoteLink["send"] },
-): RemoteLink => {
-  const latest = useRef({ options, ctx });
-  const [connection, setConnection] = useState<StatewireConnection | null>(
-    null,
-  );
-  const [c] = useState(() => create(latest, setConnection));
-
-  useEffect(() => {
-    latest.current = { options, ctx };
+export const useStatewireConn = (props: {
+  url: string;
+  onChange?: ((connection: StatewireClient.Connection) => void) | undefined;
+  ctx: StatewireRemoteProps;
+  attemptOnce: (
+    c: Conn,
+    abort: AbortController,
+  ) => Promise<"stop" | "reattach" | "ended">;
+}): Conn => {
+  const latest = useRef(props);
+  latest.current = props;
+  const [, setConnection] = useState<StatewireClient.Connection | null>(null);
+  const [c] = useState((): Conn => {
+    const conn: Conn = {
+      hasSnapshot: false,
+      lease: null,
+      attempt: 0,
+      episode: null,
+      abort: null,
+      gate: createGate(),
+      lifetime: null,
+      ctx: props.ctx,
+      onChange: (connection) => latest.current.onChange?.(connection),
+      attemptOnce: (abort) => latest.current.attemptOnce(conn, abort),
+      notify: setConnection,
+      reconnect: () => reconnectConn(conn),
+      connection: { status: "connecting", reconnect: () => conn.reconnect() },
+    };
+    return conn;
   });
+
   useEffect(() => {
-    startConn(c);
-    return () => stopConn(c);
-  }, [c, options.url]);
+    c.hasSnapshot = false;
+    c.lease = null;
+    c.attempt = 0;
+    c.episode = null;
+    if (c.connection.status !== "connecting") {
+      setStatus(c, { status: "connecting" });
+    }
+    const lifetime = new AbortController();
+    c.lifetime = lifetime;
+    c.gate = createGate();
+    void run(c, lifetime, c.gate);
+    return () => {
+      c.abort?.abort();
+      lifetime.abort();
+      if (c.lifetime === lifetime) c.lifetime = null;
+      c.gate.open();
+    };
+  }, [c, props.url]);
 
-  return {
-    connection: connection ?? c.connection,
-    send: c.send,
-  };
+  return c;
 };
 
 export const classify = (timeout: AbortSignal) =>

package/src/client/core.ts

@@ -1,27 +1,21 @@
+import { useEffect, useState } from "react";
 import { createChanges } from "./changes";
 import { getCommandsHost, getEmitHost, getStateHost } from "../host/host";
 import type { CommandsInvocation, CommandsListener } from "../host/host";
-import { recordMutations } from "./optimistic";
+import { recordMutations } from "../util/recordMutations";
+import { createMacrotaskPoster } from "../util/macrotask";
+import { createMethodProxy } from "../util/methodProxy";
 import type { StatewirePath } from "../wire/ops";
 import { StatewireSendError } from "../types";
-import type {
-  SendFailure as StatewireSendFailure,
-  StatewireStateSource,
-  StatewireTransport,
-  StatewireCommand,
-  StatewireCommandsProxy,
-  StatewireCommandUpdate,
-  StatewireOptimisticContext,
-  StatewireOptions,
-} from "../types";
-import type { StatewireConnection } from "../transports/sse";
+import type { Statewire } from "../types";
+import type { StatewireClient } from "../statewire";
 
-export const LIVE_CONNECTION: StatewireConnection = {
+export const LIVE_CONNECTION: StatewireClient.Connection = {
   status: "live",
   reconnect: () => {},
 };
 
-const failureOf = (error: unknown): StatewireSendFailure =>
+const failureOf = (error: unknown): StatewireClient.SendFailure =>
   error instanceof StatewireSendError
     ? error.failure
     : {
@@ -30,43 +24,15 @@ const failureOf = (error: unknown): StatewireSendFailure =>
         message: error instanceof Error ? error.message : String(error),
       };
 
-// 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.
-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);
-};
-
 type Overlay = { inv: CommandsInvocation; dropped: boolean };
 
-export type StatewireCore = ReturnType<typeof createStatewireCore>;
-
-export const createStatewireCore = (
-  getOptions: () => StatewireOptions<any, any, any>,
+const createCore = (
+  getOptions: () => StatewireClient.Options<any, any, any>,
 ) => {
-  let value: StatewireTransport<unknown> | null = null;
-  let source: StatewireStateSource | null = null;
+  let value: Statewire<unknown> | null = null;
+  let source: Statewire.StateSource | null = null;
   let overlays: Overlay[] = [];
-  let updates: StatewireCommandUpdate[] = [];
+  let updates: Statewire.CommandUpdate[] = [];
   let events: unknown[] = [];
   let pendingChanged: StatewirePath[] = [];
   let canonical: unknown;
@@ -74,11 +40,10 @@ export const createStatewireCore = (
   let overlayPaths: readonly StatewirePath[] = [];
   let notifiedPublished: unknown;
   let notifiedOverlayPaths: readonly StatewirePath[] = [];
-  let notifiedConnection: StatewireConnection | null = null;
+  let notifiedConnection: StatewireClient.Connection | null = null;
   let stale = false;
   let overlaysDirty = false;
   let flushing = false;
-  let disposed = false;
   const listeners = new Set<() => void>();
 
   const post = createMacrotaskPoster(() => {
@@ -87,7 +52,7 @@ export const createStatewireCore = (
   });
   let scheduled = false;
   const schedule = () => {
-    if (scheduled || disposed) return;
+    if (scheduled) return;
     scheduled = true;
     post();
   };
@@ -100,7 +65,7 @@ export const createStatewireCore = (
   const drainCanonical = () => {
     if (source) {
       pendingChanged.push(...source.takeChanged());
-      canonical = source.root();
+      canonical = source.snapshot();
     } else if (value && value.state !== canonical) {
       pendingChanged.push([]);
       canonical = value.state;
@@ -121,7 +86,7 @@ export const createStatewireCore = (
       for (const overlay of overlays) {
         if (overlay.dropped) continue;
         const { inv } = overlay;
-        const ctx: StatewireOptimisticContext = {
+        const ctx: StatewireClient.OptimisticContext = {
           ts: inv.ts,
           seq: inv.seq,
           ...(inv.clientId !== undefined && { clientId: inv.clientId }),
@@ -130,7 +95,7 @@ export const createStatewireCore = (
           const recorded = recordMutations(next, (draft) =>
             optimistic(
               draft as never,
-              { method: inv.method, params: inv.params } as StatewireCommand,
+              { method: inv.method, params: inv.params } as Statewire.Command,
               ctx,
             ),
           );
@@ -149,11 +114,11 @@ export const createStatewireCore = (
     overlayPaths = paths;
   };
 
-  const getConnection = (): StatewireConnection =>
+  const getConnection = (): StatewireClient.Connection =>
     value?.connection ?? LIVE_CONNECTION;
 
   const flush = () => {
-    if (disposed || !value) return;
+    if (!value) return;
     if (flushing) {
       schedule();
       return;
@@ -184,7 +149,7 @@ export const createStatewireCore = (
           options.onCommandChange?.(update, { state: published as never });
         }
       }
-      if (events.length > 0) {
+      if (events.length > 0 && published !== undefined) {
         const batch = events;
         events = [];
         for (const event of batch) {
@@ -204,8 +169,8 @@ export const createStatewireCore = (
 
   const note = (
     inv: CommandsInvocation,
-    status: StatewireCommandUpdate["status"],
-    extra?: { result?: unknown; failure?: StatewireSendFailure },
+    status: Statewire.CommandUpdate["status"],
+    extra?: { result?: unknown; failure?: StatewireClient.SendFailure },
   ) => {
     if (!getOptions().onCommandChange) return;
     updates.push({
@@ -251,8 +216,8 @@ export const createStatewireCore = (
     schedule();
   };
 
-  const attach = (next: StatewireTransport<unknown>) => {
-    if (disposed || next === value) return;
+  const attach = (next: Statewire<unknown>) => {
+    if (next === value) return;
     const prev = value;
     value = next;
     const nextSource =
@@ -294,48 +259,33 @@ export const createStatewireCore = (
     }
   };
 
-  const memo = new Map<string, (...params: unknown[]) => Promise<unknown>>();
-  const commands = new Proxy({} as StatewireCommandsProxy<any>, {
-    get: (_target, method) => {
-      if (typeof method !== "string") return undefined;
-      let fn = memo.get(method);
-      if (fn === undefined) {
-        fn = (...params: unknown[]) => {
-          if (!value) {
-            return Promise.reject(
-              new StatewireSendError({ fate: "aborted", cause: "unmount" }),
-            );
-          }
-          const send = (
-            value.commands as Record<
-              string,
-              (...args: unknown[]) => Promise<unknown>
-            >
-          )[method]!;
-          const promise = send(...params);
-          flush();
-          return promise;
-        };
-        memo.set(method, fn);
+  const commands = createMethodProxy<Statewire.CommandsProxy<any>>(
+    (method, params) => {
+      if (!value) {
+        return Promise.reject(
+          new StatewireSendError({ fate: "aborted", cause: "unmount" }),
+        );
       }
-      return fn;
+      const send = (
+        value.commands as Record<
+          string,
+          (...args: unknown[]) => Promise<unknown>
+        >
+      )[method]!;
+      const promise = send(...params);
+      flush();
+      return promise;
     },
-  });
+  );
 
   return {
     attach,
     detach,
-    dispose: () => {
-      detach();
-      disposed = true;
-    },
     getState: () => {
       recompute();
       return published;
     },
-    getConnection,
     commands,
-    flush,
     subscribe: (listener: () => void) => {
       listeners.add(listener);
       return () => {
@@ -344,3 +294,19 @@ export const createStatewireCore = (
     },
   };
 };
+
+export const useStatewireCore = (
+  getOptions: () => StatewireClient.Options<any, any, any>,
+  value: Statewire<unknown>,
+) => {
+  const [core] = useState(() => createCore(getOptions));
+  // Attach during render so the first snapshot reads the transport's state;
+  // re-attaching the same transport is a no-op and the single-slot host
+  // listeners make a swap land on the last writer.
+  core.attach(value);
+  useEffect(() => {
+    core.attach(value);
+  });
+  useEffect(() => () => core.detach(), [core]);
+  return core;
+};