@serfab/cadre-host 1.13.0 → 1.15.0

package/src/{donation → hosted}/__tests__/fake-orchestrator.test.ts

@@ -1,173 +1,172 @@
-/**
- * Contract tests for `FakeOrchestrator` itself — the handle lifecycle it borrows
- * from `HostProcessOrchestrator`. The donation suites lean on these semantics to
- * express races that only exist because the real class drops and rejects
- * handles, so this file exists to stop a later relaxation of the fake from
- * quietly turning one of those tests green.
- *
- * The rules the fake shares with the real class live in
- * `src/__tests__/orchestrator-handle-contract.ts` and run against both — here
- * and in `src/__tests__/orchestrator.test.ts` — so a disagreement between the
- * two fails a test. The cases in this file add what only the fake has: its
- * recording arrays (`stopped`, `removed`, `reclaimedWorkdirs`) and its hooks.
- * Each names the real behaviour it mirrors.
- */
-
-import { describe, expect, it } from 'vitest';
-
-import type { OrchestratorCreateRequest } from '@serfab/cadre-provider';
-
-import { describeHandleContract } from '../../__tests__/orchestrator-handle-contract.js';
-import { FakeOrchestrator } from './fake-orchestrator.js';
-
-const request = (containerId: string): OrchestratorCreateRequest => ({
-  containerId,
-  partyId: 'party-P',
-  bootstrapNodes: ['/ip4/127.0.0.1/tcp/4001/p2p/12D3KooWA9hbnKrRnPRSPTRkzXqTHzGE8YpJ3JHZmQ5tGwLRTMmp'],
-  profile: 'storage',
-});
-
-describeHandleContract<FakeOrchestrator>('FakeOrchestrator', {
-  make: () => new FakeOrchestrator(),
-  request,
-  // No process to wait for: a fake child is running as soon as it exists.
-  started: () => Promise.resolve(),
-  failNextCreate: (orch) => { orch.failCreate = true; },
-});
-
-describe('FakeOrchestrator handle lifecycle', () => {
-  it('drops the prior handle when a re-spawn succeeds (mirrors dropStaleHandle)', async () => {
-    const orch = new FakeOrchestrator();
-    const first = await orch.createContainer(request('grn_1'));
-    orch.crash(first.dockerId);
-    const second = await orch.createContainer(request('grn_1'));
-
-    await expect(orch.stopContainer(first.dockerId)).rejects.toThrow(
-      `Container not found: ${first.dockerId}`,
-    );
-    // The rejected call left no trace: `stopped` records handles acted on, not
-    // calls attempted.
-    expect(orch.stopped).toEqual([]);
-    // …and the container now resolves only to the new spawn.
-    expect(orch.resolveDockerId('grn_1')).toBe(second.dockerId);
-
-    await orch.stopContainer(second.dockerId);
-    expect(orch.stopped).toEqual([second.dockerId]);
-  });
-
-  it('keeps the prior handle live across the whole pre-drop await window', async () => {
-    const orch = new FakeOrchestrator();
-    const first = await orch.createContainer(request('grn_1'));
-
-    // The invariant the donation race tests rest on: a concurrent stop started
-    // from `onCreate` still finds the old handle. Deferring it onto a microtask
-    // puts it strictly after `onCreate` returns and strictly before the
-    // `createDelayMs` timer, so this one case pins the drop behind BOTH — with
-    // no dependence on wall-clock timing. The outcome is captured rather than
-    // rethrown so a regression fails this assertion instead of surfacing as an
-    // unhandled rejection.
-    orch.createDelayMs = 1;
-    let outcome: Promise<string> | undefined;
-    orch.onCreate = () => {
-      outcome ??= Promise.resolve()
-        .then(() => orch.stopContainer(first.dockerId))
-        .then(() => 'stopped', (err: Error) => `rejected: ${err.message}`);
-    };
-
-    const second = await orch.createContainer(request('grn_1'));
-
-    expect(await outcome).toBe('stopped');
-    expect(orch.stopped).toEqual([first.dockerId]);
-    expect(orch.resolveDockerId('grn_1')).toBe(second.dockerId);
-  });
-
-  it('leaves the prior handle in place when the re-spawn fails (mirrors restoreDroppedHandles)', async () => {
-    const orch = new FakeOrchestrator();
-    const first = await orch.createContainer(request('grn_1'));
-
-    orch.failCreate = true;
-    await expect(orch.createContainer(request('grn_1'))).rejects.toThrow('spawn boom');
-
-    // Host state is exactly as the failed attempt found it — which is what lets
-    // `DonationSupervisor.giveUp` still stop the child it knows about.
-    await expect(orch.stopContainer(first.dockerId)).resolves.toBeUndefined();
-    expect(orch.stopped).toEqual([first.dockerId]);
-    expect(orch.resolveDockerId('grn_1')).toBe(first.dockerId);
-  });
-
-  it('rejects a never-issued dockerId (mirrors requireHandle)', async () => {
-    const orch = new FakeOrchestrator();
-
-    await expect(orch.removeContainer('dock_nope')).rejects.toThrow(
-      'Container not found: dock_nope',
-    );
-    expect(orch.removed).toEqual([]);
-  });
-
-  it('rejects a second call once a handle has been removed (mirrors removeContainer deleting it)', async () => {
-    const orch = new FakeOrchestrator();
-    const { dockerId } = await orch.createContainer(request('grn_1'));
-
-    await orch.removeContainer(dockerId);
-    expect(orch.removed).toEqual([dockerId]);
-
-    await expect(orch.stopContainer(dockerId)).rejects.toThrow(
-      `Container not found: ${dockerId}`,
-    );
-    expect(orch.stopped).toEqual([]);
-  });
-
-  it('fires onStop for a rejected stop, so a test can still observe the attempt', async () => {
-    const orch = new FakeOrchestrator();
-    const attempted: string[] = [];
-    orch.onStop = (id) => { attempted.push(id); };
-
-    await expect(orch.stopContainer('dock_nope')).rejects.toThrow('Container not found');
-    expect(attempted).toEqual(['dock_nope']);
-    expect(orch.stopped).toEqual([]);
-  });
-
-  it('refuses to reclaim the workdir of a container that still resolves (mirrors the live-handle guard)', async () => {
-    const orch = new FakeOrchestrator();
-    await orch.createContainer(request('grn_1'));
-
-    // A live handle owns that directory; only `removeContainer` — which stops
-    // the child first — may delete it.
-    expect(orch.reclaimWorkdir('grn_1')).toBe(false);
-    expect(orch.reclaimedWorkdirs).toEqual([]);
-  });
-
-  it('reclaims the workdir of a container no handle owns', async () => {
-    const orch = new FakeOrchestrator();
-
-    // Never spawned — the stuck-`provisioning` record whose host died before a
-    // handle ever existed.
-    expect(orch.reclaimWorkdir('grn_orphan')).toBe(true);
-    expect(orch.reclaimedWorkdirs).toEqual(['grn_orphan']);
-
-    // …and once the container's own handle is removed, its id becomes
-    // reclaimable too.
-    const { dockerId } = await orch.createContainer(request('grn_1'));
-    expect(orch.reclaimWorkdir('grn_1')).toBe(false);
-    await orch.removeContainer(dockerId);
-    expect(orch.reclaimWorkdir('grn_1')).toBe(true);
-    expect(orch.reclaimedWorkdirs).toEqual(['grn_orphan', 'grn_1']);
-  });
-
-  it('fires onSpawned after the drop, with the new handle live and the old one gone', async () => {
-    const orch = new FakeOrchestrator();
-    const first = await orch.createContainer(request('grn_1'));
-    orch.crash(first.dockerId);
-
-    let observed: { spawned: string; resolves: string | undefined } | undefined;
-    orch.onSpawned = (dockerId) => {
-      observed = { spawned: dockerId, resolves: orch.resolveDockerId('grn_1') };
-    };
-    const second = await orch.createContainer(request('grn_1'));
-
-    // The post-drop world: the container already resolves to the new handle, so
-    // work driven from here sees what `abandonRespawn`'s caller would see.
-    expect(observed).toEqual({ spawned: second.dockerId, resolves: second.dockerId });
-    expect(second.dockerId).not.toBe(first.dockerId);
-  });
-});
+/**
+ * Contract tests for `FakeOrchestrator` itself — the handle lifecycle it borrows
+ * from `HostProcessOrchestrator`. The hosted-node suites lean on these semantics to
+ * express races that only exist because the real class drops and rejects
+ * handles, so this file exists to stop a later relaxation of the fake from
+ * quietly turning one of those tests green.
+ *
+ * The rules the fake shares with the real class live in
+ * `src/__tests__/orchestrator-handle-contract.ts` and run against both — here
+ * and in `src/__tests__/orchestrator.test.ts` — so a disagreement between the
+ * two fails a test. The cases in this file add what only the fake has: its
+ * recording arrays (`stopped`, `removed`, `reclaimedWorkdirs`) and its hooks.
+ * Each names the real behaviour it mirrors.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import type { HostedSpawnRequest } from '../../orchestrator/types.js';
+
+import { describeHandleContract } from '../../__tests__/orchestrator-handle-contract.js';
+import { FakeOrchestrator } from './fake-orchestrator.js';
+
+const request = (containerId: string): HostedSpawnRequest => ({
+  containerId,
+  partyId: 'party-P',
+  profile: 'storage',
+});
+
+describeHandleContract<FakeOrchestrator>('FakeOrchestrator', {
+  make: () => new FakeOrchestrator(),
+  request,
+  // No process to wait for: a fake child is running as soon as it exists.
+  started: () => Promise.resolve(),
+  failNextCreate: (orch) => { orch.failCreate = true; },
+});
+
+describe('FakeOrchestrator handle lifecycle', () => {
+  it('drops the prior handle when a re-spawn succeeds (mirrors dropStaleHandle)', async () => {
+    const orch = new FakeOrchestrator();
+    const first = await orch.createContainer(request('hn_1'));
+    orch.crash(first.dockerId);
+    const second = await orch.createContainer(request('hn_1'));
+
+    await expect(orch.stopContainer(first.dockerId)).rejects.toThrow(
+      `Container not found: ${first.dockerId}`,
+    );
+    // The rejected call left no trace: `stopped` records handles acted on, not
+    // calls attempted.
+    expect(orch.stopped).toEqual([]);
+    // …and the container now resolves only to the new spawn.
+    expect(orch.resolveDockerId('hn_1')).toBe(second.dockerId);
+
+    await orch.stopContainer(second.dockerId);
+    expect(orch.stopped).toEqual([second.dockerId]);
+  });
+
+  it('keeps the prior handle live across the whole pre-drop await window', async () => {
+    const orch = new FakeOrchestrator();
+    const first = await orch.createContainer(request('hn_1'));
+
+    // The invariant the hosted-node race tests rest on: a concurrent stop started
+    // from `onCreate` still finds the old handle. Deferring it onto a microtask
+    // puts it strictly after `onCreate` returns and strictly before the
+    // `createDelayMs` timer, so this one case pins the drop behind BOTH — with
+    // no dependence on wall-clock timing. The outcome is captured rather than
+    // rethrown so a regression fails this assertion instead of surfacing as an
+    // unhandled rejection.
+    orch.createDelayMs = 1;
+    let outcome: Promise<string> | undefined;
+    orch.onCreate = () => {
+      outcome ??= Promise.resolve()
+        .then(() => orch.stopContainer(first.dockerId))
+        .then(() => 'stopped', (err: Error) => `rejected: ${err.message}`);
+    };
+
+    const second = await orch.createContainer(request('hn_1'));
+
+    expect(await outcome).toBe('stopped');
+    expect(orch.stopped).toEqual([first.dockerId]);
+    expect(orch.resolveDockerId('hn_1')).toBe(second.dockerId);
+  });
+
+  it('leaves the prior handle in place when the re-spawn fails (mirrors restoreDroppedHandles)', async () => {
+    const orch = new FakeOrchestrator();
+    const first = await orch.createContainer(request('hn_1'));
+
+    orch.failCreate = true;
+    await expect(orch.createContainer(request('hn_1'))).rejects.toThrow('spawn boom');
+
+    // Host state is exactly as the failed attempt found it — which is what lets
+    // `HostedNodeSupervisor.giveUp` still stop the child it knows about.
+    await expect(orch.stopContainer(first.dockerId)).resolves.toBeUndefined();
+    expect(orch.stopped).toEqual([first.dockerId]);
+    expect(orch.resolveDockerId('hn_1')).toBe(first.dockerId);
+  });
+
+  it('rejects a never-issued dockerId (mirrors requireHandle)', async () => {
+    const orch = new FakeOrchestrator();
+
+    await expect(orch.removeContainer('dock_nope')).rejects.toThrow(
+      'Container not found: dock_nope',
+    );
+    expect(orch.removed).toEqual([]);
+  });
+
+  it('rejects a second call once a handle has been removed (mirrors removeContainer deleting it)', async () => {
+    const orch = new FakeOrchestrator();
+    const { dockerId } = await orch.createContainer(request('hn_1'));
+
+    await orch.removeContainer(dockerId);
+    expect(orch.removed).toEqual([dockerId]);
+
+    await expect(orch.stopContainer(dockerId)).rejects.toThrow(
+      `Container not found: ${dockerId}`,
+    );
+    expect(orch.stopped).toEqual([]);
+  });
+
+  it('fires onStop for a rejected stop, so a test can still observe the attempt', async () => {
+    const orch = new FakeOrchestrator();
+    const attempted: string[] = [];
+    orch.onStop = (id) => { attempted.push(id); };
+
+    await expect(orch.stopContainer('dock_nope')).rejects.toThrow('Container not found');
+    expect(attempted).toEqual(['dock_nope']);
+    expect(orch.stopped).toEqual([]);
+  });
+
+  it('refuses to reclaim the workdir of a container that still resolves (mirrors the live-handle guard)', async () => {
+    const orch = new FakeOrchestrator();
+    await orch.createContainer(request('hn_1'));
+
+    // A live handle owns that directory; only `removeContainer` — which stops
+    // the child first — may delete it.
+    expect(orch.reclaimWorkdir('hn_1')).toBe(false);
+    expect(orch.reclaimedWorkdirs).toEqual([]);
+  });
+
+  it('reclaims the workdir of a container no handle owns', async () => {
+    const orch = new FakeOrchestrator();
+
+    // Never spawned — the stuck-`spawning` record whose host died before a
+    // handle ever existed.
+    expect(orch.reclaimWorkdir('hn_orphan')).toBe(true);
+    expect(orch.reclaimedWorkdirs).toEqual(['hn_orphan']);
+
+    // …and once the container's own handle is removed, its id becomes
+    // reclaimable too.
+    const { dockerId } = await orch.createContainer(request('hn_1'));
+    expect(orch.reclaimWorkdir('hn_1')).toBe(false);
+    await orch.removeContainer(dockerId);
+    expect(orch.reclaimWorkdir('hn_1')).toBe(true);
+    expect(orch.reclaimedWorkdirs).toEqual(['hn_orphan', 'hn_1']);
+  });
+
+  it('fires onSpawned after the drop, with the new handle live and the old one gone', async () => {
+    const orch = new FakeOrchestrator();
+    const first = await orch.createContainer(request('hn_1'));
+    orch.crash(first.dockerId);
+
+    let observed: { spawned: string; resolves: string | undefined } | undefined;
+    orch.onSpawned = (dockerId) => {
+      observed = { spawned: dockerId, resolves: orch.resolveDockerId('hn_1') };
+    };
+    const second = await orch.createContainer(request('hn_1'));
+
+    // The post-drop world: the container already resolves to the new handle, so
+    // work driven from here sees what `abandonRespawn`'s caller would see.
+    expect(observed).toEqual({ spawned: second.dockerId, resolves: second.dockerId });
+    expect(second.dockerId).not.toBe(first.dockerId);
+  });
+});

package/src/{donation → hosted}/__tests__/fake-orchestrator.ts

@@ -1,5 +1,5 @@
 /**
- * Shared fake orchestrator for the donation unit tests — no real child
+ * Shared fake orchestrator for the hosted-node unit tests — no real child
  * processes. Records every create / stop / remove, hands out deterministic
  * unique spawn results, and tracks per-`dockerId` liveness so a test can crash
  * one node and let the supervisor observe exactly that one as down.
@@ -9,17 +9,16 @@
  * and run against both classes, so the two cannot come to disagree unnoticed.
  * The sibling `fake-orchestrator.test.ts` runs that contract and pins what only
  * the fake has (its recording arrays and hooks). Both exist so a future agent
- * cannot make a failing donation test go green by relaxing the fake.
+ * cannot make a failing hosted-node test go green by relaxing the fake.
  */
 
 import type {
   Orchestrator,
-  OrchestratorCreateRequest,
   OrchestratorCreateResult,
   OrchestratorStats,
 } from '@serfab/cadre-provider';
 
-import type { ManagedNodeInfo, NodeStateListener } from '../../orchestrator/types.js';
+import type { HostedSpawnRequest, ManagedNodeInfo, NodePorts, NodeStateListener } from '../../orchestrator/types.js';
 
 function sleep(ms: number): Promise<void> {
   return new Promise((res) => setTimeout(res, ms));
@@ -31,15 +30,18 @@ interface FakeChild {
   partyId: string;
   profile: 'storage' | 'transaction';
   running: boolean;
+  /** The ports a re-spawn comes back on (the real `reusedNodePorts`). */
+  ports: NodePorts;
 }
 
 /**
- * Mirrors the parts of `HostProcessOrchestrator`'s handle lifecycle the donation
+ * Mirrors the parts of `HostProcessOrchestrator`'s handle lifecycle the hosted-node
  * code depends on:
  *
  * - a **successful** `createContainer` drops every prior handle for the same
  *   `containerId` (the real `dropStaleHandle`), so an old `dockerId` stops
- *   resolving the moment its container re-spawns;
+ *   resolving the moment its container re-spawns — and the new child comes back
+ *   on the dropped handle's ports (the real `reusedNodePorts`);
  * - a **failed** `createContainer` leaves those handles exactly as it found them
  *   (the real `restoreDroppedHandles`);
  * - `createContainer` refuses a container whose previous child is still running
@@ -56,7 +58,7 @@ interface FakeChild {
  * a test can observe the attempt separately from its outcome.
  */
 export class FakeOrchestrator implements Orchestrator {
-  createCalls: OrchestratorCreateRequest[] = [];
+  createCalls: HostedSpawnRequest[] = [];
   stopped: string[] = [];
   removed: string[] = [];
   /**
@@ -78,7 +80,7 @@ export class FakeOrchestrator implements Orchestrator {
    * Work driven from here sees the previous handle still alive. Contrast
    * {@link onSpawned}.
    */
-  onCreate?: (request: OrchestratorCreateRequest) => void;
+  onCreate?: (request: HostedSpawnRequest) => void;
   /**
    * Observation hook — fires once the drop has landed and the new child is
    * registered, immediately before `createContainer` resolves. Models the
@@ -95,7 +97,7 @@ export class FakeOrchestrator implements Orchestrator {
   private readonly listeners = new Set<NodeStateListener>();
   private counter = 0;
 
-  async createContainer(request: OrchestratorCreateRequest): Promise<OrchestratorCreateResult> {
+  async createContainer(request: HostedSpawnRequest): Promise<OrchestratorCreateResult> {
     this.createCalls.push(request);
     this.onCreate?.(request);
     if (this.createDelayMs) await sleep(this.createDelayMs);
@@ -107,26 +109,30 @@ export class FakeOrchestrator implements Orchestrator {
     // Success-only, and placed here on purpose: the real drop happens after the
     // spawn's every `await` and cannot fail afterwards, and a create that throws
     // puts the handles back (`restoreDroppedHandles`) — so a failed create must
-    // leave them untouched. `DonationSupervisor`'s give-up test depends on that.
+    // leave them untouched. `HostedNodeSupervisor`'s give-up test depends on that.
+    let ports: NodePorts | undefined;
     for (const [id, child] of this.children) {
-      if (child.containerId === request.containerId) this.children.delete(id);
+      if (child.containerId === request.containerId) {
+        ports = child.ports;
+        this.children.delete(id);
+      }
     }
     const n = ++this.counter;
     const dockerId = `dock_${n}`;
+    ports ??= { health: 9000 + n, metrics: 9100 + n, p2p: 4000 + n, ws: 4100 + n };
     this.children.set(dockerId, {
       containerId: request.containerId,
       partyId: request.partyId,
       profile: request.profile,
       running: true,
+      ports,
     });
     this.onSpawned?.(dockerId);
     return {
       dockerId,
-      healthEndpoint: `http://127.0.0.1:${9000 + n}/health`,
-      metricsEndpoint: `http://127.0.0.1:${9000 + n}/metrics`,
-      seedEndpoint: `http://127.0.0.1:${9000 + n}/seed`,
-      seedToken: `seed-token-${n}`,
-      p2pPort: 4000 + n,
+      healthEndpoint: `http://127.0.0.1:${ports.health}/health`,
+      metricsEndpoint: `http://127.0.0.1:${ports.metrics}/metrics`,
+      p2pPort: ports.p2p,
     };
   }
 
@@ -142,7 +148,7 @@ export class FakeOrchestrator implements Orchestrator {
   async removeContainer(dockerId: string): Promise<void> {
     // NOTE: the real `removeContainer` stops a still-live child first; this one
     // only deletes, so a remove aimed at a running child records no `stopped`
-    // entry and emits no state change. Every donation caller stops before it
+    // entry and emits no state change. Every hosted-node caller stops before it
     // reclaims, so nothing sees the difference today — if one stops doing that,
     // stop the child here too.
     this.requireChild(dockerId);
@@ -152,8 +158,8 @@ export class FakeOrchestrator implements Orchestrator {
 
   /**
    * NOTE: this and {@link getLogs} take an unknown `dockerId` where the real
-   * class throws (`requireHandle`). No donation path calls either, so the gap is
-   * unobservable — route them through `requireChild` if one starts to.
+   * class throws (`requireHandle`). No hosted-node path calls either, so the gap
+   * is unobservable — route them through `requireChild` if one starts to.
    */
   async getStats(): Promise<OrchestratorStats> {
     return { cpuPercent: 0, memoryBytes: 0, networkRxBytes: 0, networkTxBytes: 0 };
@@ -173,6 +179,20 @@ export class FakeOrchestrator implements Orchestrator {
     return undefined;
   }
 
+  /** The node by containerId or dockerId, as the real `getNode`. */
+  getNode(idOrDockerId: string): ManagedNodeInfo | undefined {
+    const direct = this.children.get(idOrDockerId);
+    if (direct) return toNodeInfo(idOrDockerId, direct);
+    for (const [dockerId, child] of this.children) {
+      if (child.containerId === idOrDockerId) return toNodeInfo(dockerId, child);
+    }
+    return undefined;
+  }
+
+  listNodes(): ManagedNodeInfo[] {
+    return [...this.children].map(([dockerId, child]) => toNodeInfo(dockerId, child));
+  }
+
   /**
    * Remove the workdir of a container no handle owns, mirroring the real
    * `reclaimWorkdir`. Refuses (returns `false`, records nothing) while a child
@@ -181,7 +201,7 @@ export class FakeOrchestrator implements Orchestrator {
    *
    * There is no directory here to check for existence, so a first reclaim of an
    * unresolvable id always reports `true`; the real class returns `false` when
-   * the path is already gone. Nothing in the donation layer branches on the
+   * the path is already gone. Nothing in the hosted-node layer branches on the
    * return value, so the gap is unobservable — model it if one starts to.
    */
   reclaimWorkdir(containerId: string): boolean {
@@ -207,8 +227,7 @@ export class FakeOrchestrator implements Orchestrator {
     this.emit(toNodeInfo(dockerId, child));
   }
 
-  /** Emit an arbitrary state change (e.g. the owner node stopping). */
-  emit(info: ManagedNodeInfo): void {
+  private emit(info: ManagedNodeInfo): void {
     for (const listener of this.listeners) listener(info);
   }
 
@@ -238,6 +257,7 @@ function toNodeInfo(dockerId: string, child: FakeChild): ManagedNodeInfo {
     status: child.running ? 'running' : 'stopped',
     spawnedAt: new Date(0).toISOString(),
     workdir: `/fake/${child.containerId}`,
-    ports: { health: 0, metrics: 0, p2p: 0, admin: 0, ws: 0 },
+    ports: { ...child.ports },
+    announcedAddrs: [],
   };
 }