statewire 0.9.0 → 0.9.2

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,7 @@ export type Conn = {
   hasSnapshot: boolean;
   lease: string | null;
   attempt: number;
+  liveAt: number | null;
   episode: Episode | null;
   awaitingHello: boolean;
   held: StatewireCmd[];
@@ -107,6 +108,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 +220,82 @@ 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.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 +311,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,10 +340,11 @@ const settleFin = (c: Conn, fin: StatewireHost.Fin): AttemptOutcome => {
     setStatus(c, { status: "idle" });
     return "idle";
   }
-  c.ctx.onFinish(finish);
-  if (isTransientFinish(finish.reason)) {
+  const terminal = finish.reason === "gone" || finish.reason === "superseded";
+  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 }),
     };
     return "reattach";
@@ -200,11 +359,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 +382,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;
 };
 
@@ -246,8 +405,7 @@ const reconnectConn = (c: Conn) => {
     c.attempt = 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 +461,7 @@ export const useStatewireConn = (props: {
       hasSnapshot: false,
       lease: null,
       attempt: 0,
+      liveAt: null,
       episode: null,
       awaitingHello: true,
       held: [],
@@ -325,6 +484,7 @@ export const useStatewireConn = (props: {
     c.hasSnapshot = false;
     c.lease = null;
     c.attempt = 0;
+    c.liveAt = null;
     c.episode = null;
     if (c.connection.status !== "connecting") {
       setStatus(c, { status: "connecting" });

package/src/client/session.ts

@@ -241,23 +241,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) {
@@ -402,7 +398,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);

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());
+};

package/src/host.ts

@@ -56,6 +56,7 @@ export namespace StatewireHost {
     reason:
       | "evicted"
       | "error"
+      | "unauthorized"
       | "gone"
       | "superseded"
       | "idle"

package/src/statewire.ts

@@ -198,7 +198,7 @@ export namespace StatewireClient {
     | {
         fate: "rejected";
         cause: "server";
-        code?: "unknown-command" | "invalid-params";
+        code?: string;
         message?: string;
         payload?: unknown;
       }

package/src/transports/sse.ts

@@ -7,6 +7,7 @@ import {
   classify,
   handleEnvelope,
   useStatewireConn,
+  validateRefusalSyn,
 } from "../client/connection";
 import type {
   AttemptOutcome,
@@ -162,7 +163,7 @@ const attemptStream = async (
     clearTimeout(headerTimer);
   }
   if (res.status === 401) {
-    if (stale) c.episode = { cause: "unauthorized" };
+    c.episode = { cause: "unauthorized" };
     auth.stale = true;
     throw new Error("unauthorized");
   }
@@ -206,9 +207,9 @@ const postFrame = async (
 // Delta-seconds only; anything else reads as absent.
 const retryAfterMs = (res: Response): number | null => {
   const header = res.headers.get("retry-after")?.trim();
-  return header !== undefined && /^\d+$/.test(header)
-    ? Number(header) * 1000
-    : null;
+  if (header === undefined || !/^\d+$/.test(header)) return null;
+  const retry = Number(header) * 1000;
+  return Number.isSafeInteger(retry) ? retry : null;
 };
 
 const refusalSyn = async (res: Response): Promise<StatewireSyn> => {
@@ -219,7 +220,7 @@ const refusalSyn = async (res: Response): Promise<StatewireSyn> => {
   if (typeof syn !== "object" || syn === null) {
     throw new Error(`HTTP ${res.status}`);
   }
-  return syn;
+  return validateRefusalSyn(syn);
 };
 
 const sendFrame = async (

package/src/transports/ws.ts

@@ -27,7 +27,6 @@ type WsChannel = {
 const OPEN = 1;
 
 export const WS_SUBPROTOCOL = "statewire.v1";
-const UNAUTHORIZED_CLOSE = 4401;
 
 const socketUrl = async (
   options: StatewireClient.WSOptions,
@@ -64,7 +63,6 @@ const runSocket = (
   w: WsChannel,
   ws: WebSocket,
   frame: string,
-  staleAuth: boolean,
   abort: AbortController,
 ): Promise<AttemptOutcome> =>
   new Promise((resolve, reject) => {
@@ -110,6 +108,7 @@ const runSocket = (
       try {
         const done = flushTapSync(() => handleEnvelope(c, env));
         if (done) {
+          if (env.fin?.reason === "unauthorized") w.authStale = true;
           outcome = done;
           ws.close();
         }
@@ -117,15 +116,11 @@ const runSocket = (
         fail(error);
       }
     };
-    ws.onclose = (event?: { code?: number }) => {
+    ws.onclose = () => {
       closed = true;
       clearTimeout(timer);
       if (outcome) resolve(outcome);
-      else if (event?.code === UNAUTHORIZED_CLOSE) {
-        if (staleAuth) c.episode = { cause: "unauthorized" };
-        w.authStale = true;
-        reject(new Error("unauthorized"));
-      } else reject(new Error(timedOut ? "timeout" : "network"));
+      else reject(new Error(timedOut ? "timeout" : "network"));
     };
   });
 
@@ -154,7 +149,7 @@ const attemptSocket = async (
           : protocols;
     ws = new WS(url, [WS_SUBPROTOCOL, ...extra]);
     w.socket = ws;
-    return await runSocket(c, w, ws, frame, stale, abort);
+    return await runSocket(c, w, ws, frame, abort);
   } finally {
     if (w.socket === ws) w.socket = null;
   }

package/src/wire/ops.ts

@@ -147,6 +147,9 @@ const applyOpToDraft = (box: { state: unknown }, op: Statewire.Op): void => {
   }
 };
 
+const isMountPlaneOp = (op: { op?: unknown; doc?: unknown }) =>
+  "doc" in op || op.op === "mount" || op.op === "unmount";
+
 const warnedOps = new Set<unknown>();
 const warnUnknownOp = (type: unknown) => {
   if (warnedOps.has(type)) return;
@@ -179,6 +182,7 @@ export const applyOps = (
 } => {
   const mutable: Statewire.Op[] = [];
   for (const op of ops as Statewire.Op[]) {
+    if (isMountPlaneOp(op)) continue;
     if (op.op === "replace" || op.op === "add" || op.op === "remove") {
       mutable.push(op);
     } else {