actor-ts 0.9.0

package/dist/testkit/MultiNodeSpec.js

@@ -0,0 +1,237 @@
+import { ActorSystem } from '../ActorSystem.js';
+import { Cluster } from '../cluster/Cluster.js';
+import { NodeAddress } from '../cluster/NodeAddress.js';
+import { LogLevel, NoopLogger } from '../Logger.js';
+import { MultiNodeTransport } from './internal/MultiNodeTransport.js';
+let nextPortBase = 30_000;
+export class MultiNodeSpec {
+    settings;
+    nodes = new Map();
+    started = false;
+    constructor(settings) {
+        if (settings.roles.length === 0) {
+            throw new Error('MultiNodeSpec: at least one role is required');
+        }
+        if (new Set(settings.roles).size !== settings.roles.length) {
+            throw new Error('MultiNodeSpec: roles must be unique');
+        }
+        this.settings = {
+            roles: settings.roles,
+            seedRoles: settings.seedRoles ?? [settings.roles[0]],
+            gossipIntervalMs: settings.gossipIntervalMs ?? 100,
+            awaitTimeoutMs: settings.awaitTimeoutMs ?? 10_000,
+            logLevel: settings.logLevel ?? LogLevel.Off,
+            addresses: settings.addresses,
+            failureDetector: settings.failureDetector,
+            downing: settings.downing,
+        };
+    }
+    /** Bring up every role. */
+    async start() {
+        if (this.started)
+            throw new Error('MultiNodeSpec: already started');
+        this.started = true;
+        const portBase = nextPortBase;
+        nextPortBase += this.settings.roles.length + 1;
+        // Step 1: build the address book up front so seeds can name peers.
+        const addressByRole = new Map();
+        this.settings.roles.forEach((role, idx) => {
+            const explicit = this.settings.addresses?.[role];
+            const host = explicit?.host ?? '127.0.0.1';
+            const port = explicit?.port ?? (portBase + idx);
+            addressByRole.set(role, new NodeAddress(role, host, port));
+        });
+        const seeds = this.settings.seedRoles
+            .map((r) => addressByRole.get(r))
+            .filter((a) => a !== undefined)
+            .map((a) => a.toString());
+        // Step 2: spin up systems + clusters.  Seed role is started first
+        // so the others can hit it with their initial join gossip.
+        const orderedRoles = [
+            ...this.settings.seedRoles,
+            ...this.settings.roles.filter((r) => !this.settings.seedRoles.includes(r)),
+        ];
+        for (const role of orderedRoles) {
+            const address = addressByRole.get(role);
+            const transport = new MultiNodeTransport(address);
+            const system = ActorSystem.create(role, {
+                logger: new NoopLogger(),
+                logLevel: this.settings.logLevel,
+            });
+            const cluster = await Cluster.join(system, {
+                host: address.host,
+                port: address.port,
+                seeds,
+                transport,
+                gossipIntervalMs: this.settings.gossipIntervalMs,
+                seedRetryIntervalMs: 100,
+                failureDetector: this.settings.failureDetector,
+                downing: this.settings.downing?.(role),
+            });
+            this.nodes.set(role, {
+                role,
+                address,
+                transport,
+                system,
+                cluster,
+                removed: false,
+            });
+        }
+    }
+    /** Tear down every node.  Idempotent — safe to call after `crash()`. */
+    async stop() {
+        const errs = [];
+        for (const node of this.nodes.values()) {
+            try {
+                if (!node.removed)
+                    await node.cluster.leave();
+            }
+            catch (e) {
+                errs.push(e);
+            }
+            try {
+                await node.system.terminate();
+            }
+            catch (e) {
+                errs.push(e);
+            }
+        }
+        this.nodes.clear();
+        this.started = false;
+        if (errs.length > 0) {
+            // eslint-disable-next-line no-console
+            console.warn(`MultiNodeSpec.stop encountered ${errs.length} error(s):`, errs.map((e) => e.message));
+        }
+    }
+    /* ----------------------------- accessors ------------------------------ */
+    systemFor(role) { return this.requireNode(role).system; }
+    clusterFor(role) { return this.requireNode(role).cluster; }
+    addressFor(role) { return this.requireNode(role).address; }
+    /** All roles currently registered, regardless of crashed/active state. */
+    allRoles() { return Array.from(this.nodes.keys()); }
+    /* -------------------------- failure simulation ----------------------- */
+    /**
+     * Hard crash — shut down the transport so the node disappears
+     * abruptly.  Other nodes notice via failure detection (typically
+     * within `failureDetector.acceptableHeartbeatPause + threshold` ms).
+     * The terminated node's `cluster` and `system` references stay live
+     * for assertion purposes; calls to them post-crash will error.
+     */
+    async crash(role) {
+        const node = this.requireNode(role);
+        if (node.removed)
+            return;
+        node.removed = true;
+        await node.transport.shutdown();
+    }
+    /** Graceful leave — node sends a Leaving gossip, then shuts down. */
+    async leave(role) {
+        const node = this.requireNode(role);
+        if (node.removed)
+            return;
+        node.removed = true;
+        await node.cluster.leave();
+    }
+    /** Bidirectional partition between two roles.  Both sides drop traffic to the other. */
+    partition(roleA, roleB) {
+        const a = this.requireNode(roleA);
+        const b = this.requireNode(roleB);
+        a.transport.partitionFromPeer(b.address);
+        b.transport.partitionFromPeer(a.address);
+    }
+    /** Undo `partition(roleA, roleB)`. */
+    heal(roleA, roleB) {
+        const a = this.requireNode(roleA);
+        const b = this.requireNode(roleB);
+        a.transport.unblockOutgoing(b.address);
+        b.transport.unblockOutgoing(a.address);
+    }
+    /* --------------------------- await helpers --------------------------- */
+    /**
+     * Wait until the named role's view of the cluster contains exactly
+     * `expectedCount` members in `up`-or-better state.  Throws on timeout.
+     */
+    async awaitMembers(role, expectedCount, timeoutMs = this.settings.awaitTimeoutMs) {
+        await this.awaitCondition(() => {
+            const cluster = this.requireNode(role).cluster;
+            const upCount = cluster.getMembers().filter((m) => m.status === 'up').length;
+            return upCount === expectedCount;
+        }, `awaitMembers(${role}, expected=${expectedCount}) — current: ${this.snapshotMemberCount(role)}`, timeoutMs);
+    }
+    /**
+     * Wait until the named role's view shows `targetMember` (by role name)
+     * in the given status (`up`, `unreachable`, `down`, `removed`).
+     */
+    async awaitMemberStatus(role, targetRole, status, timeoutMs = this.settings.awaitTimeoutMs) {
+        const targetAddr = this.requireNode(targetRole).address.toString();
+        await this.awaitCondition(() => {
+            const cluster = this.requireNode(role).cluster;
+            const member = cluster.getMembers().find((m) => m.address.toString() === targetAddr);
+            return member?.status === status;
+        }, `awaitMemberStatus(${role}, ${targetRole} → ${status}) — current: ${this.snapshotMembers(role)}`, timeoutMs);
+    }
+    /**
+     * Wait until the named role's view of the leader is `expectedLeaderRole`,
+     * or `null` to wait for "no leader".
+     */
+    async awaitLeader(role, expectedLeaderRole, timeoutMs = this.settings.awaitTimeoutMs) {
+        const expectedAddr = expectedLeaderRole
+            ? this.requireNode(expectedLeaderRole).address.toString()
+            : null;
+        await this.awaitCondition(() => {
+            const leader = this.requireNode(role).cluster.leader().toNullable();
+            if (expectedAddr === null)
+                return leader === null;
+            return leader?.address.toString() === expectedAddr;
+        }, `awaitLeader(${role}, expected=${expectedLeaderRole ?? 'null'}) — current: ${this.snapshotLeader(role)}`, timeoutMs);
+    }
+    /* ----------------------------- internals ---------------------------- */
+    requireNode(role) {
+        const node = this.nodes.get(role);
+        if (!node)
+            throw new Error(`MultiNodeSpec: unknown role '${role}'`);
+        return node;
+    }
+    async awaitCondition(cond, description, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (cond())
+                return;
+            await new Promise((r) => setTimeout(r, 25));
+        }
+        throw new Error(`MultiNodeSpec: timeout after ${timeoutMs} ms — ${description}`);
+    }
+    snapshotMemberCount(role) {
+        try {
+            const cluster = this.requireNode(role).cluster;
+            const counts = cluster.getMembers().reduce((acc, m) => {
+                acc[m.status] = (acc[m.status] ?? 0) + 1;
+                return acc;
+            }, {});
+            return JSON.stringify(counts);
+        }
+        catch (e) {
+            return `(snapshot failed: ${e.message})`;
+        }
+    }
+    snapshotMembers(role) {
+        try {
+            const cluster = this.requireNode(role).cluster;
+            return cluster.getMembers()
+                .map((m) => `${m.address.systemName}=${m.status}`)
+                .join(', ') || '(empty)';
+        }
+        catch (e) {
+            return `(snapshot failed: ${e.message})`;
+        }
+    }
+    snapshotLeader(role) {
+        try {
+            return this.requireNode(role).cluster.leader().toNullable()?.address.systemName ?? 'null';
+        }
+        catch (e) {
+            return `(snapshot failed: ${e.message})`;
+        }
+    }
+}
+//# sourceMappingURL=MultiNodeSpec.js.map

package/dist/testkit/MultiNodeSpec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MultiNodeSpec.js","sourceRoot":"","sources":["../../src/testkit/MultiNodeSpec.ts"],"names":[],"mappings":"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"}

package/dist/testkit/ParallelMultiNodeSpec.d.ts

@@ -0,0 +1,117 @@
+import type { FailureDetectorSettings } from '../cluster/FailureDetector.js';
+import type { Member } from '../cluster/Member.js';
+import { NodeAddress } from '../cluster/NodeAddress.js';
+import { LogLevel } from '../Logger.js';
+import type { MemberSnapshot } from './internal/parallel-multi-node-bootstrap.js';
+/**
+ * Worker-thread variant of `MultiNodeSpec` (#46).  Each role runs in
+ * a dedicated `worker_threads` Worker (or Web Worker on Bun/Deno),
+ * connected via a shared `MultiNodeBroker`.  Use this variant when a
+ * test needs **true parallelism** — concurrent journal writes,
+ * scheduler-thread interleaving, anything that doesn't fully
+ * serialise on the main event loop.
+ *
+ * **Trade-offs vs. `MultiNodeSpec`** (in-process variant):
+ *
+ *   - **Pro**: real OS threads.  Catches races the in-process variant
+ *     papers over by virtue of running on a single event loop.
+ *   - **Con**: slower start-up (worker spawn + cluster handshake
+ *     takes ~200-500 ms vs. ~10 ms in-process).  Stack traces span
+ *     thread boundaries and are messier.  No `systemFor` /
+ *     `clusterFor` returning real instances — the actor system
+ *     lives in the worker, so the harness exposes JSON-shaped
+ *     accessors (`getMembers()`, `getLeader()`) and a
+ *     `runIn(role, command, args)` RPC for invoking scenario-
+ *     defined commands.
+ *
+ * **Public API mirrors `MultiNodeSpec`** for the lifecycle bits —
+ * `start`, `stop`, `crash`, `leave`, `partition`, `heal`,
+ * `awaitMembers`, `awaitMemberStatus`, `awaitLeader`, `addressFor`,
+ * `allRoles` — so a test that only uses those works against either
+ * variant by changing one constructor.
+ *
+ *   const spec = new ParallelMultiNodeSpec({
+ *     roles: ['a', 'b', 'c'],
+ *     scenarioModule: new URL('./my-scenario.ts', import.meta.url),
+ *   });
+ *   await spec.start();
+ *   await spec.awaitMembers('a', 3);
+ *   const result = await spec.runIn('a', 'compute', { x: 42 });
+ *   await spec.stop();
+ *
+ * The scenario module owns the actor-shaped setup (entity classes,
+ * sharding regions, …) inside the worker — see
+ * `src/testkit/internal/parallel-multi-node-bootstrap.ts` for the
+ * `ScenarioModule` interface.
+ */
+export interface ParallelMultiNodeSpecSettings {
+    readonly roles: ReadonlyArray<string>;
+    readonly seedRoles?: ReadonlyArray<string>;
+    /**
+     * URL of the scenario module to load in each worker.  Optional —
+     * tests that only exercise the cluster lifecycle (no actor logic)
+     * don't need one.
+     */
+    readonly scenarioModule?: URL;
+    /** Per-role data passed to the scenario module's `setup(ctx)`. */
+    readonly scenarioInitDataFor?: (role: string) => unknown;
+    readonly addresses?: Readonly<Record<string, {
+        host: string;
+        port: number;
+    }>>;
+    readonly failureDetector?: Partial<FailureDetectorSettings>;
+    readonly gossipIntervalMs?: number;
+    readonly awaitTimeoutMs?: number;
+    readonly logLevel?: LogLevel;
+    /**
+     * URL of the bootstrap script.  Defaults to the bundled
+     * `parallel-multi-node-bootstrap.js`.  Tests rarely override —
+     * setting your own bootstrap means you have to re-implement the
+     * control-channel protocol, which is internal-only.
+     */
+    readonly bootstrapModule?: URL;
+}
+export declare class ParallelMultiNodeSpec {
+    private readonly settings;
+    private readonly nodes;
+    private readonly broker;
+    private started;
+    private nextReqId;
+    /** Pending RPC promises keyed by reqId. */
+    private readonly pending;
+    constructor(settings: ParallelMultiNodeSpecSettings);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    crash(role: string): Promise<void>;
+    leave(role: string): Promise<void>;
+    partition(roleA: string, roleB: string): void;
+    heal(roleA: string, roleB: string): void;
+    addressFor(role: string): NodeAddress;
+    allRoles(): string[];
+    /** Async snapshot of the worker's view of cluster members. */
+    getMembers(role: string): Promise<MemberSnapshot[]>;
+    getLeader(role: string): Promise<string | null>;
+    /** Invoke a scenario-defined command on the worker. */
+    runIn<R = unknown>(role: string, command: string, args?: unknown): Promise<R>;
+    awaitMembers(role: string, expectedCount: number, timeoutMs?: number): Promise<void>;
+    awaitMemberStatus(role: string, targetRole: string, status: Member['status'], timeoutMs?: number): Promise<void>;
+    awaitLeader(role: string, expectedLeaderRole: string | null, timeoutMs?: number): Promise<void>;
+    private requireNode;
+    private awaitCondition;
+    /**
+     * Spawn one worker, do the WorkerNode handshake, register the
+     * worker-side port with the broker, and wire up the control
+     * channel so RPC responses flow back to `this.pending`.
+     */
+    private spawnRole;
+    private brokerFacade;
+    private handshake;
+    /**
+     * Send a control request to a worker and await its response.
+     * Times out after 5s — RPC failures usually indicate the worker
+     * is wedged; fast timeouts surface the issue rather than hanging
+     * the test forever.
+     */
+    private controlRpc;
+}
+//# sourceMappingURL=ParallelMultiNodeSpec.d.ts.map

package/dist/testkit/ParallelMultiNodeSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParallelMultiNodeSpec.d.ts","sourceRoot":"","sources":["../../src/testkit/ParallelMultiNodeSpec.ts"],"names":[],"mappings":"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"}