@serfab/cadre-host 1.12.0 → 1.14.0

package/src/server/__tests__/bus.test.ts

@@ -1,38 +1,38 @@
-import { describe, it, expect } from 'vitest';
-
-import { EventBus } from '../events/bus.js';
-import type { LocalUiEvent } from '../events/types.js';
-
-describe('EventBus', () => {
-  it('delivers events to subscribers in order', () => {
-    const bus = new EventBus();
-    const received: LocalUiEvent[] = [];
-    bus.subscribe((e) => received.push(e));
-    bus.publish({ type: 'trust-circle-changed', kind: 'invited' });
-    bus.publish({ type: 'trust-circle-changed', kind: 'revoked' });
-    expect(received).toEqual([
-      { type: 'trust-circle-changed', kind: 'invited' },
-      { type: 'trust-circle-changed', kind: 'revoked' },
-    ]);
-  });
-
-  it('unsubscribe stops further deliveries', () => {
-    const bus = new EventBus();
-    const received: LocalUiEvent[] = [];
-    const unsub = bus.subscribe((e) => received.push(e));
-    bus.publish({ type: 'trust-circle-changed', kind: 'invited' });
-    unsub();
-    bus.publish({ type: 'trust-circle-changed', kind: 'redeemed' });
-    expect(received).toHaveLength(1);
-    expect(bus.listenerCount()).toBe(0);
-  });
-
-  it('one listener throwing does not block others', () => {
-    const bus = new EventBus();
-    const received: LocalUiEvent[] = [];
-    bus.subscribe(() => { throw new Error('bad listener'); });
-    bus.subscribe((e) => received.push(e));
-    bus.publish({ type: 'trust-circle-changed', kind: 'invited' });
-    expect(received).toHaveLength(1);
-  });
-});
+import { describe, it, expect } from 'vitest';
+
+import { EventBus } from '../events/bus.js';
+import type { LocalUiEvent } from '../events/types.js';
+
+describe('EventBus', () => {
+  it('delivers events to subscribers in order', () => {
+    const bus = new EventBus();
+    const received: LocalUiEvent[] = [];
+    bus.subscribe((e) => received.push(e));
+    bus.publish({ type: 'hosted-nodes-changed', kind: 'added', nodeId: 'hn_a' });
+    bus.publish({ type: 'hosted-nodes-changed', kind: 'claimed', nodeId: 'hn_a' });
+    expect(received).toEqual([
+      { type: 'hosted-nodes-changed', kind: 'added', nodeId: 'hn_a' },
+      { type: 'hosted-nodes-changed', kind: 'claimed', nodeId: 'hn_a' },
+    ]);
+  });
+
+  it('unsubscribe stops further deliveries', () => {
+    const bus = new EventBus();
+    const received: LocalUiEvent[] = [];
+    const unsub = bus.subscribe((e) => received.push(e));
+    bus.publish({ type: 'hosted-nodes-changed', kind: 'added', nodeId: 'hn_a' });
+    unsub();
+    bus.publish({ type: 'hosted-nodes-changed', kind: 'removed', nodeId: 'hn_a' });
+    expect(received).toHaveLength(1);
+    expect(bus.listenerCount()).toBe(0);
+  });
+
+  it('one listener throwing does not block others', () => {
+    const bus = new EventBus();
+    const received: LocalUiEvent[] = [];
+    bus.subscribe(() => { throw new Error('bad listener'); });
+    bus.subscribe((e) => received.push(e));
+    bus.publish({ type: 'hosted-nodes-changed', kind: 'added', nodeId: 'hn_a' });
+    expect(received).toHaveLength(1);
+  });
+});

package/src/server/__tests__/error-handler.test.ts

@@ -1,118 +1,81 @@
-import Fastify, { type FastifyRequest } from 'fastify';
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-
-import { TrustCircleError } from '../../auth/types.js';
-import { NatError } from '../../nat/types.js';
-import { UpdateErrorException } from '../../update/types.js';
-import { GrantError } from '../../donation/types.js';
-import { registerErrorHandler } from '../error-handler.js';
-
-describe('error handler', () => {
-  let app: ReturnType<typeof Fastify>;
-
-  beforeEach(async () => {
-    app = Fastify();
-    registerErrorHandler(app);
-    app.get('/trust/:code', async (req: FastifyRequest) => {
-      const { code } = req.params as { code: string };
-      throw new TrustCircleError(code as never, `trust err: ${code}`);
-    });
-    app.get('/nat/:code', async (req: FastifyRequest) => {
-      const { code } = req.params as { code: string };
-      throw new NatError(code as never, `nat err: ${code}`);
-    });
-    app.get('/update/:code', async (req: FastifyRequest) => {
-      const { code } = req.params as { code: string };
-      throw new UpdateErrorException(code as never, `update err: ${code}`);
-    });
-    app.get('/grant/:code', async (req: FastifyRequest) => {
-      const { code } = req.params as { code: string };
-      throw new GrantError(code as never, `grant err: ${code}`);
-    });
-    app.get('/unknown', async () => {
-      throw new Error('mystery');
-    });
-  });
-
-  afterEach(async () => {
-    await app.close();
-  });
-
-  it('TrustCircleError invalid_label → 400', async () => {
-    const res = await app.inject({ method: 'GET', url: '/trust/invalid_label' });
-    expect(res.statusCode).toBe(400);
-    const body = res.json() as { ok: boolean; error: { code: string; message: string } };
-    expect(body).toEqual({
-      ok: false,
-      error: { code: 'invalid_label', message: 'trust err: invalid_label' },
-    });
-  });
-
-  it('TrustCircleError not_found → 404', async () => {
-    const res = await app.inject({ method: 'GET', url: '/trust/not_found' });
-    expect(res.statusCode).toBe(404);
-  });
-
-  it('TrustCircleError already_redeemed → 404', async () => {
-    const res = await app.inject({ method: 'GET', url: '/trust/already_redeemed' });
-    expect(res.statusCode).toBe(404);
-  });
-
-  it('TrustCircleError expired → 410', async () => {
-    const res = await app.inject({ method: 'GET', url: '/trust/expired' });
-    expect(res.statusCode).toBe(410);
-  });
-
-  it('TrustCircleError storage_error → 500', async () => {
-    const res = await app.inject({ method: 'GET', url: '/trust/storage_error' });
-    expect(res.statusCode).toBe(500);
-  });
-
-  it('NatError invalid_config → 400', async () => {
-    const res = await app.inject({ method: 'GET', url: '/nat/invalid_config' });
-    expect(res.statusCode).toBe(400);
-    const body = res.json() as { error: { code: string } };
-    expect(body.error.code).toBe('invalid_config');
-  });
-
-  it('NatError secrets_unavailable → 500', async () => {
-    const res = await app.inject({ method: 'GET', url: '/nat/secrets_unavailable' });
-    expect(res.statusCode).toBe(500);
-  });
-
-  it('UpdateErrorException apply_in_progress → 409', async () => {
-    const res = await app.inject({ method: 'GET', url: '/update/apply_in_progress' });
-    expect(res.statusCode).toBe(409);
-  });
-
-  it('UpdateErrorException no_update_available → 400', async () => {
-    const res = await app.inject({ method: 'GET', url: '/update/no_update_available' });
-    expect(res.statusCode).toBe(400);
-  });
-
-  it('GrantError invalid_max_nodes → 400', async () => {
-    const res = await app.inject({ method: 'GET', url: '/grant/invalid_max_nodes' });
-    expect(res.statusCode).toBe(400);
-    const body = res.json() as { error: { code: string } };
-    expect(body.error.code).toBe('invalid_max_nodes');
-  });
-
-  it('GrantError not_found → 404', async () => {
-    const res = await app.inject({ method: 'GET', url: '/grant/not_found' });
-    expect(res.statusCode).toBe(404);
-  });
-
-  it('GrantError storage_error → 500', async () => {
-    const res = await app.inject({ method: 'GET', url: '/grant/storage_error' });
-    expect(res.statusCode).toBe(500);
-  });
-
-  it('unknown Error → 500 internal', async () => {
-    const res = await app.inject({ method: 'GET', url: '/unknown' });
-    expect(res.statusCode).toBe(500);
-    const body = res.json() as { ok: boolean; error: { code: string; message: string } };
-    expect(body.ok).toBe(false);
-    expect(body.error.code).toBe('internal');
-    expect(body.error.message).toBe('mystery');
-  });
-});
+import Fastify, { type FastifyRequest } from 'fastify';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+import { NatError } from '../../nat/types.js';
+import { UpdateErrorException } from '../../update/types.js';
+import { HostedNodeError } from '../../hosted/types.js';
+import { registerErrorHandler } from '../error-handler.js';
+
+describe('error handler', () => {
+  let app: ReturnType<typeof Fastify>;
+
+  beforeEach(async () => {
+    app = Fastify();
+    registerErrorHandler(app);
+    app.get('/nat/:code', async (req: FastifyRequest) => {
+      const { code } = req.params as { code: string };
+      throw new NatError(code as never, `nat err: ${code}`);
+    });
+    app.get('/update/:code', async (req: FastifyRequest) => {
+      const { code } = req.params as { code: string };
+      throw new UpdateErrorException(code as never, `update err: ${code}`);
+    });
+    app.get('/hosted/:code', async (req: FastifyRequest) => {
+      const { code } = req.params as { code: string };
+      throw new HostedNodeError(code as never, `hosted err: ${code}`);
+    });
+    app.get('/unknown', async () => {
+      throw new Error('mystery');
+    });
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it('NatError invalid_config → 400', async () => {
+    const res = await app.inject({ method: 'GET', url: '/nat/invalid_config' });
+    expect(res.statusCode).toBe(400);
+    const body = res.json() as { ok: boolean; error: { code: string; message: string } };
+    expect(body).toEqual({
+      ok: false,
+      error: { code: 'invalid_config', message: 'nat err: invalid_config' },
+    });
+  });
+
+  it('NatError secrets_unavailable → 500', async () => {
+    const res = await app.inject({ method: 'GET', url: '/nat/secrets_unavailable' });
+    expect(res.statusCode).toBe(500);
+  });
+
+  it('UpdateErrorException apply_in_progress → 409', async () => {
+    const res = await app.inject({ method: 'GET', url: '/update/apply_in_progress' });
+    expect(res.statusCode).toBe(409);
+  });
+
+  it('UpdateErrorException no_update_available → 400', async () => {
+    const res = await app.inject({ method: 'GET', url: '/update/no_update_available' });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('HostedNodeError maps each code to its status', async () => {
+    const statusOf = async (code: string): Promise<number> => (await app.inject({ method: 'GET', url: `/hosted/${code}` })).statusCode;
+    expect(await statusOf('invalid_request')).toBe(400);
+    expect(await statusOf('not_found')).toBe(404);
+    expect(await statusOf('invalid_state')).toBe(409);
+    expect(await statusOf('node_unavailable')).toBe(503);
+    expect(await statusOf('orchestrator_error')).toBe(500);
+    expect(await statusOf('storage_error')).toBe(500);
+    const body = (await app.inject({ method: 'GET', url: '/hosted/invalid_state' })).json() as { error: { code: string } };
+    expect(body.error.code).toBe('invalid_state');
+  });
+
+  it('unknown Error → 500 internal', async () => {
+    const res = await app.inject({ method: 'GET', url: '/unknown' });
+    expect(res.statusCode).toBe(500);
+    const body = res.json() as { ok: boolean; error: { code: string; message: string } };
+    expect(body.ok).toBe(false);
+    expect(body.error.code).toBe('internal');
+    expect(body.error.message).toBe('mystery');
+  });
+});

package/src/server/__tests__/fakes.ts

@@ -1,44 +1,40 @@
-/**
- * Shared fakes for the local-UI server tests. Holds no tests of its own.
- */
-
-import type { FounderServices } from '../index.js';
-import type { TrustCircleService } from '../../auth/index.js';
-import type { NatService } from '../../nat/index.js';
-import type { NatStatusSnapshot } from '../../nat/types.js';
-import type { StrandService } from '../../strands/index.js';
-
-export const SAMPLE_CONNECTIVITY: NatStatusSnapshot = {
-  portMode: 'auto-upnp',
-  externalPort: 4001,
-  internalPort: 4001,
-  routerExternalIp: '203.0.113.5',
-  mappingLeaseExpiresAt: null,
-  externalIp: '203.0.113.5',
-  externalIpDetectedAt: null,
-  cgnatDetected: false,
-  directReachability: 'reachable',
-  lastTestedAt: null,
-  ddns: {
-    providerId: null,
-    hostname: null,
-    externallyManaged: false,
-    lastUpdateAt: null,
-    lastUpdateOk: null,
-    lastError: null,
-  },
-};
-
-/**
- * A founder-role service set whose members answer only the reads the server
- * makes on its own (status, boot publish): an empty trust circle, the sample
- * connectivity, no strands. Pass the service a test exercises as an override.
- */
-export function fakeFounder(overrides: Partial<FounderServices> = {}): FounderServices {
-  return {
-    trustCircle: { list: async () => ({ members: [], pending: [] }) } as unknown as TrustCircleService,
-    nat: { getStatus: () => SAMPLE_CONNECTIVITY } as unknown as NatService,
-    strands: { list: async () => ({ strands: [], controlConnections: 0 }) } as unknown as StrandService,
-    ...overrides,
-  };
-}
+/**
+ * Shared fakes for the local-UI server tests. Holds no tests of its own.
+ */
+
+import type { NatService, NatChangeListener } from '../../nat/index.js';
+import type { NatStatusSnapshot } from '../../nat/types.js';
+
+export const SAMPLE_CONNECTIVITY: NatStatusSnapshot = {
+  upnpEnabled: true,
+  gateway: { found: true, lanAddress: '192.168.1.20', routerExternalIp: '203.0.113.5', lastError: null },
+  externalIp: '203.0.113.5',
+  externalIpDetectedAt: null,
+  cgnatDetected: false,
+  directReachability: 'reachable',
+  lastTestedAt: null,
+  ddns: {
+    providerId: null,
+    hostname: null,
+    externallyManaged: false,
+    lastUpdateAt: null,
+    lastUpdateOk: null,
+    lastError: null,
+  },
+  nodes: [],
+};
+
+/**
+ * A NAT service that answers only the reads the server makes on its own
+ * (status, boot publish) and the writes the settings route forwards. `emit`
+ * fires the change listeners the server registered, for tests of that wiring.
+ */
+export function fakeNat(snapshot: NatStatusSnapshot = SAMPLE_CONNECTIVITY): NatService & { emit(snap: NatStatusSnapshot): void } {
+  const listeners = new Set<NatChangeListener>();
+  return {
+    getStatus: () => snapshot,
+    onChange: (listener: NatChangeListener) => { listeners.add(listener); return () => { listeners.delete(listener); }; },
+    putSettings: async () => snapshot,
+    emit: (snap: NatStatusSnapshot) => { for (const l of listeners) l(snap); },
+  } as unknown as NatService & { emit(snap: NatStatusSnapshot): void };
+}

package/src/server/__tests__/hosted-nodes-route.test.ts

@@ -0,0 +1,160 @@
+/**
+ * `/api/hosted-nodes` route tests: the status code each outcome maps to, driven
+ * against a stub service so no child spawns, and the join-by-invitation refusals
+ * against the real service over the fake orchestrator, where "before anything is
+ * spawned" can be checked. The service's own behaviour is
+ * `hosted/__tests__/hosted-node-service.test.ts`.
+ */
+
+import Fastify from 'fastify';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { HostedNodeService } from '../../hosted/hosted-node-service.js';
+import { HostedNodeStore } from '../../hosted/hosted-node-store.js';
+import { HostedNodeError, type HostedNodeView } from '../../hosted/types.js';
+import { FakeOrchestrator } from '../../hosted/__tests__/fake-orchestrator.js';
+import { encodedTestInvitation } from '../../hosted/__tests__/test-invitation.js';
+import { registerErrorHandler } from '../error-handler.js';
+import { registerHostedNodesRoutes } from '../routes/hosted-nodes.js';
+
+const UNCLAIMED: HostedNodeView = {
+  id: 'hn_a', join: { kind: 'claim' }, partyId: 'unclaimed', profile: 'storage', status: 'unclaimed',
+  dockerId: '1:a', createdAt: '2026-01-01T00:00:00.000Z', updatedAt: '2026-01-01T00:00:00.000Z',
+};
+const JOINED: HostedNodeView = { ...UNCLAIMED, id: 'hn_b', status: 'joined', partyId: 'party-P', ownerKey: 'owner' };
+
+/** A service with two nodes, answering as the real one would for each. */
+function stubService(): HostedNodeService & { removed: string[] } {
+  const nodes = new Map([[UNCLAIMED.id, UNCLAIMED], [JOINED.id, JOINED]]);
+  const removed: string[] = [];
+  const require = (id: string): HostedNodeView => {
+    const node = nodes.get(id);
+    if (!node) throw new HostedNodeError('not_found', `No such hosted node: ${id}`);
+    return node;
+  };
+  return {
+    removed,
+    list: () => [...nodes.values()],
+    get: (id: string) => nodes.get(id),
+    join: async () => ({ ...UNCLAIMED, id: 'hn_new' }),
+    claimDetails: async (id: string) => {
+      const node = require(id);
+      if (node.status !== 'unclaimed') throw new HostedNodeError('invalid_state', `Hosted node ${id} is ${node.status}`);
+      if (id === 'hn_starting') throw new HostedNodeError('node_unavailable', 'not yet');
+      return { payload: 'sereus-join:1.x', peerId: '12D3KooW', multiaddrs: ['/ip4/192.168.1.20/tcp/1/ws/p2p/12D3KooW'], reachability: null };
+    },
+    remove: async (id: string) => { require(id); removed.push(id); },
+    reset: async (id: string) => { require(id); return { ...UNCLAIMED, id: 'hn_reset' }; },
+  } as unknown as HostedNodeService & { removed: string[] };
+}
+
+describe('/api/hosted-nodes routes', () => {
+  let app: ReturnType<typeof Fastify>;
+  let service: ReturnType<typeof stubService>;
+
+  beforeEach(() => {
+    app = Fastify();
+    registerErrorHandler(app);
+    service = stubService();
+    registerHostedNodesRoutes(app, { hostedNodes: service });
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it('answers each outcome with its status code', async () => {
+    expect((await app.inject({ method: 'GET', url: '/api/hosted-nodes' })).json()).toEqual({ ok: true, data: { nodes: [UNCLAIMED, JOINED] } });
+
+    const created = await app.inject({ method: 'POST', url: '/api/hosted-nodes' });
+    expect(created.statusCode).toBe(201);
+    expect(created.json()).toMatchObject({ ok: true, data: { node: { id: 'hn_new', status: 'unclaimed' } } });
+
+    expect((await app.inject({ method: 'GET', url: '/api/hosted-nodes/hn_a' })).json()).toEqual({ ok: true, data: { node: UNCLAIMED } });
+    const missing = await app.inject({ method: 'GET', url: '/api/hosted-nodes/hn_nobody' });
+    expect(missing.statusCode).toBe(404);
+    expect(missing.json()).toMatchObject({ ok: false, error: { code: 'not_found' } });
+
+    const claim = await app.inject({ method: 'GET', url: '/api/hosted-nodes/hn_a/claim' });
+    expect(claim.statusCode).toBe(200);
+    expect(claim.json()).toMatchObject({ ok: true, data: { payload: 'sereus-join:1.x', peerId: '12D3KooW' } });
+
+    const removed = await app.inject({ method: 'DELETE', url: '/api/hosted-nodes/hn_b' });
+    expect(removed.statusCode).toBe(204);
+    expect(service.removed).toEqual(['hn_b']);
+    expect((await app.inject({ method: 'DELETE', url: '/api/hosted-nodes/hn_nobody' })).statusCode).toBe(404);
+
+    const reset = await app.inject({ method: 'POST', url: '/api/hosted-nodes/hn_a/reset' });
+    expect(reset.statusCode).toBe(201);
+    expect(reset.json()).toMatchObject({ ok: true, data: { node: { id: 'hn_reset' } } });
+  });
+
+  it('answers 409 for the claim details of a joined node', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/hosted-nodes/hn_b/claim' });
+    expect(res.statusCode).toBe(409);
+    expect(res.json()).toMatchObject({ ok: false, error: { code: 'invalid_state' } });
+  });
+});
+
+describe('/api/hosted-nodes join by invitation, over the real service', () => {
+  let app: ReturnType<typeof Fastify>;
+  let orch: FakeOrchestrator;
+  let store: HostedNodeStore;
+  let tmpRoot: string;
+
+  beforeEach(() => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-hosted-route-'));
+    orch = new FakeOrchestrator();
+    store = new HostedNodeStore(tmpRoot);
+    const hostedNodes = new HostedNodeService({
+      orchestrator: orch,
+      store,
+      addresses: { publicAddressesFor: () => [], getStatus: () => ({ nodes: [] }) },
+    });
+    app = Fastify();
+    registerErrorHandler(app);
+    registerHostedNodesRoutes(app, { hostedNodes });
+  });
+
+  afterEach(async () => {
+    await app.close();
+    rmSync(tmpRoot, { recursive: true, force: true });
+  });
+
+  it('answers 400 for an invitation that does not decode, before anything is written or spawned', async () => {
+    for (const invitation of ['not an invitation', 42]) {
+      const res = await app.inject({ method: 'POST', url: '/api/hosted-nodes', payload: { invitation } });
+      expect(res.statusCode).toBe(400);
+      expect(res.json()).toMatchObject({ ok: false, error: { code: 'invalid_request' } });
+    }
+    expect(store.list()).toEqual([]);
+    expect(orch.createCalls).toEqual([]);
+  });
+
+  it('answers 409 to Retry unless no member of the cadre could be reached', async () => {
+    const created = await app.inject({ method: 'POST', url: '/api/hosted-nodes', payload: { invitation: encodedTestInvitation('party-P') } });
+    expect(created.statusCode).toBe(201);
+    const { id } = (created.json() as { data: { node: HostedNodeView } }).data.node;
+
+    // Still joining: nothing to retry.
+    expect((await app.inject({ method: 'POST', url: `/api/hosted-nodes/${id}/retry` })).statusCode).toBe(409);
+
+    // Refused by a member (an expired invitation): final.
+    const node = store.get(id)!;
+    store.put({ ...node, status: 'error', error: 'Cadre invitation refused: expired (invite-spent)', retryable: false });
+    const refused = await app.inject({ method: 'POST', url: `/api/hosted-nodes/${id}/retry` });
+    expect(refused.statusCode).toBe(409);
+    expect(refused.json()).toMatchObject({ ok: false, error: { code: 'invalid_state' } });
+    expect(orch.createCalls).toHaveLength(1);
+
+    // No member reachable: Retry starts it again.
+    store.put({ ...node, status: 'error', error: 'No member named in the invitation could be reached.', retryable: true });
+    orch.crash(node.dockerId!);
+    const retried = await app.inject({ method: 'POST', url: `/api/hosted-nodes/${id}/retry` });
+    expect(retried.statusCode).toBe(200);
+    expect(retried.json()).toMatchObject({ ok: true, data: { node: { id, status: 'joining' } } });
+  });
+});