@irtio/runtime 0.1.0

package/dist/test/index.js

@@ -0,0 +1,774 @@
+import {
+  RoomCore,
+  visibleNames
+} from "../chunk-X5S364FY.js";
+
+// src/test/clock.ts
+var FakeClock = class {
+  /** Current fake time in ms. Starts at 0. */
+  time = 0;
+  timers = /* @__PURE__ */ new Map();
+  nextId = 1;
+  now() {
+    return this.time;
+  }
+  setTimeout(fn, ms) {
+    const id = this.nextId++;
+    this.timers.set(id, { id, at: this.time + Math.max(0, ms), fn });
+    return id;
+  }
+  clearTimeout(handle) {
+    if (typeof handle === "number") this.timers.delete(handle);
+  }
+  /** Number of timers still armed (a room that is ticking always has at least one). */
+  get pending() {
+    return this.timers.size;
+  }
+  /**
+   * Advances to `time + ms`, firing every timer that comes due in order (earliest `at` first,
+   * ties broken by creation order). A timer that arms another timer inside the window fires too.
+   */
+  advance(ms) {
+    const target = this.time + Math.max(0, ms);
+    for (; ; ) {
+      let next;
+      for (const t of this.timers.values()) {
+        if (t.at > target) continue;
+        if (!next || t.at < next.at || t.at === next.at && t.id < next.id) next = t;
+      }
+      if (!next) break;
+      this.timers.delete(next.id);
+      if (next.at > this.time) this.time = next.at;
+      next.fn();
+    }
+    if (target > this.time) this.time = target;
+  }
+};
+
+// src/test/host.ts
+var HarnessHost = class {
+  constructor(clock) {
+    this.clock = clock;
+  }
+  clock;
+  logs = [];
+  kicks = [];
+  /** `room.close()` reasons, in order. */
+  closes = [];
+  /** `host.crashed()` reasons, in order. */
+  crashes = [];
+  /** How many times the runtime asked to hibernate. */
+  sleeps = 0;
+  /** Total frames handed to the host. */
+  framesSent = 0;
+  bytesSent = 0;
+  sentByClient = /* @__PURE__ */ new Map();
+  /** Set by the harness: where an outbound frame goes. */
+  onSend = () => {
+  };
+  /** `true` once the runtime has asked to hibernate at least once. */
+  get slept() {
+    return this.sleeps > 0;
+  }
+  /** `true` once `room.close()` has been called. */
+  get closed() {
+    return this.closes.length > 0;
+  }
+  now() {
+    return this.clock.now();
+  }
+  setTimeout(fn, ms) {
+    return this.clock.setTimeout(fn, ms);
+  }
+  clearTimeout(handle) {
+    this.clock.clearTimeout(handle);
+  }
+  send(clientId, frame) {
+    this.framesSent++;
+    this.bytesSent += frame.length;
+    let counts = this.sentByClient.get(clientId);
+    if (!counts) {
+      counts = { frames: 0, bytes: 0 };
+      this.sentByClient.set(clientId, counts);
+    }
+    counts.frames++;
+    counts.bytes += frame.length;
+    this.onSend(clientId, frame);
+  }
+  kick(clientId, code, reason) {
+    this.kicks.push({ clientId, code, reason });
+  }
+  close(reason) {
+    this.closes.push(reason);
+  }
+  sleep() {
+    this.sleeps++;
+  }
+  log(level, args) {
+    this.logs.push({ level, args });
+  }
+  crashed(reason) {
+    this.crashes.push(reason);
+  }
+  /** Logged messages of one level, flattened to strings (handy in assertions). */
+  logsOf(level) {
+    return this.logs.filter((l) => l.level === level).map((l) => l.args.map(String).join(" "));
+  }
+};
+
+// src/test/harness.ts
+import {
+  defaultRecord
+} from "@irtio/schema";
+
+// src/test/fake-client.ts
+import {
+  FrameType,
+  decodeCall,
+  decodeMsg,
+  decodeReply,
+  encodeCall,
+  encodeFrame,
+  encodeMsg,
+  encodeReply,
+  rpcTable
+} from "@irtio/protocol";
+import {
+  applyDelta,
+  cloneValue,
+  createDirtySet,
+  createState,
+  decodeDelta,
+  decodeFields,
+  decodeSnapshot,
+  encodeDelta,
+  encodeFields,
+  markField
+} from "@irtio/schema";
+function structFields(t) {
+  return Object.entries(t.fields).map(([name, type]) => ({ name, type }));
+}
+function fieldPath(c, names) {
+  const path = [];
+  let fields = c.fields.map((f) => ({
+    name: f.name,
+    type: f.type
+  }));
+  for (const n of names) {
+    const idx = fields.findIndex((f) => f.name === n);
+    if (idx < 0) throw new Error(`write: ${c.name} has no field ${JSON.stringify(n)}`);
+    path.push(idx);
+    const t = fields[idx]?.type;
+    fields = t && t.kind === "struct" ? structFields(t) : [];
+  }
+  return path;
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function mergePatch(target, patch) {
+  for (const [k, v] of Object.entries(patch)) {
+    const cur = target[k];
+    if (isPlainObject(v) && isPlainObject(cur)) mergePatch(cur, v);
+    else target[k] = v;
+  }
+}
+function patchLeaves(patch, prefix = []) {
+  const out = [];
+  for (const [k, v] of Object.entries(patch)) {
+    if (isPlainObject(v)) out.push(...patchLeaves(v, [...prefix, k]));
+    else out.push([...prefix, k]);
+  }
+  return out;
+}
+function entityOf(state, name) {
+  return state[name];
+}
+function isThenable(v) {
+  return typeof v === "object" && v !== null && typeof v.then === "function";
+}
+var FakeClientImpl = class {
+  constructor(bridge, id, options) {
+    this.bridge = bridge;
+    this.id = id;
+    this.role = options.role ?? "";
+    this.name = options.name ?? "";
+    this.joinTick = 0;
+    this.view = createState(bridge.ext);
+  }
+  bridge;
+  id;
+  role;
+  name;
+  connected = true;
+  view;
+  joinTick;
+  calls = [];
+  messages = [];
+  corrections = [];
+  frames = [];
+  impls = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  nextReqId = 1;
+  /**
+   * Joins the room. Separate from the constructor so the harness can register the client before
+   * any frame the join produces could be delivered to it.
+   */
+  initialJoin(options) {
+    const result = this.bridge.join(this.id, options);
+    this.role = result.role;
+    this.joinTick = result.tick;
+    this.loadSnapshot(result.snapshot);
+  }
+  // -------------------------------------------------------------------------
+  // View
+  // -------------------------------------------------------------------------
+  loadSnapshot(bytes) {
+    this.view = decodeSnapshot(this.bridge.ext, bytes).state;
+  }
+  entity(name) {
+    return entityOf(this.view, name);
+  }
+  get(entity, id) {
+    return this.entity(entity).get(id);
+  }
+  // -------------------------------------------------------------------------
+  // Outbound
+  // -------------------------------------------------------------------------
+  descOf(name) {
+    const desc = rpcTable(this.bridge.schema).find((r) => r.name === name);
+    if (!desc) throw new Error(`FakeClient: unknown rpc ${JSON.stringify(name)}`);
+    return desc;
+  }
+  write(entity, id, patch) {
+    const c = this.bridge.ext.collection(entity);
+    if (!c || c.kind !== "entity") {
+      throw new Error(`write: ${JSON.stringify(entity)} is not an entity collection in the view`);
+    }
+    const current = this.get(entity, id);
+    if (!current) throw new Error(`write: ${entity}[${id}] is not in ${this.id}'s view`);
+    const value = cloneValue(current);
+    mergePatch(value, patch);
+    const scratch = createState(this.bridge.ext);
+    entityOf(scratch, entity).add(id, value, { owner: "" });
+    const dirty = createDirtySet();
+    for (const names of patchLeaves(patch)) markField(dirty, entity, id, fieldPath(c, names));
+    const payload = encodeDelta(this.bridge.ext, scratch, dirty, { tick: this.bridge.tick });
+    this.bridge.toCore(this.id, encodeFrame(FrameType.WRITE, payload));
+  }
+  writeRaw(frame) {
+    this.bridge.toCore(this.id, frame);
+  }
+  call(name, params = {}) {
+    const desc = this.descOf(name);
+    const reqId = this.nextReqId++;
+    return new Promise((resolve, reject) => {
+      this.pending.set(reqId, { name, returns: desc.returns, resolve, reject });
+      const payload = encodeCall({
+        reqId,
+        rpcId: desc.index,
+        params: encodeFields(desc.params, params)
+      });
+      this.bridge.toCore(this.id, encodeFrame(FrameType.CALL, payload));
+    });
+  }
+  async requestOwnership(entity, id) {
+    const result = await this.call("requestOwnership", { entity, id });
+    return result?.granted === true;
+  }
+  send(target, bytes) {
+    const wire = target === "all" ? { kind: "all" } : typeof target === "string" ? { kind: "client", clientId: target } : { kind: "role", role: target.role };
+    this.bridge.toCore(
+      this.id,
+      encodeFrame(FrameType.MSG, encodeMsg({ target: wire, payload: bytes }))
+    );
+  }
+  onCall(name, impl) {
+    this.descOf(name);
+    this.impls.set(name, impl);
+  }
+  // -------------------------------------------------------------------------
+  // Membership
+  // -------------------------------------------------------------------------
+  disconnect() {
+    if (!this.connected) return;
+    this.connected = false;
+    this.bridge.markDisconnected(this.id);
+  }
+  reconnect() {
+    this.connected = true;
+    const result = this.bridge.join(this.id, {
+      role: this.role,
+      name: this.name,
+      reconnecting: true
+    });
+    this.role = result.role;
+    this.joinTick = result.tick;
+    this.loadSnapshot(result.snapshot);
+  }
+  leave(reason = "left") {
+    this.bridge.leave(this.id, reason);
+    this.connected = false;
+    for (const [reqId, p] of [...this.pending]) {
+      this.pending.delete(reqId);
+      p.reject(new Error(`${p.name}: client ${this.id} left before the reply arrived`));
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Inbound
+  // -------------------------------------------------------------------------
+  /** Delivers one framed protocol frame from the room. Called by the harness. */
+  receive(frame) {
+    const type = frame[0];
+    const payload = frame.subarray(1);
+    switch (type) {
+      case FrameType.DELTA:
+        this.applyDeltaFrame(payload, false);
+        return;
+      case FrameType.CORRECT:
+        this.applyDeltaFrame(payload, true);
+        return;
+      case FrameType.CALL:
+        this.handleCall(payload);
+        return;
+      case FrameType.REPLY:
+        this.handleReply(payload);
+        return;
+      case FrameType.MSG:
+        this.handleMsg(payload);
+        return;
+      default:
+        return;
+    }
+  }
+  applyDeltaFrame(payload, correction) {
+    const delta = decodeDelta(this.bridge.ext, payload);
+    this.checkFrameVisibility(delta);
+    if (correction) {
+      for (const dc of delta.collections) {
+        for (const op of dc.ops) {
+          if (op.op !== "update") continue;
+          this.corrections.push({
+            collection: dc.name,
+            id: op.id,
+            patch: cloneValue(op.patch),
+            tick: delta.tick
+          });
+        }
+      }
+    }
+    applyDelta(this.bridge.ext, this.view, delta);
+  }
+  /** Flags any collection the frame named that this client's role may not see. */
+  checkFrameVisibility(delta) {
+    const keep = this.bridge.visible(this.role);
+    for (const dc of delta.collections) {
+      if (keep.has(dc.name) || dc.ops.length === 0) continue;
+      this.bridge.noteLeak({
+        clientId: this.id,
+        role: this.role,
+        collection: dc.name,
+        kind: "frame",
+        ids: dc.ops.map((o) => o.id),
+        tick: delta.tick
+      });
+    }
+  }
+  handleCall(payload) {
+    let call;
+    try {
+      call = decodeCall(payload);
+    } catch {
+      return;
+    }
+    const desc = rpcTable(this.bridge.schema).find((r) => r.index === call.rpcId);
+    if (!desc) return;
+    let params;
+    try {
+      params = decodeFields(desc.params, call.params);
+    } catch {
+      return;
+    }
+    this.calls.push({ name: desc.name, params });
+    const impl = this.impls.get(desc.name);
+    if (!impl) return;
+    let result;
+    try {
+      result = impl(params);
+    } catch (err) {
+      this.replyError(call.reqId, err);
+      return;
+    }
+    if (isThenable(result)) {
+      Promise.resolve(result).then(
+        (v) => this.replyOk(desc, call.reqId, v),
+        (err) => this.replyError(call.reqId, err)
+      );
+      return;
+    }
+    this.replyOk(desc, call.reqId, result);
+  }
+  replyOk(desc, reqId, result) {
+    let bytes;
+    try {
+      bytes = desc.returns ? encodeFields(desc.returns, result ?? {}) : new Uint8Array(0);
+    } catch (err) {
+      this.replyError(reqId, err);
+      return;
+    }
+    this.bridge.toCore(
+      this.id,
+      encodeFrame(FrameType.REPLY, encodeReply({ reqId, ok: true, result: bytes }))
+    );
+  }
+  replyError(reqId, err) {
+    const error = err instanceof Error ? err.message : String(err);
+    this.bridge.toCore(
+      this.id,
+      encodeFrame(FrameType.REPLY, encodeReply({ reqId, ok: false, error }))
+    );
+  }
+  handleReply(payload) {
+    let reply;
+    try {
+      reply = decodeReply(payload);
+    } catch {
+      return;
+    }
+    const p = this.pending.get(reply.reqId);
+    if (!p) return;
+    this.pending.delete(reply.reqId);
+    if (!reply.ok) {
+      p.reject(new Error(reply.error));
+      return;
+    }
+    if (!p.returns) {
+      p.resolve(void 0);
+      return;
+    }
+    try {
+      p.resolve(decodeFields(p.returns, reply.result));
+    } catch (err) {
+      p.reject(new Error(`${p.name}: bad reply payload: ${String(err)}`));
+    }
+  }
+  handleMsg(payload) {
+    let msg;
+    try {
+      msg = decodeMsg(payload);
+    } catch {
+      return;
+    }
+    const from = msg.target.kind === "client" ? msg.target.clientId : "server";
+    this.messages.push({ from, bytes: msg.payload.slice() });
+  }
+};
+
+// src/test/types.ts
+import { FrameType as FrameType2 } from "@irtio/protocol";
+var NAMES = new Map(
+  Object.keys(FrameType2).map((k) => [FrameType2[k], k])
+);
+function frameTypeName(type) {
+  const name = NAMES.get(type);
+  if (!name) throw new Error(`frameTypeName: unknown frame type ${type}`);
+  return name;
+}
+
+// src/test/harness.ts
+function deepEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  const ra = a;
+  const rb = b;
+  const keys = /* @__PURE__ */ new Set([...Object.keys(ra), ...Object.keys(rb)]);
+  for (const k of keys) if (!deepEqual(ra[k], rb[k])) return false;
+  return true;
+}
+var Harness = class {
+  constructor(definition, options) {
+    this.definition = definition;
+    this.options = options;
+    this.host = new HarnessHost(this.clock);
+    this.host.onSend = (clientId, frame) => this.deliver(clientId, frame);
+    this.coreRef = new RoomCore(definition, this.host, {
+      roomId: options.roomId ?? "test-room",
+      seed: options.seed ?? 1,
+      ...options.publicUrl !== void 0 ? { publicUrl: options.publicUrl } : {},
+      ...options.restoreFrom !== void 0 ? { restoreFrom: options.restoreFrom } : {}
+    });
+    this.coreRef.start();
+    const self = this;
+    this.bridge = {
+      get ext() {
+        return self.coreRef.ext;
+      },
+      get schema() {
+        return self.coreRef.schema;
+      },
+      get tick() {
+        return self.coreRef.tick;
+      },
+      get now() {
+        return self.clock.time;
+      },
+      toCore: (clientId, frame) => this.toCore(clientId, frame),
+      join: (clientId, joinOptions) => this.enter(() => this.coreRef.join(clientId, joinOptions)),
+      leave: (clientId, reason) => this.enter(() => this.coreRef.leave(clientId, reason)),
+      markDisconnected: (clientId) => this.enter(() => this.coreRef.markDisconnected(clientId)),
+      noteLeak: (leak) => {
+        this.frameLeaks.push(leak);
+      },
+      visible: (role) => visibleNames(this.coreRef.ext, role)
+    };
+  }
+  definition;
+  options;
+  clock = new FakeClock();
+  host;
+  coreRef;
+  clientList = [];
+  byId = /* @__PURE__ */ new Map();
+  traceLog = [];
+  frameLeaks = [];
+  queue = [];
+  depth = 0;
+  pumping = false;
+  nextClientId = 1;
+  bridge;
+  // -------------------------------------------------------------------------
+  // Accessors
+  // -------------------------------------------------------------------------
+  get core() {
+    return this.coreRef;
+  }
+  get room() {
+    return this.coreRef.room;
+  }
+  get state() {
+    return this.coreRef.state;
+  }
+  get plain() {
+    return this.coreRef.plain;
+  }
+  get stats() {
+    return this.coreRef.stats;
+  }
+  get now() {
+    return this.clock.time;
+  }
+  get tickCount() {
+    return this.coreRef.tick;
+  }
+  get mode() {
+    return this.coreRef.mode;
+  }
+  get clients() {
+    return this.clientList;
+  }
+  get trace() {
+    return this.traceLog;
+  }
+  get intervalMs() {
+    return 1e3 / this.definition.config.tickRate;
+  }
+  // -------------------------------------------------------------------------
+  // Frame plumbing
+  // -------------------------------------------------------------------------
+  record(dir, clientId, frame) {
+    let name;
+    try {
+      name = frameTypeName(frame[0] ?? -1);
+    } catch {
+      return;
+    }
+    const entry = {
+      dir,
+      clientId,
+      frame: name,
+      tick: this.coreRef.tick,
+      bytes: frame.length,
+      at: this.clock.time
+    };
+    this.traceLog.push(entry);
+    this.byId.get(clientId)?.frames.push(entry);
+  }
+  /**
+   * One room → client frame. The client is "busy" while it decodes, so anything it sends back
+   * (a `REPLY` to a server→client `CALL`) is queued rather than fed straight back into the core:
+   * the core is mid-`send` and has not finished bookkeeping the call yet.
+   *
+   * When the send did not come from a harness entry point (a test calling `h.room.call(...)`
+   * directly), the drain is deferred to a microtask — which is exactly where the test's `await`
+   * picks it up.
+   */
+  deliver(clientId, frame) {
+    const client = this.byId.get(clientId);
+    this.record("out", clientId, frame);
+    this.depth++;
+    try {
+      if (client?.connected) client.receive(frame);
+    } finally {
+      this.depth--;
+      if (this.depth === 0 && this.queue.length > 0) queueMicrotask(() => this.pump());
+    }
+  }
+  toCore(clientId, frame) {
+    this.queue.push({ clientId, frame });
+    if (this.depth === 0) this.pump();
+  }
+  /** Runs `fn` with the core "busy"; drains client frames once the outermost call returns. */
+  enter(fn) {
+    this.depth++;
+    try {
+      return fn();
+    } finally {
+      this.depth--;
+      if (this.depth === 0) this.pump();
+    }
+  }
+  pump() {
+    if (this.pumping) return;
+    this.pumping = true;
+    try {
+      let guard = 0;
+      for (; ; ) {
+        const item = this.queue.shift();
+        if (!item) break;
+        if (++guard > 1e5) throw new Error("harness: the frame pump did not settle");
+        this.record("in", item.clientId, item.frame);
+        this.depth++;
+        try {
+          this.coreRef.receive(item.clientId, item.frame);
+        } finally {
+          this.depth--;
+        }
+      }
+    } finally {
+      this.pumping = false;
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Clock
+  // -------------------------------------------------------------------------
+  tick(n = 1) {
+    this.enter(() => {
+      for (let i = 0; i < n; i++) {
+        if (this.mode === "tick") this.clock.advance(this.intervalMs);
+        else this.clock.advance(0);
+      }
+    });
+  }
+  run(ms) {
+    this.enter(() => this.clock.advance(ms));
+  }
+  until(pred, options = {}) {
+    const maxTicks = options.maxTicks ?? 1e3;
+    if (pred()) return;
+    for (let i = 0; i < maxTicks; i++) {
+      this.tick(1);
+      if (pred()) return;
+    }
+    throw new Error(`h.until: predicate still false after ${maxTicks} ticks`);
+  }
+  join(a, b) {
+    if (typeof a === "number") {
+      const out = [];
+      for (let i = 0; i < a; i++) out.push(this.joinOne(b ?? {}));
+      return out;
+    }
+    return this.joinOne(a ?? {});
+  }
+  joinOne(spec) {
+    const id = spec.id ?? `c${this.nextClientId++}`;
+    const roles = this.definition.schema.roles;
+    const role = spec.role ?? roles[0] ?? "";
+    const options = {
+      role,
+      ...spec.name !== void 0 ? { name: spec.name } : {}
+    };
+    const client = new FakeClientImpl(this.bridge, id, options);
+    this.byId.set(id, client);
+    this.clientList.push(client);
+    try {
+      client.initialJoin(options);
+    } catch (err) {
+      this.byId.delete(id);
+      this.clientList.splice(this.clientList.indexOf(client), 1);
+      throw err;
+    }
+    return client;
+  }
+  // -------------------------------------------------------------------------
+  // Visibility
+  // -------------------------------------------------------------------------
+  checkVisibility() {
+    const leaks = [...this.frameLeaks];
+    const ext = this.coreRef.ext;
+    for (const client of this.clientList) {
+      const keep = visibleNames(ext, client.role);
+      for (const c of ext.collections) {
+        if (keep.has(c.name)) continue;
+        if (c.kind === "entity") {
+          const coll = client.view[c.name];
+          if (!coll || coll.size === 0) continue;
+          leaks.push({
+            clientId: client.id,
+            role: client.role,
+            collection: c.name,
+            kind: "view",
+            ids: [...coll.ids()],
+            tick: this.coreRef.tick
+          });
+        } else {
+          const value = client.view[c.name];
+          if (deepEqual(value, defaultRecord(c))) continue;
+          leaks.push({
+            clientId: client.id,
+            role: client.role,
+            collection: c.name,
+            kind: "view",
+            ids: [""],
+            tick: this.coreRef.tick
+          });
+        }
+      }
+    }
+    return leaks;
+  }
+  // -------------------------------------------------------------------------
+  // Hibernation
+  // -------------------------------------------------------------------------
+  serialize() {
+    return this.enter(() => this.coreRef.serialize());
+  }
+  restore(bytes) {
+    this.coreRef.stop();
+    this.queue.length = 0;
+    this.clientList.length = 0;
+    this.byId.clear();
+    this.nextClientId = 1;
+    this.coreRef = RoomCore.restore(this.definition, bytes, this.host, {
+      roomId: this.options.roomId ?? "test-room",
+      seed: this.options.seed ?? 1,
+      ...this.options.publicUrl !== void 0 ? { publicUrl: this.options.publicUrl } : {}
+    });
+    this.coreRef.start();
+  }
+  stop() {
+    this.coreRef.stop();
+  }
+};
+function createRoomHarness(definition, options = {}) {
+  return new Harness(definition, options);
+}
+export {
+  FakeClock,
+  HarnessHost,
+  createRoomHarness,
+  frameTypeName
+};