@irtio/bots 0.5.1 → 0.5.2

package/dist/index.d.ts

@@ -14,15 +14,37 @@ import { Correction, Room, RelayRoom, Transport, JoinOptions } from '@irtio/clie
  */
 
 /** The invariants every simulation checks, in report order. */
-declare const INVARIANT_NAMES: readonly ["schema-validity", "visibility-leak", "bandwidth", "handler-error", "correction-storm", "misprediction", "snaps", "disconnects"];
+declare const INVARIANT_NAMES: readonly ["schema-validity", "visibility-leak", "bandwidth", "handler-error", "correction-storm", "misprediction", "snaps", "disconnects", "tick-health"];
 type InvariantName = (typeof INVARIANT_NAMES)[number];
+/**
+ * D36: three states, not two. `unavailable` exists because the server's own tick counters cannot
+ * always be fetched, and reporting `ok` for a number nobody read is exactly the class of lie the
+ * M2 exit tests were built to catch. An `unavailable` invariant does not fail a run.
+ */
+type InvariantState = 'ok' | 'violation' | 'unavailable';
 interface InvariantResult {
     readonly name: InvariantName;
+    /** False only for `violation`. An `unavailable` invariant is not a failure. */
     readonly ok: boolean;
+    readonly state: InvariantState;
     readonly violations: number;
     /** One line a human can act on: the threshold, the peak, the first offenders. */
     readonly detail: string;
 }
+/**
+ * D36: what the server said about its own tick loop over the run window, as the caller managed to
+ * read it. Every field is optional because every field can be missing, and the report says which.
+ */
+interface TickHealthReading {
+    /** Tick overruns inside the run window (a delta, not a lifetime count). */
+    readonly overruns?: number;
+    /** The worst single tick in ms the server saw. Lifetime, not windowed. */
+    readonly maxTickMs?: number;
+    /** Why the numbers could not be read. Present ⇒ the invariant reports `unavailable`. */
+    readonly unavailable?: string;
+    /** Where the numbers came from, so a reader can go and check. */
+    readonly source?: string;
+}
 interface SpatialVisibilityContext {
     /**
      * The state the anchor and the judged positions are read from. Server truth when a test has it
@@ -60,6 +82,12 @@ interface InvariantThresholds {
     readonly mispredictionMagnitudeMax: number;
     /** `snaps`: tolerated cap-exceeded reconciliations (corrections past the resim window), per run. */
     readonly snapsMax: number;
+    /**
+     * `tick-health`: server tick overruns tolerated inside the run window. Zero by default, which
+     * is strict on purpose — a room dropping even one tick's backlog is shedding work a player
+     * paid for — and one `--overruns-max` away from being usable on a deliberately busy room.
+     */
+    readonly overrunsMax: number;
 }
 declare const DEFAULT_THRESHOLDS: InvariantThresholds;
 /**
@@ -213,13 +241,19 @@ interface ObserverOptions {
 declare class BotObserver {
     private readonly options;
     readonly ring: TraceRing;
-    readonly violations: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "misprediction" | "snaps" | "disconnects", string[]>;
-    readonly counts: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "misprediction" | "snaps" | "disconnects", number>;
+    readonly violations: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "misprediction" | "snaps" | "disconnects" | "tick-health", string[]>;
+    readonly counts: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "misprediction" | "snaps" | "disconnects" | "tick-health", number>;
     id: string;
     role: string;
     roomId: string;
     /** Set before `leave()`, so a deliberate teardown is not reported as a disconnect. */
     stopping: boolean;
+    /**
+     * D36: the last connection status this bot's client reported, recorded whatever it was. This
+     * is the *fact* of where the connection is — the room-gone watcher and the join-timeout
+     * message read it — while `disconnects` below stays the judgement, with its old rules.
+     */
+    lastStatus: string;
     framesIn: number;
     framesOut: number;
     bytesIn: number;
@@ -422,6 +456,11 @@ interface BuildReportOptions {
     readonly lags: readonly number[];
     readonly thresholds?: InvariantThresholds;
     readonly tracePath?: string | undefined;
+    /**
+     * D36: the server's own view of its tick loop over the run window. Absent ⇒ `tick-health`
+     * reports `unavailable`, which is the honest answer for a caller that could not read it.
+     */
+    readonly tickHealth?: TickHealthReading | undefined;
 }
 /** Folds the observers into the report `irtio simulate` prints and tests assert on. */
 declare function buildReport(options: BuildReportOptions): SimulationReport;
@@ -444,6 +483,21 @@ declare function buildReport(options: BuildReportOptions): SimulationReport;
 declare const DEFAULT_SEED = 96016;
 /** Trace ring size per bot. 20 bots × 4096 ≈ 80k headers, a few megabytes at worst. */
 declare const DEFAULT_TRACE_LIMIT = 4096;
+/**
+ * D36 defect A: the client's patience with `E_STARTING` is documented, correct, and unbounded —
+ * `session.start()` has no deadline, so a room that answers `starting` forever never settles the
+ * join and the run's duration timer (armed *after* the join) never even gets set. The bound
+ * belongs here rather than in the client, because other callers rely on that patience.
+ */
+declare const DEFAULT_JOIN_TIMEOUT_MS = 20000;
+/**
+ * D36: how long every bot may be disconnected at once before the run is called dead. A room that
+ * went away takes every socket with it; a room that restarted takes them for a moment and hands
+ * them back. This is the width of "for a moment".
+ */
+declare const DEFAULT_ROOM_GONE_GRACE_MS = 5000;
+/** Why a run stopped. `undefined` until it has. */
+type RunEnd = 'scripts' | 'duration' | 'room-gone';
 /** The room a bot holds: a full `Room` with a schema, or a schemaless `RelayRoom`. */
 type BotRoom<S> = S extends AnySchema ? Room<S> : RelayRoom;
 interface UntilOptions {
@@ -501,6 +555,18 @@ interface SpawnOptionsBase {
     readonly mispredictionMagnitudeMax?: number;
     /** `snaps` tolerance: cap-exceeded reconciliations per bot. Default: infinite. */
     readonly snapsMax?: number;
+    /** `tick-health` threshold: server tick overruns tolerated in the run window. Default 0. */
+    readonly overrunsMax?: number;
+    /**
+     * D36: how long one bot's initial join may take before `spawnBots` gives up on the whole run.
+     * Default {@link DEFAULT_JOIN_TIMEOUT_MS}; `0` restores the old unbounded wait.
+     */
+    readonly joinTimeoutMs?: number;
+    /**
+     * D36: how long every bot may be disconnected at once before the run ends as `room-gone`.
+     * Default {@link DEFAULT_ROOM_GONE_GRACE_MS}; `0` disables the watcher.
+     */
+    readonly roomGoneGraceMs?: number;
     /** @internal Wrap `webSocketTransport` to get at the socket (the reconnection scenarios). */
     readonly transport?: Transport;
 }
@@ -531,6 +597,17 @@ interface BotRunner<S = undefined> extends Iterable<Bot<S>> {
         bot: number;
         error: unknown;
     }[];
+    /**
+     * D36: what ended the run, once something has. `scripts` (every script returned), `duration`
+     * (the deadline fired) or `room-gone` (every bot was disconnected for longer than the grace).
+     */
+    readonly endedBy: RunEnd | undefined;
+    /**
+     * D36: hand the runner the server's own tick counters for the run window, taken however the
+     * caller can take them. Every report built afterwards carries the `tick-health` invariant;
+     * without this call it reports `unavailable`.
+     */
+    recordTickHealth(reading: TickHealthReading): void;
     /** Resolves when every script has finished; rejects with the first one that threw. */
     done(): Promise<void>;
     /** Stops the scripts, leaves every room, and returns the final report. */
@@ -538,6 +615,17 @@ interface BotRunner<S = undefined> extends Iterable<Bot<S>> {
     /** The report as of now — safe to call mid-run. */
     report(): SimulationReport;
 }
+/**
+ * D36: a join that never settled. Thrown by `spawnBots`, and the reason `irtio simulate` can say
+ * "the run was not performed" instead of exiting 13 with nothing printed.
+ */
+declare class JoinTimeoutError extends Error {
+    readonly bot: number;
+    readonly timeoutMs: number;
+    readonly lastStatus: string;
+    readonly name = "JoinTimeoutError";
+    constructor(bot: number, timeoutMs: number, lastStatus: string);
+}
 /** Spawns `n` real clients on one room, runs `script` on each, and watches every invariant. */
 declare function spawnBots<S extends AnySchema>(n: number, options: SpawnOptions<S>): Promise<BotRunner<S>>;
 declare function spawnBots(n: number, options?: RelaySpawnOptions): Promise<BotRunner<undefined>>;
@@ -591,4 +679,4 @@ interface RelayEchoScriptOptions {
  */
 declare function relayEchoScript(options?: RelayEchoScriptOptions): BotScript<undefined>;
 
-export { type Bot, BotObserver, type BotRoom, type BotRunner, type BotScript, type BotStats, type BuildReportOptions, type ConvergenceStats, DEFAULT_SEED, DEFAULT_THRESHOLDS, DEFAULT_TRACE_LIMIT, INVARIANT_NAMES, type InvariantName, type InvariantResult, type InvariantThresholds, type ObserverOptions, type RandomScriptOptions, type RelayEchoScriptOptions, type RelaySpawnOptions, type Rng, type SimulationReport, type SimulationTotals, type SpatialVisibilityContext, type SpawnOptions, type Trace, type TraceDump, type TraceEntry, TraceRing, type UntilOptions, type ValueContext, WriteLog, buildReport, convergenceStats, deltaVisibilityLeaks, frameName, frameVisibilityLeaks, freshValue, makeRng, makeTrace, nextValue, randomScript, relayEchoScript, snapshotVisibilityLeaks, spawnBots };
+export { type Bot, BotObserver, type BotRoom, type BotRunner, type BotScript, type BotStats, type BuildReportOptions, type ConvergenceStats, DEFAULT_JOIN_TIMEOUT_MS, DEFAULT_ROOM_GONE_GRACE_MS, DEFAULT_SEED, DEFAULT_THRESHOLDS, DEFAULT_TRACE_LIMIT, INVARIANT_NAMES, type InvariantName, type InvariantResult, type InvariantState, type InvariantThresholds, JoinTimeoutError, type ObserverOptions, type RandomScriptOptions, type RelayEchoScriptOptions, type RelaySpawnOptions, type Rng, type RunEnd, type SimulationReport, type SimulationTotals, type SpatialVisibilityContext, type SpawnOptions, type TickHealthReading, type Trace, type TraceDump, type TraceEntry, TraceRing, type UntilOptions, type ValueContext, WriteLog, buildReport, convergenceStats, deltaVisibilityLeaks, frameName, frameVisibilityLeaks, freshValue, makeRng, makeTrace, nextValue, randomScript, relayEchoScript, snapshotVisibilityLeaks, spawnBots };

package/dist/index.js

@@ -13,14 +13,16 @@ var INVARIANT_NAMES = [
   "correction-storm",
   "misprediction",
   "snaps",
-  "disconnects"
+  "disconnects",
+  "tick-health"
 ];
 var DEFAULT_THRESHOLDS = {
   budgetBytesPerSec: 128e3,
   correctionsPerSecMax: 5,
   handlerErrorsMax: 0,
   mispredictionMagnitudeMax: Number.POSITIVE_INFINITY,
-  snapsMax: Number.POSITIVE_INFINITY
+  snapsMax: Number.POSITIVE_INFINITY,
+  overrunsMax: 0
 };
 var widenedSchemas = /* @__PURE__ */ new WeakMap();
 function widenGrids(ext, slack) {
@@ -270,6 +272,12 @@ var BotObserver = class {
   roomId = "";
   /** Set before `leave()`, so a deliberate teardown is not reported as a disconnect. */
   stopping = false;
+  /**
+   * D36: the last connection status this bot's client reported, recorded whatever it was. This
+   * is the *fact* of where the connection is — the room-gone watcher and the join-timeout
+   * message read it — while `disconnects` below stays the judgement, with its old rules.
+   */
+  lastStatus = "connecting";
   framesIn = 0;
   framesOut = 0;
   bytesIn = 0;
@@ -353,6 +361,7 @@ var BotObserver = class {
   }
   /** `room.on('status')`: transitions away from a healthy connection, ignored during teardown. */
   onStatus(status) {
+    this.lastStatus = status;
     if (this.stopping) return;
     if (status !== "reconnecting" && status !== "closed") return;
     this.disconnects++;
@@ -809,7 +818,39 @@ function detailFor(name, observers, violations, thresholds) {
       const count = observers.reduce((sum, o) => sum + o.disconnects, 0);
       return count === 0 ? "every bot stayed connected" : `${count} disconnect(s)${examples(observers, name)}`;
     }
+    case "tick-health":
+      return "";
+  }
+}
+function tickHealthResult(reading, thresholds) {
+  const where = reading?.source !== void 0 ? ` (from ${reading.source})` : "";
+  if (reading === void 0 || reading.unavailable !== void 0) {
+    return {
+      name: "tick-health",
+      ok: true,
+      state: "unavailable",
+      violations: 0,
+      detail: reading?.unavailable ?? "the server was not asked for its tick counters, so this run says nothing about them"
+    };
+  }
+  if (reading.overruns === void 0) {
+    return {
+      name: "tick-health",
+      ok: true,
+      state: "unavailable",
+      violations: 0,
+      detail: `no overrun count came back${where}`
+    };
   }
+  const worst = reading.maxTickMs !== void 0 ? `, worst tick ${round(reading.maxTickMs)} ms` : "";
+  const violated = reading.overruns > thresholds.overrunsMax;
+  return {
+    name: "tick-health",
+    ok: !violated,
+    state: violated ? "violation" : "ok",
+    violations: violated ? reading.overruns : 0,
+    detail: `${reading.overruns} tick overrun(s) in the run window, tolerated ${thresholds.overrunsMax}${worst}${where}` + (violated ? " \u2014 the room fell behind and dropped the backlog" : "")
+  };
 }
 function buildReport(options) {
   const { observers, roomId, lags } = options;
@@ -817,9 +858,17 @@ function buildReport(options) {
   const durationMs = Math.max(1, options.durationMs);
   const seconds = durationMs / 1e3;
   const invariants = INVARIANT_NAMES.map((name) => {
+    if (name === "tick-health") return tickHealthResult(options.tickHealth, thresholds);
     const violations = total(observers, name);
     const ok = name === "handler-error" ? violations <= thresholds.handlerErrorsMax : violations === 0;
-    return { name, ok, violations, detail: detailFor(name, observers, violations, thresholds) };
+    const state = ok ? "ok" : "violation";
+    return {
+      name,
+      ok,
+      state,
+      violations,
+      detail: detailFor(name, observers, violations, thresholds)
+    };
   });
   const perBot = observers.map((o) => o.stats);
   const totals = {
@@ -947,11 +996,15 @@ function relayEchoScript(options = {}) {
 // src/spawn.ts
 import {
   joinRelay,
-  joinRoom
+  joinRoom,
+  webSocketTransport
 } from "@irtio/client";
 import { relaySchema, withBuiltins } from "@irtio/protocol";
 var DEFAULT_SEED = 96016;
 var DEFAULT_TRACE_LIMIT = 4096;
+var DEFAULT_JOIN_TIMEOUT_MS = 2e4;
+var DEFAULT_ROOM_GONE_GRACE_MS = 5e3;
+var ROOM_GONE_POLL_MS = 250;
 function per(value, index) {
   if (value === void 0) return void 0;
   return typeof value === "function" ? value(index) : value;
@@ -1025,6 +1078,42 @@ var BotImpl = class {
     }
   }
 };
+var JoinTimeoutError = class extends Error {
+  constructor(bot, timeoutMs, lastStatus) {
+    super(
+      `irtio bots: bot ${bot} did not finish joining within ${timeoutMs} ms (last status: ${lastStatus})` + (lastStatus === "starting" ? " \u2014 the room kept answering E_STARTING, so it never came up" : "")
+    );
+    this.bot = bot;
+    this.timeoutMs = timeoutMs;
+    this.lastStatus = lastStatus;
+  }
+  bot;
+  timeoutMs;
+  lastStatus;
+  name = "JoinTimeoutError";
+};
+async function withJoinTimeout(joining, index, timeoutMs, observer, sockets) {
+  if (timeoutMs <= 0) return joining;
+  let timer;
+  try {
+    return await Promise.race([
+      joining,
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+          for (const socket of sockets) {
+            try {
+              socket.close();
+            } catch {
+            }
+          }
+          reject(new JoinTimeoutError(index, timeoutMs, observer.lastStatus));
+        }, timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
 async function spawnBots(n, options = {}) {
   if (!Number.isInteger(n) || n < 1) {
     throw new Error(`irtio bots: spawnBots needs at least one bot, got ${String(n)}`);
@@ -1035,7 +1124,8 @@ async function spawnBots(n, options = {}) {
     correctionsPerSecMax: options.correctionsPerSecMax ?? DEFAULT_THRESHOLDS.correctionsPerSecMax,
     handlerErrorsMax: options.handlerErrorsMax ?? DEFAULT_THRESHOLDS.handlerErrorsMax,
     mispredictionMagnitudeMax: options.mispredictionMagnitudeMax ?? DEFAULT_THRESHOLDS.mispredictionMagnitudeMax,
-    snapsMax: options.snapsMax ?? DEFAULT_THRESHOLDS.snapsMax
+    snapsMax: options.snapsMax ?? DEFAULT_THRESHOLDS.snapsMax,
+    overrunsMax: options.overrunsMax ?? DEFAULT_THRESHOLDS.overrunsMax
   };
   const ext = options.schema ? withBuiltins(options.schema) : relaySchema;
   const seed = options.seed ?? DEFAULT_SEED;
@@ -1044,6 +1134,9 @@ async function spawnBots(n, options = {}) {
   const lags = [];
   const observers = [];
   const bots = [];
+  const joinTimeoutMs = options.joinTimeoutMs ?? DEFAULT_JOIN_TIMEOUT_MS;
+  const roomGoneGraceMs = options.roomGoneGraceMs ?? DEFAULT_ROOM_GONE_GRACE_MS;
+  const baseTransport = options.transport ?? webSocketTransport;
   async function joinOne(index, roomId2) {
     const observer = new BotObserver({
       index,
@@ -1056,22 +1149,31 @@ async function spawnBots(n, options = {}) {
     });
     const role = per(options.role, index);
     const name = per(options.name, index);
+    const sockets = [];
+    const transport = {
+      connect(url) {
+        const socket = baseTransport.connect(url);
+        sockets.push(socket);
+        return socket;
+      }
+    };
     const common = {
       room: roomId2,
       ...options.url !== void 0 ? { url: options.url } : {},
       ...options.key !== void 0 ? { key: options.key } : {},
       ...role !== void 0 ? { role } : {},
       ...name !== void 0 ? { name } : {},
-      ...options.transport !== void 0 ? { transport: options.transport } : {},
+      transport,
       onFrame: (dir, type, bytes) => observer.onFrame(dir, type, bytes),
       onStatus: (status) => observer.onStatus(status)
     };
-    const room = options.schema ? await joinRoom(options.schema, {
+    const joining = options.schema ? joinRoom(options.schema, {
       ...common,
       ...options.flushMs !== void 0 ? { writeIntervalMs: options.flushMs } : {},
       ...options.rpc !== void 0 ? { rpc: options.rpc } : {},
       ...options.physics !== void 0 ? { physics: options.physics } : {}
-    }) : await joinRelay(common);
+    }) : joinRelay(common);
+    const room = await withJoinTimeout(joining, index, joinTimeoutMs, observer, sockets);
     room.on("correct", (correction) => observer.onCorrection(correction));
     const prediction = room.prediction;
     if (prediction) observer.predictsBody = (c, id) => prediction.predicts(c, id);
@@ -1082,8 +1184,20 @@ async function spawnBots(n, options = {}) {
   bots.push(first);
   const roomId = first.room.id;
   if (n > 1) {
-    const rest = await Promise.all(Array.from({ length: n - 1 }, (_, i) => joinOne(i + 1, roomId)));
-    bots.push(...rest);
+    const rest = await Promise.allSettled(
+      Array.from({ length: n - 1 }, (_, i) => joinOne(i + 1, roomId))
+    );
+    const failure = rest.find((r) => r.status === "rejected");
+    if (failure !== void 0) {
+      for (const settled of rest) {
+        if (settled.status === "fulfilled") settled.value.room.leave();
+      }
+      first.room.leave();
+      throw failure.reason;
+    }
+    for (const settled of rest) {
+      if (settled.status === "fulfilled") bots.push(settled.value);
+    }
   }
   const scriptErrors = [];
   let firstError;
@@ -1101,36 +1215,69 @@ async function spawnBots(n, options = {}) {
     }
   });
   const finished = Promise.all(scripts).then(() => void 0);
+  let endedBy;
   let deadline;
   if (options.durationMs !== void 0) {
     deadline = setTimeout(() => {
+      endedBy ??= "duration";
       for (const bot of bots) bot.stop();
     }, options.durationMs);
-    deadline.unref?.();
   }
+  let goneSince = 0;
+  let goneTimer;
+  if (roomGoneGraceMs > 0) {
+    goneTimer = setInterval(() => {
+      const down = observers.every(
+        (o) => o.lastStatus === "reconnecting" || o.lastStatus === "closed"
+      );
+      if (!down) {
+        goneSince = 0;
+        return;
+      }
+      goneSince ||= Date.now();
+      if (Date.now() - goneSince < roomGoneGraceMs) return;
+      endedBy ??= "room-gone";
+      for (const bot of bots) bot.stop();
+    }, ROOM_GONE_POLL_MS);
+    goneTimer.unref?.();
+  }
+  void finished.then(() => {
+    endedBy ??= "scripts";
+    if (deadline) clearTimeout(deadline);
+    if (goneTimer) clearInterval(goneTimer);
+  });
   let stoppedAt;
+  let tickHealth;
   const rings = () => observers.map((o) => o.ring);
   const runner = {
     bots,
     roomId,
     trace: makeTrace(startedAt, rings),
     scriptErrors,
+    get endedBy() {
+      return endedBy;
+    },
     [Symbol.iterator]: () => bots[Symbol.iterator](),
     async done() {
       await finished;
       if (firstError !== void 0) throw firstError;
     },
+    recordTickHealth(reading) {
+      tickHealth = reading;
+    },
     report() {
       return buildReport({
         observers,
         roomId,
         durationMs: (stoppedAt ?? Date.now()) - startedAt,
         lags,
-        thresholds
+        thresholds,
+        tickHealth
       });
     },
     async stop() {
       if (deadline) clearTimeout(deadline);
+      if (goneTimer) clearInterval(goneTimer);
       for (const bot of bots) bot.stop();
       await finished;
       stoppedAt ??= Date.now();
@@ -1143,10 +1290,13 @@ async function spawnBots(n, options = {}) {
 }
 export {
   BotObserver,
+  DEFAULT_JOIN_TIMEOUT_MS,
+  DEFAULT_ROOM_GONE_GRACE_MS,
   DEFAULT_SEED,
   DEFAULT_THRESHOLDS,
   DEFAULT_TRACE_LIMIT,
   INVARIANT_NAMES,
+  JoinTimeoutError,
   TraceRing,
   WriteLog,
   buildReport,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/bots",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "irtio bot runtime: N real clients, scripted behaviours, trace recorder, built-in invariants",
   "license": "MIT",
   "publishConfig": {
@@ -19,10 +19,10 @@
     "dist"
   ],
   "dependencies": {
-    "@irtio/client": "0.5.1",
-    "@irtio/protocol": "0.5.1",
-    "@irtio/runtime": "0.5.1",
-    "@irtio/schema": "0.5.1"
+    "@irtio/client": "0.5.2",
+    "@irtio/runtime": "0.5.2",
+    "@irtio/schema": "0.5.2",
+    "@irtio/protocol": "0.5.2"
   },
   "scripts": {
     "build": "tsup",