@serfab/cadre-host 0.12.0 → 1.0.0

package/src/orchestrator/port-allocator.ts

@@ -1,91 +1,148 @@
-import type { NodePorts } from './types.js';
-
-/**
- * Range-based port tracker. Allocations are in-memory; on orchestrator
- * restart the caller rehydrates the used-set from persisted state via
- * `markUsed(port)` before serving new allocations.
- */
-export class PortAllocator {
-  private readonly usedPorts = new Set<number>();
-
-  constructor(
-    private readonly start: number,
-    private readonly end: number,
-  ) {
-    if (!Number.isInteger(start) || !Number.isInteger(end) || start <= 0 || end < start) {
-      throw new Error(`Invalid port range: ${start}..${end}`);
-    }
-  }
-
-  allocate(): number {
-    for (let port = this.start; port <= this.end; port++) {
-      if (!this.usedPorts.has(port)) {
-        this.usedPorts.add(port);
-        return port;
-      }
-    }
-    throw new Error(`No available ports in range ${this.start}..${this.end}`);
-  }
-
-  release(port: number): void {
-    this.usedPorts.delete(port);
-  }
-
-  /** Used during restart rehydration to reserve ports already in use. */
-  markUsed(port: number): void {
-    if (port < this.start || port > this.end) {
-      return;
-    }
-    this.usedPorts.add(port);
-  }
-
-  has(port: number): boolean {
-    return this.usedPorts.has(port);
-  }
-}
-
-/**
- * Allocation order for a node's port set. Fixed so that swapping a caller onto
- * {@link allocateNodePorts} does not shift the ports an existing deployment
- * already handed out.
- */
-const NODE_PORT_KEYS = ['health', 'metrics', 'p2p', 'admin'] as const;
-
-/**
- * Allocate a full NodePorts set atomically — a mid-way failure (an exhausted
- * range) releases everything already taken rather than stranding the ports it
- * got before the throw. `overrides` supply a port instead of allocating one
- * (the owner node's p2p port, which is fixed by NAT config).
- *
- * Overrides are reserved FIRST, before any allocation, so an override that
- * happens to sit inside the managed range cannot also be handed out to another
- * key. Reserving is `markUsed`, a documented no-op outside the range — which is
- * the production case for the owner node's libp2p port, and why reserving first
- * leaves every real port assignment unchanged.
- */
-export function allocateNodePorts(
-  allocator: PortAllocator,
-  overrides?: Partial<NodePorts>,
-): NodePorts {
-  const reserved: number[] = [];
-  const ports: Partial<NodePorts> = {};
-  try {
-    for (const key of NODE_PORT_KEYS) {
-      const override = overrides?.[key];
-      if (override === undefined) continue;
-      allocator.markUsed(override);
-      reserved.push(override);
-      ports[key] = override;
-    }
-    for (const key of NODE_PORT_KEYS) {
-      if (ports[key] !== undefined) continue;
-      const port = allocator.allocate();
-      reserved.push(port);
-      ports[key] = port;
-    }
-  } catch (err) {
-    for (const port of reserved) allocator.release(port);
-    throw err;
-  }
-  return ports as NodePorts;
-}
+import type { NodePorts } from './types.js';
+
+/**
+ * Range-based port tracker. Allocations are in-memory; on orchestrator
+ * restart the caller rehydrates the used-set from persisted state via
+ * `markUsed(port)` before serving new allocations.
+ */
+export class PortAllocator {
+  private readonly usedPorts = new Set<number>();
+
+  constructor(
+    private readonly start: number,
+    private readonly end: number,
+  ) {
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start <= 0 || end < start) {
+      throw new Error(`Invalid port range: ${start}..${end}`);
+    }
+  }
+
+  allocate(): number {
+    for (let port = this.start; port <= this.end; port++) {
+      if (!this.usedPorts.has(port)) {
+        this.usedPorts.add(port);
+        return port;
+      }
+    }
+    throw new Error(`No available ports in range ${this.start}..${this.end}`);
+  }
+
+  release(port: number): void {
+    this.usedPorts.delete(port);
+  }
+
+  /**
+   * Used during restart rehydration to reserve ports already in use. A no-op for a
+   * port outside the range, and for a non-integer: a handle persisted by an older
+   * build lacks the ports added since, and `undefined` must not enter the used-set.
+   */
+  markUsed(port: number): void {
+    if (!Number.isInteger(port) || port < this.start || port > this.end) {
+      return;
+    }
+    this.usedPorts.add(port);
+  }
+
+  has(port: number): boolean {
+    return this.usedPorts.has(port);
+  }
+}
+
+/**
+ * Allocation order for a node's port set. Fixed so that swapping a caller onto
+ * {@link allocateNodePorts} does not shift the ports an existing deployment
+ * already handed out — which is also why a key added later goes on the end
+ * (`ws` came after the first four).
+ */
+const NODE_PORT_KEYS = ['health', 'metrics', 'p2p', 'admin', 'ws'] as const;
+
+/**
+ * Allocate a full NodePorts set atomically — a mid-way failure (an exhausted
+ * range) releases everything already taken rather than stranding the ports it
+ * got before the throw. `overrides` supply a port instead of allocating one
+ * (the owner node's p2p port, which is fixed by NAT config; a re-spawn's
+ * previous ports, see {@link reusedNodePorts}).
+ *
+ * Overrides are reserved FIRST, before any allocation, so an override that
+ * happens to sit inside the managed range cannot also be handed out to another
+ * key. Reserving is `markUsed`, a documented no-op outside the range — which is
+ * the production case for the owner node's libp2p port, and why reserving first
+ * leaves every real port assignment unchanged.
+ *
+ * NOTE: an override is trusted, not checked — `markUsed` does not refuse a port
+ * another handle already holds, nor two keys naming the same port. Safe for
+ * today's callers: a re-spawn's overrides were released by its own handle drop
+ * with no `await` in between, and the owner's `libp2pPort` can only collide if an
+ * operator configures it inside the range onto a port a node already holds. If a
+ * caller ever passes ports it did not just release, refuse an override that
+ * `allocator.has()` or that repeats another key's port.
+ */
+export function allocateNodePorts(
+  allocator: PortAllocator,
+  overrides?: Partial<NodePorts>,
+): NodePorts {
+  const reserved: number[] = [];
+  const ports: Partial<NodePorts> = {};
+  try {
+    for (const key of NODE_PORT_KEYS) {
+      const override = overrides?.[key];
+      if (override === undefined) continue;
+      allocator.markUsed(override);
+      reserved.push(override);
+      ports[key] = override;
+    }
+    for (const key of NODE_PORT_KEYS) {
+      if (ports[key] !== undefined) continue;
+      const port = allocator.allocate();
+      reserved.push(port);
+      ports[key] = port;
+    }
+  } catch (err) {
+    for (const port of reserved) allocator.release(port);
+    throw err;
+  }
+  return ports as NodePorts;
+}
+
+/**
+ * Hold a node's whole port set against `allocator` — the inverse of
+ * {@link releaseNodePorts}. A key the set lacks is skipped (see `markUsed`).
+ */
+export function reserveNodePorts(allocator: PortAllocator, ports: NodePorts): void {
+  for (const key of NODE_PORT_KEYS) allocator.markUsed(ports[key]);
+}
+
+/**
+ * Give a node's whole port set back to `allocator`. A key the set lacks releases
+ * nothing: deleting a value the used-set never held is a no-op.
+ */
+export function releaseNodePorts(allocator: PortAllocator, ports: NodePorts): void {
+  for (const key of NODE_PORT_KEYS) allocator.release(ports[key]);
+}
+
+/**
+ * The ports a re-spawn comes back on: the set the dropped handle held, as
+ * {@link allocateNodePorts} overrides. `{}` when nothing was dropped (a first
+ * spawn, or a handle lost along with `state.json`), so every port is allocated
+ * fresh.
+ *
+ * Why a re-spawn must not simply take the lowest free ports: a requester with no
+ * address of its own (a phone) reaches a lent node only by dialing the address it
+ * was given, so a node that comes back on a different port is one that requester
+ * can no longer find.
+ *
+ * A key the dropped handle lacks — `ws` on a handle persisted by an older build —
+ * is left out, and so allocated fresh. When more than one handle was dropped (only
+ * possible from a `state.json` that already held duplicates), the last one stored
+ * wins and the others' ports stay released.
+ */
+export function reusedNodePorts(dropped: readonly { ports: NodePorts }[]): Partial<NodePorts> {
+  const reused: Partial<NodePorts> = {};
+  const previous = dropped[dropped.length - 1]?.ports;
+  if (!previous) return reused;
+  for (const key of NODE_PORT_KEYS) {
+    const port = previous[key];
+    if (Number.isInteger(port)) reused[key] = port;
+  }
+  return reused;
+}

package/src/orchestrator/port-probe.ts

@@ -0,0 +1,31 @@
+import { createServer } from 'node:net';
+
+/** One TCP port a child binds, on the address it binds it to. */
+export interface PortBinding {
+  port: number;
+  host: string;
+}
+
+/**
+ * Resolve when `binding` can be bound right now; reject, naming the port and the
+ * OS error code, when it cannot. Binds briefly and closes again at once.
+ *
+ * Any bind error counts as "unavailable", not just `EADDRINUSE`: on Windows a
+ * port held with `SO_EXCLUSIVEADDRUSE` (which libuv sets on every TCP bind) can
+ * answer `EACCES` instead, and a child launched onto a port that fails either way
+ * would die on it.
+ */
+export function assertPortFree(binding: PortBinding): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once('error', (err: NodeJS.ErrnoException) => {
+      reject(new Error(
+        `port ${binding.port} on ${binding.host} is unavailable (${err.code ?? err.message})`,
+        { cause: err },
+      ));
+    });
+    server.listen({ port: binding.port, host: binding.host }, () => {
+      server.close(() => resolve());
+    });
+  });
+}

package/src/orchestrator/types.ts

@@ -42,13 +42,25 @@ export interface HostProcessConfig {
  */
 export type PushCredentialsResolver = () => Promise<PushCredentials | undefined>;
 
-/** Per-child allocated ports. `admin` carries the loopback admin channel (6.6). */
+/**
+ * Per-child allocated ports. `admin` carries the loopback admin channel (6.6).
+ *
+ * A handle read back from a `state.json` written by an older build lacks every key
+ * added since, whatever this type says — the node-set helpers in `port-allocator.ts`
+ * skip a missing key rather than reserving `undefined`.
+ */
 export interface NodePorts {
   health: number;
   metrics: number;
+  /** libp2p TCP listener. */
   p2p: number;
   /** Loopback admin-channel port. Bound only by the owner node. */
   admin: number;
+  /**
+   * libp2p WebSocket listener. The one a phone dials: a phone's node has no TCP
+   * transport, so the `p2p` port is unreachable to it.
+   */
+  ws: number;
 }
 
 /** In-memory record per managed child. */

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

@@ -0,0 +1,138 @@
+/**
+ * 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 an identical
+ * copy of this rule's per-entry half
+ * (`packages/cadre-provider/src/server/bootstrap-node-validation.ts`) and the
+ * per-entry rows below are the same rows
+ * `packages/cadre-provider/src/server/__tests__/bootstrap-node-validation.test.ts`
+ * pins that copy to. The empty-list row differs on purpose: this host accepts an
+ * empty list (a phone requester dials its lent node instead), the provider still
+ * requires one. 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] });
+  });
+
+  // The one row that differs from cadre-provider's table: a requester with no address
+  // of its own (a phone) sends none and dials the lent node itself.
+  it('treats an absent field and an empty list alike: no addresses, nothing rejected', () => {
+    expect(validateBootstrapNodes(undefined)).toEqual({ nodes: [] });
+    expect(validateBootstrapNodes([])).toEqual({ nodes: [] });
+  });
+
+  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);
+  });
+});