@serfab/cadre-host 0.10.0 → 0.11.0

package/src/server/error-handler.ts

@@ -1,178 +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`, `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' };
-}
+/**
+ * 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;
+  }
+}

package/src/server/events/sse-route.ts

@@ -1,81 +1,81 @@
-/**
- * Server-Sent Events route — `GET /api/events`.
- *
- * Hand-rolled (~40 lines vs. the 30 KB @fastify/sse-v2 dep). The wire format:
- *
- *   retry: 5000\n\n          ← reconnect hint
- *   : heartbeat\n\n          ← comment line, every 15 s
- *   event: <type>\n          ← event name
- *   data: <json>\n\n         ← payload
- *
- * The handler subscribes to the bus on connect, unsubscribes on client
- * disconnect, and ticks a heartbeat so corporate proxies don't close the
- * connection at the idle timeout.
- */
-
-import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
-import debug from 'debug';
-
-import type { EventBus } from './bus.js';
-import type { LocalUiEvent } from './types.js';
-
-const log = debug('cadre:host:sse');
-
-const HEARTBEAT_INTERVAL_MS = 15_000;
-const RECONNECT_HINT_MS = 5_000;
-
-export interface SseRouteOptions {
-  events: EventBus;
-  /** Test override: shorter heartbeat. */
-  heartbeatIntervalMs?: number;
-}
-
-export function registerSseRoute(app: FastifyInstance, opts: SseRouteOptions): void {
-  const heartbeatMs = opts.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
-
-  app.get('/api/events', (request: FastifyRequest, reply: FastifyReply) => {
-    // Tell Fastify we're handling the reply ourselves — it won't try to
-    // serialise or send a payload.
-    reply.hijack();
-    reply.raw.writeHead(200, {
-      'Content-Type': 'text/event-stream',
-      'Cache-Control': 'no-cache, no-transform',
-      Connection: 'keep-alive',
-      'X-Accel-Buffering': 'no',
-    });
-    reply.raw.write(`retry: ${RECONNECT_HINT_MS}\n\n`);
-    reply.raw.write(`: connected\n\n`);
-
-    const onEvent = (event: LocalUiEvent): void => {
-      try {
-        reply.raw.write(`event: ${event.type}\n`);
-        reply.raw.write(`data: ${JSON.stringify(event)}\n\n`);
-      } catch (err) {
-        log('write failed (client likely gone): %s', (err as Error).message);
-      }
-    };
-    const unsubscribe = opts.events.subscribe(onEvent);
-
-    const heartbeat = setInterval(() => {
-      try {
-        reply.raw.write(`: heartbeat\n\n`);
-      } catch (err) {
-        log('heartbeat write failed: %s', (err as Error).message);
-      }
-    }, heartbeatMs);
-    // Don't hold the event loop open for the heartbeat alone.
-    if (typeof heartbeat === 'object' && 'unref' in heartbeat) {
-      (heartbeat as { unref?: () => void }).unref?.();
-    }
-
-    const cleanup = (): void => {
-      clearInterval(heartbeat);
-      unsubscribe();
-    };
-    request.raw.on('close', cleanup);
-    request.raw.on('error', cleanup);
-
-    // The reply object is intentionally not returned — Fastify must not
-    // attempt to serialise an SSE response.
-  });
-}
+/**
+ * Server-Sent Events route — `GET /api/events`.
+ *
+ * Hand-rolled (~40 lines vs. the 30 KB @fastify/sse-v2 dep). The wire format:
+ *
+ *   retry: 5000\n\n          ← reconnect hint
+ *   : heartbeat\n\n          ← comment line, every 15 s
+ *   event: <type>\n          ← event name
+ *   data: <json>\n\n         ← payload
+ *
+ * The handler subscribes to the bus on connect, unsubscribes on client
+ * disconnect, and ticks a heartbeat so corporate proxies don't close the
+ * connection at the idle timeout.
+ */
+
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import debug from 'debug';
+
+import type { EventBus } from './bus.js';
+import type { LocalUiEvent } from './types.js';
+
+const log = debug('cadre:host:sse');
+
+const HEARTBEAT_INTERVAL_MS = 15_000;
+const RECONNECT_HINT_MS = 5_000;
+
+export interface SseRouteOptions {
+  events: EventBus;
+  /** Test override: shorter heartbeat. */
+  heartbeatIntervalMs?: number;
+}
+
+export function registerSseRoute(app: FastifyInstance, opts: SseRouteOptions): void {
+  const heartbeatMs = opts.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
+
+  app.get('/api/events', (request: FastifyRequest, reply: FastifyReply) => {
+    // Tell Fastify we're handling the reply ourselves — it won't try to
+    // serialise or send a payload.
+    reply.hijack();
+    reply.raw.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    });
+    reply.raw.write(`retry: ${RECONNECT_HINT_MS}\n\n`);
+    reply.raw.write(`: connected\n\n`);
+
+    const onEvent = (event: LocalUiEvent): void => {
+      try {
+        reply.raw.write(`event: ${event.type}\n`);
+        reply.raw.write(`data: ${JSON.stringify(event)}\n\n`);
+      } catch (err) {
+        log('write failed (client likely gone): %s', (err as Error).message);
+      }
+    };
+    const unsubscribe = opts.events.subscribe(onEvent);
+
+    const heartbeat = setInterval(() => {
+      try {
+        reply.raw.write(`: heartbeat\n\n`);
+      } catch (err) {
+        log('heartbeat write failed: %s', (err as Error).message);
+      }
+    }, heartbeatMs);
+    // Don't hold the event loop open for the heartbeat alone.
+    if (typeof heartbeat === 'object' && 'unref' in heartbeat) {
+      (heartbeat as { unref?: () => void }).unref?.();
+    }
+
+    const cleanup = (): void => {
+      clearInterval(heartbeat);
+      unsubscribe();
+    };
+    request.raw.on('close', cleanup);
+    request.raw.on('error', cleanup);
+
+    // The reply object is intentionally not returned — Fastify must not
+    // attempt to serialise an SSE response.
+  });
+}

package/src/server/events/types.ts

@@ -1,23 +1,23 @@
-/**
- * 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: '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: 'connectivity-changed';
+      portMode: PortForwardMode;
+      directReachability: DirectReachability;
+    }
+  | { type: 'update-available'; version: string; releaseNotesUrl?: string };
+
+export type LocalUiEventType = LocalUiEvent['type'];