@serfab/cadre-host 0.10.0 → 0.12.0

package/src/server/routes/nodes.ts

@@ -1,170 +1,170 @@
-/**
- * /api/nodes — list managed cadre nodes, look up details, and control
- * lifecycle.
- *
- * Bus events for lifecycle transitions are emitted by the orchestrator's
- * `onStateChange` (forwarded by `createLocalUiServer.start`) — the route
- * handlers don't re-publish.
- *
- * start/restart are real for the admin's owner node (re-spawned from the
- * persisted `OwnerSpawnConfig`). Generic node lifecycle is owned by the
- * grantee-facing donation surface (`/grants`) — this route no longer spawns
- * generic nodes; start/restart of a known non-owner node points the caller
- * there. Stop works for any running node.
- */
-
-import { existsSync, openSync, readSync, closeSync, statSync } from 'node:fs';
-
-import type { FastifyInstance } from 'fastify';
-
-import type { HostProcessOrchestrator } from '../../orchestrator/index.js';
-import { defaultLogPath } from '../../orchestrator/log-rotator.js';
-
-const DEFAULT_LOG_LINES = 200;
-const MAX_LOG_LINES = 2000;
-
-export interface NodesRoutesOptions {
-  orchestrator: HostProcessOrchestrator;
-}
-
-export function registerNodesRoutes(app: FastifyInstance, opts: NodesRoutesOptions): void {
-  const { orchestrator } = opts;
-
-  app.get('/api/nodes', async () => {
-    return { ok: true, data: { nodes: orchestrator.listNodes() } };
-  });
-
-  app.get<{ Params: { id: string } }>('/api/nodes/:id', async (request, reply) => {
-    const node = orchestrator.getNode(request.params.id);
-    if (!node) {
-      return reply.code(404).send({
-        ok: false,
-        error: { code: 'not_found', message: `Unknown node: ${request.params.id}` },
-      });
-    }
-    let stats = null;
-    try {
-      stats = await orchestrator.getStats(node.dockerId);
-    } catch {
-      // Stats unavailable (dead process etc.) — surface null.
-    }
-    return { ok: true, data: { node, stats } };
-  });
-
-  app.get<{ Params: { id: string }; Querystring: { lines?: string } }>(
-    '/api/nodes/:id/logs',
-    async (request, reply) => {
-      const node = orchestrator.getNode(request.params.id);
-      if (!node) {
-        return reply.code(404).send({
-          ok: false,
-          error: { code: 'not_found', message: `Unknown node: ${request.params.id}` },
-        });
-      }
-      const requested = Number(request.query.lines ?? DEFAULT_LOG_LINES);
-      const tail = Number.isFinite(requested)
-        ? Math.max(1, Math.min(MAX_LOG_LINES, Math.floor(requested)))
-        : DEFAULT_LOG_LINES;
-      const lines = tailLogFile(defaultLogPath(node.workdir), tail);
-      return { ok: true, data: { lines } };
-    },
-  );
-
-  app.post<{ Params: { id: string } }>('/api/nodes/:id/stop', async (request, reply) => {
-    const dockerId = orchestrator.resolveDockerId(request.params.id);
-    if (!dockerId) {
-      return reply.code(404).send({
-        ok: false,
-        error: { code: 'not_found', message: `Unknown node: ${request.params.id}` },
-      });
-    }
-    await orchestrator.stopContainer(dockerId);
-    // The orchestrator emits its own onStateChange — createLocalUiServer
-    // forwards that to the bus. Don't double-publish here.
-    return { ok: true };
-  });
-
-  // start / restart: real for the admin's owner node (spawned from the
-  // persisted OwnerSpawnConfig). Generic node lifecycle now belongs to the
-  // donation surface (/grants) — those ids return a clear not_implemented that
-  // points there; unknown ids 404.
-  app.post<{ Params: { id: string } }>('/api/nodes/:id/start', async (request, reply) => {
-    const { id } = request.params;
-    if (orchestrator.isOwnerNode(id)) {
-      if (!orchestrator.hasOwnerConfig()) {
-        return notImplemented(reply, `start ${id}: owner node has no saved spawn config.`);
-      }
-      const node = await orchestrator.ensureOwnerNode();
-      return { ok: true, data: { node } };
-    }
-    return startRestartFallback(reply, orchestrator, id, 'start');
-  });
-
-  app.post<{ Params: { id: string } }>('/api/nodes/:id/restart', async (request, reply) => {
-    const { id } = request.params;
-    if (orchestrator.isOwnerNode(id)) {
-      if (!orchestrator.hasOwnerConfig()) {
-        return notImplemented(reply, `restart ${id}: owner node has no saved spawn config.`);
-      }
-      const node = await orchestrator.restartOwnerNode();
-      return { ok: true, data: { node } };
-    }
-    return startRestartFallback(reply, orchestrator, id, 'restart');
-  });
-}
-
-/** 404 for unknown ids; 501 not_implemented for known non-owner nodes. */
-function startRestartFallback(
-  reply: import('fastify').FastifyReply,
-  orchestrator: HostProcessOrchestrator,
-  id: string,
-  verb: string,
-) {
-  if (!orchestrator.getNode(id)) {
-    return reply.code(404).send({
-      ok: false,
-      error: { code: 'not_found', message: `Unknown node: ${id}` },
-    });
-  }
-  return notImplemented(
-    reply,
-    `${verb} ${id}: only the owner node is start/restart-able here; generic donated-node lifecycle is owned by the donation surface — use POST /grants to provision and DELETE /grants/:id to terminate.`,
-  );
-}
-
-function notImplemented(reply: import('fastify').FastifyReply, message: string) {
-  return reply.code(501).send({ ok: false, error: { code: 'not_implemented', message } });
-}
-
-/**
- * Read the last `n` lines from a log file by walking the tail in chunks.
- * Returns [] for a missing file.
- */
-export function tailLogFile(path: string, n: number): string[] {
-  if (!existsSync(path)) return [];
-  const fd = openSync(path, 'r');
-  try {
-    const size = statSync(path).size;
-    const chunkSize = 8192;
-    let pos = size;
-    const buffers: Buffer[] = [];
-    let newlineCount = 0;
-    while (pos > 0 && newlineCount <= n) {
-      const readLen = Math.min(chunkSize, pos);
-      pos -= readLen;
-      const buf = Buffer.alloc(readLen);
-      readSync(fd, buf, 0, readLen, pos);
-      buffers.unshift(buf);
-      for (let i = 0; i < buf.length; i++) {
-        if (buf[i] === 0x0a) newlineCount++;
-      }
-    }
-    const joined = Buffer.concat(buffers).toString('utf8');
-    const lines = joined.split('\n');
-    const trimmed = lines[lines.length - 1] === '' ? lines.slice(0, -1) : lines;
-    return trimmed.slice(-n);
-  } finally {
-    closeSync(fd);
-  }
-}
-
+/**
+ * /api/nodes — list managed cadre nodes, look up details, and control
+ * lifecycle.
+ *
+ * Bus events for lifecycle transitions are emitted by the orchestrator's
+ * `onStateChange` (forwarded by `createLocalUiServer.start`) — the route
+ * handlers don't re-publish.
+ *
+ * start/restart are real for the admin's owner node (re-spawned from the
+ * persisted `OwnerSpawnConfig`). Generic node lifecycle is owned by the
+ * grantee-facing donation surface (`/grants`) — this route no longer spawns
+ * generic nodes; start/restart of a known non-owner node points the caller
+ * there. Stop works for any running node.
+ */
+
+import { existsSync, openSync, readSync, closeSync, statSync } from 'node:fs';
+
+import type { FastifyInstance } from 'fastify';
+
+import type { HostProcessOrchestrator } from '../../orchestrator/index.js';
+import { defaultLogPath } from '../../orchestrator/log-rotator.js';
+
+const DEFAULT_LOG_LINES = 200;
+const MAX_LOG_LINES = 2000;
+
+export interface NodesRoutesOptions {
+  orchestrator: HostProcessOrchestrator;
+}
+
+export function registerNodesRoutes(app: FastifyInstance, opts: NodesRoutesOptions): void {
+  const { orchestrator } = opts;
+
+  app.get('/api/nodes', async () => {
+    return { ok: true, data: { nodes: orchestrator.listNodes() } };
+  });
+
+  app.get<{ Params: { id: string } }>('/api/nodes/:id', async (request, reply) => {
+    const node = orchestrator.getNode(request.params.id);
+    if (!node) {
+      return reply.code(404).send({
+        ok: false,
+        error: { code: 'not_found', message: `Unknown node: ${request.params.id}` },
+      });
+    }
+    let stats = null;
+    try {
+      stats = await orchestrator.getStats(node.dockerId);
+    } catch {
+      // Stats unavailable (dead process etc.) — surface null.
+    }
+    return { ok: true, data: { node, stats } };
+  });
+
+  app.get<{ Params: { id: string }; Querystring: { lines?: string } }>(
+    '/api/nodes/:id/logs',
+    async (request, reply) => {
+      const node = orchestrator.getNode(request.params.id);
+      if (!node) {
+        return reply.code(404).send({
+          ok: false,
+          error: { code: 'not_found', message: `Unknown node: ${request.params.id}` },
+        });
+      }
+      const requested = Number(request.query.lines ?? DEFAULT_LOG_LINES);
+      const tail = Number.isFinite(requested)
+        ? Math.max(1, Math.min(MAX_LOG_LINES, Math.floor(requested)))
+        : DEFAULT_LOG_LINES;
+      const lines = tailLogFile(defaultLogPath(node.workdir), tail);
+      return { ok: true, data: { lines } };
+    },
+  );
+
+  app.post<{ Params: { id: string } }>('/api/nodes/:id/stop', async (request, reply) => {
+    const dockerId = orchestrator.resolveDockerId(request.params.id);
+    if (!dockerId) {
+      return reply.code(404).send({
+        ok: false,
+        error: { code: 'not_found', message: `Unknown node: ${request.params.id}` },
+      });
+    }
+    await orchestrator.stopContainer(dockerId);
+    // The orchestrator emits its own onStateChange — createLocalUiServer
+    // forwards that to the bus. Don't double-publish here.
+    return { ok: true };
+  });
+
+  // start / restart: real for the admin's owner node (spawned from the
+  // persisted OwnerSpawnConfig). Generic node lifecycle now belongs to the
+  // donation surface (/grants) — those ids return a clear not_implemented that
+  // points there; unknown ids 404.
+  app.post<{ Params: { id: string } }>('/api/nodes/:id/start', async (request, reply) => {
+    const { id } = request.params;
+    if (orchestrator.isOwnerNode(id)) {
+      if (!orchestrator.hasOwnerConfig()) {
+        return notImplemented(reply, `start ${id}: owner node has no saved spawn config.`);
+      }
+      const node = await orchestrator.ensureOwnerNode();
+      return { ok: true, data: { node } };
+    }
+    return startRestartFallback(reply, orchestrator, id, 'start');
+  });
+
+  app.post<{ Params: { id: string } }>('/api/nodes/:id/restart', async (request, reply) => {
+    const { id } = request.params;
+    if (orchestrator.isOwnerNode(id)) {
+      if (!orchestrator.hasOwnerConfig()) {
+        return notImplemented(reply, `restart ${id}: owner node has no saved spawn config.`);
+      }
+      const node = await orchestrator.restartOwnerNode();
+      return { ok: true, data: { node } };
+    }
+    return startRestartFallback(reply, orchestrator, id, 'restart');
+  });
+}
+
+/** 404 for unknown ids; 501 not_implemented for known non-owner nodes. */
+function startRestartFallback(
+  reply: import('fastify').FastifyReply,
+  orchestrator: HostProcessOrchestrator,
+  id: string,
+  verb: string,
+) {
+  if (!orchestrator.getNode(id)) {
+    return reply.code(404).send({
+      ok: false,
+      error: { code: 'not_found', message: `Unknown node: ${id}` },
+    });
+  }
+  return notImplemented(
+    reply,
+    `${verb} ${id}: only the owner node is start/restart-able here; generic donated-node lifecycle is owned by the donation surface — use POST /grants to provision and DELETE /grants/:id to terminate.`,
+  );
+}
+
+function notImplemented(reply: import('fastify').FastifyReply, message: string) {
+  return reply.code(501).send({ ok: false, error: { code: 'not_implemented', message } });
+}
+
+/**
+ * Read the last `n` lines from a log file by walking the tail in chunks.
+ * Returns [] for a missing file.
+ */
+export function tailLogFile(path: string, n: number): string[] {
+  if (!existsSync(path)) return [];
+  const fd = openSync(path, 'r');
+  try {
+    const size = statSync(path).size;
+    const chunkSize = 8192;
+    let pos = size;
+    const buffers: Buffer[] = [];
+    let newlineCount = 0;
+    while (pos > 0 && newlineCount <= n) {
+      const readLen = Math.min(chunkSize, pos);
+      pos -= readLen;
+      const buf = Buffer.alloc(readLen);
+      readSync(fd, buf, 0, readLen, pos);
+      buffers.unshift(buf);
+      for (let i = 0; i < buf.length; i++) {
+        if (buf[i] === 0x0a) newlineCount++;
+      }
+    }
+    const joined = Buffer.concat(buffers).toString('utf8');
+    const lines = joined.split('\n');
+    const trimmed = lines[lines.length - 1] === '' ? lines.slice(0, -1) : lines;
+    return trimmed.slice(-n);
+  } finally {
+    closeSync(fd);
+  }
+}
+

package/src/server/routes/settings.ts

@@ -1,123 +1,123 @@
-/**
- * /api/settings — host-level settings UI surface.
- *
- * The persisted shape is `host.config.json` (managed by the installer).
- * This route is a thin passthrough plus a write-whitelist:
- *
- *   - uiPort        rejected (restart required; only edit at install time)
- *   - libp2pPort    rejected (restart required)
- *   - upnpEnabled   accepted → also propagated to NatService.putSettings
- *   - updates.autoApply  accepted → propagated to UpdateService.putSettings
- *   - updates.manifestUrl accepted → propagated to UpdateService.putSettings
- *   - anything else 400 invalid_setting
- *
- * GET returns the full `HostConfigFile` (the SPA wants the full shape so it
- * can render a read-only view of the rejected keys).
- */
-
-import type { FastifyInstance } from 'fastify';
-
-import type { NatService } from '../../nat/index.js';
-import type { UpdateService } from '../../update/index.js';
-import type { HostSettingsStore } from '../settings-store.js';
-
-const FORBIDDEN_KEYS = new Set<string>(['uiPort', 'libp2pPort', 'dataDir', 'identityPath', 'installId', 'installedAt', 'installerVersion', 'version', 'ownCadre']);
-
-const WRITABLE_TOP_KEYS = new Set<string>(['upnpEnabled', 'updates']);
-const WRITABLE_UPDATES_KEYS = new Set<string>(['autoApply', 'manifestUrl']);
-
-export interface SettingsRoutesOptions {
-  settingsStore: HostSettingsStore;
-  /**
-   * Present only when the host runs its own personal cadre. In donor-only mode
-   * an `upnpEnabled` write still persists to host.config.json but has no running
-   * NatService to propagate into.
-   */
-  nat?: NatService;
-  update?: UpdateService;
-}
-
-export function registerSettingsRoutes(app: FastifyInstance, opts: SettingsRoutesOptions): void {
-  const { settingsStore, nat, update } = opts;
-
-  app.get('/api/settings', async () => {
-    return { ok: true, data: settingsStore.read() };
-  });
-
-  app.put('/api/settings', async (request, reply) => {
-    const body = (request.body ?? {}) as Record<string, unknown>;
-    const validation = validatePatch(body);
-    if (validation.error) {
-      return reply.code(400).send({
-        ok: false,
-        error: { code: 'invalid_setting', message: validation.error },
-      });
-    }
-
-    const current = settingsStore.read();
-    const patch: { upnpEnabled?: boolean; updates?: typeof current.updates } = {};
-
-    if ('upnpEnabled' in body) {
-      patch.upnpEnabled = body.upnpEnabled as boolean;
-      // Propagate UPnP toggle into the running NatService so the change
-      // takes effect immediately. NatService persists into nat.json — that's
-      // independent of host.config.json's `upnpEnabled` (which the installer
-      // uses on first run to seed nat.json). Update both for consistency.
-      // In donor-only mode there is no NatService — the write still persists.
-      if (nat) {
-        await nat.putSettings({ upnpEnabled: body.upnpEnabled as boolean });
-      }
-    }
-    if ('updates' in body) {
-      const updates = body.updates as { autoApply?: boolean; manifestUrl?: string };
-      const nextUpdates = { ...current.updates };
-      if ('autoApply' in updates) nextUpdates.autoApply = updates.autoApply as boolean;
-      if ('manifestUrl' in updates) nextUpdates.manifestUrl = updates.manifestUrl as string;
-      patch.updates = nextUpdates;
-      if (update) {
-        const propagate: { autoApply?: boolean; manifestUrl?: string } = {};
-        if ('autoApply' in updates) propagate.autoApply = updates.autoApply as boolean;
-        if ('manifestUrl' in updates) propagate.manifestUrl = updates.manifestUrl as string;
-        await update.putSettings(propagate);
-      }
-    }
-
-    const next = settingsStore.update(patch);
-    return { ok: true, data: next };
-  });
-}
-
-function validatePatch(body: Record<string, unknown>): { error?: string } {
-  for (const key of Object.keys(body)) {
-    if (FORBIDDEN_KEYS.has(key)) {
-      return { error: `Setting "${key}" is not editable at runtime; change it in host.config.json and restart cadre-host.` };
-    }
-    if (!WRITABLE_TOP_KEYS.has(key)) {
-      return { error: `Unknown setting "${key}"` };
-    }
-  }
-  if ('upnpEnabled' in body && typeof body.upnpEnabled !== 'boolean') {
-    return { error: '"upnpEnabled" must be a boolean' };
-  }
-  if ('updates' in body) {
-    if (!body.updates || typeof body.updates !== 'object') {
-      return { error: '"updates" must be an object' };
-    }
-    const updates = body.updates as Record<string, unknown>;
-    for (const key of Object.keys(updates)) {
-      if (!WRITABLE_UPDATES_KEYS.has(key)) {
-        return { error: `Unknown setting "updates.${key}"` };
-      }
-    }
-    if ('autoApply' in updates && typeof updates.autoApply !== 'boolean') {
-      return { error: '"updates.autoApply" must be a boolean' };
-    }
-    if (
-      'manifestUrl' in updates &&
-      typeof updates.manifestUrl !== 'string'
-    ) {
-      return { error: '"updates.manifestUrl" must be a string' };
-    }
-  }
-  return {};
-}
+/**
+ * /api/settings — host-level settings UI surface.
+ *
+ * The persisted shape is `host.config.json` (managed by the installer).
+ * This route is a thin passthrough plus a write-whitelist:
+ *
+ *   - uiPort        rejected (restart required; only edit at install time)
+ *   - libp2pPort    rejected (restart required)
+ *   - upnpEnabled   accepted → also propagated to NatService.putSettings
+ *   - updates.autoApply  accepted → propagated to UpdateService.putSettings
+ *   - updates.manifestUrl accepted → propagated to UpdateService.putSettings
+ *   - anything else 400 invalid_setting
+ *
+ * GET returns the full `HostConfigFile` (the SPA wants the full shape so it
+ * can render a read-only view of the rejected keys).
+ */
+
+import type { FastifyInstance } from 'fastify';
+
+import type { NatService } from '../../nat/index.js';
+import type { UpdateService } from '../../update/index.js';
+import type { HostSettingsStore } from '../settings-store.js';
+
+const FORBIDDEN_KEYS = new Set<string>(['uiPort', 'libp2pPort', 'dataDir', 'identityPath', 'installId', 'installedAt', 'installerVersion', 'version', 'ownCadre']);
+
+const WRITABLE_TOP_KEYS = new Set<string>(['upnpEnabled', 'updates']);
+const WRITABLE_UPDATES_KEYS = new Set<string>(['autoApply', 'manifestUrl']);
+
+export interface SettingsRoutesOptions {
+  settingsStore: HostSettingsStore;
+  /**
+   * Present only when the host runs its own personal cadre. In donor-only mode
+   * an `upnpEnabled` write still persists to host.config.json but has no running
+   * NatService to propagate into.
+   */
+  nat?: NatService;
+  update?: UpdateService;
+}
+
+export function registerSettingsRoutes(app: FastifyInstance, opts: SettingsRoutesOptions): void {
+  const { settingsStore, nat, update } = opts;
+
+  app.get('/api/settings', async () => {
+    return { ok: true, data: settingsStore.read() };
+  });
+
+  app.put('/api/settings', async (request, reply) => {
+    const body = (request.body ?? {}) as Record<string, unknown>;
+    const validation = validatePatch(body);
+    if (validation.error) {
+      return reply.code(400).send({
+        ok: false,
+        error: { code: 'invalid_setting', message: validation.error },
+      });
+    }
+
+    const current = settingsStore.read();
+    const patch: { upnpEnabled?: boolean; updates?: typeof current.updates } = {};
+
+    if ('upnpEnabled' in body) {
+      patch.upnpEnabled = body.upnpEnabled as boolean;
+      // Propagate UPnP toggle into the running NatService so the change
+      // takes effect immediately. NatService persists into nat.json — that's
+      // independent of host.config.json's `upnpEnabled` (which the installer
+      // uses on first run to seed nat.json). Update both for consistency.
+      // In donor-only mode there is no NatService — the write still persists.
+      if (nat) {
+        await nat.putSettings({ upnpEnabled: body.upnpEnabled as boolean });
+      }
+    }
+    if ('updates' in body) {
+      const updates = body.updates as { autoApply?: boolean; manifestUrl?: string };
+      const nextUpdates = { ...current.updates };
+      if ('autoApply' in updates) nextUpdates.autoApply = updates.autoApply as boolean;
+      if ('manifestUrl' in updates) nextUpdates.manifestUrl = updates.manifestUrl as string;
+      patch.updates = nextUpdates;
+      if (update) {
+        const propagate: { autoApply?: boolean; manifestUrl?: string } = {};
+        if ('autoApply' in updates) propagate.autoApply = updates.autoApply as boolean;
+        if ('manifestUrl' in updates) propagate.manifestUrl = updates.manifestUrl as string;
+        await update.putSettings(propagate);
+      }
+    }
+
+    const next = settingsStore.update(patch);
+    return { ok: true, data: next };
+  });
+}
+
+function validatePatch(body: Record<string, unknown>): { error?: string } {
+  for (const key of Object.keys(body)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      return { error: `Setting "${key}" is not editable at runtime; change it in host.config.json and restart cadre-host.` };
+    }
+    if (!WRITABLE_TOP_KEYS.has(key)) {
+      return { error: `Unknown setting "${key}"` };
+    }
+  }
+  if ('upnpEnabled' in body && typeof body.upnpEnabled !== 'boolean') {
+    return { error: '"upnpEnabled" must be a boolean' };
+  }
+  if ('updates' in body) {
+    if (!body.updates || typeof body.updates !== 'object') {
+      return { error: '"updates" must be an object' };
+    }
+    const updates = body.updates as Record<string, unknown>;
+    for (const key of Object.keys(updates)) {
+      if (!WRITABLE_UPDATES_KEYS.has(key)) {
+        return { error: `Unknown setting "updates.${key}"` };
+      }
+    }
+    if ('autoApply' in updates && typeof updates.autoApply !== 'boolean') {
+      return { error: '"updates.autoApply" must be a boolean' };
+    }
+    if (
+      'manifestUrl' in updates &&
+      typeof updates.manifestUrl !== 'string'
+    ) {
+      return { error: '"updates.manifestUrl" must be a string' };
+    }
+  }
+  return {};
+}