@serfab/cadre-host 0.10.0 → 0.11.0

package/src/nat/__tests__/nat-store.test.ts

@@ -1,93 +1,93 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { NatStore } from '../nat-store.js';
-import { NatError } from '../types.js';
-
-let tmpRoot: string;
-
-beforeEach(() => {
-  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-nat-store-'));
-});
-
-afterEach(() => {
-  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
-});
-
-describe('NatStore', () => {
-  it('returns defaults when file is missing', () => {
-    const store = new NatStore(tmpRoot);
-    const s = store.load();
-    expect(s.externalPort).toBe(4001);
-    expect(s.internalPort).toBe(4001);
-    expect(s.upnpEnabled).toBe(true);
-    expect(s.ddns.providerId).toBeNull();
-    expect(s.ddns.externallyManaged).toBe(false);
-    expect(s.ddns.intervalMs).toBe(5 * 60 * 1000);
-  });
-
-  it('persists and reloads settings atomically', () => {
-    const store = new NatStore(tmpRoot);
-    store.update({ externalPort: 4002, upnpEnabled: false });
-
-    expect(existsSync(join(tmpRoot, 'nat.json'))).toBe(true);
-    expect(existsSync(join(tmpRoot, 'nat.json.tmp'))).toBe(false);
-
-    const reread = new NatStore(tmpRoot);
-    const s = reread.load();
-    expect(s.externalPort).toBe(4002);
-    expect(s.upnpEnabled).toBe(false);
-  });
-
-  it('merges ddns subtree on update', () => {
-    const store = new NatStore(tmpRoot);
-    store.update({
-      ddns: {
-        providerId: 'duckdns',
-        hostname: 'foo.duckdns.org',
-        externallyManaged: false,
-        intervalMs: 60_000,
-      },
-    });
-
-    store.update({ ddns: { externallyManaged: true } as never });
-
-    const s = store.load();
-    expect(s.ddns.providerId).toBe('duckdns');
-    expect(s.ddns.hostname).toBe('foo.duckdns.org');
-    expect(s.ddns.externallyManaged).toBe(true);
-    expect(s.ddns.intervalMs).toBe(60_000);
-  });
-
-  it('persists version field', () => {
-    const store = new NatStore(tmpRoot);
-    store.update({ externalPort: 4001 });
-    const raw = JSON.parse(readFileSync(join(tmpRoot, 'nat.json'), 'utf8'));
-    expect(raw.version).toBe(1);
-  });
-
-  it('throws on malformed JSON rather than silently wiping', () => {
-    writeFileSync(join(tmpRoot, 'nat.json'), 'not json', 'utf8');
-    const store = new NatStore(tmpRoot);
-    expect(() => store.load()).toThrow(NatError);
-  });
-
-  it('rejects invalid port', () => {
-    const store = new NatStore(tmpRoot);
-    expect(() => store.update({ externalPort: 0 })).toThrow(NatError);
-    expect(() => store.update({ externalPort: 70000 })).toThrow(NatError);
-  });
-
-  it('rejects too-small interval', () => {
-    const store = new NatStore(tmpRoot);
-    expect(() => store.update({ ddns: { intervalMs: 500 } as never })).toThrow(NatError);
-  });
-
-  it('rejects empty string providerId/hostname', () => {
-    const store = new NatStore(tmpRoot);
-    expect(() => store.update({ ddns: { providerId: '' } as never })).toThrow(NatError);
-    expect(() => store.update({ ddns: { hostname: '' } as never })).toThrow(NatError);
-  });
-});
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { NatStore } from '../nat-store.js';
+import { NatError } from '../types.js';
+
+let tmpRoot: string;
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-nat-store-'));
+});
+
+afterEach(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe('NatStore', () => {
+  it('returns defaults when file is missing', () => {
+    const store = new NatStore(tmpRoot);
+    const s = store.load();
+    expect(s.externalPort).toBe(4001);
+    expect(s.internalPort).toBe(4001);
+    expect(s.upnpEnabled).toBe(true);
+    expect(s.ddns.providerId).toBeNull();
+    expect(s.ddns.externallyManaged).toBe(false);
+    expect(s.ddns.intervalMs).toBe(5 * 60 * 1000);
+  });
+
+  it('persists and reloads settings atomically', () => {
+    const store = new NatStore(tmpRoot);
+    store.update({ externalPort: 4002, upnpEnabled: false });
+
+    expect(existsSync(join(tmpRoot, 'nat.json'))).toBe(true);
+    expect(existsSync(join(tmpRoot, 'nat.json.tmp'))).toBe(false);
+
+    const reread = new NatStore(tmpRoot);
+    const s = reread.load();
+    expect(s.externalPort).toBe(4002);
+    expect(s.upnpEnabled).toBe(false);
+  });
+
+  it('merges ddns subtree on update', () => {
+    const store = new NatStore(tmpRoot);
+    store.update({
+      ddns: {
+        providerId: 'duckdns',
+        hostname: 'foo.duckdns.org',
+        externallyManaged: false,
+        intervalMs: 60_000,
+      },
+    });
+
+    store.update({ ddns: { externallyManaged: true } as never });
+
+    const s = store.load();
+    expect(s.ddns.providerId).toBe('duckdns');
+    expect(s.ddns.hostname).toBe('foo.duckdns.org');
+    expect(s.ddns.externallyManaged).toBe(true);
+    expect(s.ddns.intervalMs).toBe(60_000);
+  });
+
+  it('persists version field', () => {
+    const store = new NatStore(tmpRoot);
+    store.update({ externalPort: 4001 });
+    const raw = JSON.parse(readFileSync(join(tmpRoot, 'nat.json'), 'utf8'));
+    expect(raw.version).toBe(1);
+  });
+
+  it('throws on malformed JSON rather than silently wiping', () => {
+    writeFileSync(join(tmpRoot, 'nat.json'), 'not json', 'utf8');
+    const store = new NatStore(tmpRoot);
+    expect(() => store.load()).toThrow(NatError);
+  });
+
+  it('rejects invalid port', () => {
+    const store = new NatStore(tmpRoot);
+    expect(() => store.update({ externalPort: 0 })).toThrow(NatError);
+    expect(() => store.update({ externalPort: 70000 })).toThrow(NatError);
+  });
+
+  it('rejects too-small interval', () => {
+    const store = new NatStore(tmpRoot);
+    expect(() => store.update({ ddns: { intervalMs: 500 } as never })).toThrow(NatError);
+  });
+
+  it('rejects empty string providerId/hostname', () => {
+    const store = new NatStore(tmpRoot);
+    expect(() => store.update({ ddns: { providerId: '' } as never })).toThrow(NatError);
+    expect(() => store.update({ ddns: { hostname: '' } as never })).toThrow(NatError);
+  });
+});

package/src/nat/__tests__/port-mapper.test.ts

@@ -1,191 +1,191 @@
-import { describe, expect, it } from 'vitest';
-
-import { NatError } from '../types.js';
-import {
-  PortMapperService,
-  type PortMapper,
-  type PortMappingResult,
-} from '../port-mapper.js';
-
-interface FakeOpts {
-  mapShouldThrow?: Error;
-  verifyResult?: boolean;
-  verifyShouldThrow?: Error;
-  externalIp?: string | null;
-}
-
-function makeFakeMapper(initial: FakeOpts = {}): PortMapper & {
-  calls: { map: number; verify: number; unmap: number; stop: number };
-  options: FakeOpts;
-} {
-  const opts = { ...initial };
-  const calls = { map: 0, verify: 0, unmap: 0, stop: 0 };
-  return {
-    options: opts,
-    calls,
-    async map(o): Promise<PortMappingResult> {
-      calls.map++;
-      if (opts.mapShouldThrow) throw opts.mapShouldThrow;
-      return {
-        mode: 'auto-upnp',
-        externalIp: opts.externalIp ?? '203.0.113.1',
-        externalPort: o.externalPort,
-        internalPort: o.internalPort,
-        protocol: o.protocol ?? 'tcp',
-        leaseExpiresAt: new Date(Date.now() + (o.ttlMs ?? 60_000)),
-      };
-    },
-    async verify() {
-      calls.verify++;
-      if (opts.verifyShouldThrow) throw opts.verifyShouldThrow;
-      return opts.verifyResult ?? true;
-    },
-    async externalIp() {
-      return opts.externalIp ?? '203.0.113.1';
-    },
-    async unmap() {
-      calls.unmap++;
-    },
-    async stop() {
-      calls.stop++;
-    },
-  };
-}
-
-function fakeTimers(): {
-  setTimer: (fn: () => void, ms: number) => NodeJS.Timeout;
-  clearTimer: (h: NodeJS.Timeout) => void;
-  fire(): void;
-  pending: number;
-} {
-  let callback: (() => void) | null = null;
-  return {
-    setTimer: (fn) => {
-      callback = fn;
-      return {} as NodeJS.Timeout;
-    },
-    clearTimer: () => {
-      callback = null;
-    },
-    fire: () => {
-      const cb = callback;
-      callback = null;
-      cb?.();
-    },
-    get pending() { return callback ? 1 : 0; },
-  };
-}
-
-describe('PortMapperService', () => {
-  it('installs the mapping on start and records mode + externalIp', async () => {
-    const mapper = makeFakeMapper({ externalIp: '203.0.113.42' });
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper,
-      externalPort: 4001,
-      internalPort: 4001,
-      setTimer: timers.setTimer,
-      clearTimer: timers.clearTimer,
-    });
-
-    await svc.start();
-    const state = svc.getState();
-    expect(state.mode).toBe('auto-upnp');
-    expect(state.routerExternalIp).toBe('203.0.113.42');
-    expect(state.externalPort).toBe(4001);
-    expect(state.lastError).toBeNull();
-    expect(mapper.calls.map).toBe(1);
-  });
-
-  it('flips to mode=failed when the mapper throws', async () => {
-    const mapper = makeFakeMapper({ mapShouldThrow: new NatError('mapping_failed', 'router said no') });
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper,
-      externalPort: 4001,
-      internalPort: 4001,
-      setTimer: timers.setTimer,
-      clearTimer: timers.clearTimer,
-    });
-
-    await svc.start();
-    expect(svc.getState().mode).toBe('failed');
-    expect(svc.getState().lastError).toContain('router said no');
-  });
-
-  it('unmaps and stops the mapper on stop()', async () => {
-    const mapper = makeFakeMapper();
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper,
-      externalPort: 4001,
-      internalPort: 4001,
-      setTimer: timers.setTimer,
-      clearTimer: timers.clearTimer,
-    });
-    await svc.start();
-    await svc.stop();
-    expect(mapper.calls.unmap).toBeGreaterThanOrEqual(1);
-    expect(mapper.calls.stop).toBeGreaterThanOrEqual(1);
-    expect(svc.getState().mode).toBe('disabled');
-  });
-
-  it('stop() is idempotent', async () => {
-    const mapper = makeFakeMapper();
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper, externalPort: 4001, internalPort: 4001,
-      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
-    });
-    await svc.start();
-    await svc.stop();
-    await svc.stop();
-    expect(mapper.calls.unmap).toBe(1);
-  });
-
-  it('refresh() re-maps when verify fails', async () => {
-    const mapper = makeFakeMapper({ verifyResult: false });
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper, externalPort: 4001, internalPort: 4001,
-      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
-    });
-    await svc.start();
-    expect(mapper.calls.map).toBe(1);
-
-    await svc.refresh();
-    // verify=false → re-map
-    expect(mapper.calls.map).toBe(2);
-  });
-
-  it('refresh() re-issues the mapping when verify succeeds (extends lease)', async () => {
-    const mapper = makeFakeMapper({ verifyResult: true });
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper, externalPort: 4001, internalPort: 4001,
-      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
-    });
-    await svc.start();
-    expect(mapper.calls.map).toBe(1);
-    await svc.refresh();
-    expect(mapper.calls.map).toBe(2);
-    expect(mapper.calls.verify).toBe(1);
-  });
-
-  it('schedules a refresh timer', async () => {
-    const mapper = makeFakeMapper();
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper, externalPort: 4001, internalPort: 4001,
-      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
-    });
-    await svc.start();
-    expect(timers.pending).toBe(1);
-
-    // Fire the timer — should re-arm after the inner refresh resolves.
-    timers.fire();
-    // Wait for the async refresh chain to complete.
-    await new Promise((r) => setTimeout(r, 0));
-    expect(timers.pending).toBe(1);
-  });
-});
+import { describe, expect, it } from 'vitest';
+
+import { NatError } from '../types.js';
+import {
+  PortMapperService,
+  type PortMapper,
+  type PortMappingResult,
+} from '../port-mapper.js';
+
+interface FakeOpts {
+  mapShouldThrow?: Error;
+  verifyResult?: boolean;
+  verifyShouldThrow?: Error;
+  externalIp?: string | null;
+}
+
+function makeFakeMapper(initial: FakeOpts = {}): PortMapper & {
+  calls: { map: number; verify: number; unmap: number; stop: number };
+  options: FakeOpts;
+} {
+  const opts = { ...initial };
+  const calls = { map: 0, verify: 0, unmap: 0, stop: 0 };
+  return {
+    options: opts,
+    calls,
+    async map(o): Promise<PortMappingResult> {
+      calls.map++;
+      if (opts.mapShouldThrow) throw opts.mapShouldThrow;
+      return {
+        mode: 'auto-upnp',
+        externalIp: opts.externalIp ?? '203.0.113.1',
+        externalPort: o.externalPort,
+        internalPort: o.internalPort,
+        protocol: o.protocol ?? 'tcp',
+        leaseExpiresAt: new Date(Date.now() + (o.ttlMs ?? 60_000)),
+      };
+    },
+    async verify() {
+      calls.verify++;
+      if (opts.verifyShouldThrow) throw opts.verifyShouldThrow;
+      return opts.verifyResult ?? true;
+    },
+    async externalIp() {
+      return opts.externalIp ?? '203.0.113.1';
+    },
+    async unmap() {
+      calls.unmap++;
+    },
+    async stop() {
+      calls.stop++;
+    },
+  };
+}
+
+function fakeTimers(): {
+  setTimer: (fn: () => void, ms: number) => NodeJS.Timeout;
+  clearTimer: (h: NodeJS.Timeout) => void;
+  fire(): void;
+  pending: number;
+} {
+  let callback: (() => void) | null = null;
+  return {
+    setTimer: (fn) => {
+      callback = fn;
+      return {} as NodeJS.Timeout;
+    },
+    clearTimer: () => {
+      callback = null;
+    },
+    fire: () => {
+      const cb = callback;
+      callback = null;
+      cb?.();
+    },
+    get pending() { return callback ? 1 : 0; },
+  };
+}
+
+describe('PortMapperService', () => {
+  it('installs the mapping on start and records mode + externalIp', async () => {
+    const mapper = makeFakeMapper({ externalIp: '203.0.113.42' });
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper,
+      externalPort: 4001,
+      internalPort: 4001,
+      setTimer: timers.setTimer,
+      clearTimer: timers.clearTimer,
+    });
+
+    await svc.start();
+    const state = svc.getState();
+    expect(state.mode).toBe('auto-upnp');
+    expect(state.routerExternalIp).toBe('203.0.113.42');
+    expect(state.externalPort).toBe(4001);
+    expect(state.lastError).toBeNull();
+    expect(mapper.calls.map).toBe(1);
+  });
+
+  it('flips to mode=failed when the mapper throws', async () => {
+    const mapper = makeFakeMapper({ mapShouldThrow: new NatError('mapping_failed', 'router said no') });
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper,
+      externalPort: 4001,
+      internalPort: 4001,
+      setTimer: timers.setTimer,
+      clearTimer: timers.clearTimer,
+    });
+
+    await svc.start();
+    expect(svc.getState().mode).toBe('failed');
+    expect(svc.getState().lastError).toContain('router said no');
+  });
+
+  it('unmaps and stops the mapper on stop()', async () => {
+    const mapper = makeFakeMapper();
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper,
+      externalPort: 4001,
+      internalPort: 4001,
+      setTimer: timers.setTimer,
+      clearTimer: timers.clearTimer,
+    });
+    await svc.start();
+    await svc.stop();
+    expect(mapper.calls.unmap).toBeGreaterThanOrEqual(1);
+    expect(mapper.calls.stop).toBeGreaterThanOrEqual(1);
+    expect(svc.getState().mode).toBe('disabled');
+  });
+
+  it('stop() is idempotent', async () => {
+    const mapper = makeFakeMapper();
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper, externalPort: 4001, internalPort: 4001,
+      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
+    });
+    await svc.start();
+    await svc.stop();
+    await svc.stop();
+    expect(mapper.calls.unmap).toBe(1);
+  });
+
+  it('refresh() re-maps when verify fails', async () => {
+    const mapper = makeFakeMapper({ verifyResult: false });
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper, externalPort: 4001, internalPort: 4001,
+      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
+    });
+    await svc.start();
+    expect(mapper.calls.map).toBe(1);
+
+    await svc.refresh();
+    // verify=false → re-map
+    expect(mapper.calls.map).toBe(2);
+  });
+
+  it('refresh() re-issues the mapping when verify succeeds (extends lease)', async () => {
+    const mapper = makeFakeMapper({ verifyResult: true });
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper, externalPort: 4001, internalPort: 4001,
+      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
+    });
+    await svc.start();
+    expect(mapper.calls.map).toBe(1);
+    await svc.refresh();
+    expect(mapper.calls.map).toBe(2);
+    expect(mapper.calls.verify).toBe(1);
+  });
+
+  it('schedules a refresh timer', async () => {
+    const mapper = makeFakeMapper();
+    const timers = fakeTimers();
+    const svc = new PortMapperService({
+      mapper, externalPort: 4001, internalPort: 4001,
+      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
+    });
+    await svc.start();
+    expect(timers.pending).toBe(1);
+
+    // Fire the timer — should re-arm after the inner refresh resolves.
+    timers.fire();
+    // Wait for the async refresh chain to complete.
+    await new Promise((r) => setTimeout(r, 0));
+    expect(timers.pending).toBe(1);
+  });
+});

package/src/nat/__tests__/reachability.test.ts

@@ -1,24 +1,24 @@
-import { describe, expect, it } from 'vitest';
-
-import { evaluateReachability } from '../reachability.js';
-
-describe('evaluateReachability', () => {
-  it('returns cgnat when cgnatDetected is true (overrides portMode)', () => {
-    expect(evaluateReachability({ portMode: 'auto-upnp', cgnatDetected: true })).toBe('cgnat');
-    expect(evaluateReachability({ portMode: 'failed', cgnatDetected: true })).toBe('cgnat');
-  });
-
-  it('returns reachable for auto-upnp / auto-natpmp', () => {
-    expect(evaluateReachability({ portMode: 'auto-upnp', cgnatDetected: false })).toBe('reachable');
-    expect(evaluateReachability({ portMode: 'auto-natpmp', cgnatDetected: false })).toBe('reachable');
-  });
-
-  it('returns unreachable when port mapping failed', () => {
-    expect(evaluateReachability({ portMode: 'failed', cgnatDetected: false })).toBe('unreachable');
-  });
-
-  it('returns unknown for manual / disabled', () => {
-    expect(evaluateReachability({ portMode: 'manual', cgnatDetected: false })).toBe('unknown');
-    expect(evaluateReachability({ portMode: 'disabled', cgnatDetected: false })).toBe('unknown');
-  });
-});
+import { describe, expect, it } from 'vitest';
+
+import { evaluateReachability } from '../reachability.js';
+
+describe('evaluateReachability', () => {
+  it('returns cgnat when cgnatDetected is true (overrides portMode)', () => {
+    expect(evaluateReachability({ portMode: 'auto-upnp', cgnatDetected: true })).toBe('cgnat');
+    expect(evaluateReachability({ portMode: 'failed', cgnatDetected: true })).toBe('cgnat');
+  });
+
+  it('returns reachable for auto-upnp / auto-natpmp', () => {
+    expect(evaluateReachability({ portMode: 'auto-upnp', cgnatDetected: false })).toBe('reachable');
+    expect(evaluateReachability({ portMode: 'auto-natpmp', cgnatDetected: false })).toBe('reachable');
+  });
+
+  it('returns unreachable when port mapping failed', () => {
+    expect(evaluateReachability({ portMode: 'failed', cgnatDetected: false })).toBe('unreachable');
+  });
+
+  it('returns unknown for manual / disabled', () => {
+    expect(evaluateReachability({ portMode: 'manual', cgnatDetected: false })).toBe('unknown');
+    expect(evaluateReachability({ portMode: 'disabled', cgnatDetected: false })).toBe('unknown');
+  });
+});