@serfab/cadre-host 0.7.1

package/dist/nat/types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * NAT/DDNS types for cadre-host.
+ *
+ * cadre-host runs on home/SMB machines that are typically behind NAT. To be
+ * dialable from the open internet the host must:
+ *   1. Punch a port forward on the upstream router (UPnP/NAT-PMP).
+ *   2. Detect its external IP (and whether it's behind CGNAT).
+ *   3. Optionally publish a stable hostname via dynamic DNS.
+ *
+ * State for these three concerns lives in `<rootDir>/nat.json` (user settings)
+ * and is exposed as a single `NatStatusSnapshot` to the management UI.
+ *
+ * Credentials for DDNS providers are NOT stored in `nat.json`. They go through
+ * the SecretsStore (keytar, with a 0600 file fallback).
+ */
+/** Port-forwarding mode currently in effect. */
+export type PortForwardMode = 'auto-upnp' | 'auto-natpmp' | 'manual' | 'failed' | 'disabled';
+/** Reachability verdict — best-effort heuristic until AutoNAT lands. */
+export type DirectReachability = 'reachable' | 'unreachable' | 'unknown' | 'cgnat';
+/** Snapshot returned to the management UI / CLI. */
+export interface NatStatusSnapshot {
+    portMode: PortForwardMode;
+    externalPort: number;
+    internalPort: number;
+    /** IP the router reports as its WAN address. Null when not auto-mapped. */
+    routerExternalIp: string | null;
+    /** ISO timestamp when the current mapping lease expires. */
+    mappingLeaseExpiresAt: string | null;
+    externalIp: string | null;
+    externalIpDetectedAt: string | null;
+    cgnatDetected: boolean;
+    directReachability: DirectReachability;
+    lastTestedAt: string | null;
+    ddns: NatDdnsStatus;
+}
+/** DDNS sub-section of the status snapshot. */
+export interface NatDdnsStatus {
+    /** Provider ID (e.g. "duckdns"), null when no DDNS is configured. */
+    providerId: string | null;
+    /** Configured hostname (e.g. "foo.duckdns.org"), null when unconfigured. */
+    hostname: string | null;
+    /** True when the user opted out of cadre-host updating the record. */
+    externallyManaged: boolean;
+    /** Last attempt timestamp (ISO), null until first attempt. */
+    lastUpdateAt: string | null;
+    /** Whether the most recent attempt succeeded. */
+    lastUpdateOk: boolean | null;
+    /** Most recent error message, null when last attempt succeeded. */
+    lastError: string | null;
+}
+/**
+ * On-disk shape of `nat.json`. NEVER contains DDNS credentials — those live
+ * in the SecretsStore.
+ */
+export interface NatSettingsFile {
+    version: 1;
+    /** External port to map (and announce). Default 4001. */
+    externalPort: number;
+    /** Internal libp2p port. Default 4001. */
+    internalPort: number;
+    /** Whether to attempt UPnP/NAT-PMP at all. */
+    upnpEnabled: boolean;
+    ddns: NatDdnsSettings;
+}
+/** DDNS sub-section of `nat.json`. */
+export interface NatDdnsSettings {
+    /** Provider ID (e.g. "duckdns"). Null = unconfigured. */
+    providerId: string | null;
+    /** Hostname to publish. Null = unconfigured. */
+    hostname: string | null;
+    /**
+     * True means the user maintains the DNS record themselves (e.g. via the
+     * provider's own auto-update agent on the router). cadre-host shows the
+     * hostname but never tries to update it.
+     */
+    externallyManaged: boolean;
+    /** DDNS update interval in milliseconds. Default 5 min. */
+    intervalMs: number;
+}
+/** Typed error codes for NatError. */
+export type NatErrorCode = 'mapping_failed' | 'router_unreachable' | 'ip_detection_failed' | 'ddns_provider_unknown' | 'ddns_credentials_missing' | 'ddns_update_failed' | 'secrets_unavailable' | 'storage_error' | 'invalid_config';
+/** Typed error carrying a stable `code` for HTTP mapping in the local-ui. */
+export declare class NatError extends Error {
+    readonly code: NatErrorCode;
+    constructor(code: NatErrorCode, message: string);
+}
+/** Description of a configurable field on a DDNS provider. */
+export interface DdnsConfigField {
+    /** Field key (e.g. "token"). */
+    key: string;
+    /** Human-readable label (e.g. "DuckDNS token"). */
+    label: string;
+    /** True if the value is a credential that must be stored in the SecretsStore. */
+    secret: boolean;
+}
+/** Summary of a DDNS provider for UI / CLI listing. */
+export interface DdnsProviderInfo {
+    id: string;
+    displayName: string;
+    configFields: ReadonlyArray<DdnsConfigField>;
+}
+/**
+ * Typed HTTP handlers exposed to `cadre-host-local-ui` for Fastify wiring.
+ *
+ * Like TrustCircleHandlers, these take typed objects and either return typed
+ * results or throw a `NatError` whose `.code` the UI ticket maps to an HTTP
+ * status code.
+ */
+export interface NatHandlers {
+    getStatus(): Promise<NatStatusSnapshot>;
+    testReachability(): Promise<NatStatusSnapshot>;
+    listDdnsProviders(): Promise<DdnsProviderInfo[]>;
+    putDdns(body: {
+        providerId: string;
+        hostname: string;
+        config: Record<string, string>;
+        externallyManaged?: boolean;
+    }): Promise<NatStatusSnapshot>;
+    putSettings(body: Partial<Omit<NatSettingsFile, 'version'>>): Promise<NatStatusSnapshot>;
+}

package/dist/nat/types.js

@@ -0,0 +1,24 @@
+/**
+ * NAT/DDNS types for cadre-host.
+ *
+ * cadre-host runs on home/SMB machines that are typically behind NAT. To be
+ * dialable from the open internet the host must:
+ *   1. Punch a port forward on the upstream router (UPnP/NAT-PMP).
+ *   2. Detect its external IP (and whether it's behind CGNAT).
+ *   3. Optionally publish a stable hostname via dynamic DNS.
+ *
+ * State for these three concerns lives in `<rootDir>/nat.json` (user settings)
+ * and is exposed as a single `NatStatusSnapshot` to the management UI.
+ *
+ * Credentials for DDNS providers are NOT stored in `nat.json`. They go through
+ * the SecretsStore (keytar, with a 0600 file fallback).
+ */
+/** Typed error carrying a stable `code` for HTTP mapping in the local-ui. */
+export class NatError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'NatError';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/nat/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/nat/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgGH,6EAA6E;AAC7E,MAAM,OAAO,QAAS,SAAQ,KAAK;IAGjC,YAAY,IAAkB,EAAE,OAAe;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/orchestrator/host-process-orchestrator.d.ts

@@ -0,0 +1,87 @@
+import type { Orchestrator, OrchestratorCreateRequest, OrchestratorCreateResult, OrchestratorStats } from '@serfab/cadre-provider';
+import { type PersistedHandle } from './state-store.js';
+import { type HostProcessConfig, type ManagedNodeInfo, type NodeStateListener } from './types.js';
+/**
+ * Runs cadre nodes as plain Node child processes on the host.
+ *
+ * Each container gets its own workdir under `rootDir`. Handles are mirrored
+ * to `<rootDir>/state.json` so cadre-host can re-attach after a restart.
+ *
+ * ## Child stdio: direct-fd inheritance
+ *
+ * Spawned children inherit a file descriptor opened on `<workdir>/node.log`
+ * directly as their stdout and stderr. The orchestrator closes its own copy
+ * of the fd immediately after spawn, so the child's write path no longer
+ * touches any handle owned by this process. This is what lets children
+ * survive — and keep logging through — an orchestrator restart. Were the
+ * orchestrator instead piping stdout/stderr through an in-process Writable,
+ * a parent exit would deliver SIGPIPE to the child (POSIX) or fail its
+ * writes with EPIPE (Windows), silently breaking the documented "init()
+ * re-attach" flow.
+ *
+ * ## Log rotation: spawn-time only
+ *
+ * Because the child holds a stable fd open against the inode, the
+ * orchestrator cannot safely rename `node.log` while the child is running.
+ * Rotation therefore happens only at spawn time, when no live child is
+ * attached to the workdir (`createContainer` is the single producer per
+ * workdir). If `node.log` already exceeds `logMaxBytes`, the rotation
+ * cascade runs against the on-disk paths before the fresh fd is opened.
+ * A child whose log grows past `logMaxBytes` mid-run will keep appending
+ * to the active file until it (or its successor) is restarted; v1 traffic
+ * is low enough that this is acceptable.
+ */
+export declare class HostProcessOrchestrator implements Orchestrator {
+    private readonly cfg;
+    private readonly rootDir;
+    private readonly portAllocator;
+    private readonly stateStore;
+    private readonly stopTimeoutMs;
+    private readonly logMaxBytes;
+    private readonly logMaxFiles;
+    private readonly defaultMemoryLimit?;
+    private readonly handles;
+    private readonly cliEntrypoint;
+    /** State-change listeners — invoked when a handle's alive state changes. */
+    private readonly stateListeners;
+    constructor(cfg: HostProcessConfig);
+    /**
+     * Read persisted state and re-attach to surviving children. Not part of
+     * `Orchestrator` — call once before handing the instance to a container
+     * service.
+     */
+    init(): Promise<void>;
+    /**
+     * Snapshot of currently-known managed nodes. Used by the local UI's
+     * `/api/nodes` route.
+     */
+    listNodes(): ManagedNodeInfo[];
+    /**
+     * Look up a single managed node by either containerId (friendly id) or
+     * dockerId (opaque `pid:token`). Returns undefined when neither matches.
+     */
+    getNode(idOrDockerId: string): ManagedNodeInfo | undefined;
+    /**
+     * Resolve the opaque dockerId for a friendly containerId so callers can
+     * pass it into stopContainer / getLogs / getStats.
+     */
+    resolveDockerId(idOrDockerId: string): string | undefined;
+    /**
+     * Register a state-change listener. Invoked when a handle's `alive`
+     * transitions (child exit, manual stop). Returns an unsubscribe fn.
+     */
+    onStateChange(listener: NodeStateListener): () => void;
+    /** Handles that init() found dead (PID gone or token mismatch). */
+    listDeadHandles(): PersistedHandle[];
+    createContainer(request: OrchestratorCreateRequest): Promise<OrchestratorCreateResult>;
+    stopContainer(dockerId: string): Promise<void>;
+    removeContainer(dockerId: string): Promise<void>;
+    isRunning(dockerId: string): Promise<boolean>;
+    getStats(dockerId: string): Promise<OrchestratorStats>;
+    getLogs(dockerId: string, tail?: number): Promise<string>;
+    private requireHandle;
+    private buildChildConfig;
+    private persist;
+    private emitStateChange;
+    private toPersisted;
+}