@irtio/runtime 0.1.0

package/dist/worker/index.d.ts

@@ -0,0 +1,173 @@
+import { L as LogLevel, h as RoomStats, R as RoomCoreApi, f as RoomHost } from '../contract-BhD88PGb.js';
+import { ErrorCodeName } from '@irtio/protocol';
+import { LeaveReason } from '@irtio/server';
+import '@irtio/schema';
+
+/**
+ * Supervisor ↔ room-worker `postMessage` protocol. Every `Uint8Array` is transferred.
+ * Keep it additive: deployed supervisors speak exactly this.
+ */
+
+/**
+ * One deployment in a wake-time migration chain. The worker imports each
+ * `migrationUrl` and runs `up` inside its own sandbox — migrations are tenant code and never run
+ * in the supervisor process. The first step is the version the snapshot was written under and
+ * carries no migration; it is there to supply the decoding schema.
+ */
+interface MigrationChainStep {
+    version: number;
+    /** `schema.canonical` of that deployment. */
+    schemaJson: string;
+    /** `file://` URL of a bundled module exporting `{ up }` (default or named). */
+    migrationUrl?: string;
+}
+type ToWorker = {
+    t: 'init';
+    roomId: string;
+    /** `file://` URL of the bundled room (default export = RoomDefinition). */
+    bundleUrl: string;
+    seed?: number;
+    publicUrl?: string;
+    /** Restore from a hibernation snapshot. */
+    snapshot?: Uint8Array;
+    /**
+     * Bring `snapshot` forward before restoring it. Ascending; the last version must be
+     * the one `bundleUrl` implements.
+     */
+    migrate?: MigrationChainStep[];
+} | {
+    t: 'join';
+    clientId: string;
+    role?: string;
+    name?: string;
+    reconnecting?: boolean;
+} | {
+    t: 'leave';
+    clientId: string;
+    reason: LeaveReason;
+} | {
+    t: 'disconnected';
+    clientId: string;
+} | {
+    t: 'frame';
+    clientId: string;
+    bytes: Uint8Array;
+} | {
+    t: 'serialize';
+    reqId: number;
+} | {
+    t: 'inspect';
+    reqId: number;
+} | {
+    t: 'stats';
+} | {
+    t: 'stop';
+};
+type FromWorker = {
+    t: 'ready';
+    roomId: string;
+    schemaHash: string;
+    extHash: string;
+    /** The room definition's resolved config: the supervisor needs
+     * idleMs/reconnectGraceMs/maxClients/mode without importing the bundle twice. */
+    config: {
+        mode: 'tick' | 'event';
+        tickRate: number;
+        idleMs: number;
+        reconnectGraceMs: number;
+        maxClients: number;
+    };
+    /** Present when `init.migrate` ran; the supervisor re-snapshots on the strength of it. */
+    migrated?: {
+        fromVersion: number;
+        toVersion: number;
+        applied: number[];
+        ms: number;
+    };
+} | {
+    t: 'initFailed';
+    reason: string;
+} | {
+    t: 'joined';
+    clientId: string;
+    role: string;
+    tick: number;
+    snapshot: Uint8Array;
+} | {
+    t: 'joinRejected';
+    clientId: string;
+    code: ErrorCodeName;
+    reason?: string;
+} | {
+    t: 'send';
+    clientId: string;
+    bytes: Uint8Array;
+} | {
+    t: 'kick';
+    clientId: string;
+    code: ErrorCodeName;
+    reason?: string;
+} | {
+    t: 'close';
+    reason?: string;
+} | {
+    t: 'sleep';
+} | {
+    t: 'log';
+    level: LogLevel;
+    args: unknown[];
+} | {
+    t: 'crashed';
+    reason: string;
+} | {
+    t: 'serialized';
+    reqId: number;
+    bytes: Uint8Array;
+} | {
+    t: 'inspected';
+    reqId: number;
+    tick: number;
+    stateJson: Record<string, unknown>;
+    recent: readonly {
+        tick: number;
+        kind: string;
+        clientId?: string;
+        detail?: string;
+    }[];
+    /** Worker process RSS in bytes. */
+    rss: number;
+} | {
+    t: 'stats';
+    stats: Omit<RoomStats, 'bytesOutByClient'> & {
+        bytesOutByClient: [string, number][];
+    };
+} | {
+    t: 'stopped';
+};
+/** Collects transferable buffers from a message (for `postMessage(msg, transfer)`). */
+declare function transferList(msg: ToWorker | FromWorker): ArrayBuffer[];
+
+/**
+ * The `worker_threads` room host. Imported as a worker, this file drives one
+ * `RoomCore` over the typed `ToWorker`/`FromWorker` `postMessage` protocol. It is also safe to
+ * import from the main thread — nothing runs unless `!isMainThread && parentPort`, so tests and
+ * future hosts can import `createWorkerHost`/`handleMessage` directly.
+ */
+
+/**
+ * Builds a `RoomHost` that posts `FromWorker` messages via `post`. Uses real timers
+ * (`setTimeout`/`clearTimeout`) and a monotonic clock (`performance.now()`).
+ */
+declare function createWorkerHost(post: (msg: FromWorker, transfer?: ArrayBuffer[]) => void): RoomHost;
+/** Mutable state the message handler drives. Exported for tests that want to inspect it. */
+interface WorkerState {
+    core: RoomCoreApi | undefined;
+}
+/**
+ * Handles one `ToWorker` message against `state`, using `host` (already wired to `post`) to
+ * construct/drive the `RoomCore`. Never throws — handler bugs are logged via `post` instead of
+ * killing the worker.
+ */
+declare function handleMessage(state: WorkerState, host: RoomHost, post: (msg: FromWorker, transfer?: ArrayBuffer[]) => void, msg: ToWorker): Promise<void>;
+
+export { type FromWorker, type MigrationChainStep, type ToWorker, type WorkerState, createWorkerHost, handleMessage, transferList };

package/dist/worker/index.js

@@ -0,0 +1,280 @@
+import {
+  migrateSnapshot
+} from "../chunk-3DQHT4CM.js";
+import {
+  RoomCore,
+  RoomFullError
+} from "../chunk-X5S364FY.js";
+
+// src/worker/index.ts
+import { isMainThread, parentPort } from "worker_threads";
+import { isRoomDefinition } from "@irtio/server";
+
+// src/worker/protocol.ts
+function transferList(msg) {
+  const out = [];
+  for (const v of Object.values(msg)) {
+    if (v instanceof Uint8Array && v.buffer instanceof ArrayBuffer) out.push(v.buffer);
+  }
+  return out;
+}
+
+// src/worker/index.ts
+function ownBuffer(bytes) {
+  if (bytes.byteOffset !== 0 || bytes.byteLength !== bytes.buffer.byteLength) {
+    return bytes.slice();
+  }
+  return bytes;
+}
+function createWorkerHost(post) {
+  return {
+    now() {
+      return performance.now();
+    },
+    setTimeout(fn, ms) {
+      return setTimeout(fn, ms);
+    },
+    clearTimeout(handle) {
+      clearTimeout(handle);
+    },
+    send(clientId, frame) {
+      const bytes = ownBuffer(frame);
+      post({ t: "send", clientId, bytes }, [bytes.buffer]);
+    },
+    kick(clientId, code, reason) {
+      post({ t: "kick", clientId, code, ...reason !== void 0 ? { reason } : {} });
+    },
+    close(reason) {
+      post({ t: "close", ...reason !== void 0 ? { reason } : {} });
+    },
+    sleep() {
+      post({ t: "sleep" });
+    },
+    log(level, args) {
+      post({ t: "log", level, args });
+    },
+    crashed(reason) {
+      post({ t: "crashed", reason });
+    }
+  };
+}
+async function loadChain(steps) {
+  const out = [];
+  for (const step of steps) {
+    let migration;
+    if (step.migrationUrl !== void 0) {
+      const mod = await import(step.migrationUrl);
+      const candidate = typeof mod.up === "function" ? mod : mod.default;
+      if (!candidate || typeof candidate.up !== "function") {
+        throw new Error(
+          `migration for v${step.version} at ${step.migrationUrl} does not export an \`up\` function`
+        );
+      }
+      migration = candidate;
+    }
+    out.push({
+      version: step.version,
+      schemaJson: step.schemaJson,
+      ...migration !== void 0 ? { migration } : {}
+    });
+  }
+  return out;
+}
+function statsPayload(stats) {
+  const { bytesOutByClient, ...rest } = stats;
+  return { t: "stats", stats: { ...rest, bytesOutByClient: [...bytesOutByClient.entries()] } };
+}
+async function handleMessage(state, host, post, msg) {
+  try {
+    switch (msg.t) {
+      case "init": {
+        let def;
+        try {
+          const mod = await import(msg.bundleUrl);
+          if (!isRoomDefinition(mod.default)) {
+            post({ t: "initFailed", reason: "bundle default export is not a RoomDefinition" });
+            return;
+          }
+          def = mod.default;
+        } catch (err) {
+          post({ t: "initFailed", reason: String(err instanceof Error ? err.stack : err) });
+          return;
+        }
+        let snapshot = msg.snapshot;
+        let migrated;
+        if (snapshot && msg.migrate && msg.migrate.length > 0) {
+          try {
+            const chain = await loadChain(msg.migrate);
+            migrated = migrateSnapshot(snapshot, chain, {
+              roomId: msg.roomId,
+              log: (level, args) => post({ t: "log", level, args })
+            });
+            snapshot = migrated.bytes;
+          } catch (err) {
+            post({
+              t: "initFailed",
+              reason: `migration failed: ${String(err instanceof Error ? err.stack ?? err.message : err)}`
+            });
+            return;
+          }
+        }
+        try {
+          const options = {
+            roomId: msg.roomId,
+            ...msg.seed !== void 0 ? { seed: msg.seed } : {},
+            ...msg.publicUrl !== void 0 ? { publicUrl: msg.publicUrl } : {}
+          };
+          const core = snapshot ? RoomCore.restore(def, snapshot, host, options) : new RoomCore(def, host, options);
+          state.core = core;
+          core.start();
+          const c = def.config;
+          post({
+            t: "ready",
+            roomId: msg.roomId,
+            schemaHash: def.schema.hash,
+            extHash: core.ext.hash,
+            config: {
+              mode: c.mode,
+              tickRate: c.tickRate,
+              idleMs: c.idleMs,
+              reconnectGraceMs: c.reconnectGraceMs,
+              maxClients: c.maxClients
+            },
+            ...migrated ? {
+              migrated: {
+                fromVersion: migrated.fromVersion,
+                toVersion: migrated.toVersion,
+                applied: [...migrated.applied],
+                ms: migrated.ms
+              }
+            } : {}
+          });
+        } catch (err) {
+          post({ t: "initFailed", reason: String(err instanceof Error ? err.stack : err) });
+        }
+        return;
+      }
+      case "join": {
+        const core = state.core;
+        if (!core) {
+          post({
+            t: "joinRejected",
+            clientId: msg.clientId,
+            code: "E_INTERNAL",
+            reason: "not initialized"
+          });
+          return;
+        }
+        try {
+          const joinOptions = {
+            ...msg.role !== void 0 ? { role: msg.role } : {},
+            ...msg.name !== void 0 ? { name: msg.name } : {},
+            ...msg.reconnecting !== void 0 ? { reconnecting: msg.reconnecting } : {}
+          };
+          const result = core.join(msg.clientId, joinOptions);
+          const snapshot = ownBuffer(result.snapshot);
+          post(
+            {
+              t: "joined",
+              clientId: msg.clientId,
+              role: result.role,
+              tick: result.tick,
+              snapshot
+            },
+            [snapshot.buffer]
+          );
+        } catch (err) {
+          if (err instanceof RoomFullError) {
+            post({ t: "joinRejected", clientId: msg.clientId, code: "E_ROOM_FULL" });
+          } else {
+            post({
+              t: "joinRejected",
+              clientId: msg.clientId,
+              code: "E_INTERNAL",
+              reason: String(err instanceof Error ? err.message : err)
+            });
+          }
+        }
+        return;
+      }
+      case "leave": {
+        state.core?.leave(msg.clientId, msg.reason);
+        return;
+      }
+      case "disconnected": {
+        state.core?.markDisconnected(msg.clientId);
+        return;
+      }
+      case "frame": {
+        state.core?.receive(msg.clientId, msg.bytes);
+        return;
+      }
+      case "serialize": {
+        const core = state.core;
+        if (!core) return;
+        const bytes = ownBuffer(core.serialize());
+        post({ t: "serialized", reqId: msg.reqId, bytes }, [bytes.buffer]);
+        return;
+      }
+      case "inspect": {
+        const core = state.core;
+        if (!core) return;
+        const ins = core.inspect();
+        post({
+          t: "inspected",
+          reqId: msg.reqId,
+          tick: ins.tick,
+          stateJson: ins.state,
+          recent: ins.recent,
+          rss: typeof process !== "undefined" ? process.memoryUsage().rss : 0
+        });
+        return;
+      }
+      case "stats": {
+        const core = state.core;
+        if (!core) return;
+        post(statsPayload(core.stats));
+        return;
+      }
+      case "stop": {
+        state.core?.stop();
+        post({ t: "stopped" });
+        return;
+      }
+      default: {
+        const unknown = msg;
+        post({
+          t: "log",
+          level: "warn",
+          args: [`worker: unknown message type ${String(unknown.t)}`]
+        });
+        return;
+      }
+    }
+  } catch (err) {
+    post({
+      t: "log",
+      level: "error",
+      args: [
+        `worker: handling '${msg.t}' threw`,
+        err instanceof Error ? err.stack ?? err.message : err
+      ]
+    });
+  }
+}
+if (!isMainThread && parentPort) {
+  const port = parentPort;
+  const post = (msg, transfer) => {
+    port.postMessage(msg, transfer ?? transferList(msg));
+  };
+  const host = createWorkerHost(post);
+  const state = { core: void 0 };
+  port.on("message", (msg) => {
+    void handleMessage(state, host, post, msg);
+  });
+}
+export {
+  createWorkerHost,
+  handleMessage,
+  transferList
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@irtio/runtime",
+  "version": "0.1.0",
+  "description": "irtio room runtime: RoomCore, worker_threads host, in-process test harness",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./worker": {
+      "types": "./dist/worker/index.d.ts",
+      "import": "./dist/worker/index.js"
+    },
+    "./test": {
+      "types": "./dist/test/index.d.ts",
+      "import": "./dist/test/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@irtio/protocol": "0.1.0",
+    "@irtio/schema": "0.1.0",
+    "@irtio/server": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}