@irtio/testing 0.1.0

package/dist/index.js

@@ -0,0 +1,469 @@
+import {
+  InProcessSocket,
+  TRACE_TAIL,
+  TestHarness,
+  clockScheduler,
+  divergence,
+  matchers,
+  materialize,
+  toHaveConverged,
+  toHaveNoVisibilityLeaks,
+  toHaveRejected,
+  toStayUnderBandwidth
+} from "./chunk-O3OZKC3D.js";
+
+// src/relay-harness.ts
+import { joinRelay } from "@irtio/client";
+import {
+  ErrorCode,
+  FrameType,
+  PRESENCE_COLLECTION,
+  decodeFrame,
+  decodeHello,
+  decodeMsg,
+  decodePing,
+  encodeErrorPayload,
+  encodeFrame,
+  encodeMsg,
+  encodePong,
+  encodeWelcome,
+  formatError,
+  relaySchema
+} from "@irtio/protocol";
+import { Mulberry32 } from "@irtio/runtime";
+import { FakeClock, frameTypeName } from "@irtio/runtime/test";
+import {
+  createDirtySet,
+  createState,
+  encodeDelta,
+  encodeSnapshot,
+  markAdd,
+  markField,
+  markRemove
+} from "@irtio/schema";
+var TEST_URL = "ws://localhost:7070";
+var TEST_KEY = "test-relay";
+var DEFAULT_MAX_CLIENTS = 64;
+var MICROTASK_TURNS = 8;
+var SETTLE_ROUNDS = 64;
+var JOIN_TIMEOUT_MS = 3e4;
+var DROPPABLE = /* @__PURE__ */ new Set([FrameType.MSG]);
+async function microtasks(turns = MICROTASK_TURNS) {
+  for (let i = 0; i < turns; i++) await Promise.resolve();
+}
+var CLIENTS = relaySchema.collection(PRESENCE_COLLECTION);
+function fieldIndex(name) {
+  const idx = CLIENTS.fieldIndex.get(name);
+  if (idx === void 0) throw new Error(`relaySchema presence has no ${name} field`);
+  return idx;
+}
+var ROLE_IDX = fieldIndex("role");
+var NAME_IDX = fieldIndex("name");
+var CONNECTED_IDX = fieldIndex("connected");
+var RelayState = class {
+  state = createState(relaySchema);
+  tick = 0;
+  get clients() {
+    return this.state[PRESENCE_COLLECTION];
+  }
+  has(clientId) {
+    return this.clients.has(clientId);
+  }
+  get size() {
+    return this.clients.size;
+  }
+  add(clientId, role, name) {
+    const dirty = createDirtySet();
+    const existing = this.clients.get(clientId);
+    if (existing) {
+      existing.role = role;
+      existing.name = name;
+      existing.connected = true;
+      markField(dirty, PRESENCE_COLLECTION, clientId, [ROLE_IDX]);
+      markField(dirty, PRESENCE_COLLECTION, clientId, [NAME_IDX]);
+      markField(dirty, PRESENCE_COLLECTION, clientId, [CONNECTED_IDX]);
+    } else {
+      this.clients.add(clientId, { clientId, role, name, connected: true }, { owner: "" });
+      markAdd(dirty, PRESENCE_COLLECTION, clientId);
+    }
+    this.tick++;
+    return encodeDelta(relaySchema, this.state, dirty, { tick: this.tick });
+  }
+  setConnected(clientId, connected) {
+    const rec = this.clients.get(clientId);
+    if (!rec || rec.connected === connected) return void 0;
+    rec.connected = connected;
+    const dirty = createDirtySet();
+    markField(dirty, PRESENCE_COLLECTION, clientId, [CONNECTED_IDX]);
+    this.tick++;
+    return encodeDelta(relaySchema, this.state, dirty, { tick: this.tick });
+  }
+  remove(clientId) {
+    if (!this.clients.remove(clientId)) return void 0;
+    const dirty = createDirtySet();
+    markRemove(dirty, PRESENCE_COLLECTION, clientId);
+    this.tick++;
+    return encodeDelta(relaySchema, this.state, dirty, { tick: this.tick });
+  }
+  advance() {
+    return ++this.tick;
+  }
+  snapshot() {
+    return encodeSnapshot(relaySchema, this.state, { tick: this.tick });
+  }
+};
+var TestRelayHarness = class {
+  clock = new FakeClock();
+  scheduler;
+  rng;
+  relay = new RelayState();
+  roomId;
+  maxClients;
+  latency;
+  links = [];
+  byId = /* @__PURE__ */ new Map();
+  resumeTokens = /* @__PURE__ */ new Map();
+  clientList = [];
+  traceLog = [];
+  nextClientId = 1;
+  activity = 0;
+  stopped = false;
+  constructor(options) {
+    this.roomId = options.roomId ?? "test-relay";
+    this.maxClients = options.maxClients ?? DEFAULT_MAX_CLIENTS;
+    this.latency = options.latency;
+    this.rng = new Mulberry32(options.seed ?? 1);
+    this.scheduler = clockScheduler(this.clock);
+  }
+  get clients() {
+    return this.clientList;
+  }
+  get trace() {
+    return this.traceLog;
+  }
+  // -------------------------------------------------------------------------
+  // The link
+  // -------------------------------------------------------------------------
+  transportFor() {
+    return {
+      connect: () => {
+        const link = {
+          socket: void 0,
+          clientId: `c${this.nextClientId++}`,
+          role: "",
+          name: "",
+          joined: false,
+          connected: true,
+          nextIn: this.clock.time,
+          nextOut: this.clock.time
+        };
+        link.socket = new InProcessSocket(
+          (bytes) => this.fromClient(link, bytes),
+          () => this.linkClosed(link)
+        );
+        this.links.push(link);
+        this.clock.setTimeout(() => link.socket.open(), 0);
+        this.activity++;
+        return link.socket;
+      }
+    };
+  }
+  linkClosed(link) {
+    if (!link.connected) return;
+    link.connected = false;
+    this.byId.delete(link.clientId);
+    if (!link.joined || this.stopped) return;
+    link.joined = false;
+    const delta = this.relay.remove(link.clientId);
+    if (delta) this.broadcastDelta(delta, link.clientId);
+  }
+  dropClient(clientId, options) {
+    const link = this.byId.get(clientId);
+    if (!link || !link.connected || link.socket.closed) return;
+    link.connected = false;
+    this.byId.delete(clientId);
+    const delta = this.relay.setConnected(clientId, false);
+    if (delta) this.broadcastDelta(delta, clientId);
+    link.socket.hangUp(options);
+  }
+  schedule(link, dir, type, run) {
+    const loss = this.latency?.loss ?? 0;
+    if (loss > 0 && DROPPABLE.has(type) && this.rng.next() < loss) return false;
+    const jitterMs = this.latency?.jitterMs ?? 0;
+    const oneWay = (this.latency?.rttMs ?? 0) / 2 + (jitterMs > 0 ? this.rng.next() * jitterMs : 0);
+    const floor = dir === "in" ? link.nextIn : link.nextOut;
+    const at = Math.max(this.clock.time + oneWay, floor);
+    if (dir === "in") link.nextIn = at;
+    else link.nextOut = at;
+    this.activity++;
+    this.clock.setTimeout(() => {
+      this.activity++;
+      run();
+    }, at - this.clock.time);
+    return true;
+  }
+  // -------------------------------------------------------------------------
+  // Client to relay
+  // -------------------------------------------------------------------------
+  fromClient(link, frame) {
+    let type;
+    let payload;
+    try {
+      const decoded = decodeFrame(frame);
+      type = decoded.type;
+      payload = decoded.payload;
+    } catch {
+      return;
+    }
+    if (type === FrameType.HELLO) this.preresolve(link, payload);
+    this.record("in", link.clientId, type, frame.length);
+    this.schedule(link, "in", type, () => this.toRelay(link, type, payload));
+  }
+  preresolve(link, payload) {
+    try {
+      const hello = decodeHello(payload);
+      const resumed = hello.resumeToken ? this.resumeTokens.get(hello.resumeToken) : void 0;
+      if (resumed) link.clientId = resumed;
+    } catch {
+    }
+  }
+  toRelay(link, type, payload) {
+    if (!link.connected || this.stopped) return;
+    if (type === FrameType.HELLO) {
+      this.handleHello(link, payload);
+      return;
+    }
+    if (type === FrameType.PING) {
+      let t = 0;
+      try {
+        t = decodePing(payload).t;
+      } catch {
+      }
+      this.toClient(
+        link,
+        encodeFrame(FrameType.PONG, encodePong({ t, serverTick: this.relay.tick }))
+      );
+      return;
+    }
+    if (!link.joined) return;
+    if (type !== FrameType.MSG) return;
+    this.relayMsg(link, payload);
+    return;
+  }
+  handleHello(link, payload) {
+    let role;
+    let name;
+    try {
+      const hello = decodeHello(payload);
+      role = hello.role;
+      name = hello.name;
+    } catch {
+      this.fail(link, "E_BAD_FRAME", "malformed HELLO");
+      return;
+    }
+    if (!this.relay.has(link.clientId) && this.relay.size >= this.maxClients) {
+      this.fail(link, "E_ROOM_FULL", formatError("E_ROOM_FULL", { roomId: this.roomId }));
+      return;
+    }
+    link.role = role ?? "";
+    link.name = name ?? "";
+    const delta = this.relay.add(link.clientId, link.role, link.name);
+    link.joined = true;
+    this.byId.set(link.clientId, link);
+    const resumeToken = `resume:${link.clientId}`;
+    this.resumeTokens.set(resumeToken, link.clientId);
+    this.toClient(
+      link,
+      encodeFrame(
+        FrameType.WELCOME,
+        encodeWelcome({
+          clientId: link.clientId,
+          role: link.role,
+          tick: this.relay.tick,
+          snapshot: this.relay.snapshot(),
+          resumeToken,
+          roomId: this.roomId,
+          tickIntervalMs: 0
+          // relay rooms have no tick
+        })
+      )
+    );
+    this.broadcastDelta(delta, link.clientId);
+  }
+  fail(link, code, message) {
+    this.toClient(
+      link,
+      encodeFrame(
+        FrameType.ERROR,
+        encodeErrorPayload({ code: ErrorCode[code].code, message, fatal: true })
+      )
+    );
+  }
+  relayMsg(link, payload) {
+    let target;
+    let body;
+    try {
+      const msg = decodeMsg(payload);
+      target = msg.target;
+      body = msg.payload;
+    } catch {
+      return;
+    }
+    if (target.kind === "server") return;
+    const out = encodeFrame(
+      FrameType.MSG,
+      encodeMsg({ target: { kind: "client", clientId: link.clientId }, payload: body })
+    );
+    for (const peer of this.links) {
+      if (peer === link || !peer.joined || !peer.connected) continue;
+      if (target.kind === "client" && peer.clientId !== target.clientId) continue;
+      if (target.kind === "role" && peer.role !== target.role) continue;
+      this.toClient(peer, out);
+    }
+    this.relay.advance();
+  }
+  // -------------------------------------------------------------------------
+  // Relay to client
+  // -------------------------------------------------------------------------
+  toClient(link, frame) {
+    const type = frame[0] ?? -1;
+    this.record("out", link.clientId, type, frame.length);
+    this.schedule(link, "out", type, () => link.socket.deliver(frame));
+  }
+  /** Sends a presence delta to everyone except (optionally) the client it is about. */
+  broadcastDelta(delta, exceptClientId) {
+    const out = encodeFrame(FrameType.DELTA, delta);
+    for (const peer of this.links) {
+      if (!peer.joined || !peer.connected) continue;
+      if (exceptClientId !== void 0 && peer.clientId === exceptClientId) continue;
+      this.toClient(peer, out);
+    }
+  }
+  record(dir, clientId, type, bytes) {
+    let frame;
+    try {
+      frame = frameTypeName(type);
+    } catch {
+      return;
+    }
+    this.traceLog.push({ dir, clientId, frame, tick: this.relay.tick, bytes, at: this.clock.time });
+  }
+  // -------------------------------------------------------------------------
+  // Clock
+  // -------------------------------------------------------------------------
+  async settle() {
+    for (let i = 0; i < SETTLE_ROUNDS; i++) {
+      const before = this.activity;
+      await microtasks();
+      this.clock.advance(0);
+      if (this.activity === before) return;
+    }
+    throw new Error("testRelay: the frame pump did not settle");
+  }
+  async tick(n = 1) {
+    for (let i = 0; i < n; i++) {
+      this.clock.advance(0);
+      await this.settle();
+    }
+  }
+  async run(ms) {
+    this.clock.advance(ms);
+    await this.settle();
+  }
+  async until(pred, options = {}) {
+    const maxTicks = options.maxTicks ?? 1e3;
+    await this.settle();
+    if (pred()) return;
+    for (let i = 0; i < maxTicks; i++) {
+      await this.run(1);
+      if (pred()) return;
+    }
+    throw new Error(`t.until: predicate still false after ${maxTicks} ticks`);
+  }
+  async join(a, b) {
+    if (typeof a === "number") {
+      const out = [];
+      for (let i = 0; i < a; i++) out.push(await this.joinOne(b ?? {}));
+      return out;
+    }
+    return this.joinOne(a ?? {});
+  }
+  async joinOne(spec) {
+    const received = [];
+    const room = await this.awaitJoin(
+      joinRelay({
+        url: TEST_URL,
+        key: TEST_KEY,
+        room: this.roomId,
+        transport: this.transportFor(),
+        scheduler: this.scheduler,
+        ...spec.role !== void 0 ? { role: spec.role } : {},
+        ...spec.name !== void 0 ? { name: spec.name } : {}
+      })
+    );
+    room.onMessage((from, bytes) => received.push({ from, bytes }));
+    const client = Object.create(room);
+    Object.defineProperties(client, {
+      received: { get: () => received, enumerable: true },
+      drop: {
+        value: (options) => this.dropClient(room.me, options),
+        enumerable: true
+      }
+    });
+    this.clientList.push(client);
+    return client;
+  }
+  async awaitJoin(promise) {
+    let settled = false;
+    let value;
+    let error;
+    promise.then(
+      (v) => {
+        settled = true;
+        value = v;
+      },
+      (e) => {
+        settled = true;
+        error = e instanceof Error ? e : new Error(String(e));
+      }
+    );
+    this.clock.advance(0);
+    await microtasks();
+    for (let ms = 0; ms < JOIN_TIMEOUT_MS && !settled; ms++) {
+      this.clock.advance(1);
+      await microtasks();
+    }
+    if (error !== void 0) throw error;
+    if (!settled) throw new Error("testRelay: join never resolved");
+    await this.settle();
+    return value;
+  }
+  stop() {
+    this.stopped = true;
+    for (const client of this.clientList) client.leave();
+    for (const link of this.links) link.socket.hangUp();
+  }
+};
+
+// src/index.ts
+async function testRoom(definition, options = {}) {
+  return new TestHarness(definition, options);
+}
+async function testRelay(options = {}) {
+  return new TestRelayHarness(options);
+}
+export {
+  TRACE_TAIL,
+  TestHarness,
+  TestRelayHarness,
+  clockScheduler,
+  divergence,
+  matchers,
+  materialize,
+  testRelay,
+  testRoom,
+  toHaveConverged,
+  toHaveNoVisibilityLeaks,
+  toHaveRejected,
+  toStayUnderBandwidth
+};

package/dist/matchers.d.ts

@@ -0,0 +1,31 @@
+export { m as matchers, t as toHaveConverged, a as toHaveNoVisibilityLeaks, b as toHaveRejected, c as toStayUnderBandwidth } from './assertions-BP4as6ol.js';
+
+/**
+ * `@irtio/testing/matchers` — the Vitest entry.
+ *
+ * Importing this module registers the four matchers and augments `expect`'s types. It is a
+ * separate entry point on purpose: Vitest is an **optional** peer of `@irtio/testing`, so the main
+ * entry (and anything that only wants `testRoom`) never touches it.
+ *
+ * ```ts
+ * import '@irtio/testing/matchers';
+ * expect(t).toHaveNoVisibilityLeaks();
+ * ```
+ */
+/** The matchers this package adds to `expect`. */
+interface IrtioMatchers<R = unknown> {
+    /** No client's view or received frame named a collection its role must not see. */
+    toHaveNoVisibilityLeaks(): R;
+    /** Every client's view equals the authority projected to that client's role. */
+    toHaveConverged(): R;
+    /** Some call to `rpcName` came back as an error `REPLY`. */
+    toHaveRejected(rpcName: string): R;
+    /** No client averaged more than `bytesPerTick` outbound bytes per room tick. */
+    toStayUnderBandwidth(bytesPerTick: number): R;
+}
+declare module 'vitest' {
+    interface Matchers<T = any> extends IrtioMatchers<T> {
+    }
+}
+
+export type { IrtioMatchers };

package/dist/matchers.js

@@ -0,0 +1,18 @@
+import {
+  matchers,
+  toHaveConverged,
+  toHaveNoVisibilityLeaks,
+  toHaveRejected,
+  toStayUnderBandwidth
+} from "./chunk-O3OZKC3D.js";
+
+// src/matchers.ts
+import { expect } from "vitest";
+expect.extend(matchers);
+export {
+  matchers,
+  toHaveConverged,
+  toHaveNoVisibilityLeaks,
+  toHaveRejected,
+  toStayUnderBandwidth
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@irtio/testing",
+  "version": "0.1.0",
+  "description": "irtio's blessed test API: testRoom() in-process rooms with real client semantics, plus Vitest matchers",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./matchers": {
+      "types": "./dist/matchers.d.ts",
+      "import": "./dist/matchers.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@irtio/client": "0.1.0",
+    "@irtio/protocol": "0.1.0",
+    "@irtio/runtime": "0.1.0",
+    "@irtio/server": "0.1.0",
+    "@irtio/schema": "0.1.0"
+  },
+  "peerDependencies": {
+    "vitest": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}