@camstack/server 0.2.2 → 1.0.1

package/dist/core/logging/logging.service.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoggingService = void 0;
+const core_1 = require("@camstack/core");
+const types_1 = require("@camstack/types");
+/** Baseline tags every hub-local logger gets, so console output never
+ *  falls back to `?` for the agent slot. Hub-local addons already
+ *  re-tag with their addonId; this ensures non-addon scopes (core
+ *  services like `AddonRegistry`, `StreamProbeService`, `moleculer`)
+ *  render as `hub` in the agent column.
+ *
+ *  `pid` is the hub renderer's own OS pid. Entries forwarded from
+ *  forked workers via `$hub.log` carry their own `tags.pid` which
+ *  wins over this baseline (right-biased merge in `writeFromWorker`). */
+const HUB_BASELINE_TAGS = { agentId: 'hub', nodeId: 'hub', pid: process.pid };
+class LoggingService extends core_1.LogManager {
+    /**
+     * Device-name cache consulted by the formatter when a log line
+     * carries `tags.deviceId` but no explicit `deviceName`. Populated
+     * by `setDeviceNames` whenever device-manager emits registered /
+     * updated / removed events. Missing entries fall back to `#<id>`.
+     */
+    deviceNames = new Map();
+    constructor(configService) {
+        // The log buffer is now partitioned per addonId (see PartitionedLogBuffer):
+        // this value caps EACH addon's bucket, not the total. A chatty addon evicts
+        // only its own lines, so quiet addons (e.g. a HomeAssistant `image` entity)
+        // keep their sparse history. `eventBus.ringBufferSize` still sizes the
+        // separate system-event ring; logs get their own per-addon cap.
+        const perAddonCapacity = configService.get('eventBus.perAddonLogBufferSize') ?? 5000;
+        super(perAddonCapacity);
+        // Enriches every emitted LogEntry with `tags.deviceName` before
+        // destinations / subscribers see it — works across bundled copies
+        // of `@camstack/core` (addon packages) because the mutation
+        // happens upstream of their formatters.
+        this.setDeviceNameLookup((id) => this.deviceNames.get(id) ?? null);
+    }
+    /** Bulk-refresh from device-manager snapshot. Replaces every entry. */
+    setDeviceNames(entries) {
+        this.deviceNames.clear();
+        for (const { id, name } of entries) {
+            if (typeof id === 'number' &&
+                Number.isFinite(id) &&
+                typeof name === 'string' &&
+                name.length > 0) {
+                this.deviceNames.set(id, name);
+            }
+        }
+    }
+    /** Incremental update — called from DeviceRegistered / DeviceUpdated. */
+    upsertDeviceName(id, name) {
+        if (!Number.isFinite(id))
+            return;
+        if (typeof name === 'string' && name.length > 0)
+            this.deviceNames.set(id, name);
+        else
+            this.deviceNames.delete(id);
+    }
+    /** Drop on DeviceRemoved. */
+    removeDeviceName(id) {
+        this.deviceNames.delete(id);
+    }
+    /**
+     * Subscribe to `device.*` events so the cache stays live: every
+     * DeviceRegistered / updated emit carries `{deviceId, name}` — we
+     * upsert, and DeviceUnregistered clears. Call once at boot.
+     */
+    attachDeviceNameStream(eventBus) {
+        const selfLogger = this.createLogger('logging').withTags({ addonId: 'logging' });
+        eventBus.subscribe({ category: types_1.EventCategory.DeviceRegistered }, (event) => {
+            const data = event.data;
+            if (data && typeof data.deviceId === 'number') {
+                this.upsertDeviceName(data.deviceId, data.name);
+                selfLogger.info('device-name cache upserted', {
+                    meta: {
+                        deviceId: data.deviceId,
+                        name: data.name ?? null,
+                        cacheSize: this.deviceNames.size,
+                    },
+                });
+            }
+        });
+        eventBus.subscribe({ category: types_1.EventCategory.DeviceUnregistered }, (event) => {
+            const data = event.data;
+            if (data && typeof data.deviceId === 'number')
+                this.removeDeviceName(data.deviceId);
+        });
+    }
+    /**
+     * Override — every logger created hub-side comes pre-tagged with
+     * `agentId: 'hub'`. Callers that need per-addon identity chain
+     * `.withTags({ addonId })` on top (the merge is right-biased, so
+     * the explicit tag wins).
+     */
+    createLogger(scope) {
+        return super.createLogger(scope).withTags(HUB_BASELINE_TAGS);
+    }
+    /**
+     * Write a log entry received from a forked worker / remote agent.
+     * Called by the `$hub.log` action and `log-receiver.ingest` action.
+     *
+     * Tags propagated by the worker (including `deviceId`, `deviceName`,
+     * `integrationId`, `streamId`, etc.) are preserved via `withTags`;
+     * baseline tags (`addonId`, `nodeId`, `agentId`) are always ensured
+     * even if the worker didn't set them explicitly.
+     */
+    writeFromWorker(entry) {
+        // Scope is a single optional sub-component label; addon/node identity
+        // lives in tags, not in scope. Pass through whatever the worker set.
+        let logger = this.createLogger(entry.scope);
+        const nodeId = entry.nodeId;
+        const agentId = nodeId?.includes('/') ? nodeId.split('/')[0] : nodeId;
+        const mergedTags = {
+            ...entry.tags,
+            addonId: entry.addonId,
+            ...(nodeId !== undefined ? { nodeId } : {}),
+            ...(agentId !== undefined ? { agentId } : {}),
+        };
+        logger = logger.withTags(mergedTags);
+        const level = entry.level;
+        const extras = entry.meta !== undefined ? { meta: entry.meta } : undefined;
+        if (typeof logger[level] === 'function') {
+            logger[level](entry.message, extras);
+        }
+        else {
+            logger.info(entry.message, extras);
+        }
+    }
+}
+exports.LoggingService = LoggingService;

package/dist/core/logging/scoped-logger.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopedLogger = void 0;
+// Re-export from @camstack/core
+var core_1 = require("@camstack/core");
+Object.defineProperty(exports, "ScopedLogger", { enumerable: true, get: function () { return core_1.ScopedLogger; } });

package/dist/core/moleculer/cap-call-fn.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCapCallFn = buildCapCallFn;
+/** Extract a numeric `deviceId` routing hint out of arbitrary method args. */
+function extractDeviceId(params) {
+    if (params === null || typeof params !== 'object')
+        return undefined;
+    const raw = Reflect.get(params, 'deviceId');
+    return typeof raw === 'number' ? raw : undefined;
+}
+/**
+ * Build the `CallFn` (`(method, params, targetNodeId?) => Promise`) for one
+ * registered provider. See module docs for the routing rationale.
+ */
+function buildCapCallFn(deps) {
+    return async (method, params, targetNodeId) => {
+        const deviceId = extractDeviceId(params);
+        // ── Hub-local child: route per-child over UDS (collection-safe — keyed by
+        //    the specific child, not by capName which would collapse a collection
+        //    cap onto the first child). NEVER fall back to Moleculer: a hub-local
+        //    child is not a Moleculer service, so a broker call would wait the full
+        //    discovery timeout for a node that never appears. If the child isn't
+        //    currently providing the cap, fail fast.
+        if (deps.udsChildId !== null && targetNodeId === undefined) {
+            const registry = deps.getLocalChildRegistry();
+            if (registry !== null && registry.childProvides(deps.udsChildId, deps.capName, deviceId)) {
+                deps.onUdsRoute?.(deps.capName);
+                const input = {
+                    capName: deps.capName,
+                    method,
+                    args: params,
+                    ...(deviceId !== undefined ? { deviceId } : {}),
+                };
+                return registry.callCapOnChild(deps.udsChildId, input);
+            }
+            throw new Error(`hub-local child "${deps.udsChildId}" does not currently provide cap "${deps.capName}"`);
+        }
+        // ── Agent-hosted or explicit remote: delegate to the unified resolver.
+        const resolver = deps.getResolver();
+        if (resolver !== null) {
+            const route = resolver.resolveCapRoute(deps.capName, {
+                nodeId: targetNodeId ?? deps.nodeId,
+                ...(deviceId !== undefined ? { deviceId } : {}),
+            });
+            return resolver.dispatch(route, method, params);
+        }
+        // ── Pre-init window (resolver not yet constructed): legacy Moleculer call.
+        return deps.legacyBrokerCall(method, params, targetNodeId ?? deps.nodeId);
+    };
+}

package/dist/core/moleculer/cap-route-authority.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Adapter factories that bridge the server-side registry/service state into the
+ * narrow interfaces that CapRouteResolver (in @camstack/kernel) requires.
+ *
+ * Layer note: this file is in server/backend and may import server-side types.
+ * The resolver itself (in @camstack/kernel) must NOT import from here —
+ * it depends only on the narrow interfaces (NodeCapAuthority, InProcessProviderLookup)
+ * defined in the kernel. These factories are the wiring adapters.
+ *
+ * nodeIsAgent format rule (from agent-registry.service.ts:74-77):
+ *   hub         → 'hub'  → not an agent
+ *   hub child   → 'hub/<runnerId>' → not an agent
+ *   agent       → bare id with no '/' → agent
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNodeCapAuthority = createNodeCapAuthority;
+exports.createInProcessProviderLookup = createInProcessProviderLookup;
+/**
+ * Build a NodeCapAuthority backed by a HubNodeRegistry.
+ *
+ * nodeIsAgent rule: a node is an agent when its id is not 'hub' and does not
+ * contain '/' (hub children are `hub/<runnerId>`; agents are bare ids).
+ *
+ * nodeOnline: uses registry membership — per CLAUDE.md "the registry is the
+ * union of registerNode manifests minus disconnected nodes" because
+ * `removeNode` is called on `$node.disconnected`. Registry membership is the
+ * cleanest, cast-free liveness check.
+ *
+ * getAgentChildId: always returns null — the hub cannot resolve which forked
+ * child under an agent provides a cap (the agent flattens its subtree into
+ * one merged manifest). The agent resolves its own child locally (Task 6).
+ */
+function createNodeCapAuthority(nodeRegistry, resolver) {
+    return {
+        nodeKnowsCap(nodeId, capName) {
+            // Check system (manifest) caps first
+            const manifest = nodeRegistry.getNodeManifest(nodeId);
+            if (manifest !== undefined &&
+                manifest.some((addon) => addon.capabilities.includes(capName))) {
+                return true;
+            }
+            // Also check device-scoped native caps — these are NOT in the addon manifest
+            const nativeEntries = nodeRegistry.listNativeCapEntries?.() ?? [];
+            return nativeEntries.some((n) => n.nodeId === nodeId && n.capName === capName);
+        },
+        getAddonId(nodeId, capName) {
+            // Check system (manifest) caps first
+            const manifest = nodeRegistry.getNodeManifest(nodeId);
+            if (manifest !== undefined) {
+                const manifestAddons = manifest
+                    .filter((addon) => addon.capabilities.includes(capName))
+                    .map((addon) => addon.addonId);
+                if (manifestAddons.length > 0) {
+                    // Per-node override / global-default resolution, constrained to what
+                    // the node actually hosts. Falls back to the first manifest match.
+                    const resolved = resolver?.resolveSingleton(capName, nodeId) ?? null;
+                    if (resolved !== null && manifestAddons.includes(resolved))
+                        return resolved;
+                    return manifestAddons[0] ?? null;
+                }
+            }
+            // Check device-scoped native caps (unchanged path)
+            const nativeEntries = nodeRegistry.listNativeCapEntries?.() ?? [];
+            const nat = nativeEntries.find((n) => n.nodeId === nodeId && n.capName === capName);
+            return nat?.addonId ?? null;
+        },
+        nodeIsAgent(nodeId) {
+            return nodeId !== 'hub' && !nodeId.includes('/');
+        },
+        nodeOnline(nodeId) {
+            // O(1) Map lookup — registry membership is the authoritative liveness
+            // check: HubNodeRegistry.removeNode is called on $node.disconnected,
+            // so a defined manifest means the node is connected.
+            return nodeRegistry.getNodeManifest(nodeId) !== undefined;
+        },
+        listNodeIds() {
+            return nodeRegistry.listNodeIds();
+        },
+        getAgentChildId(_agentNodeId, _capName) {
+            // The hub cannot resolve the agent's child — the agent resolves locally (Task 6).
+            return null;
+        },
+        isNativeCap(nodeId, capName, deviceId) {
+            const nativeEntries = nodeRegistry.listNativeCapEntries?.() ?? [];
+            if (deviceId !== undefined) {
+                return nativeEntries.some((n) => n.nodeId === nodeId && n.capName === capName && n.deviceId === deviceId);
+            }
+            return nativeEntries.some((n) => n.nodeId === nodeId && n.capName === capName);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// createInProcessProviderLookup
+// ---------------------------------------------------------------------------
+/**
+ * Build an InProcessProviderLookup backed by a CapabilityService.
+ *
+ * Cast-free design: `getSingleton<Record<string, unknown>>` makes the provider
+ * indexable without any `as` casts. `typeof fn === 'function'` narrows to
+ * Function (implicit `any` return); calling via `fn.call(provider, args)` is
+ * then safe and the result is captured as `unknown`. No `as` casts anywhere.
+ */
+function createInProcessProviderLookup(capabilityService) {
+    return (capName) => {
+        const provider = capabilityService.getSingletonForNode?.(capName, 'hub') ??
+            capabilityService.getSingleton(capName);
+        if (provider === null || provider === undefined)
+            return null;
+        const ref = {
+            invoke: (method, args) => {
+                const fn = provider[method];
+                if (typeof fn !== 'function') {
+                    return Promise.reject(new Error(`method "${method}" not found on cap "${capName}"`));
+                }
+                const result = fn.call(provider, args);
+                return Promise.resolve(result);
+            },
+        };
+        return ref;
+    };
+}