@serfab/cadre-host 0.10.0 → 0.11.0

package/src/strands/__tests__/strand-service.test.ts

@@ -1,165 +1,165 @@
-/**
- * StrandService unit tests — a fake node, no HTTP.
- *
- * The two things this layer actually owns: id validation (which must never reach
- * the node) and the translation of the admin channel's single
- * `OwnerNodeUnavailableError` into a vocabulary the HTTP layer can map. The
- * confirmation *policy* is the node's and is not re-tested here — only that the
- * flag is forwarded verbatim.
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-
-import { OwnerNodeUnavailableError } from '../../owner/owner-node-client.js';
-import { StrandService } from '../strand-service.js';
-import { StrandError } from '../types.js';
-import type { CadreNodeLike } from '../strand-service.js';
-import type { StrandListSnapshot, StrandRemovalResult } from '../types.js';
-
-interface FakeNode extends CadreNodeLike {
-  calls: Array<{ strandId: string; confirm: boolean }>;
-  listCalls: number;
-  /** Thrown by both methods when set. */
-  failWith?: unknown;
-}
-
-const SNAPSHOT: StrandListSnapshot = {
-  strands: [
-    { id: 'open-one', type: 'o', running: true, status: 'active' },
-    { id: 'closed-one', type: 'c', running: false, status: null },
-  ],
-  controlConnections: 2,
-};
-
-function fakeNode(): FakeNode {
-  const node: FakeNode = {
-    calls: [],
-    listCalls: 0,
-    async listStrands() {
-      node.listCalls++;
-      if (node.failWith) throw node.failWith;
-      return SNAPSHOT;
-    },
-    async removeStrand(strandId, opts) {
-      node.calls.push({ strandId, confirm: opts.confirm });
-      if (node.failWith) throw node.failWith;
-      const result: StrandRemovalResult = {
-        strandId,
-        published: true,
-        type: 'o',
-        removed: true,
-        alone: false,
-      };
-      return result;
-    },
-  };
-  return node;
-}
-
-/** Await a call expected to reject, assert it is a StrandError, and hand it back. */
-async function catchStrandError(p: Promise<unknown>): Promise<StrandError> {
-  const err = await p.then(() => undefined, (e: unknown) => e);
-  expect(err).toBeInstanceOf(StrandError);
-  return err as StrandError;
-}
-
-let node: FakeNode;
-let service: StrandService;
-
-beforeEach(() => {
-  node = fakeNode();
-  service = new StrandService({ cadreNode: node });
-});
-
-describe('StrandService.list', () => {
-  it('passes the node snapshot through unchanged', async () => {
-    await expect(service.list()).resolves.toEqual(SNAPSHOT);
-    expect(node.listCalls).toBe(1);
-  });
-});
-
-describe('StrandService.remove — id validation', () => {
-  it.each([
-    ['blank', ''],
-    ['whitespace-only', '   '],
-    ['tab/newline only', '\t\n'],
-  ])('rejects a %s id with invalid_id and never calls the node', async (_label, id) => {
-    await expect(service.remove(id, { confirm: false })).rejects.toMatchObject({
-      name: 'StrandError',
-      code: 'invalid_id',
-    });
-    expect(node.calls).toEqual([]);
-  });
-
-  it('forwards an id containing "/" rather than refusing it', async () => {
-    // The whole chain carries it: Fastify decodes `%2F` into `params.id`,
-    // `OwnerNodeClient` re-encodes it, and the admin channel splits on the still
-    // -encoded segment and decodes it back. Refusing here would break the only
-    // form that works. `strands-route.test.ts` pins the Fastify half.
-    await service.remove('ns/strand', { confirm: true });
-    expect(node.calls).toEqual([{ strandId: 'ns/strand', confirm: true }]);
-  });
-
-  it('trims a padded id before forwarding it', async () => {
-    await service.remove('  spaced  ', { confirm: false });
-    expect(node.calls).toEqual([{ strandId: 'spaced', confirm: false }]);
-  });
-});
-
-describe('StrandService.remove — confirmation forwarding', () => {
-  it('forwards confirm: false as false', async () => {
-    await service.remove('open-one', { confirm: false });
-    expect(node.calls).toEqual([{ strandId: 'open-one', confirm: false }]);
-  });
-
-  it('forwards confirm: true as true', async () => {
-    await service.remove('closed-one', { confirm: true });
-    expect(node.calls).toEqual([{ strandId: 'closed-one', confirm: true }]);
-  });
-
-  it('does not retry a refused removal with confirmation added', async () => {
-    node.failWith = new OwnerNodeUnavailableError('needs confirmation', 'confirmation_required');
-    await expect(service.remove('closed-one', { confirm: false })).rejects.toBeInstanceOf(StrandError);
-    // Exactly one attempt, and it carried the caller's flag.
-    expect(node.calls).toEqual([{ strandId: 'closed-one', confirm: false }]);
-  });
-});
-
-describe('StrandService — error translation', () => {
-  const cases: Array<{ nodeCode: string | undefined; code: string; keepsMessage: boolean }> = [
-    { nodeCode: 'confirmation_required', code: 'confirmation_required', keepsMessage: true },
-    { nodeCode: 'bad_request', code: 'invalid_id', keepsMessage: true },
-    { nodeCode: 'not_ready', code: 'node_unavailable', keepsMessage: false },
-    { nodeCode: 'not_authorized', code: 'node_unavailable', keepsMessage: false },
-    { nodeCode: undefined, code: 'node_unavailable', keepsMessage: false },
-    { nodeCode: 'internal', code: 'internal', keepsMessage: true },
-    { nodeCode: 'something_new', code: 'internal', keepsMessage: true },
-  ];
-
-  for (const { nodeCode, code, keepsMessage } of cases) {
-    it(`maps nodeCode ${nodeCode ?? '(absent)'} → ${code}`, async () => {
-      const message = `node said ${nodeCode ?? 'nothing'}`;
-      node.failWith = new OwnerNodeUnavailableError(message, nodeCode);
-      const err = await catchStrandError(service.remove('x', { confirm: false }));
-      expect(err.code).toBe(code);
-      if (keepsMessage) {
-        expect(err.message).toBe(message);
-      } else {
-        // Wrapped, but the node's words survive inside.
-        expect(err.message).toContain(message);
-      }
-    });
-  }
-
-  it('translates a transport failure (no nodeCode) on list() too', async () => {
-    node.failWith = new OwnerNodeUnavailableError('Owner node unreachable: ECONNREFUSED');
-    const err = await catchStrandError(service.list());
-    expect(err.code).toBe('node_unavailable');
-  });
-
-  it('rethrows a non-owner-node error unchanged rather than dressing it as a strand error', async () => {
-    const boom = new TypeError('something else broke');
-    node.failWith = boom;
-    await expect(service.list()).rejects.toBe(boom);
-  });
-});
+/**
+ * StrandService unit tests — a fake node, no HTTP.
+ *
+ * The two things this layer actually owns: id validation (which must never reach
+ * the node) and the translation of the admin channel's single
+ * `OwnerNodeUnavailableError` into a vocabulary the HTTP layer can map. The
+ * confirmation *policy* is the node's and is not re-tested here — only that the
+ * flag is forwarded verbatim.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import { OwnerNodeUnavailableError } from '../../owner/owner-node-client.js';
+import { StrandService } from '../strand-service.js';
+import { StrandError } from '../types.js';
+import type { CadreNodeLike } from '../strand-service.js';
+import type { StrandListSnapshot, StrandRemovalResult } from '../types.js';
+
+interface FakeNode extends CadreNodeLike {
+  calls: Array<{ strandId: string; confirm: boolean }>;
+  listCalls: number;
+  /** Thrown by both methods when set. */
+  failWith?: unknown;
+}
+
+const SNAPSHOT: StrandListSnapshot = {
+  strands: [
+    { id: 'open-one', type: 'o', running: true, status: 'active' },
+    { id: 'closed-one', type: 'c', running: false, status: null },
+  ],
+  controlConnections: 2,
+};
+
+function fakeNode(): FakeNode {
+  const node: FakeNode = {
+    calls: [],
+    listCalls: 0,
+    async listStrands() {
+      node.listCalls++;
+      if (node.failWith) throw node.failWith;
+      return SNAPSHOT;
+    },
+    async removeStrand(strandId, opts) {
+      node.calls.push({ strandId, confirm: opts.confirm });
+      if (node.failWith) throw node.failWith;
+      const result: StrandRemovalResult = {
+        strandId,
+        published: true,
+        type: 'o',
+        removed: true,
+        alone: false,
+      };
+      return result;
+    },
+  };
+  return node;
+}
+
+/** Await a call expected to reject, assert it is a StrandError, and hand it back. */
+async function catchStrandError(p: Promise<unknown>): Promise<StrandError> {
+  const err = await p.then(() => undefined, (e: unknown) => e);
+  expect(err).toBeInstanceOf(StrandError);
+  return err as StrandError;
+}
+
+let node: FakeNode;
+let service: StrandService;
+
+beforeEach(() => {
+  node = fakeNode();
+  service = new StrandService({ cadreNode: node });
+});
+
+describe('StrandService.list', () => {
+  it('passes the node snapshot through unchanged', async () => {
+    await expect(service.list()).resolves.toEqual(SNAPSHOT);
+    expect(node.listCalls).toBe(1);
+  });
+});
+
+describe('StrandService.remove — id validation', () => {
+  it.each([
+    ['blank', ''],
+    ['whitespace-only', '   '],
+    ['tab/newline only', '\t\n'],
+  ])('rejects a %s id with invalid_id and never calls the node', async (_label, id) => {
+    await expect(service.remove(id, { confirm: false })).rejects.toMatchObject({
+      name: 'StrandError',
+      code: 'invalid_id',
+    });
+    expect(node.calls).toEqual([]);
+  });
+
+  it('forwards an id containing "/" rather than refusing it', async () => {
+    // The whole chain carries it: Fastify decodes `%2F` into `params.id`,
+    // `OwnerNodeClient` re-encodes it, and the admin channel splits on the still
+    // -encoded segment and decodes it back. Refusing here would break the only
+    // form that works. `strands-route.test.ts` pins the Fastify half.
+    await service.remove('ns/strand', { confirm: true });
+    expect(node.calls).toEqual([{ strandId: 'ns/strand', confirm: true }]);
+  });
+
+  it('trims a padded id before forwarding it', async () => {
+    await service.remove('  spaced  ', { confirm: false });
+    expect(node.calls).toEqual([{ strandId: 'spaced', confirm: false }]);
+  });
+});
+
+describe('StrandService.remove — confirmation forwarding', () => {
+  it('forwards confirm: false as false', async () => {
+    await service.remove('open-one', { confirm: false });
+    expect(node.calls).toEqual([{ strandId: 'open-one', confirm: false }]);
+  });
+
+  it('forwards confirm: true as true', async () => {
+    await service.remove('closed-one', { confirm: true });
+    expect(node.calls).toEqual([{ strandId: 'closed-one', confirm: true }]);
+  });
+
+  it('does not retry a refused removal with confirmation added', async () => {
+    node.failWith = new OwnerNodeUnavailableError('needs confirmation', 'confirmation_required');
+    await expect(service.remove('closed-one', { confirm: false })).rejects.toBeInstanceOf(StrandError);
+    // Exactly one attempt, and it carried the caller's flag.
+    expect(node.calls).toEqual([{ strandId: 'closed-one', confirm: false }]);
+  });
+});
+
+describe('StrandService — error translation', () => {
+  const cases: Array<{ nodeCode: string | undefined; code: string; keepsMessage: boolean }> = [
+    { nodeCode: 'confirmation_required', code: 'confirmation_required', keepsMessage: true },
+    { nodeCode: 'bad_request', code: 'invalid_id', keepsMessage: true },
+    { nodeCode: 'not_ready', code: 'node_unavailable', keepsMessage: false },
+    { nodeCode: 'not_authorized', code: 'node_unavailable', keepsMessage: false },
+    { nodeCode: undefined, code: 'node_unavailable', keepsMessage: false },
+    { nodeCode: 'internal', code: 'internal', keepsMessage: true },
+    { nodeCode: 'something_new', code: 'internal', keepsMessage: true },
+  ];
+
+  for (const { nodeCode, code, keepsMessage } of cases) {
+    it(`maps nodeCode ${nodeCode ?? '(absent)'} → ${code}`, async () => {
+      const message = `node said ${nodeCode ?? 'nothing'}`;
+      node.failWith = new OwnerNodeUnavailableError(message, nodeCode);
+      const err = await catchStrandError(service.remove('x', { confirm: false }));
+      expect(err.code).toBe(code);
+      if (keepsMessage) {
+        expect(err.message).toBe(message);
+      } else {
+        // Wrapped, but the node's words survive inside.
+        expect(err.message).toContain(message);
+      }
+    });
+  }
+
+  it('translates a transport failure (no nodeCode) on list() too', async () => {
+    node.failWith = new OwnerNodeUnavailableError('Owner node unreachable: ECONNREFUSED');
+    const err = await catchStrandError(service.list());
+    expect(err.code).toBe('node_unavailable');
+  });
+
+  it('rethrows a non-owner-node error unchanged rather than dressing it as a strand error', async () => {
+    const boom = new TypeError('something else broke');
+    node.failWith = boom;
+    await expect(service.list()).rejects.toBe(boom);
+  });
+});

package/src/strands/index.ts

@@ -1,14 +1,14 @@
-/**
- * Strand management for cadre-host. See ./strand-service.ts and ./types.ts.
- */
-
-export { StrandService, createStrandHandlers } from './strand-service.js';
-export type { StrandServiceOptions, CadreNodeLike } from './strand-service.js';
-export { StrandError } from './types.js';
-export type {
-  StrandSummary,
-  StrandListSnapshot,
-  StrandRemovalResult,
-  StrandHandlers,
-  StrandErrorCode,
-} from './types.js';
+/**
+ * Strand management for cadre-host. See ./strand-service.ts and ./types.ts.
+ */
+
+export { StrandService, createStrandHandlers } from './strand-service.js';
+export type { StrandServiceOptions, CadreNodeLike } from './strand-service.js';
+export { StrandError } from './types.js';
+export type {
+  StrandSummary,
+  StrandListSnapshot,
+  StrandRemovalResult,
+  StrandHandlers,
+  StrandErrorCode,
+} from './types.js';

package/src/strands/strand-service.ts

@@ -1,135 +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 });
-    },
-  };
-}
+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 });
+    },
+  };
+}