@serfab/cadre-host 0.9.0 → 0.11.0

package/src/strands/strand-service.ts

@@ -0,0 +1,135 @@
+import debug from 'debug';
+
+import { OwnerNodeUnavailableError } from '../owner/owner-node-client.js';
+
+import type {
+  StrandHandlers,
+  StrandListSnapshot,
+  StrandRemovalResult,
+} from './types.js';
+import { StrandError } from './types.js';
+
+const log = debug('cadre:host:strands');
+
+/**
+ * Minimal slice of the owner node that StrandService uses. Declared here (rather
+ * than reaching into `OwnerNodeClient`) so unit tests can inject a fake without
+ * standing up an admin channel — the third such trimmed interface the client
+ * satisfies, alongside the trust-circle and NAT ones.
+ */
+export interface CadreNodeLike {
+  listStrands(): Promise<StrandListSnapshot>;
+  removeStrand(strandId: string, opts: { confirm: boolean }): Promise<StrandRemovalResult>;
+}
+
+/** Constructor options. */
+export interface StrandServiceOptions {
+  /** The owner node — provides listStrands / removeStrand over the admin channel. */
+  cadreNode: CadreNodeLike;
+}
+
+/**
+ * StrandService — validation and error translation over the owner node's strand
+ * admin routes.
+ *
+ * It owns no state and makes no policy. In particular it does NOT decide whether a
+ * closed strand needs confirmation: it never reads the row, so it could only guess.
+ * The node enforces that rule and answers `confirmation_required`; this layer
+ * forwards the caller's flag verbatim and surfaces the refusal as a distinct code
+ * so the UI can raise the right dialog.
+ */
+export class StrandService {
+  private readonly cadreNode: CadreNodeLike;
+
+  constructor(opts: StrandServiceOptions) {
+    this.cadreNode = opts.cadreNode;
+  }
+
+  /** This party's strands, plus the node's current control-connection count. */
+  async list(): Promise<StrandListSnapshot> {
+    return await this.cadreNode.listStrands().catch((err: unknown) => toDomainError(err));
+  }
+
+  /**
+   * Remove this party's participation in one strand.
+   *
+   * `confirm` is forwarded exactly as given — never defaulted to true, never
+   * re-sent as true after a refusal. A closed strand's row carries this party's
+   * membership key for that network and is stored nowhere else, so an automatic
+   * retry would destroy it on the caller's behalf.
+   */
+  async remove(rawId: string, opts: { confirm: boolean }): Promise<StrandRemovalResult> {
+    const strandId = validateStrandId(rawId);
+    log('remove %s (confirm=%s)', strandId, opts.confirm);
+    return await this.cadreNode
+      .removeStrand(strandId, { confirm: opts.confirm })
+      .catch((err: unknown) => toDomainError(err));
+  }
+}
+
+/**
+ * Trim and reject an id this surface cannot act on. Blank is the only such id.
+ *
+ * A `/` is deliberately NOT refused. `/api/strands/:id` is one path segment, but a
+ * caller that percent-encodes the id reaches this layer with the `/` restored
+ * (Fastify decodes `params`), `OwnerNodeClient` re-encodes it, and the admin channel
+ * splits on the still-encoded `%2F` and decodes it back — so the whole chain carries
+ * it. Refusing here would break the only form that works, while doing nothing about
+ * an UNencoded `/`, which never reaches this handler at all (the router 404s it).
+ */
+function validateStrandId(rawId: string): string {
+  const strandId = typeof rawId === 'string' ? rawId.trim() : '';
+  if (!strandId) {
+    throw new StrandError('invalid_id', 'A strand id is required');
+  }
+  return strandId;
+}
+
+/**
+ * Translate an owner-node failure into the strand error vocabulary.
+ *
+ * `OwnerNodeUnavailableError` is thrown for *every* non-ok admin response, not only
+ * for a node that is down — so read `nodeCode` first and fall back to
+ * `node_unavailable` only when nothing better fits. Reporting a 428 as "your node is
+ * down" would be actively misleading.
+ *
+ * Declared to return `never` so callers can `.catch((err) => toDomainError(err))`.
+ *
+ * NOTE: the trust-circle and NAT services translate the SAME error blanket-style —
+ * every `OwnerNodeUnavailableError` becomes `node_unavailable` — because neither has
+ * a code worth distinguishing yet. If a second surface ever needs a code-aware
+ * mapping, hoist this switch into a shared owner-error translator instead of growing
+ * a third copy.
+ */
+function toDomainError(err: unknown): never {
+  if (!(err instanceof OwnerNodeUnavailableError)) {
+    throw err instanceof Error ? err : new Error(String(err));
+  }
+  switch (err.nodeCode) {
+    case 'confirmation_required':
+      throw new StrandError('confirmation_required', err.message);
+    case 'bad_request':
+      throw new StrandError('invalid_id', err.message);
+    case undefined:
+    case 'not_ready':
+    case 'not_authorized':
+      throw new StrandError('node_unavailable', `Owner node unavailable: ${err.message}`);
+    default:
+      throw new StrandError('internal', err.message);
+  }
+}
+
+/**
+ * Wrap a StrandService into the typed handler shape the local UI server mounts.
+ * Errors propagate as StrandError; `server/error-handler.ts` maps `.code` → status.
+ */
+export function createStrandHandlers(service: StrandService): StrandHandlers {
+  return {
+    async listStrands() {
+      return await service.list();
+    },
+    async removeStrand(strandId, opts) {
+      return await service.remove(strandId, { confirm: opts.confirm === true });
+    },
+  };
+}

package/src/strands/types.ts

@@ -0,0 +1,102 @@
+/**
+ * Strand-management types for cadre-host.
+ *
+ * A *strand* is a shared data network this party participates in. Membership is
+ * canonical in the cadre control network's `Strand` table, reached over the owner
+ * node's loopback admin channel (`GET /admin/strands`,
+ * `DELETE /admin/strands/:id?confirm=1`).
+ *
+ * Unlike the trust circle — which layers host-local labels and pending invites on
+ * top of the node's state — this layer holds **no host-local state at all**. There
+ * is no `strands.json`. It exists for id validation, for translating the admin
+ * channel's error codes into a stable vocabulary the management API can map to HTTP
+ * statuses, and for nothing else. Keep it small.
+ */
+
+/** One strand this party belongs to, as projected by the admin channel. */
+export interface StrandSummary {
+  /** The `Strand` row id — what a removal takes. */
+  id: string;
+  /** `'o'` = open, `'c'` = closed (the row carries this party's membership key). */
+  type: 'o' | 'c';
+  /** Whether the owner node currently has a running instance for the id. */
+  running: boolean;
+  /**
+   * The instance's status when running, else `null`. Deliberately `string` rather
+   * than cadre-core's `StrandStatus`: this is a wire projection the manager only
+   * forwards, and widening it keeps cadre-host from tracking a cadre-core union it
+   * never inspects.
+   */
+  status: string | null;
+}
+
+/** The result of listing this party's strands. */
+export interface StrandListSnapshot {
+  strands: StrandSummary[];
+  /**
+   * Open control-network connections on the owner node; 0 ⇒ writes commit
+   * local-only. A snapshot at read time, not a subscription — treat it as advisory.
+   */
+  controlConnections: number;
+}
+
+/** The result of removing this party's participation in one strand. */
+export interface StrandRemovalResult {
+  /** The trimmed id the call was about. */
+  strandId: string;
+  /** Whether a row existed before the write. */
+  published: boolean;
+  /** The found row's type; `null` when no row was found. */
+  type: 'o' | 'c' | null;
+  /**
+   * Whether THIS call issued the delete — not that the row was observed to vanish.
+   * The node's read and write are not atomic, so a concurrent removal landing in
+   * between makes this a no-op that still reports `true`.
+   */
+  removed: boolean;
+  /**
+   * The node saw 0 control connections at the end of the call. Sampled on EVERY
+   * call, including one that found no row and wrote nothing — read it as "this
+   * machine currently sees no siblings", and only as "your delete may not have
+   * travelled" when `removed` is also true.
+   */
+  alone: boolean;
+}
+
+/** Error codes thrown by StrandService. */
+export type StrandErrorCode =
+  /** The id was blank or whitespace-only, here or at the node. */
+  | 'invalid_id'
+  /** The node refused a closed-strand removal that carried no confirmation. */
+  | 'confirmation_required'
+  /** The owner node's admin channel is unreachable / not ready. */
+  | 'node_unavailable'
+  /** The node answered with a code this layer has no better word for. */
+  | 'internal';
+
+/** Typed error carrying a stable `code` for HTTP mapping. */
+export class StrandError extends Error {
+  readonly code: StrandErrorCode;
+
+  constructor(code: StrandErrorCode, message: string) {
+    super(message);
+    this.name = 'StrandError';
+    this.code = code;
+  }
+}
+
+/**
+ * Typed handlers exposed to the local UI server for Fastify wiring.
+ *
+ * Handlers either return typed results or throw a `StrandError` whose `.code`
+ * `server/error-handler.ts` maps to an HTTP status:
+ *
+ *   - `invalid_id`            → 400
+ *   - `confirmation_required` → 428
+ *   - `node_unavailable`      → 503
+ *   - `internal`              → 500
+ */
+export interface StrandHandlers {
+  listStrands(): Promise<StrandListSnapshot>;
+  removeStrand(strandId: string, opts: { confirm: boolean }): Promise<StrandRemovalResult>;
+}

package/src/update/__tests__/apply.test.ts

@@ -1,158 +1,158 @@
-import { describe, expect, it } from 'vitest';
-
-import { applyUpdate, buildNpmSpawnSpec, quoteWindowsArg, type NpmExecutor, type NpmResult } from '../apply.js';
-import { UpdateErrorException } from '../types.js';
-
-function recordingExecutor(responses: NpmResult[]): { exec: NpmExecutor; calls: string[][] } {
-  const calls: string[][] = [];
-  let i = 0;
-  return {
-    calls,
-    async exec(args) {
-      calls.push(args);
-      const res = responses[i++] ?? { exitCode: 0, stdout: '', stderr: '' };
-      return res;
-    },
-  };
-}
-
-describe('applyUpdate', () => {
-  it('happy path: install succeeds, restart called', async () => {
-    const { exec, calls } = recordingExecutor([{ exitCode: 0, stdout: 'ok', stderr: '' }]);
-    let restartCount = 0;
-    const result = await applyUpdate({
-      npmPackage: '@serfab/cadre-host',
-      fromVersion: '0.6.0',
-      toVersion: '0.7.0',
-      npmExecutor: exec,
-      restart: async () => { restartCount++; return undefined; },
-    });
-    expect(calls).toEqual([['install', '-g', '@serfab/cadre-host@0.7.0']]);
-    expect(restartCount).toBe(1);
-    expect(result).toMatchObject({ fromVersion: '0.6.0', toVersion: '0.7.0', restarted: true });
-  });
-
-  it('install succeeds but restart fails: result reports restartError, no throw', async () => {
-    const { exec } = recordingExecutor([{ exitCode: 0, stdout: 'ok', stderr: '' }]);
-    const result = await applyUpdate({
-      npmPackage: '@serfab/cadre-host',
-      fromVersion: '0.6.0',
-      toVersion: '0.7.0',
-      npmExecutor: exec,
-      restart: async () => 'systemctl returned 1',
-    });
-    expect(result.restarted).toBe(false);
-    expect(result.restartError).toBe('systemctl returned 1');
-  });
-
-  it('install fails: rollback invoked, restart NOT called, throws apply_failed', async () => {
-    const { exec, calls } = recordingExecutor([
-      { exitCode: 1, stdout: '', stderr: 'EACCES' },
-      { exitCode: 0, stdout: 'rolled back', stderr: '' },
-    ]);
-    let restartCount = 0;
-    await expect(applyUpdate({
-      npmPackage: '@serfab/cadre-host',
-      fromVersion: '0.6.0',
-      toVersion: '0.7.0',
-      npmExecutor: exec,
-      restart: async () => { restartCount++; return undefined; },
-    })).rejects.toBeInstanceOf(UpdateErrorException);
-    expect(calls).toEqual([
-      ['install', '-g', '@serfab/cadre-host@0.7.0'],
-      ['install', '-g', '@serfab/cadre-host@0.6.0'],
-    ]);
-    expect(restartCount).toBe(0);
-  });
-
-  it('install fails and rollback also fails: throws rollback_failed', async () => {
-    const { exec } = recordingExecutor([
-      { exitCode: 1, stdout: '', stderr: 'EACCES' },
-      { exitCode: 1, stdout: '', stderr: 'EACCES on rollback' },
-    ]);
-    await expect(applyUpdate({
-      npmPackage: '@serfab/cadre-host',
-      fromVersion: '0.6.0',
-      toVersion: '0.7.0',
-      npmExecutor: exec,
-    })).rejects.toMatchObject({ code: 'rollback_failed' });
-  });
-
-  it('install throws (spawn error): rollback still attempted', async () => {
-    let i = 0;
-    const calls: string[][] = [];
-    const exec: NpmExecutor = async (args) => {
-      calls.push(args);
-      i++;
-      if (i === 1) throw new Error('ENOENT npm');
-      return { exitCode: 0, stdout: '', stderr: '' };
-    };
-    await expect(applyUpdate({
-      npmPackage: '@serfab/cadre-host',
-      fromVersion: '0.6.0',
-      toVersion: '0.7.0',
-      npmExecutor: exec,
-    })).rejects.toMatchObject({ code: 'apply_failed' });
-    expect(calls).toEqual([
-      ['install', '-g', '@serfab/cadre-host@0.7.0'],
-      ['install', '-g', '@serfab/cadre-host@0.6.0'],
-    ]);
-  });
-});
-
-describe('quoteWindowsArg', () => {
-  it('leaves safe args untouched', () => {
-    expect(quoteWindowsArg('install')).toBe('install');
-    expect(quoteWindowsArg('-g')).toBe('-g');
-    expect(quoteWindowsArg('@serfab/cadre-host@0.7.0')).toBe('@serfab/cadre-host@0.7.0');
-  });
-
-  it('quotes args containing whitespace or shell metachars', () => {
-    expect(quoteWindowsArg('has space')).toBe('"has space"');
-    expect(quoteWindowsArg('with&amp')).toBe('"with&amp"');
-    expect(quoteWindowsArg('pipe|me')).toBe('"pipe|me"');
-  });
-
-  it('escapes embedded quotes and trailing backslashes', () => {
-    expect(quoteWindowsArg('with"quote')).toBe('"with\\"quote"');
-    expect(quoteWindowsArg('trailing\\')).toBe('trailing\\');
-    expect(quoteWindowsArg('trail ing\\')).toBe('"trail ing\\\\"');
-  });
-
-  it('rejects control characters', () => {
-    expect(() => quoteWindowsArg('bad\nnewline')).toThrow(/control character/);
-    expect(() => quoteWindowsArg('bad\x00null')).toThrow(/control character/);
-  });
-});
-
-describe('buildNpmSpawnSpec', () => {
-  it('builds a single-string command with empty args on Windows', () => {
-    const original = process.platform;
-    Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
-    try {
-      const spec = buildNpmSpawnSpec(['install', '-g', '@serfab/cadre-host@0.7.0']);
-      expect(spec).toEqual({
-        command: 'npm install -g @serfab/cadre-host@0.7.0',
-        args: [],
-        shell: true,
-      });
-    } finally {
-      Object.defineProperty(process, 'platform', { value: original, configurable: true });
-    }
-  });
-
-  it('passes args through verbatim on posix (no shell)', () => {
-    const original = process.platform;
-    Object.defineProperty(process, 'platform', { value: 'linux', configurable: true });
-    try {
-      const spec = buildNpmSpawnSpec(['install', '-g', '@serfab/cadre-host@0.7.0']);
-      expect(spec).toEqual({
-        command: 'npm',
-        args: ['install', '-g', '@serfab/cadre-host@0.7.0'],
-        shell: false,
-      });
-    } finally {
-      Object.defineProperty(process, 'platform', { value: original, configurable: true });
-    }
-  });
-});
+import { describe, expect, it } from 'vitest';
+
+import { applyUpdate, buildNpmSpawnSpec, quoteWindowsArg, type NpmExecutor, type NpmResult } from '../apply.js';
+import { UpdateErrorException } from '../types.js';
+
+function recordingExecutor(responses: NpmResult[]): { exec: NpmExecutor; calls: string[][] } {
+  const calls: string[][] = [];
+  let i = 0;
+  return {
+    calls,
+    async exec(args) {
+      calls.push(args);
+      const res = responses[i++] ?? { exitCode: 0, stdout: '', stderr: '' };
+      return res;
+    },
+  };
+}
+
+describe('applyUpdate', () => {
+  it('happy path: install succeeds, restart called', async () => {
+    const { exec, calls } = recordingExecutor([{ exitCode: 0, stdout: 'ok', stderr: '' }]);
+    let restartCount = 0;
+    const result = await applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+      restart: async () => { restartCount++; return undefined; },
+    });
+    expect(calls).toEqual([['install', '-g', '@serfab/cadre-host@0.7.0']]);
+    expect(restartCount).toBe(1);
+    expect(result).toMatchObject({ fromVersion: '0.6.0', toVersion: '0.7.0', restarted: true });
+  });
+
+  it('install succeeds but restart fails: result reports restartError, no throw', async () => {
+    const { exec } = recordingExecutor([{ exitCode: 0, stdout: 'ok', stderr: '' }]);
+    const result = await applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+      restart: async () => 'systemctl returned 1',
+    });
+    expect(result.restarted).toBe(false);
+    expect(result.restartError).toBe('systemctl returned 1');
+  });
+
+  it('install fails: rollback invoked, restart NOT called, throws apply_failed', async () => {
+    const { exec, calls } = recordingExecutor([
+      { exitCode: 1, stdout: '', stderr: 'EACCES' },
+      { exitCode: 0, stdout: 'rolled back', stderr: '' },
+    ]);
+    let restartCount = 0;
+    await expect(applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+      restart: async () => { restartCount++; return undefined; },
+    })).rejects.toBeInstanceOf(UpdateErrorException);
+    expect(calls).toEqual([
+      ['install', '-g', '@serfab/cadre-host@0.7.0'],
+      ['install', '-g', '@serfab/cadre-host@0.6.0'],
+    ]);
+    expect(restartCount).toBe(0);
+  });
+
+  it('install fails and rollback also fails: throws rollback_failed', async () => {
+    const { exec } = recordingExecutor([
+      { exitCode: 1, stdout: '', stderr: 'EACCES' },
+      { exitCode: 1, stdout: '', stderr: 'EACCES on rollback' },
+    ]);
+    await expect(applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+    })).rejects.toMatchObject({ code: 'rollback_failed' });
+  });
+
+  it('install throws (spawn error): rollback still attempted', async () => {
+    let i = 0;
+    const calls: string[][] = [];
+    const exec: NpmExecutor = async (args) => {
+      calls.push(args);
+      i++;
+      if (i === 1) throw new Error('ENOENT npm');
+      return { exitCode: 0, stdout: '', stderr: '' };
+    };
+    await expect(applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+    })).rejects.toMatchObject({ code: 'apply_failed' });
+    expect(calls).toEqual([
+      ['install', '-g', '@serfab/cadre-host@0.7.0'],
+      ['install', '-g', '@serfab/cadre-host@0.6.0'],
+    ]);
+  });
+});
+
+describe('quoteWindowsArg', () => {
+  it('leaves safe args untouched', () => {
+    expect(quoteWindowsArg('install')).toBe('install');
+    expect(quoteWindowsArg('-g')).toBe('-g');
+    expect(quoteWindowsArg('@serfab/cadre-host@0.7.0')).toBe('@serfab/cadre-host@0.7.0');
+  });
+
+  it('quotes args containing whitespace or shell metachars', () => {
+    expect(quoteWindowsArg('has space')).toBe('"has space"');
+    expect(quoteWindowsArg('with&amp')).toBe('"with&amp"');
+    expect(quoteWindowsArg('pipe|me')).toBe('"pipe|me"');
+  });
+
+  it('escapes embedded quotes and trailing backslashes', () => {
+    expect(quoteWindowsArg('with"quote')).toBe('"with\\"quote"');
+    expect(quoteWindowsArg('trailing\\')).toBe('trailing\\');
+    expect(quoteWindowsArg('trail ing\\')).toBe('"trail ing\\\\"');
+  });
+
+  it('rejects control characters', () => {
+    expect(() => quoteWindowsArg('bad\nnewline')).toThrow(/control character/);
+    expect(() => quoteWindowsArg('bad\x00null')).toThrow(/control character/);
+  });
+});
+
+describe('buildNpmSpawnSpec', () => {
+  it('builds a single-string command with empty args on Windows', () => {
+    const original = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+    try {
+      const spec = buildNpmSpawnSpec(['install', '-g', '@serfab/cadre-host@0.7.0']);
+      expect(spec).toEqual({
+        command: 'npm install -g @serfab/cadre-host@0.7.0',
+        args: [],
+        shell: true,
+      });
+    } finally {
+      Object.defineProperty(process, 'platform', { value: original, configurable: true });
+    }
+  });
+
+  it('passes args through verbatim on posix (no shell)', () => {
+    const original = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'linux', configurable: true });
+    try {
+      const spec = buildNpmSpawnSpec(['install', '-g', '@serfab/cadre-host@0.7.0']);
+      expect(spec).toEqual({
+        command: 'npm',
+        args: ['install', '-g', '@serfab/cadre-host@0.7.0'],
+        shell: false,
+      });
+    } finally {
+      Object.defineProperty(process, 'platform', { value: original, configurable: true });
+    }
+  });
+});