statewire 0.9.1 → 0.10.0

package/src/client/connection.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from "react";
 import { flushTapSync } from "@assistant-ui/tap";
 import { reviveOps, reviveValue } from "../wire/meta";
-import { backoff } from "./timing";
+import { backoff, timing } from "./timing";
 import type { ConnectionState, StatewireRemoteProps } from "../transports/sse";
 import type { StatewireClient } from "../statewire";
 import type { StatewireHost } from "../host";
@@ -83,6 +83,8 @@ export type Conn = {
   hasSnapshot: boolean;
   lease: string | null;
   attempt: number;
+  authDenials: number;
+  liveAt: number | null;
   episode: Episode | null;
   awaitingHello: boolean;
   held: StatewireCmd[];
@@ -107,6 +109,108 @@ const protocolError = (message: string): never => {
   throw new Error(`statewire: protocol error: ${message}`);
 };
 
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isNonnegativeSafeInteger = (value: unknown): value is number =>
+  Number.isSafeInteger(value) && (value as number) >= 0;
+
+const isPositiveSafeInteger = (value: unknown): value is number =>
+  Number.isSafeInteger(value) && (value as number) > 0;
+
+const validateOptionalString = (value: unknown, field: string): void => {
+  if (value !== undefined && typeof value !== "string") {
+    protocolError(`${field} must be a string`);
+  }
+};
+
+const validateSynScalars = (syn: Record<string, unknown>) => {
+  if (syn["seq"] !== undefined && !isNonnegativeSafeInteger(syn["seq"])) {
+    protocolError("syn.seq must be a nonnegative safe integer");
+  }
+  if (syn["ctxSeq"] !== undefined && !isNonnegativeSafeInteger(syn["ctxSeq"])) {
+    protocolError("syn.ctxSeq must be a nonnegative safe integer");
+  }
+  if (syn["retry"] !== undefined && !isNonnegativeSafeInteger(syn["retry"])) {
+    protocolError("syn.retry must be a nonnegative safe integer");
+  }
+  validateOptionalString(syn["id"], "syn.id");
+  if (syn["idle"] !== undefined && typeof syn["idle"] !== "boolean") {
+    protocolError("syn.idle must be a boolean");
+  }
+  validateOptionalString(syn["record"], "syn.record");
+};
+
+export const validateRefusalSyn = (value: unknown): StatewireSyn => {
+  if (!isObject(value)) return protocolError("syn must be an object");
+  validateSynScalars(value);
+  if (
+    value["id"] !== undefined ||
+    value["idle"] !== undefined ||
+    value["record"] !== undefined
+  ) {
+    protocolError("invalid refusal syn");
+  }
+  if (
+    value["seq"] === undefined &&
+    value["ctxSeq"] === undefined &&
+    value["retry"] === undefined
+  ) {
+    protocolError("refusal syn has no watermarks or retry");
+  }
+  return value as StatewireSyn;
+};
+
+const validateCmd = (value: unknown): value is StatewireCmd => {
+  if (!isObject(value)) return protocolError("cmd entry must be an object");
+  if (!isPositiveSafeInteger(value["seq"])) {
+    protocolError("cmd.seq must be a positive safe integer");
+  }
+  validateOptionalString(value["type"], "cmd.type");
+  validateOptionalString(value["code"], "cmd.code");
+  validateOptionalString(value["message"], "cmd.message");
+  if (value["dur"] !== undefined && value["dur"] !== true) {
+    protocolError("cmd.dur must be true");
+  }
+  return true;
+};
+
+const validateFin = (value: unknown): value is StatewireHost.Fin => {
+  if (!isObject(value)) return protocolError("fin must be an object");
+  if (typeof value["reason"] !== "string") {
+    protocolError("fin.reason must be a string");
+  }
+  validateOptionalString(value["message"], "fin.message");
+  return true;
+};
+
+const validateEnvelope = (value: unknown): StatewireEnvelope => {
+  if (!isObject(value)) return protocolError("packet must be an object");
+  if (value["ops"] !== undefined && !Array.isArray(value["ops"])) {
+    protocolError("ops must be an array");
+  }
+  if (value["cmd"] !== undefined) {
+    const cmd = value["cmd"];
+    if (!Array.isArray(cmd)) return protocolError("cmd must be an array");
+    for (const entry of cmd) validateCmd(entry);
+  }
+  if (value["idle"] !== undefined && typeof value["idle"] !== "boolean") {
+    protocolError("idle must be a boolean");
+  }
+  if (value["next"] !== undefined) {
+    if (value["next"] !== true) protocolError("next must be true");
+    if (
+      value["cmd"] === undefined ||
+      value["ops"] !== undefined ||
+      value["fin"] !== undefined
+    ) {
+      protocolError("next must ride a cmd-only packet");
+    }
+  }
+  if (value["fin"] !== undefined) validateFin(value["fin"]);
+  return value as StatewireEnvelope;
+};
+
 // A hold's release delivers, never settles: fin and bare close both drain it.
 const releaseHeld = (c: Conn) => {
   if (c.held.length === 0) return;
@@ -117,38 +221,83 @@ const releaseHeld = (c: Conn) => {
 
 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 snapshotOf = (env: StatewireEnvelope): unknown[] => {
+  const ops = env.ops;
+  if (ops === undefined) return protocolError("hello missing snapshot");
+  if (ops.length !== 1 || !isObject(ops[0])) {
+    return protocolError("hello snapshot must be one root replace op");
+  }
+  const op = ops[0];
+  if (
+    op["op"] !== "replace" ||
+    !Array.isArray(op["path"]) ||
+    op["path"].length !== 0 ||
+    !Object.hasOwn(op, "value")
+  ) {
+    return protocolError("hello snapshot must be one root replace op");
+  }
+  return reviveOps(ops);
+};
+
+const helloSynOf = (env: StatewireEnvelope): StatewireSyn => {
+  if (!isObject(env.syn)) return protocolError("expected hello");
+  validateSynScalars(env.syn);
+  if (env.syn["retry"] !== undefined) {
+    protocolError("hello syn cannot carry retry");
+  }
+  return env.syn as StatewireSyn;
+};
+
 const handleHello = (c: Conn, env: StatewireEnvelope) => {
-  const syn = env.syn;
-  if (syn === undefined) return protocolError("expected hello");
-  c.awaitingHello = false;
-  c.hasSnapshot = true;
+  const syn = helloSynOf(env);
+  const ops = snapshotOf(env);
   c.ctx.onHello({
-    ops: env.ops === undefined ? [] : reviveOps(env.ops),
+    ops,
     syn,
   });
   c.ctx.onIdle(syn.idle ?? false);
-  c.attempt = 0;
+  c.awaitingHello = false;
+  c.hasSnapshot = true;
+  c.liveAt = Date.now();
+  c.authDenials = 0;
   c.episode = null;
   setStatus(c, { status: "live" });
 };
 
-const deliverEnvelope = (c: Conn, env: StatewireEnvelope) => {
-  if (env.syn !== undefined) {
-    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");
-    }
+let warnedUnknownSynFact = false;
+
+const warnUnknownSynFact = () => {
+  if (warnedUnknownSynFact) return;
+  warnedUnknownSynFact = true;
+  console.warn("statewire: ignoring unknown syn fact");
+};
+
+const deliverSyn = (c: Conn, value: unknown) => {
+  if (!isObject(value)) return protocolError("syn must be an object");
+  validateSynScalars(value);
+  if (value["record"] !== undefined || value["idle"] !== undefined) {
+    protocolError("invalid mid-stream syn");
+  }
+  if (
+    value["seq"] !== undefined ||
+    value["ctxSeq"] !== undefined ||
+    value["retry"] !== undefined
+  ) {
+    c.ctx.onRefusal(validateRefusalSyn(value));
+    return;
+  }
+  if (value["id"] !== undefined) return;
+  if (Object.keys(value).length === 0) {
+    protocolError("invalid mid-stream syn");
   }
+  warnUnknownSynFact();
+};
+
+const deliverEnvelope = (c: Conn, env: StatewireEnvelope) => {
+  if (env.syn !== undefined) deliverSyn(c, env.syn);
   if (env.ops !== undefined) {
     const held = c.held;
     c.held = [];
@@ -164,9 +313,20 @@ const deliverEnvelope = (c: Conn, env: StatewireEnvelope) => {
   if (typeof env.idle === "boolean") c.ctx.onIdle(env.idle);
 };
 
-const isTransientFinish = (
+const transientCauseOf = (
   reason: StatewireHost.Fin["reason"],
-): reason is "evicted" | "error" => reason === "evicted" || reason === "error";
+): Episode["cause"] => {
+  switch (reason) {
+    case "evicted":
+      return "evicted";
+    case "error":
+      return "error";
+    case "unauthorized":
+      return "unauthorized";
+    default:
+      return "error";
+  }
+};
 
 const settleFin = (c: Conn, fin: StatewireHost.Fin): AttemptOutcome => {
   let finish = fin;
@@ -182,12 +342,20 @@ const settleFin = (c: Conn, fin: StatewireHost.Fin): AttemptOutcome => {
     setStatus(c, { status: "idle" });
     return "idle";
   }
-  c.ctx.onFinish(finish);
-  if (isTransientFinish(finish.reason)) {
+  // An auth denial gets one immediate redial; a consecutive repeat parks as gone.
+  const denial = finish.reason === "unauthorized";
+  const terminal =
+    finish.reason === "gone" ||
+    finish.reason === "superseded" ||
+    (denial && c.authDenials > 0);
+  if (denial) c.authDenials += 1;
+  c.ctx.onFinish(terminal ? finish : { ...finish, reason: "error" });
+  if (!terminal) {
     c.episode = {
-      cause: finish.reason,
+      cause: transientCauseOf(finish.reason),
       ...(finish.message !== undefined && { message: finish.message }),
     };
+    if (denial) openGate(c.gate);
     return "reattach";
   }
   setStatus(c, {
@@ -200,11 +368,9 @@ const settleFin = (c: Conn, fin: StatewireHost.Fin): AttemptOutcome => {
 
 export const handleEnvelope = (
   c: Conn,
-  env: StatewireEnvelope,
+  value: unknown,
 ): AttemptOutcome | null => {
-  if (typeof env !== "object" || env === null) {
-    return protocolError("packet must be an object");
-  }
+  const env = validateEnvelope(value);
   if (c.awaitingHello) {
     if (env.fin !== undefined) return settleFin(c, env.fin);
     handleHello(c, env);
@@ -225,18 +391,20 @@ const scheduleRetry = (
   failure: string | undefined,
   immediate: boolean,
 ) => {
+  if (c.liveAt !== null && Date.now() - c.liveAt >= timing.backoffResetMs) {
+    c.attempt = 0;
+  }
+  c.liveAt = null;
   c.attempt += 1;
   c.episode ??= { cause: "dropped" };
   const delay = immediate ? 0 : backoff(c.attempt);
-  if (c.hasSnapshot) {
-    setStatus(c, {
-      status: "reconnecting",
-      ...c.episode,
-      attempt: c.attempt,
-      nextRetryAt: Date.now() + delay,
-      ...(failure !== undefined && { lastError: failure }),
-    });
-  }
+  setStatus(c, {
+    status: "reconnecting",
+    ...c.episode,
+    attempt: c.attempt,
+    nextRetryAt: Date.now() + delay,
+    ...(failure !== undefined && { lastError: failure }),
+  });
   return delay;
 };
 
@@ -244,10 +412,10 @@ const reconnectConn = (c: Conn) => {
   if (!c.lifetime) return;
   if (c.connection.status === "gone" || c.connection.status === "idle") {
     c.attempt = 0;
+    c.authDenials = 0;
     c.episode = { cause: "dropped" };
     flushTapSync(() => {
-      if (c.hasSnapshot) scheduleRetry(c, undefined, true);
-      else setStatus(c, { status: "connecting" });
+      scheduleRetry(c, undefined, true);
     });
   }
   openGate(c.gate);
@@ -303,6 +471,8 @@ export const useStatewireConn = (props: {
       hasSnapshot: false,
       lease: null,
       attempt: 0,
+      authDenials: 0,
+      liveAt: null,
       episode: null,
       awaitingHello: true,
       held: [],
@@ -325,6 +495,8 @@ export const useStatewireConn = (props: {
     c.hasSnapshot = false;
     c.lease = null;
     c.attempt = 0;
+    c.authDenials = 0;
+    c.liveAt = null;
     c.episode = null;
     if (c.connection.status !== "connecting") {
       setStatus(c, { status: "connecting" });

package/src/client/session.ts

@@ -1,17 +1,20 @@
-import { useEffect, useState } from "react";
+import { useContext, useEffect, useState } from "react";
 import { applyOps } from "../wire/ops";
 import type { StatewirePath } from "../wire/ops";
 import type { StatewireCmd, StatewireSyn } from "./connection";
-import { encodeParams, encodeValue, reviveResponse } from "../wire/meta";
+import {
+  encodeParams,
+  encodeValue,
+  reviveResponse,
+  reviveValue,
+} from "../wire/meta";
 import { bindCommandsHost } from "../host/host";
 import type { CommandsInvocation, CommandsListener } from "../host/host";
 import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
-import { createMemorySessionStore } from "./sessionStore";
-import type {
-  StatewireSessionRecord,
-  StatewireSessionStore,
-  StatewireSessionStoreOptions,
+import {
+  SessionStorageContext,
+  createMemorySessionStore,
 } from "./sessionStore";
 import { backoff } from "./timing";
 import { createMethodProxy } from "../util/methodProxy";
@@ -65,16 +68,19 @@ const rejectedSend = (
 
 type AttachState = "detached" | "attached" | "finished";
 
-export type StatewireSessionOptions = StatewireSessionStoreOptions & {
+export type StatewireSessionOptions = {
+  sessionStore?: StatewireClient.SessionStorage | undefined;
   onDone?: (() => void) | undefined;
 };
 
 type Session = {
-  record: StatewireSessionRecord;
+  record: StatewireClient.SessionRecord;
   ctx: StatewireRemoteProps;
   recordPersisted: boolean;
-  store: StatewireSessionStore;
+  store: StatewireClient.SessionStorage;
   ephemeral: boolean;
+  /** An ephemeral record died with its attach: the storage is off for good. */
+  deactivated: boolean;
   sessionKnown: boolean;
   durableSeq: number;
   resumeAt: number;
@@ -128,9 +134,25 @@ const sleepUntilWake = (s: Session, delayMs: number) =>
     s.waiters.push(waiter);
   });
 
-const setRecord = (s: Session, record: StatewireSessionRecord) => {
+const setRecord = (s: Session, record: StatewireClient.SessionRecord) => {
   s.record = record;
-  if (!s.ephemeral) s.store.save(record);
+  if (!s.deactivated) s.store.save(record);
+};
+
+const backlog = (s: Session): StatewireClient.SessionCommand[] =>
+  s.pending
+    .filter((p) => p.seq > s.durableSeq)
+    .map((p) => ({ seq: p.seq, ...p.command }));
+
+// Storage holds what a reload must resend: a command leaves at its dur, at a
+// server verdict, or at a record reset — never at a local channel death.
+const syncBacklog = (s: Session) => {
+  const commands = backlog(s);
+  const unchanged =
+    commands.length === s.record.commands.length &&
+    commands.every((c, i) => c.seq === s.record.commands[i]!.seq);
+  if (unchanged) return;
+  setRecord(s, { ...s.record, commands });
 };
 
 const setIdle = (s: Session, level: boolean) => {
@@ -223,7 +245,7 @@ const resetRecord = (s: Session, clientId: string) => {
   }
   s.pending = [];
   s.durableSeq = 0;
-  setRecord(s, { clientId, nextSeq: 1, ctxNextSeq: 1 });
+  setRecord(s, { clientId, nextSeq: 1, ctxNextSeq: 1, commands: [] });
   for (const old of survivors) {
     s.lifecycle?.onCovered?.(old.inv);
     enqueue(s, old.command, old.inv.params, old.resolve, old.reject);
@@ -241,23 +263,19 @@ const ephemeralDetach = (s: Session) => {
 };
 
 const rejectedFailure = (cmd: StatewireCmd): StatewireClient.SendFailure => {
-  const code =
-    cmd.code === undefined ||
-    cmd.code === "unknown-command" ||
-    cmd.code === "invalid-params"
-      ? cmd.code
-      : protocolError(`unknown rejected code: ${cmd.code}`);
   return {
     fate: "rejected",
     cause: "server",
-    ...(code !== undefined && { code }),
+    ...(cmd.code !== undefined && { code: cmd.code }),
     ...(cmd.message !== undefined && { message: cmd.message }),
     ...(cmd.payload !== undefined && { payload: cmd.payload }),
   };
 };
 
 const handleCmd = (s: Session, cmd: StatewireCmd) => {
-  if (typeof cmd.seq !== "number") protocolError("cmd entry missing seq");
+  if (!Number.isSafeInteger(cmd.seq) || cmd.seq <= 0) {
+    protocolError("cmd.seq must be a positive safe integer");
+  }
   if (cmd.dur === true) {
     s.durableSeq = Math.max(s.durableSeq, cmd.seq);
     for (const entry of s.pending) {
@@ -305,6 +323,7 @@ const handleCmd = (s: Session, cmd: StatewireCmd) => {
 
 const handleCmds = (s: Session, cmds: StatewireCmd[]) => {
   for (const cmd of cmds) handleCmd(s, cmd);
+  syncBacklog(s);
   wake(s);
 };
 
@@ -360,6 +379,7 @@ const handleHello = (
   s.frameFailures = 0;
   s.resumeAt = 0;
   s.ephemeral = record === "ephemeral";
+  if (s.ephemeral) s.deactivated = true;
   const [attachCmd, attachCtx] = s.attachLaneSeqs;
   s.attachLaneSeqs = [new Set(), new Set()];
   if (record === "resumed") {
@@ -372,6 +392,7 @@ const handleHello = (
     s.ctxPending = s.ctxPending.filter((c) => c.seq > ctxWatermark);
     for (const c of s.ctxPending) c.posted = attachCtx.has(c.seq);
     snapClocks(s, syn.seq ?? 0, ctxWatermark);
+    syncBacklog(s);
   } else {
     resetRecord(s, s.record.clientId);
   }
@@ -386,6 +407,7 @@ const handleOps = (
 ) => {
   ingestOps(s, ops);
   for (const cmd of cmds) handleCmd(s, cmd);
+  syncBacklog(s);
   publishIngested(s);
 };
 
@@ -402,7 +424,7 @@ const handleRefusal = (s: Session, syn: StatewireSyn) => {
     for (const c of s.ctxPending) c.posted = false;
   }
   if (typeof syn.retry === "number") {
-    s.resumeAt = Date.now() + Math.max(0, syn.retry);
+    s.resumeAt = Date.now() + syn.retry;
   }
   const firstCmd = s.pending.find((p) => !p.posted);
   const firstCtx = s.ctxPending.find((c) => !c.posted);
@@ -562,6 +584,7 @@ const start = (s: Session) => {
     s.recordPersisted = true;
     s.store.save(s.record);
   }
+  resume(s);
   s.running = true;
   void pump(s);
 };
@@ -586,7 +609,6 @@ const enqueue = (
   reject: (error: StatewireSendError) => void,
 ) => {
   const seq = s.record.nextSeq;
-  setRecord(s, { ...s.record, nextSeq: seq + 1 });
   const entry: Pending = {
     seq,
     command,
@@ -604,10 +626,41 @@ const enqueue = (
     reject,
   };
   s.pending.push(entry);
+  setRecord(s, { ...s.record, nextSeq: seq + 1, commands: backlog(s) });
   s.lifecycle?.onStart(entry.inv);
   void pump(s);
 };
 
+// A stored command cannot be told from one that reached the server: attempted
+// keeps a fresh record settling it lost instead of replaying it blind.
+const resume = (s: Session) => {
+  const stored = [...s.record.commands].sort((a, b) => a.seq - b.seq);
+  for (const { seq, ...command } of stored) {
+    const params =
+      command.meta === undefined
+        ? command.params
+        : (reviveValue([...command.params], command.meta) as unknown[]);
+    const entry: Pending = {
+      seq,
+      command,
+      inv: {
+        method: command.method,
+        params,
+        ts: Date.now(),
+        seq,
+        clientId: s.record.clientId,
+      },
+      attempted: true,
+      posted: false,
+      applied: false,
+      resolve: () => {},
+      reject: () => {},
+    };
+    s.pending.push(entry);
+    s.lifecycle?.onStart(entry.inv);
+  }
+};
+
 const sendCommand = (
   s: Session,
   method: string,
@@ -657,13 +710,25 @@ export const useStatewireSession = (
   options: StatewireSessionOptions,
 ): Session => {
   const [defaultStore] = useState(createMemorySessionStore);
-  const store = options.sessionStore ?? defaultStore;
+  const mounted = useContext(SessionStorageContext);
+  if (options.sessionStore !== undefined && mounted !== undefined) {
+    throw new Error(
+      "statewire: session storage is set twice — drop the transport's sessionStore or the client's storage.session",
+    );
+  }
+  const store = options.sessionStore ?? mounted ?? defaultStore;
   const [s] = useState((): Session => {
     const stored = store.load();
+    if (stored !== null && !Array.isArray(stored.commands)) {
+      throw new Error(
+        "statewire: session storage loaded a record without a commands array",
+      );
+    }
     const record = stored ?? {
       clientId: newClientId(),
       nextSeq: 1,
       ctxNextSeq: 1,
+      commands: [],
     };
     const session: Session = {
       record,
@@ -683,6 +748,7 @@ export const useStatewireSession = (
       recordPersisted: stored !== null,
       store,
       ephemeral: false,
+      deactivated: false,
       sessionKnown: false,
       durableSeq: 0,
       resumeAt: 0,

package/src/client/sessionStore.ts

@@ -1,20 +1,13 @@
-export type StatewireSessionRecord = {
-  clientId: string;
-  nextSeq: number;
-  ctxNextSeq: number;
-};
-
-export type StatewireSessionStore = {
-  load: () => StatewireSessionRecord | null;
-  save: (record: StatewireSessionRecord) => void;
-};
+import { createContext } from "react";
+import type { StatewireClient } from "../statewire";
 
-export type StatewireSessionStoreOptions = {
-  sessionStore?: StatewireSessionStore | undefined;
-};
+/** The session storage `useStatewire` mounts, read by the transport's session. */
+export const SessionStorageContext = createContext<
+  StatewireClient.SessionStorage | undefined
+>(undefined);
 
-export const createMemorySessionStore = (): StatewireSessionStore => {
-  let record: StatewireSessionRecord | null = null;
+export const createMemorySessionStore = (): StatewireClient.SessionStorage => {
+  let record: StatewireClient.SessionRecord | null = null;
   return {
     load: () => record,
     save: (next) => {

package/src/client/timing.ts

@@ -1,8 +1,16 @@
 export const timing = {
   backoffBaseMs: 250,
   backoffMaxMs: 30_000,
+  backoffResetMs: 30_000,
   heartbeatTimeoutMs: 30_000,
+  random: Math.random,
 };
 
-export const backoff = (attempt: number) =>
-  Math.min(timing.backoffBaseMs * 2 ** (attempt - 1), timing.backoffMaxMs);
+export const backoff = (attempt: number) => {
+  const limit = Math.min(
+    timing.backoffBaseMs * 2 ** (attempt - 1),
+    timing.backoffMaxMs,
+  );
+  const floor = Math.min(timing.backoffBaseMs, limit);
+  return Math.round(floor + (limit - floor) * timing.random());
+};