@serfab/cadre-host 0.8.1 → 0.10.0

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

@@ -0,0 +1,225 @@
+/**
+ * Shared fake orchestrator for the donation 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.
+ *
+ * This file holds no tests of its own; its contract is pinned by the sibling
+ * `fake-orchestrator.test.ts`, which exists so a future agent cannot make a
+ * failing donation 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';
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+/** What the fake remembers about one spawned child. */
+interface FakeChild {
+  containerId: string;
+  partyId: string;
+  profile: 'storage' | 'transaction';
+  running: boolean;
+}
+
+/**
+ * Mirrors the parts of `HostProcessOrchestrator`'s handle lifecycle the donation
+ * 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;
+ * - a **failed** `createContainer` leaves those handles exactly as it found them
+ *   (the real `restoreDroppedHandles`);
+ * - `stopContainer` / `removeContainer` throw `Container not found: <dockerId>`
+ *   for a handle this orchestrator no longer knows (the real `requireHandle`);
+ * - `reclaimWorkdir` refuses a containerId that still resolves to a live
+ *   handle (the real guard — that directory belongs to `removeContainer`).
+ *
+ * Consequently `stopped` / `removed` mean **"handles this orchestrator actually
+ * acted on"**, not "calls attempted" — a stop aimed at a dropped handle is
+ * rejected and never appears. `onStop` still fires for those rejected calls, so
+ * a test can observe the attempt separately from its outcome.
+ */
+export class FakeOrchestrator implements Orchestrator {
+  createCalls: OrchestratorCreateRequest[] = [];
+  stopped: string[] = [];
+  removed: string[] = [];
+  /**
+   * Container ids whose workdir this orchestrator actually removed. Same
+   * "acted on, not attempted" rule as `stopped` / `removed`: a refused reclaim
+   * leaves no entry.
+   */
+  reclaimedWorkdirs: string[] = [];
+  failCreate = false;
+  createDelayMs = 0;
+  /**
+   * Observation hook — lets a test inspect the world as the stop happens. Fires
+   * even when the handle is unknown and the stop is then rejected.
+   */
+  onStop?: (dockerId: string) => void;
+  /**
+   * Observation hook — fires before the spawn resolves or fails, modelling the
+   * real class's *pre-drop* `await` window (`ensureNodeIdentity`, `resolvePush`).
+   * Work driven from here sees the previous handle still alive. Contrast
+   * {@link onSpawned}.
+   */
+  onCreate?: (request: OrchestratorCreateRequest) => void;
+  /**
+   * Observation hook — fires once the drop has landed and the new child is
+   * registered, immediately before `createContainer` resolves. Models the
+   * microtask gap between the real `createContainer` returning and its caller's
+   * `await` resuming: the real drop → launch → return runs synchronously, so
+   * this is the earliest point other code can observe the post-drop world.
+   * Contrast {@link onCreate}.
+   */
+  onSpawned?: (dockerId: string) => void;
+  /** Observation hook — fires before the liveness answer is computed. */
+  onIsRunning?: (dockerId: string) => void;
+
+  private readonly children = new Map<string, FakeChild>();
+  private readonly listeners = new Set<NodeStateListener>();
+  private counter = 0;
+
+  async createContainer(request: OrchestratorCreateRequest): Promise<OrchestratorCreateResult> {
+    this.createCalls.push(request);
+    this.onCreate?.(request);
+    if (this.createDelayMs) await sleep(this.createDelayMs);
+    if (this.failCreate) throw new Error('spawn boom');
+    // Drop the prior handles for this container, mirroring `dropStaleHandle`.
+    // 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.
+    for (const [id, child] of this.children) {
+      if (child.containerId === request.containerId) this.children.delete(id);
+    }
+    const n = ++this.counter;
+    const dockerId = `dock_${n}`;
+    this.children.set(dockerId, {
+      containerId: request.containerId,
+      partyId: request.partyId,
+      profile: request.profile,
+      running: true,
+    });
+    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,
+    };
+  }
+
+  async stopContainer(dockerId: string): Promise<void> {
+    // Before the check: a test may want to observe that a stop was *attempted*
+    // even when this orchestrator rejects it.
+    this.onStop?.(dockerId);
+    const child = this.requireChild(dockerId);
+    this.stopped.push(dockerId);
+    child.running = false;
+  }
+
+  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
+    // reclaims, so nothing sees the difference today — if one stops doing that,
+    // stop the child here too.
+    this.requireChild(dockerId);
+    this.removed.push(dockerId);
+    this.children.delete(dockerId);
+  }
+
+  /**
+   * 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.
+   */
+  async getStats(): Promise<OrchestratorStats> {
+    return { cpuPercent: 0, memoryBytes: 0, networkRxBytes: 0, networkTxBytes: 0 };
+  }
+
+  /** Unknown handles read as not running, matching the real orchestrator. */
+  async isRunning(dockerId: string): Promise<boolean> {
+    this.onIsRunning?.(dockerId);
+    return this.children.get(dockerId)?.running ?? false;
+  }
+
+  /** Resolve a spawn's friendly containerId back to its dockerId. */
+  resolveDockerId(containerId: string): string | undefined {
+    for (const [dockerId, child] of this.children) {
+      if (child.containerId === containerId) return dockerId;
+    }
+    return undefined;
+  }
+
+  /**
+   * Remove the workdir of a container no handle owns, mirroring the real
+   * `reclaimWorkdir`. Refuses (returns `false`, records nothing) while a child
+   * for that containerId still resolves — that directory belongs to
+   * `removeContainer`, which stops the child first.
+   *
+   * 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
+   * return value, so the gap is unobservable — model it if one starts to.
+   */
+  reclaimWorkdir(containerId: string): boolean {
+    if (this.resolveDockerId(containerId)) return false;
+    this.reclaimedWorkdirs.push(containerId);
+    return true;
+  }
+
+  async getLogs(): Promise<string> {
+    return '';
+  }
+
+  onStateChange(listener: NodeStateListener): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  /** Kill a child out from under the host — the crash the supervisor exists for. */
+  crash(dockerId: string): void {
+    const child = this.children.get(dockerId);
+    if (!child?.running) return;
+    child.running = false;
+    this.emit(toNodeInfo(dockerId, child));
+  }
+
+  /** Emit an arbitrary state change (e.g. the owner node stopping). */
+  emit(info: ManagedNodeInfo): void {
+    for (const listener of this.listeners) listener(info);
+  }
+
+  /** Mirrors `HostProcessOrchestrator.requireHandle` — unknown handles throw. */
+  private requireChild(dockerId: string): FakeChild {
+    const child = this.children.get(dockerId);
+    if (!child) throw new Error(`Container not found: ${dockerId}`);
+    return child;
+  }
+}
+
+function toNodeInfo(dockerId: string, child: FakeChild): ManagedNodeInfo {
+  return {
+    id: child.containerId,
+    dockerId,
+    partyId: child.partyId,
+    profile: child.profile,
+    status: child.running ? 'running' : 'stopped',
+    spawnedAt: new Date(0).toISOString(),
+    workdir: `/fake/${child.containerId}`,
+    ports: { health: 0, metrics: 0, p2p: 0, admin: 0 },
+  };
+}

package/src/donation/__tests__/grant-service.test.ts

@@ -0,0 +1,213 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { GrantService, createGrantAdminHandlers, DEFAULT_MAX_NODES } from '../grant-service.js';
+import { GrantStore } from '../grant-store.js';
+import { GrantError } from '../types.js';
+
+let tmpRoot: string;
+let store: GrantStore;
+let service: GrantService;
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-grant-svc-'));
+  store = new GrantStore(tmpRoot);
+  service = new GrantService({ store });
+});
+
+afterEach(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe('GrantService.issue', () => {
+  it('persists a grant and returns a base64url token', () => {
+    const grant = service.issue({ label: "Alice's cadre", maxNodes: 2 });
+    expect(grant.token).toBeTruthy();
+    // base64url alphabet only.
+    expect(grant.token).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(grant.label).toBe("Alice's cadre");
+    expect(grant.maxNodes).toBe(2);
+    expect(grant.createdAt).toBeTruthy();
+    expect(grant.expiresAt).toBeUndefined();
+    expect(grant.revokedAt).toBeUndefined();
+
+    expect(store.get(grant.token)).toMatchObject({ label: "Alice's cadre", maxNodes: 2 });
+  });
+
+  it('defaults maxNodes when omitted', () => {
+    const grant = service.issue({ label: 'Bob' });
+    expect(grant.maxNodes).toBe(DEFAULT_MAX_NODES);
+  });
+
+  it('sets expiresAt from ttlMs', () => {
+    const clock = new Date('2025-01-01T00:00:00.000Z');
+    const svc = new GrantService({ store, now: () => clock });
+    const grant = svc.issue({ label: 'Carol', ttlMs: 24 * 60 * 60 * 1000 });
+    expect(grant.expiresAt).toBe('2025-01-02T00:00:00.000Z');
+  });
+
+  it('rejects empty / whitespace labels', () => {
+    expect(() => service.issue({ label: '   ' })).toThrow(GrantError);
+    expect(() => service.issue({ label: '' })).toThrow(GrantError);
+  });
+
+  it('rejects labels over 200 characters', () => {
+    expect(() => service.issue({ label: 'a'.repeat(201) }))
+      .toThrow(expect.objectContaining({ code: 'invalid_label' }));
+  });
+
+  it('rejects non-positive / non-integer maxNodes', () => {
+    expect(() => service.issue({ label: 'X', maxNodes: 0 }))
+      .toThrow(expect.objectContaining({ code: 'invalid_max_nodes' }));
+    expect(() => service.issue({ label: 'X', maxNodes: -1 }))
+      .toThrow(expect.objectContaining({ code: 'invalid_max_nodes' }));
+    expect(() => service.issue({ label: 'X', maxNodes: 1.5 }))
+      .toThrow(expect.objectContaining({ code: 'invalid_max_nodes' }));
+  });
+
+  it('rejects non-positive ttl', () => {
+    expect(() => service.issue({ label: 'X', ttlMs: 0 }))
+      .toThrow(expect.objectContaining({ code: 'invalid_ttl' }));
+    expect(() => service.issue({ label: 'X', ttlMs: -1 }))
+      .toThrow(expect.objectContaining({ code: 'invalid_ttl' }));
+  });
+});
+
+describe('GrantService.validate', () => {
+  it('accepts a live grant', () => {
+    const { token } = service.issue({ label: 'Alice' });
+    const v = service.validate(token);
+    expect(v.ok).toBe(true);
+    expect(v.grant?.token).toBe(token);
+    expect(v.reason).toBeUndefined();
+  });
+
+  it('denies an empty bearer with unknown_token (never throws)', () => {
+    expect(service.validate('')).toEqual({ ok: false, reason: 'unknown_token' });
+  });
+
+  it('denies an unknown token with unknown_token (never throws)', () => {
+    expect(service.validate('does-not-exist')).toEqual({ ok: false, reason: 'unknown_token' });
+  });
+
+  it('denies a revoked grant with reason "revoked"', () => {
+    const { token } = service.issue({ label: 'Rev' });
+    service.revoke(token);
+    const v = service.validate(token);
+    expect(v.ok).toBe(false);
+    expect(v.reason).toBe('revoked');
+    expect(v.grant?.token).toBe(token);
+  });
+
+  it('denies an expired grant with reason "expired" even when not revoked', () => {
+    let clock = new Date('2025-01-01T00:00:00.000Z');
+    const svc = new GrantService({ store, now: () => clock });
+    const { token } = svc.issue({ label: 'Exp', ttlMs: 60_000 });
+
+    clock = new Date('2025-01-02T00:00:00.000Z'); // past expiry
+    const v = svc.validate(token);
+    expect(v.ok).toBe(false);
+    expect(v.reason).toBe('expired');
+  });
+
+  it('reports revoked over expired when both apply', () => {
+    let clock = new Date('2025-01-01T00:00:00.000Z');
+    const svc = new GrantService({ store, now: () => clock });
+    const { token } = svc.issue({ label: 'Both', ttlMs: 60_000 });
+    svc.revoke(token);
+
+    clock = new Date('2025-01-02T00:00:00.000Z'); // also past expiry now
+    expect(svc.validate(token).reason).toBe('revoked');
+  });
+});
+
+describe('GrantService.validateForProvision', () => {
+  it('allows up to the quota, then denies with quota_exceeded', () => {
+    const { token } = service.issue({ label: 'Alice', maxNodes: 2 });
+
+    // First two provisions (live count 0, then 1) pass.
+    expect(service.validateForProvision(token, () => 0).ok).toBe(true);
+    expect(service.validateForProvision(token, () => 1).ok).toBe(true);
+
+    // Third (live count already at 2) is denied.
+    const v = service.validateForProvision(token, () => 2);
+    expect(v.ok).toBe(false);
+    expect(v.reason).toBe('quota_exceeded');
+    expect(v.grant?.token).toBe(token);
+  });
+
+  it('does not consult liveNodeCount for an unknown token', () => {
+    let called = false;
+    const v = service.validateForProvision('nope', () => { called = true; return 0; });
+    expect(v).toEqual({ ok: false, reason: 'unknown_token' });
+    expect(called).toBe(false);
+  });
+
+  it('does not consult liveNodeCount for a revoked or expired grant', () => {
+    const { token } = service.issue({ label: 'Rev', maxNodes: 5 });
+    service.revoke(token);
+    let called = false;
+    const v = service.validateForProvision(token, () => { called = true; return 0; });
+    expect(v.reason).toBe('revoked');
+    expect(called).toBe(false);
+  });
+});
+
+describe('GrantService.revoke', () => {
+  it('throws not_found for an unknown token', () => {
+    expect(() => service.revoke('nope'))
+      .toThrow(expect.objectContaining({ code: 'not_found' }));
+  });
+
+  it('is idempotent (second revoke keeps the original timestamp)', () => {
+    let clock = new Date('2025-01-01T00:00:00.000Z');
+    const svc = new GrantService({ store, now: () => clock });
+    const { token } = svc.issue({ label: 'X' });
+
+    svc.revoke(token);
+    const first = store.get(token)?.revokedAt;
+
+    clock = new Date('2025-02-01T00:00:00.000Z');
+    svc.revoke(token); // no throw; keeps first timestamp
+    expect(store.get(token)?.revokedAt).toBe(first);
+  });
+});
+
+describe('GrantService.list', () => {
+  it('enumerates issued grants', () => {
+    service.issue({ label: 'A' });
+    service.issue({ label: 'B' });
+    expect(service.list().map(g => g.label).sort()).toEqual(['A', 'B']);
+  });
+});
+
+describe('createGrantAdminHandlers', () => {
+  it('exposes the admin HTTP-handler surface', async () => {
+    const handlers = createGrantAdminHandlers(service);
+
+    const issued = await handlers.postGrant({ label: 'Pat', maxNodes: 3 });
+    expect(issued.grant.token).toBeTruthy();
+    expect(issued.grant.maxNodes).toBe(3);
+
+    let listed = await handlers.listGrants();
+    expect(listed.grants.map(g => g.token)).toContain(issued.grant.token);
+
+    await handlers.deleteGrant(issued.grant.token);
+    listed = await handlers.listGrants();
+    // Revocation marks, not removes — the grant is still listed but revoked.
+    expect(listed.grants.find(g => g.token === issued.grant.token)?.revokedAt).toBeTruthy();
+  });
+
+  it('postGrant rejects a missing label', async () => {
+    const handlers = createGrantAdminHandlers(service);
+    await expect(handlers.postGrant({ label: undefined as unknown as string }))
+      .rejects.toMatchObject({ code: 'invalid_label' });
+  });
+
+  it('deleteGrant surfaces not_found for an unknown token', async () => {
+    const handlers = createGrantAdminHandlers(service);
+    await expect(handlers.deleteGrant('nope')).rejects.toMatchObject({ code: 'not_found' });
+  });
+});

package/src/donation/__tests__/grant-store.test.ts

@@ -0,0 +1,113 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { GrantStore } from '../grant-store.js';
+import { GrantError } from '../types.js';
+import type { Grant } from '../types.js';
+
+let tmpRoot: string;
+
+function grant(over: Partial<Grant> = {}): Grant {
+  return {
+    token: 'tok-A',
+    label: "Alice's cadre",
+    maxNodes: 2,
+    createdAt: '2025-01-01T00:00:00.000Z',
+    ...over,
+  };
+}
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-grant-store-'));
+});
+
+afterEach(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe('GrantStore', () => {
+  it('returns empty state when file is missing', () => {
+    const store = new GrantStore(tmpRoot);
+    expect(store.list()).toEqual([]);
+    expect(store.get('anything')).toBeUndefined();
+  });
+
+  it('round-trips grants through save/load', () => {
+    const store = new GrantStore(tmpRoot);
+    store.add(grant({ token: 'tok-A', label: 'Alice' }));
+    store.add(grant({ token: 'tok-B', label: 'Bob', maxNodes: 1, expiresAt: '2025-06-01T00:00:00.000Z' }));
+
+    const reread = new GrantStore(tmpRoot);
+    expect(reread.list()).toHaveLength(2);
+    expect(reread.get('tok-A')).toMatchObject({ token: 'tok-A', label: 'Alice', maxNodes: 2 });
+    expect(reread.get('tok-B')?.expiresAt).toBe('2025-06-01T00:00:00.000Z');
+    expect(reread.get('tok-A')?.expiresAt).toBeUndefined();
+  });
+
+  it('removes grants', () => {
+    const store = new GrantStore(tmpRoot);
+    store.add(grant({ token: 'tok-A' }));
+    expect(store.remove('tok-A')).toBe(true);
+    expect(store.remove('tok-A')).toBe(false);
+
+    const reread = new GrantStore(tmpRoot);
+    expect(reread.list()).toEqual([]);
+  });
+
+  it('marks a grant revoked, idempotently', () => {
+    const store = new GrantStore(tmpRoot);
+    store.add(grant({ token: 'tok-A' }));
+
+    expect(store.markRevoked('tok-A', '2025-02-01T00:00:00.000Z')).toBe(true);
+    expect(store.get('tok-A')?.revokedAt).toBe('2025-02-01T00:00:00.000Z');
+
+    // Second revoke keeps the original timestamp.
+    expect(store.markRevoked('tok-A', '2025-03-01T00:00:00.000Z')).toBe(true);
+    expect(store.get('tok-A')?.revokedAt).toBe('2025-02-01T00:00:00.000Z');
+
+    // Unknown token.
+    expect(store.markRevoked('nope', '2025-02-01T00:00:00.000Z')).toBe(false);
+  });
+
+  it('writes through a temp file (atomic rename, no residue)', () => {
+    const store = new GrantStore(tmpRoot);
+    store.add(grant());
+    expect(existsSync(join(tmpRoot, 'grants.json'))).toBe(true);
+    expect(existsSync(join(tmpRoot, 'grants.json.tmp'))).toBe(false);
+  });
+
+  it('persists the version field in saved JSON', () => {
+    const store = new GrantStore(tmpRoot);
+    store.add(grant({ token: 'tok-A', label: 'one' }));
+    const raw = JSON.parse(readFileSync(join(tmpRoot, 'grants.json'), 'utf8'));
+    expect(raw.version).toBe(1);
+    expect(raw.grants['tok-A'].label).toBe('one');
+    // token is the map key, not duplicated inside the row.
+    expect(raw.grants['tok-A'].token).toBeUndefined();
+  });
+
+  it('throws on malformed JSON rather than silently wiping (would revoke everyone)', () => {
+    writeFileSync(join(tmpRoot, 'grants.json'), 'not json', 'utf8');
+    const store = new GrantStore(tmpRoot);
+    expect(() => store.load()).toThrow(GrantError);
+  });
+
+  it('throws on a file with the wrong shape', () => {
+    writeFileSync(join(tmpRoot, 'grants.json'), JSON.stringify({ version: 99, foo: 'bar' }), 'utf8');
+    const store = new GrantStore(tmpRoot);
+    expect(() => store.load()).toThrow(GrantError);
+  });
+
+  it('wraps a write failure as storage_error (not a bare Error)', () => {
+    const store = new GrantStore(tmpRoot);
+    // load() sees no grants.json (empty), then save() writes grants.json.tmp.
+    // Make that temp path a directory so writeFileSync fails (EISDIR) — the
+    // failure must surface as GrantError storage_error, not a bare Error.
+    mkdirSync(join(tmpRoot, 'grants.json.tmp'));
+    expect(() => store.add(grant())).toThrow(
+      expect.objectContaining({ code: 'storage_error' }),
+    );
+  });
+});