@serfab/cadre-host 0.13.0 → 1.1.0

package/dist/ui/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="color-scheme" content="light dark" />
     <title>cadre-host</title>
-    <script type="module" crossorigin src="./assets/index-C-iks41M.js"></script>
+    <script type="module" crossorigin src="./assets/index-CEoNRwM_.js"></script>
     <link rel="stylesheet" crossorigin href="./assets/index-BVoqLjyX.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-host",
-  "version": "0.13.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Self-hosted cadre node manager for basement-PC deployments",
   "main": "dist/index.js",
@@ -65,9 +65,9 @@
     "@libp2p/interface": "^3.1.0",
     "@libp2p/peer-id": "^6.0.4",
     "@multiformats/multiaddr": "^12.5.1",
-    "@serfab/cadre-cli": "^0.13.0",
-    "@serfab/cadre-core": "^0.13.0",
-    "@serfab/cadre-provider": "^0.13.0",
+    "@serfab/cadre-cli": "^1.1.0",
+    "@serfab/cadre-core": "^1.1.0",
+    "@serfab/cadre-provider": "^1.1.0",
     "commander": "^14.0.2",
     "debug": "^4.4.3",
     "fastify": "^5.7.1",

package/src/__tests__/orchestrator-env-scrub.test.ts

@@ -12,6 +12,10 @@
  *
  * A fake CLI records the vars under test from its environment to a file so
  * the scrub is observable without a real cadre node.
+ *
+ * The same record carries `CADRE_LISTEN_ADDRS`, one of the vars the orchestrator
+ * deliberately SETS: a child must be handed a WebSocket listener beside its TCP one,
+ * on the ports its handle holds, or a phone cannot reach it.
  */
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
@@ -35,6 +39,7 @@ if (tokenPath) {
     CADRE_PARTY_ID: process.env.CADRE_PARTY_ID ?? null,
     CADRE_STORAGE_PATH: process.env.CADRE_STORAGE_PATH ?? null,
     CADRE_ADMIN_PORT: process.env.CADRE_ADMIN_PORT ?? null,
+    CADRE_LISTEN_ADDRS: process.env.CADRE_LISTEN_ADDRS ?? null,
     DEBUG: process.env.DEBUG ?? null,
   };
   try { fs.writeFileSync(path.join(dir, 'env-seen.json'), JSON.stringify(record), 'utf8'); } catch (e) { console.error(e); }
@@ -137,4 +142,21 @@ describe('HostProcessOrchestrator child env scrub', () => {
       expect(seen.DEBUG).toBe('some:value');
     }
   });
+
+  it('hands each child a TCP and a WebSocket listen address on its own ports', async () => {
+    const rootDir = join(tmpRoot, 'b');
+    const orch = makeOrchestrator(rootDir);
+    await orch.init();
+
+    await orch.createContainer({
+      containerId: 'child-1',
+      partyId: 'party-1',
+      bootstrapNodes: [],
+      profile: 'storage',
+    });
+
+    const seen = JSON.parse(await waitForFile(join(rootDir, 'child-1', 'env-seen.json')));
+    const ports = orch.getNode('child-1')!.ports;
+    expect(seen.CADRE_LISTEN_ADDRS).toBe(`/ip4/0.0.0.0/tcp/${ports.p2p},/ip4/0.0.0.0/tcp/${ports.ws}/ws`);
+  });
 });

package/src/__tests__/orchestrator-node-identity.test.ts

@@ -162,12 +162,12 @@ describe('HostProcessOrchestrator node identity', () => {
   // The failure the identity step can actually produce is a damaged key file,
   // and `DonationService.provision` turns every such throw into an `error`
   // record and lets the grantee retry. If the spawn path reserved its ports
-  // before the step that throws, each retry would burn four more ports out of a
+  // before the step that throws, each retry would burn five more ports out of a
   // bounded range until provisioning stopped working altogether.
   it('reserves no ports when the identity step fails', async () => {
     const rootDir = join(tmpRoot, 'd');
-    // Exactly one node's worth of ports (health, metrics, p2p, admin).
-    const orch = makeOrchestrator(rootDir, { start: 18100, end: 18103 });
+    // Exactly one node's worth of ports (health, metrics, p2p, admin, ws).
+    const orch = makeOrchestrator(rootDir, { start: 18100, end: 18104 });
     await orch.init();
 
     mkdirSync(join(rootDir, 'donated-bad'), { recursive: true });
@@ -181,7 +181,7 @@ describe('HostProcessOrchestrator node identity', () => {
     };
     await expect(orch.createContainer({ ...request, containerId: 'donated-bad' })).rejects.toThrow();
 
-    // The whole range is still free, so a healthy container still gets its four.
+    // The whole range is still free, so a healthy container still gets its five.
     const ok = await orch.createContainer({ ...request, containerId: 'donated-good' });
     expect(ok.p2pPort).toBeGreaterThanOrEqual(18100);
   });

package/src/__tests__/orchestrator-owner.test.ts

@@ -8,7 +8,7 @@
  */
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -165,7 +165,9 @@ describe('HostProcessOrchestrator.ensureOwnerNode', () => {
     const a = makeOrchestrator(rootDir);
     await a.init();
     const node = await a.ensureOwnerNode(CFG);
-    await waitFor(() => a.isRunning(node.dockerId));
+    // Not `a.isRunning`: that answers from the ChildProcess at once, but `b`
+    // below can only recognise the node once it has written its startup token.
+    await waitFor(() => existsSync(join(rootDir, OWNER_CONTAINER_ID, '.startup-token')));
     const before = a.getOwnerAdminEndpoint();
 
     const b = makeOrchestrator(rootDir);
@@ -180,6 +182,29 @@ describe('HostProcessOrchestrator.ensureOwnerNode', () => {
     expect(isPidAlive(pid)).toBe(true);
   });
 
+  // The owner's own guard arm: its admin channel binds on loopback, so the probe
+  // must check 127.0.0.1 too — the fake owner binds nothing else.
+  it('refuses to re-spawn over a re-attached owner whose admin port is still bound', async () => {
+    const rootDir = join(tmpRoot, 'g');
+    const a = makeOrchestrator(rootDir);
+    await a.init();
+    const node = await a.ensureOwnerNode(CFG);
+    const tokenPath = join(rootDir, OWNER_CONTAINER_ID, '.startup-token');
+    await waitFor(async () => (await a.getLogs(node.dockerId)).includes('admin listening'));
+
+    // Unverified as far as `b` can tell: live pid, token not (yet) matching.
+    writeFileSync(tokenPath, 'not-yet', 'utf8');
+    const b = makeOrchestrator(rootDir);
+    await b.init();
+    expect(await b.isRunning(node.dockerId)).toBe(false);
+
+    await expect(b.ensureOwnerNode(CFG)).rejects.toThrow(
+      new RegExp(`owner may still be running: port ${node.ports.admin} on 127\\.0\\.0\\.1 is unavailable`),
+    );
+    expect(b.listNodes().map((n) => n.dockerId)).toEqual([node.dockerId]);
+    expect(isPidAlive(decodeDockerId(node.dockerId).pid)).toBe(true);
+  });
+
   it('restartOwnerNode preserves the workdir and re-spawns', async () => {
     const orch = makeOrchestrator(join(tmpRoot, 'e'));
     await orch.init();
@@ -195,4 +220,22 @@ describe('HostProcessOrchestrator.ensureOwnerNode', () => {
     expect(orch.listNodes()).toHaveLength(1);
     await waitFor(() => !isPidAlive(firstPid));
   });
+
+  // Like a lent node, the owner node comes back on its previous ports even when lower
+  // ones are free. Only its TCP port differs: the configured libp2pPort wins over the
+  // previous handle's, because the NAT mapping points at the configured one.
+  it('re-spawns on its previous ports, taking p2p from the current config', async () => {
+    const orch = makeOrchestrator(join(tmpRoot, 'f'));
+    await orch.init();
+    const lower = await orch.createContainer({ containerId: 'c0', partyId: 'party-c0', bootstrapNodes: [], profile: 'transaction' });
+    const first = await orch.ensureOwnerNode(CFG);
+    await waitFor(() => orch.isRunning(first.dockerId));
+
+    await orch.removeContainer(lower.dockerId);
+    await orch.stopOwnerNode();
+    const respawned = await orch.ensureOwnerNode({ ...CFG, libp2pPort: 4556 });
+
+    expect(respawned.dockerId).not.toBe(first.dockerId);
+    expect(respawned.ports).toEqual({ ...first.ports, p2p: 4556 });
+  });
 });

package/src/__tests__/orchestrator-ports.test.ts

@@ -0,0 +1,172 @@
+/**
+ * The pure port-set logic behind `HostProcessOrchestrator`: the allocator, the
+ * helpers that allocate, hold, release and reuse one node's set of ports, and the
+ * listen addresses a child is started with. No child processes — the behaviour these
+ * feed is exercised against a stub child in `orchestrator.test.ts`.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { childListenAddrs } from '../orchestrator/host-process-orchestrator.js';
+import {
+  allocateNodePorts,
+  PortAllocator,
+  releaseNodePorts,
+  reserveNodePorts,
+  reusedNodePorts,
+} from '../orchestrator/port-allocator.js';
+import type { NodePorts } from '../orchestrator/types.js';
+
+/**
+ * A port set as `state.json` hands it back from a build that predates the `ws` key:
+ * the type says every key is present, the data does not.
+ */
+function portsWithoutWs(ports: Omit<NodePorts, 'ws'>): NodePorts {
+  return ports as NodePorts;
+}
+
+describe('PortAllocator', () => {
+  it('allocates sequentially, releases, and reuses', () => {
+    const a = new PortAllocator(100, 102);
+    expect(a.allocate()).toBe(100);
+    expect(a.allocate()).toBe(101);
+    expect(a.allocate()).toBe(102);
+    expect(() => a.allocate()).toThrow(/No available ports/);
+    a.release(101);
+    expect(a.allocate()).toBe(101);
+  });
+
+  it('markUsed reserves ports without allocating', () => {
+    const a = new PortAllocator(100, 102);
+    a.markUsed(101);
+    expect(a.allocate()).toBe(100);
+    expect(a.allocate()).toBe(102);
+    expect(() => a.allocate()).toThrow();
+  });
+
+  // Without the integer check, `undefined` and NaN pass both range comparisons (each
+  // is false) and land in the used-set, as would an in-range fraction.
+  it('markUsed ignores a non-integer', () => {
+    const a = new PortAllocator(100, 101);
+    for (const junk of [undefined as unknown as number, Number.NaN, 100.5]) {
+      a.markUsed(junk);
+      expect(a.has(junk)).toBe(false);
+    }
+  });
+});
+
+describe('allocateNodePorts', () => {
+  it('allocates the five ports in a fixed order, the newest key last', () => {
+    const a = new PortAllocator(10000, 10010);
+    expect(allocateNodePorts(a)).toEqual({ health: 10000, metrics: 10001, p2p: 10002, admin: 10003, ws: 10004 });
+  });
+
+  // A partial set left reserved would leak from a bounded range on every failed
+  // provision — the whole reason this helper exists rather than five allocates.
+  it('is all-or-nothing: an exhausted range releases everything it took', () => {
+    const a = new PortAllocator(13000, 13002);
+    expect(() => allocateNodePorts(a)).toThrow(/No available ports/);
+    expect(a.has(13000)).toBe(false);
+    expect(a.has(13001)).toBe(false);
+    expect(a.has(13002)).toBe(false);
+  });
+
+  // Four ports used to be one node's worth. A range sized for that now fails on the
+  // fifth, and must neither hand back a set missing `ws` nor keep the four it took.
+  it('fails cleanly on a range with room for four ports but not five', () => {
+    const a = new PortAllocator(13000, 13003);
+    expect(() => allocateNodePorts(a)).toThrow(/No available ports/);
+    for (let port = 13000; port <= 13003; port++) expect(a.has(port)).toBe(false);
+  });
+
+  // The owner node's p2p port is pinned by the NAT mapping, not allocated.
+  it('honours an override and reserves it', () => {
+    const a = new PortAllocator(10000, 10010);
+    expect(allocateNodePorts(a, { p2p: 10005 })).toEqual({
+      health: 10000,
+      metrics: 10001,
+      p2p: 10005,
+      admin: 10002,
+      ws: 10003,
+    });
+    // Reserved, so no later allocation can hand it out again.
+    expect(a.has(10005)).toBe(true);
+  });
+
+  // An out-of-range override is the production case for the owner node: its
+  // libp2p port is chosen by NAT config, not by the allocator, so reserving it
+  // is a documented no-op rather than an error.
+  it('accepts an override outside the managed range without reserving it', () => {
+    const a = new PortAllocator(10000, 10010);
+    expect(allocateNodePorts(a, { p2p: 40000 })).toMatchObject({ p2p: 40000, health: 10000 });
+    expect(a.has(40000)).toBe(false);
+  });
+
+  // A re-spawn passes its previous set as overrides; every one must come back exactly.
+  it('returns a full set of overrides exactly, allocating nothing', () => {
+    const a = new PortAllocator(10000, 10010);
+    const previous = { health: 10006, metrics: 10007, p2p: 10008, admin: 10009, ws: 10010 };
+    expect(allocateNodePorts(a, previous)).toEqual(previous);
+    expect(a.allocate()).toBe(10000);
+  });
+});
+
+describe('reserveNodePorts / releaseNodePorts', () => {
+  it('hold and then release every key of the set', () => {
+    const a = new PortAllocator(10000, 10010);
+    const ports = { health: 10000, metrics: 10001, p2p: 10002, admin: 10003, ws: 10004 };
+    reserveNodePorts(a, ports);
+    for (const port of Object.values(ports)) expect(a.has(port)).toBe(true);
+    releaseNodePorts(a, ports);
+    for (const port of Object.values(ports)) expect(a.has(port)).toBe(false);
+  });
+
+  // Rehydrating, or dropping, a `state.json` handle written before `ws` existed.
+  it('skip a key the set lacks', () => {
+    const a = new PortAllocator(10000, 10010);
+    const ports = portsWithoutWs({ health: 10000, metrics: 10001, p2p: 10002, admin: 10003 });
+    reserveNodePorts(a, ports);
+    expect(a.has(undefined as unknown as number)).toBe(false);
+    expect(a.allocate()).toBe(10004);
+    releaseNodePorts(a, ports);
+    expect(a.has(10000)).toBe(false);
+    expect(a.has(10004)).toBe(true);
+  });
+});
+
+describe('reusedNodePorts', () => {
+  const previous = { health: 10005, metrics: 10006, p2p: 10007, admin: 10008, ws: 10009 };
+
+  it("returns the dropped handle's whole port set", () => {
+    expect(reusedNodePorts([{ ports: previous }])).toEqual(previous);
+  });
+
+  it('returns nothing when nothing was dropped, so every port is allocated fresh', () => {
+    expect(reusedNodePorts([])).toEqual({});
+  });
+
+  // A handle persisted before `ws` existed: its other ports come back, `ws` is new.
+  it('omits a key the dropped handle lacks', () => {
+    const legacy = portsWithoutWs({ health: 10005, metrics: 10006, p2p: 10007, admin: 10008 });
+    const reused = reusedNodePorts([{ ports: legacy }]);
+    expect(reused).toEqual({ health: 10005, metrics: 10006, p2p: 10007, admin: 10008 });
+    expect('ws' in reused).toBe(false);
+
+    const a = new PortAllocator(10000, 10010);
+    expect(allocateNodePorts(a, reused)).toEqual({ health: 10005, metrics: 10006, p2p: 10007, admin: 10008, ws: 10000 });
+  });
+
+  it('takes the last handle when a state holding duplicates dropped several', () => {
+    const older = { health: 10000, metrics: 10001, p2p: 10002, admin: 10003, ws: 10004 };
+    expect(reusedNodePorts([{ ports: older }, { ports: previous }])).toEqual(previous);
+  });
+});
+
+describe('childListenAddrs', () => {
+  it('names a TCP listener on the p2p port and a WebSocket listener on the ws port, on every interface', () => {
+    expect(childListenAddrs({ p2p: 10002, ws: 10004 })).toEqual([
+      '/ip4/0.0.0.0/tcp/10002',
+      '/ip4/0.0.0.0/tcp/10004/ws',
+    ]);
+  });
+});