@serfab/cadre-host 0.12.0 → 0.13.0

package/src/donation/__tests__/fake-orchestrator.test.ts

@@ -1,168 +1,168 @@
-/**
- * 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. Each case names the real behaviour
- * it mirrors.
- */
-
-import { describe, expect, it } from 'vitest';
-
-import type { OrchestratorCreateRequest } from '@serfab/cadre-provider';
-
-import { FakeOrchestrator } from './fake-orchestrator.js';
-
-const request = (containerId: string): OrchestratorCreateRequest => ({
-  containerId,
-  partyId: 'party-P',
-  bootstrapNodes: ['/ip4/127.0.0.1/tcp/4001/p2p/12D3KooReq'],
-  profile: 'storage',
-});
-
-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'));
-    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('drops only the re-spawned container, leaving another container untouched', async () => {
-    const orch = new FakeOrchestrator();
-    const other = await orch.createContainer(request('grn_2'));
-    await orch.createContainer(request('grn_1'));
-    await orch.createContainer(request('grn_1'));
-
-    // The real drop filters on containerId; a fake that cleared the whole map
-    // would still pass every same-container case above.
-    await expect(orch.stopContainer(other.dockerId)).resolves.toBeUndefined();
-    expect(orch.resolveDockerId('grn_2')).toBe(other.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'));
-
-    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 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. Each case names the real behaviour
+ * it mirrors.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import type { OrchestratorCreateRequest } from '@serfab/cadre-provider';
+
+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',
+});
+
+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'));
+    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('drops only the re-spawned container, leaving another container untouched', async () => {
+    const orch = new FakeOrchestrator();
+    const other = await orch.createContainer(request('grn_2'));
+    await orch.createContainer(request('grn_1'));
+    await orch.createContainer(request('grn_1'));
+
+    // The real drop filters on containerId; a fake that cleared the whole map
+    // would still pass every same-container case above.
+    await expect(orch.stopContainer(other.dockerId)).resolves.toBeUndefined();
+    expect(orch.resolveDockerId('grn_2')).toBe(other.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'));
+
+    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);
+  });
+});

package/src/orchestrator/host-process-orchestrator.ts

@@ -568,7 +568,12 @@ export class HostProcessOrchestrator implements Orchestrator {
       // pinnedOwnerKeys, so a managed child advertises only the port assigned to it here
       // — `CADRE_ANNOUNCE_ADDRS`/`CADRE_APPEND_ANNOUNCE_ADDRS` cannot reach it. Fine while
       // children are reached at that port or through a relay; if a host is ever fronted by
-      // a proxy or DNS name, plumb an announce var through from host config.
+      // a proxy or DNS name, plumb an announce var through from host config. The port is
+      // the CHILD'S CONTROL NODE's alone: each strand node the child runs binds the same
+      // entry with an OS-assigned port instead, since one port cannot be held twice
+      // (`cadre-core/src/strand-network-config.ts`). A NAT forward of this port therefore
+      // reaches the control node only, and strand nodes are reached through observed
+      // addresses or a relay.
       CADRE_SEED_TOKEN: seedToken,
       // Pin each child's node-local state (trusted-owner anchor, retained
       // cold-start dial targets) to its OWN workdir. This is the same value the

package/src/server/__tests__/bootstrap-node-validation.test.ts

@@ -0,0 +1,134 @@
+/**
+ * The host's `bootstrapNodes` rule — the requester addresses a donated node is
+ * started with — exercised directly.
+ *
+ * This is one half of a **manual tripwire**: cadre-provider carries a
+ * byte-identical copy of this rule
+ * (`packages/cadre-provider/src/server/bootstrap-node-validation.ts`) and the table
+ * below is the same table
+ * `packages/cadre-provider/src/server/__tests__/bootstrap-node-validation.test.ts`
+ * pins that copy to. Neither suite can observe the other package — nothing here
+ * imports cadre-provider's server module — so this does not detect a change made
+ * over there; what it does is fail if *this* copy is changed, which is how an
+ * editor is landed on the comment pointing at the other one.
+ *
+ * The route contract (`POST /grants` → 400, nothing provisioned) lives in
+ * `grants-route.test.ts`, next to the rest of that route's HTTP behaviour.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { validateBootstrapNodes } from '../routes/bootstrap-node-validation.js';
+
+/**
+ * A real, decodable peer id. Placeholder strings like `12D3KooReq` look right and
+ * are not: `peerIdFromString` throws `Incorrect length` on them, which is exactly
+ * the typo this rule exists to catch.
+ */
+const PEER = '12D3KooWA9hbnKrRnPRSPTRkzXqTHzGE8YpJ3JHZmQ5tGwLRTMmp';
+const GOOD = `/ip4/127.0.0.1/tcp/4001/p2p/${PEER}`;
+/** A second, distinct dialable address, for "which entry was bad" assertions. */
+const GOOD_2 = `/dns4/bootstrap.example/tcp/443/wss/p2p/${PEER}`;
+
+describe('validateBootstrapNodes (the host copy of the address rule)', () => {
+  function errorOf(value: unknown): string {
+    const result = validateBootstrapNodes(value);
+    if (!('error' in result)) throw new Error(`expected a rejection, got ${JSON.stringify(result)}`);
+    return result.error;
+  }
+
+  it('accepts a dialable address and returns it trimmed', () => {
+    expect(validateBootstrapNodes([`  ${GOOD}\n`])).toEqual({ nodes: [GOOD] });
+  });
+
+  it('accepts several dialable addresses across transports', () => {
+    expect(validateBootstrapNodes([GOOD, GOOD_2])).toEqual({ nodes: [GOOD, GOOD_2] });
+  });
+
+  it('accepts a relayed address whose relay and target peer ids both decode', () => {
+    const relayed = `/ip4/1.2.3.4/tcp/4001/p2p/${PEER}/p2p-circuit/p2p/${PEER}`;
+    expect(validateBootstrapNodes([relayed])).toEqual({ nodes: [relayed] });
+  });
+
+  it('treats an absent field and an empty list alike: the field is required', () => {
+    expect(errorOf(undefined)).toBe('bootstrapNodes is required');
+    expect(errorOf([])).toBe('bootstrapNodes is required');
+  });
+
+  it('rejects a non-array, and an array with a non-string element', () => {
+    expect(errorOf(GOOD)).toBe('bootstrapNodes must be an array of strings');
+    expect(errorOf(null)).toBe('bootstrapNodes must be an array of strings');
+    expect(errorOf([42])).toBe('bootstrapNodes must be an array of strings');
+    expect(errorOf([GOOD, { addr: GOOD }])).toBe('bootstrapNodes must be an array of strings');
+  });
+
+  it('rejects an empty or whitespace-only entry with the blank-value message', () => {
+    for (const blank of ['', '   ', '\t\n']) {
+      expect(errorOf([blank])).toMatch(/must not be empty or whitespace-only/);
+    }
+  });
+
+  // Case 1: `@libp2p/bootstrap` maps `multiaddr()` over the list before filtering,
+  // so this one throws during libp2p construction and the child never starts.
+  it('rejects a string that is not a multiaddr, naming it', () => {
+    for (const bad of ['not-an-address', '42', 'bootstrap.example:4001']) {
+      const message = errorOf([bad]);
+      expect(message).toMatch(/must be multiaddrs/);
+      expect(message).toContain(bad);
+    }
+  });
+
+  // Case 2: the quiet one — parses, then gets filtered out inside the child and
+  // the node comes up healthy-looking with zero bootstrap peers.
+  it('rejects a valid multiaddr with no /p2p/ component, naming it', () => {
+    const message = errorOf(['/ip4/127.0.0.1/tcp/4001']);
+    expect(message).toMatch(/must include a \/p2p\/<peerId> component/);
+    expect(message).toContain('/ip4/127.0.0.1/tcp/4001');
+  });
+
+  // Case 3: `multiaddr()` does not validate the /p2p/ value; `peerIdFromString`
+  // does, and throws inside the child's libp2p construction.
+  it('rejects a /p2p/ component whose peer id does not decode, naming the entry and the id', () => {
+    const bad = '/ip4/127.0.0.1/tcp/4001/p2p/12D3KooReq';
+    const message = errorOf([bad]);
+    expect(message).toMatch(/must carry a decodable peer id/);
+    expect(message).toContain(bad);
+    expect(message).toContain('12D3KooReq');
+  });
+
+  it('rejects a relayed address whose relay peer id does not decode', () => {
+    expect(errorOf([`/ip4/1.2.3.4/tcp/4001/p2p/12D3KooReq/p2p-circuit/p2p/${PEER}`]))
+      .toMatch(/must carry a decodable peer id/);
+  });
+
+  // Case 4: parses, names a decodable peer, and survives `@libp2p/bootstrap`'s
+  // filter — but names no place, so libp2p finds no transport and the dial fails
+  // with no valid addresses. Same visible outcome as case 2.
+  it('rejects an address that names only peer ids, with no location to dial', () => {
+    for (const bad of [`/p2p/${PEER}`, `/p2p/${PEER}/p2p-circuit/p2p/${PEER}`]) {
+      const message = errorOf([bad]);
+      expect(message).toMatch(/must name where to reach the peer/);
+      expect(message).toContain(bad);
+    }
+  });
+
+  // A partial address is deliberately still accepted: which transports the child
+  // can dial is the embedder's choice, so only the total absence of a location is
+  // a boundary error.
+  it('accepts an address with a location but no transport, leaving that to the child', () => {
+    const partial = `/ip4/1.2.3.4/p2p/${PEER}`;
+    expect(validateBootstrapNodes([partial])).toEqual({ nodes: [partial] });
+  });
+
+  it('names the offending entry when only one address in a batch is bad', () => {
+    const message = errorOf([GOOD, '/ip4/10.0.0.9/tcp/4001', GOOD_2]);
+    expect(message).toContain('/ip4/10.0.0.9/tcp/4001');
+  });
+
+  // A requester must not be able to turn one junk string into a megabyte of log line.
+  it('caps the echoed value for an over-long rejected address', () => {
+    const message = errorOf([`/ip4/1.2.3.4/tcp/${'9'.repeat(5000)}`]);
+    expect(message).toContain('chars)');
+    expect(message.length).toBeLessThan(400);
+  });
+});