@serfab/cadre-host 0.9.0 → 0.11.0

package/src/server/__tests__/strands-route.test.ts

@@ -0,0 +1,233 @@
+/**
+ * `/api/strands` route tests — a real Fastify built by `createLocalUiServer`
+ * (so the error handler, the mount gate, and the static not-found fallback are
+ * all the production ones) over a fake StrandService.
+ *
+ * What the service does is covered by `strands/__tests__/strand-service.test.ts`;
+ * this file is about the HTTP contract: envelope shape, status mapping, the
+ * `confirm` query param, and exactly-once bus publication.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+import { createLocalUiServer } from '../index.js';
+import type { LocalUiEvent } from '../events/types.js';
+import type { HostProcessOrchestrator } from '../../orchestrator/index.js';
+import type { StrandService } from '../../strands/index.js';
+import { StrandError } from '../../strands/index.js';
+import type { StrandListSnapshot, StrandRemovalResult } from '../../strands/index.js';
+
+function fakeOrchestrator(): HostProcessOrchestrator {
+  return {
+    listNodes: () => [],
+    getNode: () => undefined,
+    resolveDockerId: () => undefined,
+    onStateChange: () => () => undefined,
+  } as unknown as HostProcessOrchestrator;
+}
+
+const SNAPSHOT: StrandListSnapshot = {
+  strands: [
+    { id: 'open-one', type: 'o', running: true, status: 'active' },
+    { id: 'closed-one', type: 'c', running: false, status: null },
+  ],
+  controlConnections: 3,
+};
+
+interface FakeStrands {
+  service: StrandService;
+  /** Every (id, confirm) the route forwarded. */
+  calls: Array<{ strandId: string; confirm: boolean }>;
+  /** Set to make `list` and `remove` throw. */
+  failWith?: unknown;
+  /** Set to make `remove` report a strand that was never published. */
+  absent?: boolean;
+}
+
+function fakeStrandService(): FakeStrands {
+  const state: FakeStrands = {
+    calls: [],
+    service: undefined as unknown as StrandService,
+  };
+  state.service = {
+    async list(): Promise<StrandListSnapshot> {
+      if (state.failWith) throw state.failWith;
+      return SNAPSHOT;
+    },
+    async remove(strandId: string, opts: { confirm: boolean }): Promise<StrandRemovalResult> {
+      state.calls.push({ strandId, confirm: opts.confirm });
+      if (state.failWith) throw state.failWith;
+      return state.absent
+        ? { strandId, published: false, type: null, removed: false, alone: false }
+        : { strandId, published: true, type: 'o', removed: true, alone: false };
+    },
+  } as unknown as StrandService;
+  return state;
+}
+
+let dataDir: string;
+let server: ReturnType<typeof createLocalUiServer>;
+let strands: FakeStrands;
+let events: LocalUiEvent[];
+
+function buildServer(opts: { withStrands: boolean }): void {
+  server = createLocalUiServer({
+    uiPort: 8765,
+    dataDir,
+    orchestrator: fakeOrchestrator(),
+    ...(opts.withStrands ? { strands: strands.service } : {}),
+    forcePort: 0,
+  });
+  events = [];
+  server.events.subscribe((e) => events.push(e));
+}
+
+beforeEach(() => {
+  dataDir = mkdtempSync(join(tmpdir(), 'cadre-host-strands-route-'));
+  strands = fakeStrandService();
+  buildServer({ withStrands: true });
+});
+
+afterEach(async () => {
+  await server.app.close();
+  rmSync(dataDir, { recursive: true, force: true });
+});
+
+describe('GET /api/strands', () => {
+  it('returns the snapshot in the /api/* envelope', async () => {
+    const res = await server.app.inject({ method: 'GET', url: '/api/strands' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { ok: boolean; data: StrandListSnapshot };
+    expect(body.ok).toBe(true);
+    expect(body.data.strands).toHaveLength(2);
+    expect(body.data.strands[0]?.id).toBe('open-one');
+    expect(body.data.controlConnections).toBe(3);
+  });
+
+  it('maps a service failure through the same error handler as the DELETE arm', async () => {
+    strands.failWith = new StrandError('node_unavailable', 'Owner node unavailable: refused');
+    const res = await server.app.inject({ method: 'GET', url: '/api/strands' });
+    expect(res.statusCode).toBe(503);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('node_unavailable');
+  });
+});
+
+describe('DELETE /api/strands/:id', () => {
+  it('removes a published strand → 200 and exactly one strands-changed event', async () => {
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/open-one' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { ok: boolean; data: StrandRemovalResult };
+    expect(body.ok).toBe(true);
+    expect(body.data).toMatchObject({ strandId: 'open-one', published: true, removed: true });
+    expect(events).toEqual([{ type: 'strands-changed', kind: 'removed' }]);
+  });
+
+  it('an absent strand → 200, published: false, and NO event', async () => {
+    strands.absent = true;
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/never-published' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { data: StrandRemovalResult };
+    expect(body.data.published).toBe(false);
+    expect(body.data.removed).toBe(false);
+    expect(events).toEqual([]);
+  });
+
+  it('forwards confirm=1 as true and its absence as false', async () => {
+    await server.app.inject({ method: 'DELETE', url: '/api/strands/a' });
+    await server.app.inject({ method: 'DELETE', url: '/api/strands/b?confirm=1' });
+    await server.app.inject({ method: 'DELETE', url: '/api/strands/c?confirm=true' });
+    expect(strands.calls).toEqual([
+      { strandId: 'a', confirm: false },
+      { strandId: 'b', confirm: true },
+      { strandId: 'c', confirm: true },
+    ]);
+  });
+
+  it('treats a guessy confirm value as NOT confirmed', async () => {
+    // `yes`/`on`/empty are refused deliberately — a typo must not destroy a
+    // closed strand's membership key.
+    await server.app.inject({ method: 'DELETE', url: '/api/strands/a?confirm=yes' });
+    await server.app.inject({ method: 'DELETE', url: '/api/strands/b?confirm=' });
+    expect(strands.calls).toEqual([
+      { strandId: 'a', confirm: false },
+      { strandId: 'b', confirm: false },
+    ]);
+  });
+
+  it('ignores query params other than confirm rather than proxying them', async () => {
+    await server.app.inject({ method: 'DELETE', url: '/api/strands/a?force=1&confirm=1' });
+    expect(strands.calls).toEqual([{ strandId: 'a', confirm: true }]);
+  });
+
+  // The route is one path segment, so an id holding a `/` has to arrive
+  // percent-encoded. Fastify decodes `params`, so the service sees the literal id
+  // and forwards it — nothing in this chain needs to refuse such an id.
+  it('carries a percent-encoded "/" through to the service as a literal', async () => {
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/ns%2Fstrand' });
+    expect(res.statusCode).toBe(200);
+    expect(strands.calls).toEqual([{ strandId: 'ns/strand', confirm: false }]);
+  });
+
+  it('404s an UNencoded "/" at the router, before any handler runs', async () => {
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/ns/strand' });
+    expect(res.statusCode).toBe(404);
+    expect(strands.calls).toEqual([]);
+  });
+});
+
+describe('DELETE /api/strands/:id — error mapping', () => {
+  it('confirmation_required → 428 with the node message intact', async () => {
+    const message = 'Refusing to remove closed strand closed-one without confirmation: …';
+    strands.failWith = new StrandError('confirmation_required', message);
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/closed-one' });
+    expect(res.statusCode).toBe(428);
+    const body = res.json() as { ok: boolean; error: { code: string; message: string } };
+    expect(body.ok).toBe(false);
+    expect(body.error.code).toBe('confirmation_required');
+    expect(body.error.message).toBe(message);
+    expect(events).toEqual([]);
+  });
+
+  it('node_unavailable → 503', async () => {
+    strands.failWith = new StrandError('node_unavailable', 'Owner node unavailable: refused');
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/open-one' });
+    expect(res.statusCode).toBe(503);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('node_unavailable');
+  });
+
+  it('invalid_id → 400', async () => {
+    strands.failWith = new StrandError('invalid_id', 'A strand id is required');
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/%20' });
+    expect(res.statusCode).toBe(400);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('invalid_id');
+  });
+
+  it('internal → 500', async () => {
+    strands.failWith = new StrandError('internal', 'node said something new');
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/open-one' });
+    expect(res.statusCode).toBe(500);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('internal');
+  });
+});
+
+describe('donor-only mode (no strands option)', () => {
+  beforeEach(async () => {
+    await server.app.close();
+    buildServer({ withStrands: false });
+  });
+
+  it('404s GET /api/strands through the static not-found handler', async () => {
+    const res = await server.app.inject({ method: 'GET', url: '/api/strands' });
+    expect(res.statusCode).toBe(404);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('not_found');
+  });
+
+  it('404s DELETE /api/strands/:id', async () => {
+    const res = await server.app.inject({ method: 'DELETE', url: '/api/strands/open-one' });
+    expect(res.statusCode).toBe(404);
+  });
+});

package/src/server/error-handler.ts

@@ -1,155 +1,178 @@
-/**
- * Fastify error handler — translates known typed errors to stable HTTP status
- * codes and uniform `{ ok: false, error: { code, message } }` payloads.
- *
- * Codes (cross-referenced with `auth/types.ts`, `nat/types.ts`, `update/types.ts`):
- *   - TrustCircleError
- *       invalid_label, invalid_token             → 400
- *       not_found, already_redeemed              → 404
- *       expired                                  → 410
- *       node_unavailable                         → 503
- *       storage_error                            → 500
- *   - NatError
- *       invalid_config, ddns_provider_unknown,
- *       ddns_credentials_missing                 → 400
- *       secrets_unavailable, storage_error,
- *       mapping_failed, router_unreachable,
- *       ip_detection_failed, ddns_update_failed  → 500
- *       node_unavailable                         → 503
- *   - UpdateErrorException
- *       manifest_invalid, no_update_available,
- *       min_previous_version                     → 400
- *       apply_in_progress                        → 409
- *       signature_invalid, unsupported_state_version,
- *       apply_failed, rollback_failed, storage_error → 500
- *   - GrantError
- *       invalid_label, invalid_max_nodes,
- *       invalid_ttl                              → 400
- *       not_found                                → 404
- *       storage_error                            → 500
- *   - DonationError
- *       invalid_request                          → 400
- *       unauthorized                             → 401
- *       forbidden                                → 403
- *       not_found                                → 404
- *       invalid_state                            → 409
- *       quota_exceeded                           → 429
- *       orchestrator_error, storage_error        → 500
- *       seed_failed                              → 502
- *       peer_unavailable                         → 503
- *   - everything else                            → 500 (code "internal")
- */
-
-import type { FastifyError, FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
-import debug from 'debug';
-
-import { TrustCircleError, type TrustCircleErrorCode } from '../auth/types.js';
-import { NatError, type NatErrorCode } from '../nat/types.js';
-import { UpdateErrorException, type UpdateErrorCode } from '../update/types.js';
-import { GrantError, type GrantErrorCode, DonationError, type DonationErrorCode } from '../donation/types.js';
-
-const log = debug('cadre:host:error-handler');
-
-const TRUST_STATUS: Record<TrustCircleErrorCode, number> = {
-  invalid_label: 400,
-  invalid_token: 400,
-  not_found: 404,
-  already_redeemed: 404,
-  expired: 410,
-  storage_error: 500,
-  node_unavailable: 503,
-};
-
-const NAT_STATUS: Record<NatErrorCode, number> = {
-  invalid_config: 400,
-  ddns_provider_unknown: 400,
-  ddns_credentials_missing: 400,
-  secrets_unavailable: 500,
-  storage_error: 500,
-  mapping_failed: 500,
-  router_unreachable: 500,
-  ip_detection_failed: 500,
-  ddns_update_failed: 500,
-  node_unavailable: 503,
-};
-
-const GRANT_STATUS: Record<GrantErrorCode, number> = {
-  invalid_label: 400,
-  invalid_max_nodes: 400,
-  invalid_ttl: 400,
-  not_found: 404,
-  storage_error: 500,
-};
-
-const DONATION_STATUS: Record<DonationErrorCode, number> = {
-  unauthorized: 401,
-  forbidden: 403,
-  quota_exceeded: 429,
-  invalid_request: 400,
-  not_found: 404,
-  invalid_state: 409,
-  seed_failed: 502,
-  peer_unavailable: 503,
-  orchestrator_error: 500,
-  storage_error: 500,
-};
-
-const UPDATE_STATUS: Record<UpdateErrorCode, number> = {
-  manifest_invalid: 400,
-  no_update_available: 400,
-  min_previous_version: 400,
-  apply_in_progress: 409,
-  signature_invalid: 500,
-  unsupported_state_version: 500,
-  apply_failed: 500,
-  rollback_failed: 500,
-  storage_error: 500,
-};
-
-export function registerErrorHandler(app: FastifyInstance): void {
-  app.setErrorHandler((err: FastifyError, request: FastifyRequest, reply: FastifyReply) => {
-    const { status, code, message } = classify(err);
-    if (status >= 500) {
-      log('5xx %s %s: [%s] %s', request.method, request.url, code, message);
-    } else {
-      log('%d %s %s: [%s] %s', status, request.method, request.url, code, message);
-    }
-    return reply.code(status).send({
-      ok: false,
-      error: { code, message },
-    });
-  });
-}
-
-interface Classified {
-  status: number;
-  code: string;
-  message: string;
-}
-
-function classify(err: FastifyError): Classified {
-  if (err instanceof TrustCircleError) {
-    return { status: TRUST_STATUS[err.code] ?? 500, code: err.code, message: err.message };
-  }
-  if (err instanceof NatError) {
-    return { status: NAT_STATUS[err.code] ?? 500, code: err.code, message: err.message };
-  }
-  if (err instanceof UpdateErrorException) {
-    return { status: UPDATE_STATUS[err.code] ?? 500, code: err.code, message: err.message };
-  }
-  if (err instanceof GrantError) {
-    return { status: GRANT_STATUS[err.code] ?? 500, code: err.code, message: err.message };
-  }
-  if (err instanceof DonationError) {
-    return { status: DONATION_STATUS[err.code] ?? 500, code: err.code, message: err.message };
-  }
-  // Fastify body-parsing / validation errors have a statusCode we should honour.
-  if (typeof err.statusCode === 'number' && err.statusCode >= 400 && err.statusCode < 600) {
-    return {
-      status: err.statusCode,
-      code: err.code ?? (err.statusCode === 404 ? 'not_found' : 'bad_request'),
-      message: err.message ?? 'request failed',
-    };
-  }
-  return { status: 500, code: 'internal', message: err.message || 'internal error' };
-}
+/**
+ * Fastify error handler — translates known typed errors to stable HTTP status
+ * codes and uniform `{ ok: false, error: { code, message } }` payloads.
+ *
+ * Codes (cross-referenced with `auth/types.ts`, `nat/types.ts`, `strands/types.ts`,
+ * `update/types.ts`):
+ *   - TrustCircleError
+ *       invalid_label, invalid_token             → 400
+ *       not_found, already_redeemed              → 404
+ *       expired                                  → 410
+ *       node_unavailable                         → 503
+ *       storage_error                            → 500
+ *   - NatError
+ *       invalid_config, ddns_provider_unknown,
+ *       ddns_credentials_missing                 → 400
+ *       secrets_unavailable, storage_error,
+ *       mapping_failed, router_unreachable,
+ *       ip_detection_failed, ddns_update_failed  → 500
+ *       node_unavailable                         → 503
+ *   - StrandError
+ *       invalid_id                               → 400
+ *       confirmation_required                    → 428
+ *       node_unavailable                         → 503
+ *       internal                                 → 500
+ *   - UpdateErrorException
+ *       manifest_invalid, no_update_available,
+ *       min_previous_version                     → 400
+ *       apply_in_progress                        → 409
+ *       signature_invalid, unsupported_state_version,
+ *       apply_failed, rollback_failed, storage_error → 500
+ *   - GrantError
+ *       invalid_label, invalid_max_nodes,
+ *       invalid_ttl                              → 400
+ *       not_found                                → 404
+ *       storage_error                            → 500
+ *   - DonationError
+ *       invalid_request                          → 400
+ *       unauthorized                             → 401
+ *       forbidden                                → 403
+ *       not_found                                → 404
+ *       invalid_state                            → 409
+ *       quota_exceeded                           → 429
+ *       orchestrator_error, storage_error        → 500
+ *       seed_failed                              → 502
+ *       peer_unavailable                         → 503
+ *   - everything else                            → 500 (code "internal")
+ */
+
+import type { FastifyError, FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import debug from 'debug';
+
+import { TrustCircleError, type TrustCircleErrorCode } from '../auth/types.js';
+import { NatError, type NatErrorCode } from '../nat/types.js';
+import { StrandError, type StrandErrorCode } from '../strands/types.js';
+import { UpdateErrorException, type UpdateErrorCode } from '../update/types.js';
+import { GrantError, type GrantErrorCode, DonationError, type DonationErrorCode } from '../donation/types.js';
+
+const log = debug('cadre:host:error-handler');
+
+const TRUST_STATUS: Record<TrustCircleErrorCode, number> = {
+  invalid_label: 400,
+  invalid_token: 400,
+  not_found: 404,
+  already_redeemed: 404,
+  expired: 410,
+  storage_error: 500,
+  node_unavailable: 503,
+};
+
+const NAT_STATUS: Record<NatErrorCode, number> = {
+  invalid_config: 400,
+  ddns_provider_unknown: 400,
+  ddns_credentials_missing: 400,
+  secrets_unavailable: 500,
+  storage_error: 500,
+  mapping_failed: 500,
+  router_unreachable: 500,
+  ip_detection_failed: 500,
+  ddns_update_failed: 500,
+  node_unavailable: 503,
+};
+
+/**
+ * 428 (Precondition Required) for `confirmation_required`: the node refused a
+ * closed-strand removal because the caller had not confirmed. It is not a 400
+ * (the request was well-formed) and not a 409 (nothing conflicts) — the caller
+ * must re-send with the precondition satisfied.
+ */
+const STRAND_STATUS: Record<StrandErrorCode, number> = {
+  invalid_id: 400,
+  confirmation_required: 428,
+  node_unavailable: 503,
+  internal: 500,
+};
+
+const GRANT_STATUS: Record<GrantErrorCode, number> = {
+  invalid_label: 400,
+  invalid_max_nodes: 400,
+  invalid_ttl: 400,
+  not_found: 404,
+  storage_error: 500,
+};
+
+const DONATION_STATUS: Record<DonationErrorCode, number> = {
+  unauthorized: 401,
+  forbidden: 403,
+  quota_exceeded: 429,
+  invalid_request: 400,
+  not_found: 404,
+  invalid_state: 409,
+  seed_failed: 502,
+  peer_unavailable: 503,
+  orchestrator_error: 500,
+  storage_error: 500,
+};
+
+const UPDATE_STATUS: Record<UpdateErrorCode, number> = {
+  manifest_invalid: 400,
+  no_update_available: 400,
+  min_previous_version: 400,
+  apply_in_progress: 409,
+  signature_invalid: 500,
+  unsupported_state_version: 500,
+  apply_failed: 500,
+  rollback_failed: 500,
+  storage_error: 500,
+};
+
+export function registerErrorHandler(app: FastifyInstance): void {
+  app.setErrorHandler((err: FastifyError, request: FastifyRequest, reply: FastifyReply) => {
+    const { status, code, message } = classify(err);
+    if (status >= 500) {
+      log('5xx %s %s: [%s] %s', request.method, request.url, code, message);
+    } else {
+      log('%d %s %s: [%s] %s', status, request.method, request.url, code, message);
+    }
+    return reply.code(status).send({
+      ok: false,
+      error: { code, message },
+    });
+  });
+}
+
+interface Classified {
+  status: number;
+  code: string;
+  message: string;
+}
+
+function classify(err: FastifyError): Classified {
+  if (err instanceof TrustCircleError) {
+    return { status: TRUST_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+  }
+  if (err instanceof NatError) {
+    return { status: NAT_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+  }
+  if (err instanceof StrandError) {
+    return { status: STRAND_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+  }
+  if (err instanceof UpdateErrorException) {
+    return { status: UPDATE_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+  }
+  if (err instanceof GrantError) {
+    return { status: GRANT_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+  }
+  if (err instanceof DonationError) {
+    return { status: DONATION_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+  }
+  // Fastify body-parsing / validation errors have a statusCode we should honour.
+  if (typeof err.statusCode === 'number' && err.statusCode >= 400 && err.statusCode < 600) {
+    return {
+      status: err.statusCode,
+      code: err.code ?? (err.statusCode === 404 ? 'not_found' : 'bad_request'),
+      message: err.message ?? 'request failed',
+    };
+  }
+  return { status: 500, code: 'internal', message: err.message || 'internal error' };
+}

package/src/server/events/bus.ts

@@ -1,42 +1,42 @@
-/**
- * In-memory event bus for the local UI.
- *
- * Tiny synchronous fan-out: publishers (route adapters, orchestrator hook,
- * update observer) call `publish`; SSE connections subscribe and receive every
- * event until they unsubscribe. Listener errors are caught so one broken
- * client cannot break others.
- */
-
-import debug from 'debug';
-
-import type { LocalUiEvent } from './types.js';
-
-const log = debug('cadre:host:event-bus');
-
-export type LocalUiEventListener = (event: LocalUiEvent) => void;
-
-export class EventBus {
-  private readonly listeners = new Set<LocalUiEventListener>();
-
-  publish(event: LocalUiEvent): void {
-    for (const listener of this.listeners) {
-      try {
-        listener(event);
-      } catch (err) {
-        log('listener threw for event %s: %s', event.type, (err as Error).message);
-      }
-    }
-  }
-
-  subscribe(listener: LocalUiEventListener): () => void {
-    this.listeners.add(listener);
-    return () => {
-      this.listeners.delete(listener);
-    };
-  }
-
-  /** Test helper. */
-  listenerCount(): number {
-    return this.listeners.size;
-  }
-}
+/**
+ * In-memory event bus for the local UI.
+ *
+ * Tiny synchronous fan-out: publishers (route adapters, orchestrator hook,
+ * update observer) call `publish`; SSE connections subscribe and receive every
+ * event until they unsubscribe. Listener errors are caught so one broken
+ * client cannot break others.
+ */
+
+import debug from 'debug';
+
+import type { LocalUiEvent } from './types.js';
+
+const log = debug('cadre:host:event-bus');
+
+export type LocalUiEventListener = (event: LocalUiEvent) => void;
+
+export class EventBus {
+  private readonly listeners = new Set<LocalUiEventListener>();
+
+  publish(event: LocalUiEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        log('listener threw for event %s: %s', event.type, (err as Error).message);
+      }
+    }
+  }
+
+  subscribe(listener: LocalUiEventListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Test helper. */
+  listenerCount(): number {
+    return this.listeners.size;
+  }
+}