@irtio/runtime 0.1.0

package/dist/test/index.d.ts

@@ -0,0 +1,283 @@
+import { ErrorCodeName, FrameType } from '@irtio/protocol';
+import { f as RoomHost, L as LogLevel, h as RoomStats } from '../contract-BhD88PGb.js';
+import { AnySchema, PlainState, EntityCollection, State } from '@irtio/schema';
+import { LeaveReason, Room, RoomDefinition } from '@irtio/server';
+import { R as RoomCore } from '../room-CBsSCueH.js';
+
+/**
+ * The harness clock: a deterministic fake `now()` plus an ordered timer queue. `RoomCore` only
+ * ever asks the host for `now()` / `setTimeout` / `clearTimeout`, so this is the whole notion of
+ * time in a harness room. Nothing here touches real timers, `Date`, or Node built-ins.
+ */
+declare class FakeClock {
+    /** Current fake time in ms. Starts at 0. */
+    time: number;
+    private readonly timers;
+    private nextId;
+    now(): number;
+    setTimeout(fn: () => void, ms: number): number;
+    clearTimeout(handle: unknown): void;
+    /** Number of timers still armed (a room that is ticking always has at least one). */
+    get pending(): number;
+    /**
+     * 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: number): void;
+}
+
+/**
+ * `HarnessHost` — the `RoomHost` the harness gives `RoomCore`. Everything the host is told is
+ * recorded so a test can assert on it: logs, kicks, `close()`, `sleep()`, `crashed()`, and how
+ * many frames/bytes went out (per client and in total).
+ */
+
+interface KickRecord {
+    readonly clientId: string;
+    readonly code: ErrorCodeName;
+    readonly reason: string | undefined;
+}
+interface LogRecord {
+    readonly level: LogLevel;
+    readonly args: unknown[];
+}
+interface SendCounts {
+    frames: number;
+    bytes: number;
+}
+declare class HarnessHost implements RoomHost {
+    private readonly clock;
+    readonly logs: LogRecord[];
+    readonly kicks: KickRecord[];
+    /** `room.close()` reasons, in order. */
+    readonly closes: (string | undefined)[];
+    /** `host.crashed()` reasons, in order. */
+    readonly crashes: string[];
+    /** How many times the runtime asked to hibernate. */
+    sleeps: number;
+    /** Total frames handed to the host. */
+    framesSent: number;
+    bytesSent: number;
+    readonly sentByClient: Map<string, SendCounts>;
+    /** Set by the harness: where an outbound frame goes. */
+    onSend: (clientId: string, frame: Uint8Array) => void;
+    constructor(clock: FakeClock);
+    /** `true` once the runtime has asked to hibernate at least once. */
+    get slept(): boolean;
+    /** `true` once `room.close()` has been called. */
+    get closed(): boolean;
+    now(): number;
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    send(clientId: string, frame: Uint8Array): void;
+    kick(clientId: string, code: ErrorCodeName, reason?: string): void;
+    close(reason?: string): void;
+    sleep(): void;
+    log(level: LogLevel, args: unknown[]): void;
+    crashed(reason: string): void;
+    /** Logged messages of one level, flattened to strings (handy in assertions). */
+    logsOf(level: LogLevel): string[];
+}
+
+/** Shared harness value types: the frame trace and the visibility-leak report. */
+
+type FrameTypeName = keyof typeof FrameType;
+declare function frameTypeName(type: number): FrameTypeName;
+/** One frame crossing the harness seam. `in` = client → room, `out` = room → client. */
+interface TraceEntry {
+    readonly dir: 'in' | 'out';
+    readonly clientId: string;
+    readonly frame: FrameTypeName;
+    /** The room's tick counter when the frame crossed. */
+    readonly tick: number;
+    readonly bytes: number;
+    /** Fake-clock ms when the frame crossed. */
+    readonly at: number;
+}
+/**
+ * A collection a client can see that its role must not.
+ *
+ * - `kind: 'view'` — the client's decoded state holds records of an invisible collection.
+ * - `kind: 'frame'` — a `DELTA`/`CORRECT` the client received named an invisible collection
+ *   (caught while the frame was applied, even if the ops later cancelled out).
+ */
+interface VisibilityLeak {
+    readonly clientId: string;
+    readonly role: string;
+    readonly collection: string;
+    readonly kind: 'view' | 'frame';
+    /** Ids involved (`['']` for a singleton). */
+    readonly ids: readonly string[];
+    readonly tick: number;
+}
+
+/**
+ * The harness's fake client: what a real `@irtio/client` will do, with none of its semantics.
+ *
+ * It keeps a `PlainState` **view** of the extended schema — rebuilt from the join snapshot and
+ * advanced by every `DELTA` (and `CORRECT`, which carries the server's current values, so
+ * applying it is idempotent with the delta that follows it). It never predicts: a `write()` is
+ * only a frame, so a rejected write leaves the view exactly where the server left it.
+ *
+ * Everything the client sends goes through the harness's pump, so frames are delivered to the
+ * room at a safe point (never re-entrantly inside `RoomCore`).
+ */
+
+type AnyRecord = Record<string, unknown>;
+interface ReceivedCall {
+    readonly name: string;
+    readonly params: AnyRecord;
+}
+interface ReceivedMessage {
+    /** `'server'` for `room.send`, otherwise the relaying client's id. */
+    readonly from: 'server' | string;
+    readonly bytes: Uint8Array;
+}
+interface ReceivedCorrection {
+    readonly collection: string;
+    readonly id: string;
+    /** Only the fields the `CORRECT` carried. */
+    readonly patch: AnyRecord;
+    readonly tick: number;
+}
+type CallImpl = (params: AnyRecord) => unknown;
+interface FakeClient<S extends AnySchema = AnySchema> {
+    readonly id: string;
+    readonly role: string;
+    readonly name: string;
+    readonly connected: boolean;
+    /** Decoded state of the extended schema, as this client sees it. */
+    readonly view: PlainState;
+    /** The room tick this client (last) joined at. */
+    readonly joinTick: number;
+    /** Sends a `WRITE` update for `entity[id]` masking exactly the patch's leaves. */
+    write(entity: string, id: string, patch: AnyRecord): void;
+    /** Sends an arbitrary framed payload (protocol-violation tests). */
+    writeRaw(frame: Uint8Array): void;
+    /** Client → server RPC. Settles when the `REPLY` is delivered — `h.tick()` first, then `await`. */
+    call(name: string, params?: AnyRecord): Promise<unknown>;
+    /** The built-in `requestOwnership` RPC. */
+    requestOwnership(entity: string, id: string): Promise<boolean>;
+    /** Out-of-band `MSG`. */
+    send(target: 'all' | string | {
+        role: string;
+    }, bytes: Uint8Array): void;
+    /** Implements a client-direction RPC. Sync impls reply on delivery; async ones when they settle. */
+    onCall(name: string, impl: CallImpl): void;
+    readonly calls: readonly ReceivedCall[];
+    readonly messages: readonly ReceivedMessage[];
+    readonly corrections: readonly ReceivedCorrection[];
+    /** This client's slice of the harness trace. */
+    readonly frames: readonly TraceEntry[];
+    /** Opens the reconnect grace window: presence goes `connected: false`, frames stop. */
+    disconnect(): void;
+    /** Re-joins with the same id and role; the view is rebuilt from a fresh snapshot. */
+    reconnect(): void;
+    leave(reason?: LeaveReason): void;
+    /** A record from the view (`undefined` when absent). */
+    get(entity: string, id: string): AnyRecord | undefined;
+    /** A view collection, for direct inspection. */
+    entity(name: string): EntityCollection;
+}
+
+/**
+ * `createRoomHarness` — the in-process room harness. It runs a real `RoomCore`
+ * against a fake clock and fake clients, in one synchronous, deterministic process. No sockets,
+ * no worker, no Node built-ins: it runs anywhere Vitest does.
+ *
+ * ## Timing model
+ *
+ * The only clock is `FakeClock`. `h.tick(n)` advances exactly `n` tick intervals in tick mode
+ * (running `n` ticks and delivering every frame they produce) and runs due timers without moving
+ * the clock in event mode. `h.run(ms)` advances the clock by `ms`, firing ticks and timers in
+ * order. Both return only after everything due has fired and every frame has been delivered.
+ *
+ * ## Frame delivery
+ *
+ * Frames the room sends are delivered to the `FakeClient` immediately (decoded, applied to its
+ * view, traced). Frames a client sends are queued and handed to `RoomCore.receive` at the next
+ * safe point — never re-entrantly inside the core — which is before `tick()`/`run()`/`join()`
+ * returns, or immediately if nothing is currently executing.
+ *
+ * ## Promises
+ *
+ * `client.call()` settles when the `REPLY` is delivered, which happens inside a later
+ * `h.tick()` / `h.run()`. Tests therefore read:
+ *
+ * ```ts
+ * const p = a.call('start');
+ * h.tick();
+ * await expect(p).resolves.toEqual(...);
+ * ```
+ *
+ * An **async** `onCall` implementation cannot reply synchronously: its `REPLY` is sent when the
+ * promise settles, i.e. in a microtask. Tests must `await` (anything — `await null` is enough)
+ * and then `h.tick()` so the room sees the reply.
+ */
+
+interface HarnessOptions {
+    /** `room.random()` seed; default 1 (same as `RoomCore`). */
+    readonly seed?: number;
+    /** Base URL for `room.link`. */
+    readonly publicUrl?: string;
+    /** Default `'test-room'`. */
+    readonly roomId?: string;
+    /** Bytes from a previous `serialize()`: the room wakes instead of being created. */
+    readonly restoreFrom?: Uint8Array;
+}
+interface JoinSpec {
+    readonly role?: string;
+    readonly name?: string;
+    /** Default: `c1`, `c2`, … in join order. */
+    readonly id?: string;
+}
+interface UntilOptions {
+    /** Default 1000. */
+    readonly maxTicks?: number;
+}
+interface RoomHarness<S extends AnySchema = AnySchema> {
+    /** Escape hatch: the real `RoomCore`. */
+    readonly core: RoomCore<S>;
+    /** The `room` API handlers see. */
+    readonly room: Room<S>;
+    /** The tracked authority — tests may mutate it exactly like room code. */
+    readonly state: State<S>;
+    /** The authority's plain state (what the codec reads). */
+    readonly plain: PlainState;
+    readonly stats: RoomStats;
+    readonly now: number;
+    /**
+     * The room's tick counter. Named `tickCount` because `tick()` is the method that advances it —
+     * TypeScript cannot have both under one name. `h.core.tick` is the same number.
+     */
+    readonly tickCount: number;
+    readonly mode: 'tick' | 'event';
+    readonly host: HarnessHost;
+    /** Every client that ever joined, in join order. Departed ones stay, with `connected: false`. */
+    readonly clients: readonly FakeClient<S>[];
+    /** Every frame that crossed the seam, in order. */
+    readonly trace: readonly TraceEntry[];
+    /** Tick mode: run exactly `n` ticks. Event mode: run timers already due (the clock stays put). */
+    tick(n?: number): void;
+    /** Advance the fake clock, firing ticks and timers in order. */
+    run(ms: number): void;
+    /** Tick until `pred()` holds; throws when it never does. */
+    until(pred: () => boolean, options?: UntilOptions): void;
+    join(spec?: JoinSpec): FakeClient<S>;
+    join(n: number, spec?: JoinSpec): FakeClient<S>[];
+    /** Collections a client can see that its role must not. `[]` when the room is clean. */
+    checkVisibility(): VisibilityLeak[];
+    /** Hibernation bytes (`RoomCore.serialize`). */
+    serialize(): Uint8Array;
+    /**
+     * Replaces the room with a fresh `RoomCore` restored from `bytes`, keeping the same host and
+     * clock. Presence is empty after a restore, so the harness's client list is cleared too: the
+     * `FakeClient` objects from before are stale and must not be used again — re-`join()` instead.
+     */
+    restore(bytes: Uint8Array): void;
+    stop(): void;
+}
+/** Creates a room harness around a `RoomDefinition`. The room is already started on return. */
+declare function createRoomHarness<S extends AnySchema>(definition: RoomDefinition<S>, options?: HarnessOptions): RoomHarness<S>;
+
+export { type CallImpl, type FakeClient, FakeClock, type FrameTypeName, HarnessHost, type HarnessOptions, type JoinSpec, type KickRecord, type LogRecord, type ReceivedCall, type ReceivedCorrection, type ReceivedMessage, type RoomHarness, type SendCounts, type TraceEntry, type UntilOptions, type VisibilityLeak, createRoomHarness, frameTypeName };