@serfab/cadre-host 1.10.0 → 1.12.0

package/src/orchestrator/port-allocator.ts

@@ -1,73 +1,73 @@
-import {
-  allocatePortSet,
-  releasePortSet,
-  reservePortSet,
-  type PortAllocator,
-} from '@serfab/cadre-provider';
-
-import type { NodePorts } from './types.js';
-
-/**
- * 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 satisfies readonly (keyof NodePorts)[];
-
-/**
- * Allocate a full NodePorts set atomically, in {@link NODE_PORT_KEYS} order.
- * `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 before anything is allocated
- * and are trusted, not checked — see `allocatePortSet`.
- */
-export function allocateNodePorts(
-  allocator: PortAllocator,
-  overrides?: Partial<NodePorts>,
-): NodePorts {
-  return allocatePortSet(allocator, NODE_PORT_KEYS, overrides);
-}
-
-/**
- * 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 {
-  reservePortSet(allocator, NODE_PORT_KEYS, ports);
-}
-
-/**
- * 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 {
-  releasePortSet(allocator, NODE_PORT_KEYS, ports);
-}
-
-/**
- * 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;
-}
+import {
+  allocatePortSet,
+  releasePortSet,
+  reservePortSet,
+  type PortAllocator,
+} from '@serfab/cadre-provider';
+
+import type { NodePorts } from './types.js';
+
+/**
+ * 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 satisfies readonly (keyof NodePorts)[];
+
+/**
+ * Allocate a full NodePorts set atomically, in {@link NODE_PORT_KEYS} order.
+ * `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 before anything is allocated
+ * and are trusted, not checked — see `allocatePortSet`.
+ */
+export function allocateNodePorts(
+  allocator: PortAllocator,
+  overrides?: Partial<NodePorts>,
+): NodePorts {
+  return allocatePortSet(allocator, NODE_PORT_KEYS, overrides);
+}
+
+/**
+ * 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 {
+  reservePortSet(allocator, NODE_PORT_KEYS, ports);
+}
+
+/**
+ * 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 {
+  releasePortSet(allocator, NODE_PORT_KEYS, ports);
+}
+
+/**
+ * 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/server/__tests__/grants-admin-route.test.ts

@@ -1,171 +1,171 @@
-import Fastify from 'fastify';
-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 { registerErrorHandler } from '../error-handler.js';
-import { EventBus } from '../events/bus.js';
-import { registerGrantsAdminRoutes } from '../routes/grants-admin.js';
-import {
-  DonationService,
-  DonationStore,
-  GrantService,
-  GrantStore,
-  createGrantAdminHandlers,
-} from '../../donation/index.js';
-import type { DonationView, Grant, GrantListing } from '../../donation/index.js';
-import { FakeOrchestrator } from '../../donation/__tests__/fake-orchestrator.js';
-
-/** A well-formed 32-byte base64url owner key, which `provision` requires. */
-const OWNER_KEY = Buffer.alloc(32, 7).toString('base64url');
-
-let tmpRoot: string;
-let app: ReturnType<typeof Fastify>;
-let grants: GrantService;
-let donations: DonationService;
-let donationStore: DonationStore;
-let orch: FakeOrchestrator;
-
-beforeEach(() => {
-  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-grants-route-'));
-  grants = new GrantService({ store: new GrantStore(tmpRoot) });
-  orch = new FakeOrchestrator();
-  donationStore = new DonationStore(tmpRoot);
-  donations = new DonationService({ orchestrator: orch, grants, store: donationStore });
-  app = Fastify();
-  registerErrorHandler(app);
-  registerGrantsAdminRoutes(app, { handlers: createGrantAdminHandlers(grants, donations), events: new EventBus() });
-});
-
-afterEach(async () => {
-  await app.close();
-  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
-});
-
-describe('/grants-admin routes', () => {
-  it('POST issues a grant, GET lists it, DELETE revokes it', async () => {
-    const post = await app.inject({
-      method: 'POST',
-      url: '/grants-admin',
-      payload: { label: "Alice's cadre", maxNodes: 2 },
-    });
-    expect(post.statusCode).toBe(200);
-    const created = (post.json() as { grant: Grant }).grant;
-    expect(created.token).toBeTruthy();
-    expect(created.maxNodes).toBe(2);
-
-    const list = await app.inject({ method: 'GET', url: '/grants-admin' });
-    expect(list.statusCode).toBe(200);
-    expect((list.json() as { grants: Grant[] }).grants.map(g => g.token)).toContain(created.token);
-
-    const del = await app.inject({
-      method: 'DELETE',
-      url: `/grants-admin/${encodeURIComponent(created.token)}`,
-    });
-    expect(del.statusCode).toBe(200);
-
-    // Revoked → still listed, now carries revokedAt.
-    const after = await app.inject({ method: 'GET', url: '/grants-admin' });
-    const row = (after.json() as { grants: Grant[] }).grants.find(g => g.token === created.token);
-    expect(row?.revokedAt).toBeTruthy();
-  });
-
-  it('POST with an empty label → 400 invalid_label', async () => {
-    const res = await app.inject({ method: 'POST', url: '/grants-admin', payload: { label: '  ' } });
-    expect(res.statusCode).toBe(400);
-    expect((res.json() as { error: { code: string } }).error.code).toBe('invalid_label');
-  });
-
-  it('POST with a bad maxNodes → 400 invalid_max_nodes', async () => {
-    const res = await app.inject({ method: 'POST', url: '/grants-admin', payload: { label: 'X', maxNodes: 0 } });
-    expect(res.statusCode).toBe(400);
-    expect((res.json() as { error: { code: string } }).error.code).toBe('invalid_max_nodes');
-  });
-
-  it('DELETE of an unknown token → 404 not_found', async () => {
-    const res = await app.inject({ method: 'DELETE', url: '/grants-admin/nope' });
-    expect(res.statusCode).toBe(404);
-    expect((res.json() as { error: { code: string } }).error.code).toBe('not_found');
-  });
-});
-
-function provisionUnder(token: string): Promise<DonationView> {
-  return donations.provision({ grantToken: token, partyId: 'party-P', bootstrapNodes: [], ownerKeys: [OWNER_KEY] });
-}
-
-describe('/grants-admin listing', () => {
-  it("GET reports each grant's live nodes and the donations a revoke would end", async () => {
-    const a = grants.issue({ label: 'A', maxNodes: 3 });
-    const b = grants.issue({ label: 'B' });
-    const seeded = await provisionUnder(a.token);
-    const failed = await provisionUnder(a.token);
-    const ended = await provisionUnder(a.token);
-    const other = await provisionUnder(b.token);
-    donationStore.put({ ...donationStore.get(seeded.id)!, status: 'seeded' });
-    donationStore.put({ ...donationStore.get(failed.id)!, status: 'error', error: 'respawn gave up' });
-    await donations.terminate(ended.id);
-
-    const res = await app.inject({ method: 'GET', url: '/grants-admin' });
-
-    const listed = (res.json() as { grants: GrantListing[] }).grants;
-    const rowA = listed.find(g => g.token === a.token);
-    const rowB = listed.find(g => g.token === b.token);
-    // `error` is not live, but a revoke still tears it down; `terminated` is neither.
-    expect(rowA?.liveNodes).toBe(1);
-    expect(rowA?.donations).toEqual(expect.arrayContaining([
-      { id: seeded.id, status: 'seeded' },
-      { id: failed.id, status: 'error' },
-    ]));
-    expect(rowA?.donations).toHaveLength(2);
-    expect(rowB?.liveNodes).toBe(1);
-    expect(rowB?.donations).toEqual([{ id: other.id, status: 'awaiting_seed' }]);
-  });
-});
-
-describe('/grants-admin donated-node teardown', () => {
-  it('DELETE /grants-admin/:token terminates the nodes donated under the grant', async () => {
-    const { token } = grants.issue({ label: 'Alice' });
-    const donation = await provisionUnder(token);
-
-    const res = await app.inject({ method: 'DELETE', url: `/grants-admin/${encodeURIComponent(token)}` });
-
-    expect(res.statusCode).toBe(200);
-    expect(res.json()).toEqual({ ok: true, terminated: [donation.id] });
-    expect(donations.get(donation.id)?.status).toBe('terminated');
-    expect(orch.removed).toEqual(['dock_1']);
-  });
-
-  it('?keepNodes=true revokes the grant but leaves its nodes running', async () => {
-    const { token } = grants.issue({ label: 'Alice' });
-    const donation = await provisionUnder(token);
-
-    const res = await app.inject({
-      method: 'DELETE',
-      url: `/grants-admin/${encodeURIComponent(token)}?keepNodes=true`,
-    });
-
-    expect(res.statusCode).toBe(200);
-    expect(res.json()).toEqual({ ok: true, terminated: [] });
-    expect(grants.validate(token).reason).toBe('revoked');
-    expect(donations.get(donation.id)?.status).toBe('awaiting_seed');
-    expect(orch.stopped).toEqual([]);
-  });
-
-  it('DELETE /grants-admin/donations/:id ends one node under a revoked grant; an unknown id 404s', async () => {
-    const { token } = grants.issue({ label: 'Alice', maxNodes: 2 });
-    const kept = await provisionUnder(token);
-    const ended = await provisionUnder(token);
-    grants.revoke(token);
-
-    const res = await app.inject({ method: 'DELETE', url: `/grants-admin/donations/${ended.id}` });
-
-    expect(res.statusCode).toBe(200);
-    expect(donations.get(ended.id)?.status).toBe('terminated');
-    expect(donations.get(kept.id)?.status).toBe('awaiting_seed');
-
-    const unknown = await app.inject({ method: 'DELETE', url: '/grants-admin/donations/grn_nope' });
-    expect(unknown.statusCode).toBe(404);
-    expect((unknown.json() as { error: { code: string } }).error.code).toBe('not_found');
-  });
-});
+import Fastify from 'fastify';
+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 { registerErrorHandler } from '../error-handler.js';
+import { EventBus } from '../events/bus.js';
+import { registerGrantsAdminRoutes } from '../routes/grants-admin.js';
+import {
+  DonationService,
+  DonationStore,
+  GrantService,
+  GrantStore,
+  createGrantAdminHandlers,
+} from '../../donation/index.js';
+import type { DonationView, Grant, GrantListing } from '../../donation/index.js';
+import { FakeOrchestrator } from '../../donation/__tests__/fake-orchestrator.js';
+
+/** A well-formed 32-byte base64url owner key, which `provision` requires. */
+const OWNER_KEY = Buffer.alloc(32, 7).toString('base64url');
+
+let tmpRoot: string;
+let app: ReturnType<typeof Fastify>;
+let grants: GrantService;
+let donations: DonationService;
+let donationStore: DonationStore;
+let orch: FakeOrchestrator;
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-grants-route-'));
+  grants = new GrantService({ store: new GrantStore(tmpRoot) });
+  orch = new FakeOrchestrator();
+  donationStore = new DonationStore(tmpRoot);
+  donations = new DonationService({ orchestrator: orch, grants, store: donationStore });
+  app = Fastify();
+  registerErrorHandler(app);
+  registerGrantsAdminRoutes(app, { handlers: createGrantAdminHandlers(grants, donations), events: new EventBus() });
+});
+
+afterEach(async () => {
+  await app.close();
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe('/grants-admin routes', () => {
+  it('POST issues a grant, GET lists it, DELETE revokes it', async () => {
+    const post = await app.inject({
+      method: 'POST',
+      url: '/grants-admin',
+      payload: { label: "Alice's cadre", maxNodes: 2 },
+    });
+    expect(post.statusCode).toBe(200);
+    const created = (post.json() as { grant: Grant }).grant;
+    expect(created.token).toBeTruthy();
+    expect(created.maxNodes).toBe(2);
+
+    const list = await app.inject({ method: 'GET', url: '/grants-admin' });
+    expect(list.statusCode).toBe(200);
+    expect((list.json() as { grants: Grant[] }).grants.map(g => g.token)).toContain(created.token);
+
+    const del = await app.inject({
+      method: 'DELETE',
+      url: `/grants-admin/${encodeURIComponent(created.token)}`,
+    });
+    expect(del.statusCode).toBe(200);
+
+    // Revoked → still listed, now carries revokedAt.
+    const after = await app.inject({ method: 'GET', url: '/grants-admin' });
+    const row = (after.json() as { grants: Grant[] }).grants.find(g => g.token === created.token);
+    expect(row?.revokedAt).toBeTruthy();
+  });
+
+  it('POST with an empty label → 400 invalid_label', async () => {
+    const res = await app.inject({ method: 'POST', url: '/grants-admin', payload: { label: '  ' } });
+    expect(res.statusCode).toBe(400);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('invalid_label');
+  });
+
+  it('POST with a bad maxNodes → 400 invalid_max_nodes', async () => {
+    const res = await app.inject({ method: 'POST', url: '/grants-admin', payload: { label: 'X', maxNodes: 0 } });
+    expect(res.statusCode).toBe(400);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('invalid_max_nodes');
+  });
+
+  it('DELETE of an unknown token → 404 not_found', async () => {
+    const res = await app.inject({ method: 'DELETE', url: '/grants-admin/nope' });
+    expect(res.statusCode).toBe(404);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('not_found');
+  });
+});
+
+function provisionUnder(token: string): Promise<DonationView> {
+  return donations.provision({ grantToken: token, partyId: 'party-P', bootstrapNodes: [], ownerKeys: [OWNER_KEY] });
+}
+
+describe('/grants-admin listing', () => {
+  it("GET reports each grant's live nodes and the donations a revoke would end", async () => {
+    const a = grants.issue({ label: 'A', maxNodes: 3 });
+    const b = grants.issue({ label: 'B' });
+    const seeded = await provisionUnder(a.token);
+    const failed = await provisionUnder(a.token);
+    const ended = await provisionUnder(a.token);
+    const other = await provisionUnder(b.token);
+    donationStore.put({ ...donationStore.get(seeded.id)!, status: 'seeded' });
+    donationStore.put({ ...donationStore.get(failed.id)!, status: 'error', error: 'respawn gave up' });
+    await donations.terminate(ended.id);
+
+    const res = await app.inject({ method: 'GET', url: '/grants-admin' });
+
+    const listed = (res.json() as { grants: GrantListing[] }).grants;
+    const rowA = listed.find(g => g.token === a.token);
+    const rowB = listed.find(g => g.token === b.token);
+    // `error` is not live, but a revoke still tears it down; `terminated` is neither.
+    expect(rowA?.liveNodes).toBe(1);
+    expect(rowA?.donations).toEqual(expect.arrayContaining([
+      { id: seeded.id, status: 'seeded' },
+      { id: failed.id, status: 'error' },
+    ]));
+    expect(rowA?.donations).toHaveLength(2);
+    expect(rowB?.liveNodes).toBe(1);
+    expect(rowB?.donations).toEqual([{ id: other.id, status: 'awaiting_seed' }]);
+  });
+});
+
+describe('/grants-admin donated-node teardown', () => {
+  it('DELETE /grants-admin/:token terminates the nodes donated under the grant', async () => {
+    const { token } = grants.issue({ label: 'Alice' });
+    const donation = await provisionUnder(token);
+
+    const res = await app.inject({ method: 'DELETE', url: `/grants-admin/${encodeURIComponent(token)}` });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ ok: true, terminated: [donation.id] });
+    expect(donations.get(donation.id)?.status).toBe('terminated');
+    expect(orch.removed).toEqual(['dock_1']);
+  });
+
+  it('?keepNodes=true revokes the grant but leaves its nodes running', async () => {
+    const { token } = grants.issue({ label: 'Alice' });
+    const donation = await provisionUnder(token);
+
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/grants-admin/${encodeURIComponent(token)}?keepNodes=true`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ ok: true, terminated: [] });
+    expect(grants.validate(token).reason).toBe('revoked');
+    expect(donations.get(donation.id)?.status).toBe('awaiting_seed');
+    expect(orch.stopped).toEqual([]);
+  });
+
+  it('DELETE /grants-admin/donations/:id ends one node under a revoked grant; an unknown id 404s', async () => {
+    const { token } = grants.issue({ label: 'Alice', maxNodes: 2 });
+    const kept = await provisionUnder(token);
+    const ended = await provisionUnder(token);
+    grants.revoke(token);
+
+    const res = await app.inject({ method: 'DELETE', url: `/grants-admin/donations/${ended.id}` });
+
+    expect(res.statusCode).toBe(200);
+    expect(donations.get(ended.id)?.status).toBe('terminated');
+    expect(donations.get(kept.id)?.status).toBe('awaiting_seed');
+
+    const unknown = await app.inject({ method: 'DELETE', url: '/grants-admin/donations/grn_nope' });
+    expect(unknown.statusCode).toBe(404);
+    expect((unknown.json() as { error: { code: string } }).error.code).toBe('not_found');
+  });
+});

package/src/server/events/types.ts

@@ -1,24 +1,24 @@
-/**
- * Event types broadcast over the SPA's SSE channel.
- *
- * Publishers (orchestrator hook, route adapters, update observer) call
- * EventBus.publish; the `/api/events` route fan-outs to connected clients.
- */
-
-import type { ContainerStatus } from '@serfab/cadre-provider';
-
-import type { DirectReachability, PortForwardMode } from '../../nat/index.js';
-
-export type LocalUiEvent =
-  | { type: 'node-state-changed'; nodeId: string; status: ContainerStatus }
-  | { type: 'trust-circle-changed'; kind: 'invited' | 'redeemed' | 'revoked' }
-  | { type: 'strands-changed'; kind: 'removed' }
-  | { type: 'grants-changed'; kind: 'issued' | 'revoked' | 'terminated' }
-  | {
-      type: 'connectivity-changed';
-      portMode: PortForwardMode;
-      directReachability: DirectReachability;
-    }
-  | { type: 'update-available'; version: string; releaseNotesUrl?: string };
-
-export type LocalUiEventType = LocalUiEvent['type'];
+/**
+ * Event types broadcast over the SPA's SSE channel.
+ *
+ * Publishers (orchestrator hook, route adapters, update observer) call
+ * EventBus.publish; the `/api/events` route fan-outs to connected clients.
+ */
+
+import type { ContainerStatus } from '@serfab/cadre-provider';
+
+import type { DirectReachability, PortForwardMode } from '../../nat/index.js';
+
+export type LocalUiEvent =
+  | { type: 'node-state-changed'; nodeId: string; status: ContainerStatus }
+  | { type: 'trust-circle-changed'; kind: 'invited' | 'redeemed' | 'revoked' }
+  | { type: 'strands-changed'; kind: 'removed' }
+  | { type: 'grants-changed'; kind: 'issued' | 'revoked' | 'terminated' }
+  | {
+      type: 'connectivity-changed';
+      portMode: PortForwardMode;
+      directReachability: DirectReachability;
+    }
+  | { type: 'update-available'; version: string; releaseNotesUrl?: string };
+
+export type LocalUiEventType = LocalUiEvent['type'];