statewire 0.8.0 → 0.9.0

package/src/client/connection.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from "react";
 import { flushTapSync } from "@assistant-ui/tap";
-import { reviveOps, reviveResponse, reviveValue } from "../wire/meta";
-import { retryDelay } from "./timing";
+import { reviveOps, reviveValue } from "../wire/meta";
+import { backoff } from "./timing";
 import type { ConnectionState, StatewireRemoteProps } from "../transports/sse";
 import type { StatewireClient } from "../statewire";
 import type { StatewireHost } from "../host";
@@ -11,65 +11,72 @@ export type Episode = {
   message?: string;
 };
 
-export type StatewireResponse = {
+export type StatewireCmd = {
   seq: number;
-  type: "accepted" | "rejected" | "pending" | "crashed" | "result-unavailable";
+  type?: "applied" | "result" | "rejected" | "failed" | "crashed" | "expired";
   code?: string;
   message?: string;
   payload?: unknown;
   meta?: unknown;
+  /** Cumulative: resending through this seq will never be needed. */
+  dur?: boolean;
 };
 
 export type StatewireSyn = {
-  lastSeq: number;
-  lease?: string;
+  seq?: number;
+  ctxSeq?: number;
+  record?: "fresh" | "resumed" | "ephemeral";
+  id?: string;
+  idle?: boolean;
+  retry?: number;
 };
 
 export type StatewireEnvelope = {
   ops?: unknown[];
-  res?: StatewireResponse[];
-  ack?: number;
+  cmd?: StatewireCmd[];
+  next?: true;
+  idle?: boolean;
   syn?: StatewireSyn;
   fin?: StatewireHost.Fin;
 };
 
-const createGate = () => {
-  let latched = false;
-  let wake: (() => void) | undefined;
-  return {
-    take: () => {
-      const was = latched;
-      latched = false;
-      return was;
-    },
-    wait: (timeoutMs?: number) => {
-      if (latched) {
-        latched = false;
-        return Promise.resolve();
-      }
-      return new Promise<void>((resolve) => {
-        const timer =
-          timeoutMs === undefined
-            ? undefined
-            : setTimeout(() => {
-                wake = undefined;
-                resolve();
-              }, timeoutMs);
-        wake = () => {
-          clearTimeout(timer);
-          wake = undefined;
-          resolve();
-        };
-      });
-    },
-    open: () => {
-      if (wake) wake();
-      else latched = true;
-    },
-  };
+export type Gate = { latched: boolean; wake: (() => void) | undefined };
+
+const newGate = (): Gate => ({ latched: false, wake: undefined });
+
+const takeGate = (g: Gate) => {
+  const was = g.latched;
+  g.latched = false;
+  return was;
 };
 
-export type Gate = ReturnType<typeof createGate>;
+const waitGate = (g: Gate, timeoutMs?: number) => {
+  if (g.latched) {
+    g.latched = false;
+    return Promise.resolve();
+  }
+  return new Promise<void>((resolve) => {
+    const timer =
+      timeoutMs === undefined
+        ? undefined
+        : setTimeout(() => {
+            g.wake = undefined;
+            resolve();
+          }, timeoutMs);
+    g.wake = () => {
+      clearTimeout(timer);
+      g.wake = undefined;
+      resolve();
+    };
+  });
+};
+
+const openGate = (g: Gate) => {
+  if (g.wake) g.wake();
+  else g.latched = true;
+};
+
+export type AttemptOutcome = "stop" | "reattach" | "ended" | "idle";
 
 export type Conn = {
   connection: StatewireClient.Connection;
@@ -77,14 +84,14 @@ export type Conn = {
   lease: string | null;
   attempt: number;
   episode: Episode | null;
+  awaitingHello: boolean;
+  held: StatewireCmd[];
   gate: Gate;
   abort: AbortController | null;
   lifetime: AbortController | null;
   ctx: StatewireRemoteProps;
   onChange: (connection: StatewireClient.Connection) => void;
-  attemptOnce: (
-    abort: AbortController,
-  ) => Promise<"stop" | "reattach" | "ended">;
+  attemptOnce: (abort: AbortController) => Promise<AttemptOutcome>;
   notify: (connection: StatewireClient.Connection) => void;
   reconnect: () => void;
 };
@@ -96,84 +103,131 @@ const setStatus = (c: Conn, next: ConnectionState) => {
   if (changed) c.onChange(c.connection);
 };
 
-const deliverEnvelope = (
-  c: Conn,
-  env: Pick<StatewireEnvelope, "ops" | "res" | "ack" | "syn">,
-) => {
-  if (env.syn?.lease !== undefined) c.lease = env.syn.lease;
-  const ctx = c.ctx;
-  const ops = env.ops === undefined ? [] : reviveOps(env.ops);
-  const res = env.res?.map(reviveResponse);
+const protocolError = (message: string): never => {
+  throw new Error(`statewire: protocol error: ${message}`);
+};
+
+// A hold's release delivers, never settles: fin and bare close both drain it.
+const releaseHeld = (c: Conn) => {
+  if (c.held.length === 0) return;
+  const held = c.held;
+  c.held = [];
+  c.ctx.onCmds(held);
+};
+
+const cmdsOf = (env: StatewireEnvelope): StatewireCmd[] => {
+  if (env.cmd === undefined) return [];
+  if (!Array.isArray(env.cmd)) return protocolError("cmd must be an array");
+  return env.cmd;
+};
+
+const handleHello = (c: Conn, env: StatewireEnvelope) => {
+  const syn = env.syn;
+  if (syn === undefined) return protocolError("expected hello");
+  c.awaitingHello = false;
+  c.hasSnapshot = true;
+  c.ctx.onHello({
+    ops: env.ops === undefined ? [] : reviveOps(env.ops),
+    syn,
+  });
+  c.ctx.onIdle(syn.idle ?? false);
+  c.attempt = 0;
+  c.episode = null;
+  setStatus(c, { status: "live" });
+};
+
+const deliverEnvelope = (c: Conn, env: StatewireEnvelope) => {
   if (env.syn !== undefined) {
-    ctx.onSnapshot({ ops, lastSeq: env.syn.lastSeq });
-    c.hasSnapshot = true;
-  } else if (
-    env.ops !== undefined ||
-    env.res !== undefined ||
-    env.ack !== undefined
-  ) {
-    ctx.onOps({
-      ops,
-      ...(res !== undefined && { res }),
-      ...(env.ack !== undefined && { ack: env.ack }),
+    const syn = env.syn;
+    if (
+      syn.seq !== undefined ||
+      syn.ctxSeq !== undefined ||
+      syn.retry !== undefined
+    ) {
+      c.ctx.onRefusal(syn);
+    } else if (syn.id === undefined) {
+      protocolError("invalid mid-stream syn");
+    }
+  }
+  if (env.ops !== undefined) {
+    const held = c.held;
+    c.held = [];
+    c.ctx.onOps({
+      ops: reviveOps(env.ops),
+      cmds: [...held, ...cmdsOf(env)],
     });
+  } else if (env.cmd !== undefined) {
+    const cmds = cmdsOf(env);
+    if (env.next === true) c.held.push(...cmds);
+    else c.ctx.onCmds(cmds);
   }
+  if (typeof env.idle === "boolean") c.ctx.onIdle(env.idle);
 };
 
 const isTransientFinish = (
   reason: StatewireHost.Fin["reason"],
 ): reason is "evicted" | "error" => reason === "evicted" || reason === "error";
 
-const settleEnvelope = (
-  c: Conn,
-  env: StatewireEnvelope,
-): "stop" | "reattach" | null => {
-  let finish = env.fin;
-  if (finish) {
-    if (finish.meta !== undefined) {
-      const { meta, ...rest } = finish;
-      finish = { ...rest, payload: reviveValue(rest.payload, meta) };
-    }
-    c.ctx.onFinish(finish);
-    if (isTransientFinish(finish.reason)) {
-      c.episode = {
-        cause: finish.reason,
-        ...(finish.message !== undefined && { message: finish.message }),
-      };
-      return "reattach";
-    }
-    setStatus(c, {
-      status: "gone",
-      ...(finish.message !== undefined && { message: finish.message }),
-      ...(finish.payload !== undefined && { payload: finish.payload }),
-    });
-    return "stop";
+const settleFin = (c: Conn, fin: StatewireHost.Fin): AttemptOutcome => {
+  let finish = fin;
+  if (finish.meta !== undefined) {
+    const { meta, ...rest } = finish;
+    finish = { ...rest, payload: reviveValue(rest.payload, meta) };
   }
-  if (c.connection.status !== "live") {
+  releaseHeld(c);
+  if (finish.reason === "idle") {
+    c.ctx.onIdle(true);
     c.attempt = 0;
     c.episode = null;
-    setStatus(c, { status: "live" });
+    setStatus(c, { status: "idle" });
+    return "idle";
   }
-  return null;
+  c.ctx.onFinish(finish);
+  if (isTransientFinish(finish.reason)) {
+    c.episode = {
+      cause: finish.reason,
+      ...(finish.message !== undefined && { message: finish.message }),
+    };
+    return "reattach";
+  }
+  setStatus(c, {
+    status: "gone",
+    ...(finish.message !== undefined && { message: finish.message }),
+    ...(finish.payload !== undefined && { payload: finish.payload }),
+  });
+  return "stop";
 };
 
 export const handleEnvelope = (
   c: Conn,
   env: StatewireEnvelope,
-): "stop" | "reattach" | null => {
+): AttemptOutcome | null => {
+  if (typeof env !== "object" || env === null) {
+    return protocolError("packet must be an object");
+  }
+  if (c.awaitingHello) {
+    if (env.fin !== undefined) return settleFin(c, env.fin);
+    handleHello(c, env);
+    return null;
+  }
   deliverEnvelope(c, env);
-  return settleEnvelope(c, env);
+  if (env.fin !== undefined) return settleFin(c, env.fin);
+  if (c.connection.status !== "live") {
+    c.attempt = 0;
+    c.episode = null;
+    setStatus(c, { status: "live" });
+  }
+  return null;
 };
 
 const scheduleRetry = (
   c: Conn,
   failure: string | undefined,
   immediate: boolean,
-  cause?: unknown,
 ) => {
   c.attempt += 1;
   c.episode ??= { cause: "dropped" };
-  const delay = immediate ? 0 : retryDelay(cause, c.attempt);
+  const delay = immediate ? 0 : backoff(c.attempt);
   if (c.hasSnapshot) {
     setStatus(c, {
       status: "reconnecting",
@@ -188,7 +242,7 @@ const scheduleRetry = (
 
 const reconnectConn = (c: Conn) => {
   if (!c.lifetime) return;
-  if (c.connection.status === "gone") {
+  if (c.connection.status === "gone" || c.connection.status === "idle") {
     c.attempt = 0;
     c.episode = { cause: "dropped" };
     flushTapSync(() => {
@@ -196,7 +250,7 @@ const reconnectConn = (c: Conn) => {
       else setStatus(c, { status: "connecting" });
     });
   }
-  c.gate.open();
+  openGate(c.gate);
   c.abort?.abort();
 };
 
@@ -205,30 +259,33 @@ const run = async (c: Conn, lifetime: AbortController, gate: Gate) => {
   while (alive()) {
     const abort = new AbortController();
     c.abort = abort;
+    c.awaitingHello = true;
+    c.held = [];
+    let outcome: AttemptOutcome | undefined;
     let failure: string | undefined;
-    let cause: unknown;
-    let gone = false;
     try {
-      gone = (await c.attemptOnce(abort)) === "stop";
+      outcome = await c.attemptOnce(abort);
     } catch (error) {
       if (!abort.signal.aborted) {
         failure =
           error instanceof Error && error.message ? error.message : "network";
-        cause = error;
       }
     }
     abort.abort();
     if (!alive()) return;
-    if (gone) {
-      await gate.wait();
+    flushTapSync(() => {
+      releaseHeld(c);
+      c.ctx.onDetach();
+    });
+    if (!alive()) return;
+    if (outcome === "stop" || outcome === "idle") {
+      await waitGate(gate);
       continue;
     }
-    const immediate = gate.take();
-    const delay = flushTapSync(() =>
-      scheduleRetry(c, failure, immediate, cause),
-    );
+    const immediate = takeGate(gate);
+    const delay = flushTapSync(() => scheduleRetry(c, failure, immediate));
     if (delay === 0) continue;
-    await gate.wait(delay);
+    await waitGate(gate, delay);
   }
 };
 
@@ -236,10 +293,7 @@ export const useStatewireConn = (props: {
   url: string;
   onChange?: ((connection: StatewireClient.Connection) => void) | undefined;
   ctx: StatewireRemoteProps;
-  attemptOnce: (
-    c: Conn,
-    abort: AbortController,
-  ) => Promise<"stop" | "reattach" | "ended">;
+  attemptOnce: (c: Conn, abort: AbortController) => Promise<AttemptOutcome>;
 }): Conn => {
   const latest = useRef(props);
   latest.current = props;
@@ -250,10 +304,14 @@ export const useStatewireConn = (props: {
       lease: null,
       attempt: 0,
       episode: null,
+      awaitingHello: true,
+      held: [],
       abort: null,
-      gate: createGate(),
+      gate: newGate(),
       lifetime: null,
-      ctx: props.ctx,
+      get ctx() {
+        return latest.current.ctx;
+      },
       onChange: (connection) => latest.current.onChange?.(connection),
       attemptOnce: (abort) => latest.current.attemptOnce(conn, abort),
       notify: setConnection,
@@ -273,13 +331,13 @@ export const useStatewireConn = (props: {
     }
     const lifetime = new AbortController();
     c.lifetime = lifetime;
-    c.gate = createGate();
+    c.gate = newGate();
     void run(c, lifetime, c.gate);
     return () => {
       c.abort?.abort();
       lifetime.abort();
       if (c.lifetime === lifetime) c.lifetime = null;
-      c.gate.open();
+      openGate(c.gate);
     };
   }, [c, props.url]);
 
@@ -288,14 +346,3 @@ export const useStatewireConn = (props: {
 
 export const classify = (timeout: AbortSignal) =>
   new Error(timeout.aborted ? "timeout" : "network");
-
-export const parseRetryAfter = (header: string | null): number | undefined => {
-  if (!header) return undefined;
-  const value = header.trim();
-  if (/^\d+$/.test(value)) return Number(value) * 1000;
-  const date = Date.parse(value);
-  return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
-};
-
-export const overloadedError = (retryAfterMs?: number) =>
-  Object.assign(new Error("overloaded"), { retryAfterMs });