@camstack/server 1.0.0 → 1.0.1

package/dist/boot/boot-config.js

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * Phase 1: Bootstrap config loading and infrastructure setup.
+ *
+ * Extracted from main.ts — pure extraction, no behavior change.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadBootstrapConfig = loadBootstrapConfig;
+exports.autoGenerateJwtSecret = autoGenerateJwtSecret;
+exports.setupInfra = setupInfra;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const yaml = __importStar(require("js-yaml"));
+const node_crypto_1 = require("node:crypto");
+const types_1 = require("@camstack/types");
+const config_schema_1 = require("../core/config/config.schema");
+const storage_location_manager_1 = require("../core/storage/storage-location-manager");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const CONFIG_DEFAULTS = {
+    server: { port: 4443, host: '0.0.0.0', dataPath: 'camstack-data' },
+    auth: {
+        jwtSecret: null,
+        adminUsername: 'admin',
+        adminPassword: 'changeme',
+    },
+};
+const ENV_VAR_MAP = {
+    CAMSTACK_PORT: 'server.port',
+    CAMSTACK_HOST: 'server.host',
+    CAMSTACK_DATA: 'server.dataPath',
+    CAMSTACK_JWT_SECRET: 'auth.jwtSecret',
+    CAMSTACK_ADMIN_USER: 'auth.adminUsername',
+    CAMSTACK_ADMIN_PASS: 'auth.adminPassword',
+    CAMSTACK_HUB_URL: 'hub.url',
+    CAMSTACK_HUB_TOKEN: 'hub.token',
+    CAMSTACK_AGENT_NAME: 'agent.name',
+    CAMSTACK_TLS_ENABLED: 'tls.enabled',
+    CAMSTACK_TLS_CERT: 'tls.certPath',
+    CAMSTACK_TLS_KEY: 'tls.keyPath',
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function setNested(obj, p, value) {
+    const [head, ...rest] = p.split('.');
+    if (!head)
+        return obj;
+    if (rest.length === 0)
+        return { ...obj, [head]: value };
+    const child = (0, types_1.asJsonObject)(obj[head]) ?? {};
+    return { ...obj, [head]: setNested(child, rest.join('.'), value) };
+}
+// ---------------------------------------------------------------------------
+// loadBootstrapConfig
+// ---------------------------------------------------------------------------
+/**
+ * Load bootstrap config from a YAML file, apply env-var overrides, and
+ * validate via the bootstrap Zod schema.
+ */
+function loadBootstrapConfig(configPath) {
+    // Only bootstrap sections live in config.yaml.
+    // All runtime settings are stored in the SQL system_settings table.
+    let raw;
+    if (fs.existsSync(configPath)) {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        raw = (0, types_1.asJsonObject)(yaml.load(content)) ?? {};
+        // Merge in any missing bootstrap sections (server, auth only)
+        let updated = false;
+        for (const [key, defaults] of Object.entries(CONFIG_DEFAULTS)) {
+            if (!(key in raw)) {
+                raw[key] = defaults;
+                updated = true;
+            }
+        }
+        if (updated) {
+            try {
+                const tmpPath = `${configPath}.tmp`;
+                fs.writeFileSync(tmpPath, yaml.dump(raw, { lineWidth: 120, indent: 2, quotingType: '"' }), 'utf-8');
+                fs.renameSync(tmpPath, configPath);
+                console.log(`[Phase1] Updated config.yaml with missing bootstrap defaults`);
+            }
+            catch (err) {
+                console.warn(`[Phase1] Could not update config.yaml:`, err);
+            }
+        }
+        console.log(`[Phase1] Loaded bootstrap config from: ${configPath}`);
+    }
+    else {
+        console.log(`[Phase1] Config file not found at: ${configPath} — writing defaults`);
+        const defaults = { ...CONFIG_DEFAULTS };
+        try {
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            const tmpPath = `${configPath}.tmp`;
+            fs.writeFileSync(tmpPath, yaml.dump(defaults, { lineWidth: 120, indent: 2, quotingType: '"' }), 'utf-8');
+            fs.renameSync(tmpPath, configPath);
+            console.log(`[Phase1] Default config.yaml written to: ${configPath}`);
+        }
+        catch (err) {
+            console.warn(`[Phase1] Could not write default config.yaml:`, err);
+        }
+        raw = defaults;
+    }
+    // Apply env var overrides for bootstrap keys
+    for (const [envKey, configPath_] of Object.entries(ENV_VAR_MAP)) {
+        const envValue = process.env[envKey];
+        if (envValue === undefined || envValue === '')
+            continue;
+        const coerced = configPath_ === 'server.port'
+            ? Number(envValue)
+            : configPath_ === 'tls.enabled'
+                ? envValue === 'true'
+                : envValue;
+        raw = setNested(raw, configPath_, coerced);
+        console.log(`[Phase1] Env override: ${envKey} → ${configPath_}`);
+    }
+    return config_schema_1.bootstrapSchema.parse(raw);
+}
+// ---------------------------------------------------------------------------
+// autoGenerateJwtSecret
+// ---------------------------------------------------------------------------
+/**
+ * If `jwtSecret` is null in the parsed config, generate a random secret,
+ * persist it to the YAML file, and return an updated config.
+ */
+function autoGenerateJwtSecret(configPath, bootstrapConfig) {
+    if (bootstrapConfig.auth.jwtSecret !== null) {
+        return bootstrapConfig;
+    }
+    const secret = (0, node_crypto_1.randomBytes)(32).toString('hex');
+    console.log('[Phase1] jwtSecret is null — auto-generating and writing to config.yaml');
+    let raw = {};
+    if (fs.existsSync(configPath)) {
+        raw = (0, types_1.asJsonObject)(yaml.load(fs.readFileSync(configPath, 'utf-8'))) ?? {};
+    }
+    const authSection = (0, types_1.asJsonObject)(raw.auth) ?? {};
+    raw.auth = { ...authSection, jwtSecret: secret };
+    const tmpPath = `${configPath}.tmp`;
+    try {
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        fs.writeFileSync(tmpPath, yaml.dump(raw, { lineWidth: 120, indent: 2, quotingType: '"' }), 'utf-8');
+        fs.renameSync(tmpPath, configPath);
+    }
+    catch (err) {
+        console.warn('[Phase1] Could not write auto-generated jwtSecret to config.yaml:', err);
+    }
+    return {
+        ...bootstrapConfig,
+        auth: { ...bootstrapConfig.auth, jwtSecret: secret },
+    };
+}
+// ---------------------------------------------------------------------------
+// setupInfra
+// ---------------------------------------------------------------------------
+/**
+ * Phase 2: Create StorageLocationManager, ensure directories, configure TLS.
+ * Returns the full InfraContext needed by subsequent boot phases.
+ */
+async function setupInfra(configPath, bootstrapConfig) {
+    // Auto-generate jwtSecret if not set
+    const config = autoGenerateJwtSecret(configPath, bootstrapConfig);
+    const dataPath = path.resolve(config.server.dataPath);
+    const port = config.server.port;
+    const host = config.server.host;
+    console.log(`[Phase1] Bootstrap: port=${port}, host=${host}, dataPath=${dataPath}`);
+    // --- Phase 2: Init StorageLocationManager → ensure all dirs exist ---
+    console.log('[Phase2] Initializing storage locations…');
+    const locationManager = new storage_location_manager_1.StorageLocationManager(dataPath);
+    await locationManager.initializeDefaults();
+    const locationStatus = locationManager.getStatus();
+    for (const { name, available, path: locPath } of locationStatus) {
+        console.log(`[Phase2] Location "${name}": ${available ? 'OK' : 'UNAVAILABLE'} → ${locPath}`);
+    }
+    // --- Phase 2c: TLS certificate setup ---
+    let tlsOptions;
+    if (config.tls.enabled) {
+        // Use require() instead of import() — the ESM build of @camstack/core has
+        // broken chunks with require("fs") when leaked .js files exist in core/src/.
+        // CJS build works correctly and tsx supports require().
+        const core = require('@camstack/core');
+        const { ensureTlsCert, loadTlsCert } = core;
+        if (config.tls.certPath && config.tls.keyPath) {
+            // User-provided cert
+            console.log(`[Phase2c] Loading custom TLS cert from ${config.tls.certPath}`);
+            const pair = loadTlsCert(config.tls.certPath, config.tls.keyPath);
+            tlsOptions = { key: pair.key, cert: pair.cert };
+        }
+        else {
+            // Auto-generate self-signed
+            const tlsResult = await ensureTlsCert(dataPath);
+            if (tlsResult.generated) {
+                console.log(`[Phase2c] Generated self-signed TLS cert at ${tlsResult.certPath}`);
+            }
+            else {
+                console.log(`[Phase2c] Using existing TLS cert at ${tlsResult.certPath}`);
+            }
+            const pair = loadTlsCert(tlsResult.certPath, tlsResult.keyPath);
+            tlsOptions = { key: pair.key, cert: pair.cert };
+        }
+    }
+    return {
+        bootstrapConfig: config,
+        dataPath,
+        locationManager,
+        tlsOptions,
+    };
+}

package/dist/boot/integration-id-backfill.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * One-time integration-id backfill for devices created before the
+ * device-manager forwarder started stamping `integrationId` (camera
+ * providers). Maps each addon that hosts EXACTLY ONE integration to that
+ * integration id, then stamps top-level untagged devices of those addons.
+ * Multi-instance addons (e.g. Home Assistant with several brokers) are
+ * ambiguous on `addonId` alone and are skipped — they stamp going forward.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planIntegrationIdBackfill = planIntegrationIdBackfill;
+exports.planDeleteTimeStamps = planDeleteTimeStamps;
+exports.runIntegrationIdBackfill = runIntegrationIdBackfill;
+function planIntegrationIdBackfill(integrations, devices) {
+    const singleByAddon = new Map();
+    const ambiguous = new Set();
+    for (const integration of integrations) {
+        if (ambiguous.has(integration.addonId))
+            continue;
+        if (singleByAddon.has(integration.addonId)) {
+            singleByAddon.delete(integration.addonId);
+            ambiguous.add(integration.addonId);
+            continue;
+        }
+        singleByAddon.set(integration.addonId, integration.id);
+    }
+    const stamps = [];
+    for (const device of devices) {
+        if (device.parentDeviceId !== null)
+            continue;
+        if (device.integrationId !== undefined && device.integrationId !== '')
+            continue;
+        const integrationId = singleByAddon.get(device.addonId);
+        if (integrationId === undefined)
+            continue;
+        stamps.push({ deviceId: device.id, integrationId });
+    }
+    return stamps;
+}
+/**
+ * Stamps to apply at integration-DELETE time so a cascade removes legacy
+ * un-tagged devices too. The boot backfill only runs on startup; a device
+ * created before stamping (or whose provider never stamps, e.g. `provider-rtsp`)
+ * keeps no `integrationId`, so once its integration is deleted it would orphan
+ * forever — `removeByIntegration` matches on `integrationId` and finds nothing.
+ *
+ * Run this in the delete handler BEFORE deleting the integration record (while
+ * it is still present in `integrations`), then stamp the returned devices and
+ * let `removeByIntegration` cascade them. Reuses the boot backfill's safety
+ * rule (only addons hosting exactly ONE integration are unambiguous) and
+ * filters to the integration being deleted so siblings are never touched.
+ */
+function planDeleteTimeStamps(integrationId, integrations, devices) {
+    return planIntegrationIdBackfill(integrations, devices).filter((stamp) => stamp.integrationId === integrationId);
+}
+async function runIntegrationIdBackfill(deps) {
+    const [integrations, devices] = await Promise.all([deps.listIntegrations(), deps.listDevices()]);
+    const stamps = planIntegrationIdBackfill(integrations, devices);
+    let stamped = 0;
+    for (const stamp of stamps) {
+        try {
+            await deps.setIntegrationId(stamp.deviceId, stamp.integrationId);
+            stamped++;
+        }
+        catch (err) {
+            deps.logger.warn('integrationId backfill: stamp failed', {
+                deviceId: stamp.deviceId,
+                integrationId: stamp.integrationId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (stamped > 0)
+        deps.logger.info('integrationId backfill complete', { stamped });
+    return { stamped };
+}

package/dist/boot/post-boot.service.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostBootService = void 0;
+const node_crypto_1 = require("node:crypto");
+const kernel_1 = require("@camstack/kernel");
+const types_1 = require("@camstack/types");
+class PostBootService {
+    eventBus;
+    logger;
+    /**
+     * Holds the marker that fired `system.restart-completed` on this boot
+     * for `LAST_RESTART_RETENTION_MS`. Lets clients query the marker
+     * after they reconnect — the live event itself is emitted before the
+     * WS resubscribe has a chance to land.
+     */
+    static lastRestart = null;
+    /** How long the last-restart marker stays queryable after boot (5 min). */
+    static LAST_RESTART_RETENTION_MS = 5 * 60_000;
+    constructor(_addonRegistry, eventBus, loggingService) {
+        this.eventBus = eventBus;
+        this.logger = loggingService.createLogger('PostBoot');
+    }
+    /**
+     * Snapshot of the most-recent restart marker, or `null` after the
+     * retention window. The hub's `addons.getLastRestart` cap method
+     * delegates here.
+     */
+    static getLastRestart() {
+        const entry = PostBootService.lastRestart;
+        if (entry === null)
+            return null;
+        if (entry.expiresAt <= Date.now()) {
+            PostBootService.lastRestart = null;
+            return null;
+        }
+        return entry.payload;
+    }
+    async run(context) {
+        const { port, host, dataPath, trpcRegistered } = context;
+        // Device stream wiring moved into `addon-stream-broker` — the addon
+        // does its own initial sync against `ctx.deviceRegistry` plus listens
+        // to `DeviceRegistered` events for future registrations. No kernel
+        // orchestration shim needed here anymore.
+        // Emit system.boot event
+        this.eventBus.emit({
+            id: (0, node_crypto_1.randomUUID)(),
+            timestamp: new Date(),
+            source: { type: 'core', id: 'system' },
+            category: types_1.EventCategory.SystemBoot,
+            data: { port, host, trpcRegistered, dataPath },
+        });
+        // If the previous shutdown was driven by RestartCoordinator, emit a
+        // `system.restart-completed` event so the admin UI can surface a
+        // success toast describing what changed (framework update, manual
+        // restart, …). `readPendingRestart` clears the marker atomically so
+        // we never re-fire on a crash-loop boot.
+        this.emitRestartCompletedIfPending(dataPath);
+    }
+    emitRestartCompletedIfPending(dataDir) {
+        const marker = (0, kernel_1.readPendingRestart)(dataDir);
+        if (marker === null)
+            return;
+        const payload = {
+            kind: marker.kind,
+            requestedAt: marker.requestedAt,
+            ...(marker.packageName !== undefined ? { packageName: marker.packageName } : {}),
+            ...(marker.fromVersion !== undefined ? { fromVersion: marker.fromVersion } : {}),
+            ...(marker.toVersion !== undefined ? { toVersion: marker.toVersion } : {}),
+            ...(marker.requestedBy !== undefined ? { requestedBy: marker.requestedBy } : {}),
+        };
+        this.logger.info('Restart completed', { meta: payload });
+        PostBootService.lastRestart = {
+            payload,
+            expiresAt: Date.now() + PostBootService.LAST_RESTART_RETENTION_MS,
+        };
+        this.eventBus.emit({
+            id: (0, node_crypto_1.randomUUID)(),
+            timestamp: new Date(),
+            source: { type: 'core', id: 'system' },
+            category: types_1.EventCategory.SystemRestartCompleted,
+            data: payload,
+        });
+    }
+}
+exports.PostBootService = PostBootService;

package/dist/core/addon/addon-call-gateway.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AddonCallGateway = void 0;
+const REMOTE_TIMEOUT_MS = 10_000;
+class AddonCallGateway {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Classify where an addon runs. `nodeId: 'hub'` from a caller means "the hub
+     * cluster", NOT "force in-process" — a forked hub-local addon is still a
+     * `hub-local-child` (UDS), never the in-process path (which is only the
+     * `@camstack/core` builtins that have no forked runner).
+     */
+    classify(addonId, explicitNodeId) {
+        const resolved = this.deps.resolveNode(addonId);
+        const onHub = resolved === 'hub' || resolved === this.deps.hubNodeId;
+        if (onHub) {
+            const childRegistry = this.deps.getChildRegistry();
+            if (childRegistry !== null && childRegistry.isChildKnown(addonId)) {
+                return { kind: 'hub-local-child' };
+            }
+            return { kind: 'in-process' };
+        }
+        const onThisHub = explicitNodeId === 'hub' || explicitNodeId === this.deps.hubNodeId;
+        const baseNodeId = explicitNodeId && !onThisHub ? explicitNodeId : resolved;
+        return { kind: 'remote-agent', baseNodeId };
+    }
+    /** True when the addon is an in-process hub builtin (caller invokes directly). */
+    isInProcess(addonId, explicitNodeId) {
+        return this.classify(addonId, explicitNodeId).kind === 'in-process';
+    }
+    /**
+     * Dispatch a forked addon-level call to wherever the addon runs:
+     *   - `hub-local-child` → UDS `LocalChildRegistry.callAddonOnChild`
+     *   - `remote-agent`    → Moleculer `broker.call`
+     * Throws for `in-process` — that addon has no forked surface, so the caller
+     * must invoke the in-process instance directly (the invocation is
+     * surface-specific; only the ROUTING is centralised here).
+     */
+    async callForked(addonId, input, explicitNodeId) {
+        const dest = this.classify(addonId, explicitNodeId);
+        const fullInput = { ...input, addonId };
+        switch (dest.kind) {
+            case 'hub-local-child': {
+                const childRegistry = this.deps.getChildRegistry();
+                if (childRegistry === null) {
+                    throw new Error(`AddonCallGateway: child registry unavailable for "${addonId}"`);
+                }
+                return childRegistry.callAddonOnChild(addonId, fullInput);
+            }
+            case 'remote-agent':
+                return this.callRemoteAgent(addonId, dest.baseNodeId, fullInput);
+            case 'in-process':
+                throw new Error(`AddonCallGateway: addon "${addonId}" runs in-process — invoke it directly`);
+            default: {
+                const _exhaustive = dest;
+                throw new Error(`AddonCallGateway: unhandled destination ${JSON.stringify(_exhaustive)}`);
+            }
+        }
+    }
+    /** Map an addon-level call to the remote agent's Moleculer action. */
+    async callRemoteAgent(addonId, baseNodeId, input) {
+        const workerNodeId = this.resolveWorkerNodeId(addonId, baseNodeId);
+        const opts = workerNodeId
+            ? { nodeID: workerNodeId, timeout: REMOTE_TIMEOUT_MS }
+            : { timeout: REMOTE_TIMEOUT_MS };
+        if (input.target === 'settings') {
+            if (input.method == null) {
+                throw new Error(`AddonCallGateway: settings call to "${addonId}" missing method`);
+            }
+            return this.deps.broker.call(`${addonId}.settings.${input.method}`, (input.args ?? {}), opts);
+        }
+        // routes/custom are hub-local-child surfaces (mounted / invoked on the
+        // owning node); they are not proxied to a remote agent through this gateway.
+        throw new Error(`AddonCallGateway: target "${input.target}" not supported for remote agent "${baseNodeId}"`);
+    }
+    /**
+     * Resolve the Moleculer nodeID that actually hosts an addon's service.
+     * Forkable addons register under `${baseNodeId}/${addonId}`; in-process
+     * addons under the base nodeId. The registry is the ground truth — baseNodeId
+     * is a hint. (Moved verbatim from `addon-settings-provider.ts`.)
+     */
+    resolveWorkerNodeId(addonId, baseNodeId) {
+        const registry = this.deps.broker.registry;
+        const services = registry.getServiceList({ onlyAvailable: true });
+        const exactNode = `${baseNodeId}/${addonId}`;
+        const preferred = services.find((s) => s.name === addonId && s.nodeID === exactNode);
+        if (preferred)
+            return preferred.nodeID;
+        const anyForBase = services.find((s) => s.name === addonId && s.nodeID === baseNodeId);
+        if (anyForBase)
+            return anyForBase.nodeID;
+        const anyWithName = services.find((s) => s.name === addonId);
+        return anyWithName?.nodeID ?? null;
+    }
+}
+exports.AddonCallGateway = AddonCallGateway;