@serfab/cadre-host 1.13.0 → 1.15.0

package/src/nat/address-watch.ts

@@ -0,0 +1,92 @@
+import debug from 'debug';
+
+import type { ManagedNodeInfo } from '../orchestrator/types.js';
+
+const log = debug('cadre:host:nat-address-watch');
+
+/**
+ * The shortest gap between two address restarts of one node. Bounds a flapping
+ * router (a mapping that keeps failing and coming back) to one restart per node
+ * per window; a difference found inside the window waits for the first check
+ * after it ends.
+ */
+export const NAT_ADDRESS_RESTART_MIN_INTERVAL_MS = 10 * 60_000;
+
+/** Asked to restart one node so it starts announcing its current public addresses. */
+export type NodeAddressesStaleListener = (nodeId: string) => void | Promise<void>;
+
+/**
+ * Notices a running node whose announced public addresses differ from the ones
+ * it should announce now, and asks its listeners to restart that node. A node
+ * learns its public addresses only at start (`CADRE_APPEND_ANNOUNCE_ADDRS`), so
+ * a restart is how a changed mapping, forward, DDNS hostname or external IP
+ * reaches it.
+ */
+export class AddressWatch {
+  private readonly listeners = new Set<NodeAddressesStaleListener>();
+  /** When each node was last asked to restart (ms since epoch). */
+  private readonly lastRestartAt = new Map<string, number>();
+
+  constructor(private readonly now: () => number) {}
+
+  /** Register a restart listener. Returns an unsubscribe fn. */
+  subscribe(listener: NodeAddressesStaleListener): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  /**
+   * Compare every running node's announced addresses with `expected(node)`, as
+   * sets, and ask for a restart of each that differs and was not restarted
+   * within {@link NAT_ADDRESS_RESTART_MIN_INTERVAL_MS}.
+   */
+  check(nodes: ManagedNodeInfo[], expected: (node: ManagedNodeInfo) => string[]): void {
+    this.forgetMissing(nodes);
+    if (this.listeners.size === 0) return;
+    for (const node of nodes) {
+      if (node.status !== 'running') continue;
+      if (sameAddressSet(node.announcedAddrs, expected(node))) continue;
+      if (this.restartedRecently(node.id)) {
+        log('node %s announces stale addresses; restart deferred by the rate limit', node.id);
+        continue;
+      }
+      this.lastRestartAt.set(node.id, this.now());
+      log('node %s announces stale addresses; asking for a restart', node.id);
+      this.notify(node.id);
+    }
+  }
+
+  /** A terminated node's id may come back as a fresh node, which owes nothing to the old window. */
+  private forgetMissing(nodes: ManagedNodeInfo[]): void {
+    const listed = new Set(nodes.map((n) => n.id));
+    for (const id of this.lastRestartAt.keys()) {
+      if (!listed.has(id)) this.lastRestartAt.delete(id);
+    }
+  }
+
+  private restartedRecently(nodeId: string): boolean {
+    const last = this.lastRestartAt.get(nodeId);
+    return last !== undefined && this.now() - last < NAT_ADDRESS_RESTART_MIN_INTERVAL_MS;
+  }
+
+  /** Fire-and-forget: a restart takes seconds and must not hold up the NAT pass that found it. */
+  private notify(nodeId: string): void {
+    for (const listener of this.listeners) {
+      try {
+        void Promise.resolve(listener(nodeId)).catch((err: unknown) => { logRestartFailure(nodeId, err); });
+      } catch (err) {
+        logRestartFailure(nodeId, err);
+      }
+    }
+  }
+}
+
+function sameAddressSet(a: readonly string[], b: readonly string[]): boolean {
+  const left = new Set(a);
+  const right = new Set(b);
+  return left.size === right.size && [...left].every((addr) => right.has(addr));
+}
+
+function logRestartFailure(nodeId: string, err: unknown): void {
+  log('address restart of node %s failed: %s', nodeId, err instanceof Error ? err.message : String(err));
+}

package/src/nat/ddns/duckdns.ts

@@ -13,7 +13,8 @@ const log = debug('cadre:host:nat-ddns:duckdns');
  * Response is plain text — `OK` on success, `KO` on failure.
  *
  * `hostname` may be supplied as the bare subdomain (`foo`) or the FQDN
- * (`foo.duckdns.org`); we strip the suffix.
+ * (`foo.duckdns.org`); the update strips the suffix, and `qualifyHostname`
+ * adds it.
  */
 export const duckDnsProvider: DdnsProvider = {
   id: 'duckdns',
@@ -21,6 +22,9 @@ export const duckDnsProvider: DdnsProvider = {
   configFields: [
     { key: 'token', label: 'DuckDNS token', secret: true },
   ],
+  qualifyHostname(hostname: string): string {
+    return `${stripSuffix(hostname)}${SUFFIX}`;
+  },
   async update(
     config: Record<string, string>,
     hostname: string,

package/src/nat/ddns/index.ts

@@ -19,6 +19,12 @@ export interface DdnsProvider {
   readonly id: string;
   readonly displayName: string;
   readonly configFields: ReadonlyArray<DdnsConfigField>;
+  /**
+   * The fully qualified name the provider publishes for a hostname as the user
+   * typed it. Stored in place of the typed form because hosted nodes announce the
+   * stored hostname as `/dns4/<hostname>`, so it has to resolve on its own.
+   */
+  qualifyHostname(hostname: string): string;
   /** Push `ip` for `hostname`. Throws NatError(ddns_update_failed) on failure. */
   update(
     config: Record<string, string>,

package/src/nat/index.ts

@@ -2,24 +2,42 @@
  * NAT / DDNS substrate for cadre-host.
  *
  * See ./nat-service.ts for the top-level orchestrator and `docs/cadre-host.md`
- * for integration notes (the long-running process owner is `cadre-host-local-ui`).
+ * for integration notes (the long-running process owner is `cadre-host start`).
  */
 
-export { NatService, createNatHandlers } from './nat-service.js';
-export type { NatServiceOptions, CadreNodeLike, AddressesChangedListener } from './nat-service.js';
+export {
+  NatService,
+  createNatHandlers,
+  NAT_UNMAP_GRACE_MS,
+  NAT_RECONCILE_INTERVAL_MS,
+  NAT_IP_REDETECT_INTERVAL_MS,
+} from './nat-service.js';
+export type { NatServiceOptions, NatNodeSource, NatChangeListener } from './nat-service.js';
+export { NAT_ADDRESS_RESTART_MIN_INTERVAL_MS } from './address-watch.js';
+export type { NodeAddressesStaleListener } from './address-watch.js';
 export { NatStore } from './nat-store.js';
 export {
   NatError,
 } from './types.js';
 export type {
   NatStatusSnapshot,
+  NatGatewayStatus,
   NatDdnsStatus,
+  NatNetworkStatus,
+  NetworkMode,
+  NetworkSetting,
   NatSettingsFile,
   NatDdnsSettings,
   NatHandlers,
   NatErrorCode,
-  PortForwardMode,
   DirectReachability,
+  NodeReachability,
+  NodeVerdict,
+  PortKind,
+  PortRoute,
+  PortRouteSource,
+  ManualForward,
+  ManualForwardPatch,
   DdnsProviderInfo,
   DdnsConfigField,
 } from './types.js';
@@ -33,21 +51,23 @@ export type {
   ExternalIpDetectorOptions,
 } from './external-ip.js';
 export {
-  PortMapperService,
-  createDefaultPortMapper,
+  UpnpPortMapper,
+  pickLanAddress,
   DEFAULT_LEASE_TTL_MS,
   DEFAULT_REFRESH_MS,
+  GATEWAY_DISCOVERY_TIMEOUT_MS,
 } from './port-mapper.js';
 export type {
   PortMapper,
-  PortMappingResult,
-  PortMapOptions,
-  PortMapperState,
-  PortMapperServiceOptions,
+  GatewayInfo,
+  PortMapRequest,
+  PortMapResult,
 } from './port-mapper.js';
-export { evaluateReachability } from './reachability.js';
-export { buildInviteAddresses } from './address-resolver.js';
-export type { BuildInviteAddressesInput } from './address-resolver.js';
+export { evaluateNodeReachability, evaluateHostReachability } from './reachability.js';
+export type { NodeVerdictInput, NodeVerdictResult } from './reachability.js';
+export { buildPublicAddresses, isPublicIpv4 } from './address-resolver.js';
+export { publicInterfaceAddress, effectiveNetworkMode } from './network-mode.js';
+export type { PublicAddressInput } from './address-resolver.js';
 export {
   BUILTIN_PROVIDERS,
   getProvider,