@serfab/cadre-host 0.9.0 → 0.11.0

package/src/orchestrator/index.ts

@@ -1,10 +1,10 @@
-export { HostProcessOrchestrator, OWNER_CONTAINER_ID } from './host-process-orchestrator.js';
-export type { OwnerAdminEndpoint } from './host-process-orchestrator.js';
-export type {
-  HostProcessConfig,
-  ManagedNodeInfo,
-  NodeStateListener,
-  NodePorts,
-  OwnerSpawnConfig,
-} from './types.js';
-export type { PersistedHandle } from './state-store.js';
+export { HostProcessOrchestrator, OWNER_CONTAINER_ID } from './host-process-orchestrator.js';
+export type { OwnerAdminEndpoint } from './host-process-orchestrator.js';
+export type {
+  HostProcessConfig,
+  ManagedNodeInfo,
+  NodeStateListener,
+  NodePorts,
+  OwnerSpawnConfig,
+} from './types.js';
+export type { PersistedHandle } from './state-store.js';

package/src/orchestrator/log-rotator.ts

@@ -1,53 +1,53 @@
-import {
-  existsSync,
-  renameSync,
-  unlinkSync,
-} from 'node:fs';
-import { join } from 'node:path';
-
-/**
- * On-disk log rotation helper.
- *
- * Children spawned by the orchestrator inherit a direct file descriptor to
- * their `node.log` (see `host-process-orchestrator.ts`), so rotation can no
- * longer be driven by an in-process byte counter — renaming the path under a
- * running child would leave it writing to the renamed inode. Instead the
- * orchestrator calls `rotateOnDisk(...)` at spawn time, before the child is
- * launched and its fd is opened. This is the only safe point to rotate
- * without coordinating with the running process.
- *
- * Within a workdir there is at most one live child, so spawn-time rotation
- * is sufficient for v1: a child that exceeds `logMaxBytes` mid-run will
- * keep appending to the active file until it (or its successor) is restarted.
- */
-
-/**
- * Perform a rotation cascade against on-disk paths: drop the oldest, then
- * shift `.N-1 → .N`, …, `.1 → .2`, and finally `filePath → .1`.
- *
- * Caller is responsible for deciding when to rotate (e.g. when
- * `statSync(filePath).size >= logMaxBytes`). No fd is held by this helper.
- */
-export function rotateOnDisk(filePath: string, maxFiles: number): void {
-  if (maxFiles < 1) return;
-
-  const oldest = `${filePath}.${maxFiles}`;
-  if (existsSync(oldest)) {
-    try { unlinkSync(oldest); } catch { /* ignore */ }
-  }
-  for (let i = maxFiles - 1; i >= 1; i--) {
-    const from = `${filePath}.${i}`;
-    const to = `${filePath}.${i + 1}`;
-    if (existsSync(from)) {
-      try { renameSync(from, to); } catch { /* ignore */ }
-    }
-  }
-  if (existsSync(filePath)) {
-    try { renameSync(filePath, `${filePath}.1`); } catch { /* ignore */ }
-  }
-}
-
-/** Build the standard log file path for a workdir. */
-export function defaultLogPath(workdir: string): string {
-  return join(workdir, 'node.log');
-}
+import {
+  existsSync,
+  renameSync,
+  unlinkSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * On-disk log rotation helper.
+ *
+ * Children spawned by the orchestrator inherit a direct file descriptor to
+ * their `node.log` (see `host-process-orchestrator.ts`), so rotation can no
+ * longer be driven by an in-process byte counter — renaming the path under a
+ * running child would leave it writing to the renamed inode. Instead the
+ * orchestrator calls `rotateOnDisk(...)` at spawn time, before the child is
+ * launched and its fd is opened. This is the only safe point to rotate
+ * without coordinating with the running process.
+ *
+ * Within a workdir there is at most one live child, so spawn-time rotation
+ * is sufficient for v1: a child that exceeds `logMaxBytes` mid-run will
+ * keep appending to the active file until it (or its successor) is restarted.
+ */
+
+/**
+ * Perform a rotation cascade against on-disk paths: drop the oldest, then
+ * shift `.N-1 → .N`, …, `.1 → .2`, and finally `filePath → .1`.
+ *
+ * Caller is responsible for deciding when to rotate (e.g. when
+ * `statSync(filePath).size >= logMaxBytes`). No fd is held by this helper.
+ */
+export function rotateOnDisk(filePath: string, maxFiles: number): void {
+  if (maxFiles < 1) return;
+
+  const oldest = `${filePath}.${maxFiles}`;
+  if (existsSync(oldest)) {
+    try { unlinkSync(oldest); } catch { /* ignore */ }
+  }
+  for (let i = maxFiles - 1; i >= 1; i--) {
+    const from = `${filePath}.${i}`;
+    const to = `${filePath}.${i + 1}`;
+    if (existsSync(from)) {
+      try { renameSync(from, to); } catch { /* ignore */ }
+    }
+  }
+  if (existsSync(filePath)) {
+    try { renameSync(filePath, `${filePath}.1`); } catch { /* ignore */ }
+  }
+}
+
+/** Build the standard log file path for a workdir. */
+export function defaultLogPath(workdir: string): string {
+  return join(workdir, 'node.log');
+}

package/src/orchestrator/node-identity.ts

@@ -0,0 +1,40 @@
+/**
+ * Per-node identity keys for orchestrator-managed children.
+ *
+ * A donated node joins a *foreign* cadre: the requester approves its peer id
+ * and its seed nominates dial addresses keyed to that peer id. Both bind to the
+ * identity, so a node that generated a fresh libp2p keypair per process would
+ * become a stranger to the cadre that admitted it on every restart. It also
+ * needs a stable on-disk home for its node-local stores — `cadre-cli start`
+ * opens `FileBootstrapPeerStore` / `FileTrustedOwnerStore` only when a protobuf
+ * identity key file is configured.
+ *
+ * So every managed node gets its own `identity.key` inside its workdir, written
+ * once and reused thereafter. The workdir is removed when the loan is
+ * terminated (`removeContainer`), so nothing the node persisted outlives it.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { generateIdentity, loadIdentity, type IdentityRecord } from '../installer/identity.js';
+
+const IDENTITY_FILE = 'identity.key';
+
+/** Path to a managed node's own protobuf identity key inside its workdir. */
+export function nodeIdentityPath(workdir: string): string {
+  return join(workdir, IDENTITY_FILE);
+}
+
+/**
+ * Ensure `<workdir>/identity.key` exists, generating an Ed25519 protobuf key on
+ * first call and REUSING it on every later call. Reuse is the load-bearing
+ * property: a re-spawn of the same container must land on the same peer id.
+ */
+export async function ensureNodeIdentity(workdir: string): Promise<{ path: string; peerId: string }> {
+  const path = nodeIdentityPath(workdir);
+  const record: IdentityRecord = existsSync(path)
+    ? loadIdentity(path)
+    : await generateIdentity(path);
+  return { path, peerId: record.peerId };
+}

package/src/orchestrator/pid-liveness.ts

@@ -1,24 +1,24 @@
-/**
- * Cross-platform PID liveness check using only stdlib.
- *
- * `process.kill(pid, 0)` sends signal 0, which performs error checking
- * without actually delivering a signal:
- *   - returns successfully when the process exists and we have permission
- *   - throws EPERM when the process exists but is owned by another user
- *     (common on Windows where signals don't translate cleanly)
- *   - throws ESRCH when the process does not exist
- */
-export function isPidAlive(pid: number): boolean {
-  if (!Number.isInteger(pid) || pid <= 0) {
-    return false;
-  }
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    // EPERM means the process exists but we lack permission to signal it.
-    // That's still "alive" from a liveness perspective.
-    return code === 'EPERM';
-  }
-}
+/**
+ * Cross-platform PID liveness check using only stdlib.
+ *
+ * `process.kill(pid, 0)` sends signal 0, which performs error checking
+ * without actually delivering a signal:
+ *   - returns successfully when the process exists and we have permission
+ *   - throws EPERM when the process exists but is owned by another user
+ *     (common on Windows where signals don't translate cleanly)
+ *   - throws ESRCH when the process does not exist
+ */
+export function isPidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    // EPERM means the process exists but we lack permission to signal it.
+    // That's still "alive" from a liveness perspective.
+    return code === 'EPERM';
+  }
+}

package/src/orchestrator/port-allocator.ts

@@ -1,43 +1,91 @@
-/**
- * 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);
-  }
-}
+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;
+}

package/src/orchestrator/state-store.ts

@@ -1,90 +1,90 @@
-import { existsSync, readFileSync, renameSync, writeFileSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import debug from 'debug';
-
-import type { OwnerSpawnConfig, NodePorts } from './types.js';
-
-const log = debug('cadre:host:state-store');
-
-/**
- * Persisted record for a single managed child. The orchestrator mirrors its
- * in-memory map to disk so that cadre-host can re-attach to surviving
- * children after a restart.
- */
-export interface PersistedHandle {
-  containerId: string;        // provider-assigned ID, passed in createContainer
-  dockerId: string;           // opaque token returned to callers (encoded "pid:token")
-  pid: number;
-  startupToken: string;
-  workdir: string;
-  ports: NodePorts;
-  spawnedAt: string;          // ISO timestamp
-  partyId: string;
-  profile: 'storage' | 'transaction';
-  /** True for the admin's owner node. */
-  owner?: boolean;
-}
-
-export interface PersistedState {
-  version: 1;
-  handles: PersistedHandle[];
-  /** Spawn parameters for the owner node, so it can be re-spawned on demand. */
-  ownerConfig?: OwnerSpawnConfig;
-}
-
-const STATE_VERSION = 1;
-
-/** JSON state file at `<rootDir>/state.json`, written atomically. */
-export class StateStore {
-  private readonly path: string;
-
-  constructor(rootDir: string) {
-    mkdirSync(rootDir, { recursive: true });
-    this.path = join(rootDir, 'state.json');
-  }
-
-  load(): PersistedState {
-    if (!existsSync(this.path)) {
-      return { version: STATE_VERSION, handles: [] };
-    }
-    try {
-      const raw = readFileSync(this.path, 'utf8');
-      const parsed = JSON.parse(raw) as PersistedState;
-      if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.handles)) {
-        log('state file at %s has unexpected shape; treating as empty', this.path);
-        return { version: STATE_VERSION, handles: [] };
-      }
-      return {
-        version: STATE_VERSION,
-        handles: parsed.handles,
-        ...(parsed.ownerConfig ? { ownerConfig: parsed.ownerConfig } : {}),
-      };
-    } catch (err) {
-      // A corrupt state file is operationally significant — surviving children
-      // may now be leaked to the OS without an in-memory handle. Make the
-      // failure visible rather than silently returning empty.
-      log('failed to load state file at %s: %o', this.path, err);
-      return { version: STATE_VERSION, handles: [] };
-    }
-  }
-
-  save(state: PersistedState): void {
-    mkdirSync(dirname(this.path), { recursive: true });
-    const payload = JSON.stringify(
-      {
-        version: STATE_VERSION,
-        handles: state.handles,
-        ...(state.ownerConfig ? { ownerConfig: state.ownerConfig } : {}),
-      },
-      null,
-      2,
-    );
-    const tmp = `${this.path}.tmp`;
-    writeFileSync(tmp, payload, { encoding: 'utf8' });
-    renameSync(tmp, this.path);
-  }
-
-  filePath(): string {
-    return this.path;
-  }
-}
+import { existsSync, readFileSync, renameSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import debug from 'debug';
+
+import type { OwnerSpawnConfig, NodePorts } from './types.js';
+
+const log = debug('cadre:host:state-store');
+
+/**
+ * Persisted record for a single managed child. The orchestrator mirrors its
+ * in-memory map to disk so that cadre-host can re-attach to surviving
+ * children after a restart.
+ */
+export interface PersistedHandle {
+  containerId: string;        // provider-assigned ID, passed in createContainer
+  dockerId: string;           // opaque token returned to callers (encoded "pid:token")
+  pid: number;
+  startupToken: string;
+  workdir: string;
+  ports: NodePorts;
+  spawnedAt: string;          // ISO timestamp
+  partyId: string;
+  profile: 'storage' | 'transaction';
+  /** True for the admin's owner node. */
+  owner?: boolean;
+}
+
+export interface PersistedState {
+  version: 1;
+  handles: PersistedHandle[];
+  /** Spawn parameters for the owner node, so it can be re-spawned on demand. */
+  ownerConfig?: OwnerSpawnConfig;
+}
+
+const STATE_VERSION = 1;
+
+/** JSON state file at `<rootDir>/state.json`, written atomically. */
+export class StateStore {
+  private readonly path: string;
+
+  constructor(rootDir: string) {
+    mkdirSync(rootDir, { recursive: true });
+    this.path = join(rootDir, 'state.json');
+  }
+
+  load(): PersistedState {
+    if (!existsSync(this.path)) {
+      return { version: STATE_VERSION, handles: [] };
+    }
+    try {
+      const raw = readFileSync(this.path, 'utf8');
+      const parsed = JSON.parse(raw) as PersistedState;
+      if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.handles)) {
+        log('state file at %s has unexpected shape; treating as empty', this.path);
+        return { version: STATE_VERSION, handles: [] };
+      }
+      return {
+        version: STATE_VERSION,
+        handles: parsed.handles,
+        ...(parsed.ownerConfig ? { ownerConfig: parsed.ownerConfig } : {}),
+      };
+    } catch (err) {
+      // A corrupt state file is operationally significant — surviving children
+      // may now be leaked to the OS without an in-memory handle. Make the
+      // failure visible rather than silently returning empty.
+      log('failed to load state file at %s: %o', this.path, err);
+      return { version: STATE_VERSION, handles: [] };
+    }
+  }
+
+  save(state: PersistedState): void {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const payload = JSON.stringify(
+      {
+        version: STATE_VERSION,
+        handles: state.handles,
+        ...(state.ownerConfig ? { ownerConfig: state.ownerConfig } : {}),
+      },
+      null,
+      2,
+    );
+    const tmp = `${this.path}.tmp`;
+    writeFileSync(tmp, payload, { encoding: 'utf8' });
+    renameSync(tmp, this.path);
+  }
+
+  filePath(): string {
+    return this.path;
+  }
+}