@camstack/server 0.2.2 → 1.0.1

package/src/core/addon-widgets/addon-widgets.service.ts

@@ -1,95 +0,0 @@
-import * as path from 'node:path'
-import * as fs from 'node:fs'
-import { LoggingService } from '../logging/logging.service'
-import { CapabilityService } from '../capability/capability.service'
-import { AddonRegistryService } from '../addon/addon-registry.service'
-import type { IScopedLogger, IAddonWidgetsSourceProvider } from '@camstack/types'
-
-/**
- * Strip the `@<nodeId>` suffix the CapabilityBridge appends to
- * collection-provider registry keys for cross-node addons. The widget
- * static-file route always receives the bare manifest id.
- */
-function stripNodeSuffix(registryKey: string): string {
-  const at = registryKey.indexOf('@')
-  return at === -1 ? registryKey : registryKey.slice(0, at)
-}
-
-/**
- * AddonWidgetsService — server-side helper that backs the static file
- * route `/api/addon-widgets/:addonId/*` (registered in `main.ts`).
- *
- * Mirrors `AddonPagesService` exactly. The public listing surface
- * (`addonWidgets.listWidgets` on the AppRouter) lives in the
- * `addon-widgets-aggregator` builtin which walks every
- * `addon-widgets-source` collection provider and stamps versioned
- * `bundleUrl`s. Both ends flow through codegen.
- *
- * What stays here: filesystem path resolution + traversal protection
- * for the static file route. The registered-provider check uses
- * `CapabilityService` (so unknown / unregistered addons can't be
- * probed via path traversal tricks); the on-disk path comes from
- * `AddonRegistryService.getAddonInstallPath()` so bundled addons
- * (where one npm package ships multiple addon entries under
- * `dist/<entryId>/`) resolve to the right sub-folder instead of the
- * pre-bundle `addons/@camstack/addon-<id>/dist/` layout.
- */
-export class AddonWidgetsService {
-  private readonly logger: IScopedLogger
-
-  constructor(
-    private readonly loggingService: LoggingService,
-    private readonly caps: CapabilityService,
-    private readonly registry: AddonRegistryService,
-  ) {
-    this.logger = this.loggingService.createLogger('AddonWidgetsService')
-  }
-
-  /**
-   * Resolve the filesystem path to an addon's widget bundle file.
-   * Returns null if the addon is not registered, the file doesn't exist,
-   * or the path would escape the addon directory (path traversal protection).
-   */
-  resolveBundle(addonId: string, filePath: string): string | null {
-    // The collection cap doesn't carry an `id` on its provider, so we
-    // attribute via `getCollectionEntries` (returns `[addonId, provider]`).
-    //
-    // For cross-node addons the CapabilityBridge registers the provider
-    // under a node-qualified key `<addonId>@<nodeId>` (see
-    // `moleculer.service.ts`). The bundle is hub-resident and keyed by
-    // the bare manifest id, so the route always carries the bare
-    // `addonId` — match it against each registry key with the
-    // `@<nodeId>` suffix stripped.
-    const entries =
-      this.caps.getCollectionEntries<IAddonWidgetsSourceProvider>('addon-widgets-source')
-    const isRegistered = entries.some(([id]) => stripNodeSuffix(id) === addonId)
-    if (!isRegistered) {
-      this.logger.warn('Bundle resolve failed: addon not registered as widget provider', {
-        tags: { addonId },
-      })
-      return null
-    }
-
-    const installPath = this.registry.getAddonInstallPath(addonId)
-    if (!installPath) {
-      this.logger.warn('Bundle resolve failed: addon install path not found', { tags: { addonId } })
-      return null
-    }
-
-    const resolvedBase = path.resolve(installPath.distDir)
-    const resolvedFile = path.resolve(installPath.distDir, filePath)
-
-    // Path traversal protection
-    if (!resolvedFile.startsWith(resolvedBase + path.sep) && resolvedFile !== resolvedBase) {
-      this.logger.warn('Path traversal denied for addon', { tags: { addonId }, meta: { filePath } })
-      return null
-    }
-
-    if (!fs.existsSync(resolvedFile)) {
-      this.logger.debug('Bundle file not found', { meta: { resolvedFile } })
-      return null
-    }
-
-    return resolvedFile
-  }
-}

package/src/core/agent/agent-registry.service.ts

@@ -1,529 +0,0 @@
-import { randomUUID } from 'node:crypto'
-import * as os from 'node:os'
-import { EventCategory, resolveAddonPlacement } from '@camstack/types'
-import type {
-  AgentListItem,
-  CameraRoleAssignment,
-  AgentCapability,
-  IMetricsProvider,
-} from '@camstack/types'
-import { EventBusService } from '../events/event-bus.service'
-import { MoleculerService } from '../moleculer/moleculer.service'
-import { CapabilityService } from '../capability/capability.service'
-import type { AddonRegistryService } from '../addon/addon-registry.service'
-
-/** Per-call timeout for `$agent.*` RPC during reconciliation. */
-const AGENT_RECONCILE_RPC_TIMEOUT_MS = 8_000
-
-/** Shape of one addon entry in the `$agent.status` response. */
-interface AgentStatusAddon {
-  readonly id: string
-  readonly status?: string
-  readonly version?: string
-  readonly packageName?: string
-}
-
-/**
- * Narrow typed view of the Moleculer broker — its own `.d.ts` chains
- * through eventemitter2 and resolves to `error`, tripping the
- * `no-unsafe-*` rules. One documented cast through this interface
- * (see the `broker` getter) keeps every call site type-safe.
- */
-interface ReconcileBrokerLike {
-  call(
-    action: string,
-    params?: Record<string, unknown>,
-    options?: { nodeID?: string; timeout?: number },
-  ): Promise<unknown>
-  localBus: {
-    on(event: string, handler: (payload: { node: { id: string } }) => void): void
-  }
-}
-
-export class AgentRegistryService {
-  // Role assignments: key = `${cameraId}:${role}`
-  private readonly assignments: Map<string, CameraRoleAssignment> = new Map()
-  private readonly bootTimestamp = Date.now()
-
-  /**
-   * Hub addon registry — the source of truth for which addons are
-   * installed and their `execution.placement`. Injected via
-   * `setAddonRegistry()` rather than the constructor because
-   * `AddonRegistryService` is built AFTER this service in the boot
-   * order (see `manual-boot.ts`).
-   */
-  private addonRegistry: AddonRegistryService | null = null
-
-  constructor(
-    private readonly eventBus: EventBusService,
-    private readonly moleculer: MoleculerService,
-    private readonly capabilityService: CapabilityService,
-  ) {}
-
-  /** Wire the hub addon registry once it has been constructed. */
-  setAddonRegistry(addonRegistry: AddonRegistryService): void {
-    this.addonRegistry = addonRegistry
-  }
-
-  /** Typed view of the Moleculer broker — single documented cast. */
-  private get broker(): ReconcileBrokerLike {
-    return this.moleculer.broker as unknown as ReconcileBrokerLike
-  }
-
-  onModuleInit(): void {
-    const classifyNode = (id: string): 'agent' | 'worker' | null => {
-      if (id === 'hub') return null
-      if (id.includes('/')) return 'worker'
-      return 'agent'
-    }
-
-    // D3: reconcile placement when an agent completes the $hub.registerNode
-    // handshake — the manifest is authoritative and complete at that point,
-    // no grace delay needed. MoleculerService fires this callback from its
-    // onRegisterNode dep for every bare-ID agent node.
-    this.moleculer.setOnAgentRegistered((agentId) => {
-      void this.reconcileAgentAddons(agentId)
-    })
-
-    this.broker.localBus.on('$node.connected', ({ node }: { node: { id: string } }) => {
-      const kind = classifyNode(node.id)
-      if (!kind) return
-      if (kind === 'agent') {
-        console.log(`[agent-registry] Agent connected: ${node.id}`)
-        this.eventBus.emit({
-          id: randomUUID(),
-          timestamp: new Date(),
-          source: { type: 'core', id: 'agent-registry' },
-          category: EventCategory.AgentOnline,
-          data: { agentId: node.id },
-        })
-      } else {
-        this.eventBus.emit({
-          id: randomUUID(),
-          timestamp: new Date(),
-          source: { type: 'core', id: 'agent-registry' },
-          category: EventCategory.WorkerOnline,
-          data: { workerId: node.id },
-        })
-      }
-    })
-
-    this.broker.localBus.on('$node.disconnected', ({ node }: { node: { id: string } }) => {
-      const kind = classifyNode(node.id)
-      if (!kind) return
-      if (kind === 'agent') {
-        console.log(`[agent-registry] Agent disconnected: ${node.id}`)
-        this.eventBus.emit({
-          id: randomUUID(),
-          timestamp: new Date(),
-          source: { type: 'core', id: 'agent-registry' },
-          category: EventCategory.AgentOffline,
-          data: { agentId: node.id },
-        })
-      } else {
-        this.eventBus.emit({
-          id: randomUUID(),
-          timestamp: new Date(),
-          source: { type: 'core', id: 'agent-registry' },
-          category: EventCategory.WorkerOffline,
-          data: { workerId: node.id },
-        })
-      }
-    })
-
-    // Retroactive scan: emit lifecycle events for nodes already
-    // connected when the listener registers. Classifies each as
-    // agent or worker — same logic as the live handlers above.
-    try {
-      const registry = (this.moleculer.broker as unknown as Record<string, unknown>).registry as
-        | { getNodeList?: (opts: { onlyAvailable: boolean }) => readonly { id: string }[] }
-        | undefined
-      const existing = registry?.getNodeList?.({ onlyAvailable: true }) ?? []
-      for (const { id } of existing) {
-        const kind = classifyNode(id)
-        if (!kind) continue
-        if (kind === 'agent') {
-          this.eventBus.emit({
-            id: randomUUID(),
-            timestamp: new Date(),
-            source: { type: 'core', id: 'agent-registry' },
-            category: EventCategory.AgentOnline,
-            data: { agentId: id },
-          })
-        } else {
-          this.eventBus.emit({
-            id: randomUUID(),
-            timestamp: new Date(),
-            source: { type: 'core', id: 'agent-registry' },
-            category: EventCategory.WorkerOnline,
-            data: { workerId: id },
-          })
-        }
-      }
-    } catch {
-      // Registry shape varies across Moleculer versions — never fatal.
-    }
-  }
-
-  // ---- Placement reconciliation ----
-
-  /**
-   * Boot-time reconciliation pass. Agents already connected when the hub
-   * starts never fire a fresh `$node.connected` event, so the per-connect
-   * trigger would miss them — this method walks the current node list once
-   * and reconciles every connected agent. Must be invoked AFTER
-   * `AddonRegistryService.onModuleInit()` so the hub's installed-addon set
-   * is populated. Per-agent failures are isolated — one unreachable agent
-   * must not abort the pass or hub boot.
-   */
-  async reconcileConnectedAgents(): Promise<void> {
-    const registry = (this.moleculer.broker as unknown as Record<string, unknown>).registry as
-      | { getNodeList?: (opts: { onlyAvailable: boolean }) => readonly { id: string }[] }
-      | undefined
-    const nodes = registry?.getNodeList?.({ onlyAvailable: true }) ?? []
-    const agentIds = nodes.map((n) => n.id).filter((id) => id !== 'hub' && !id.includes('/'))
-    if (agentIds.length === 0) return
-    console.log(`[agent-registry] Boot reconcile: ${agentIds.length} connected agent(s)`)
-    for (const agentId of agentIds) {
-      await this.reconcileAgentAddons(agentId)
-    }
-  }
-
-  /**
-   * Reconcile a single agent's deployed addons against the hub's installed
-   * set + placements. An addon running on the agent is STALE — and must be
-   * undeployed — when it is either:
-   *   - not installed on the hub at all, or
-   *   - installed but declared `execution.placement: 'hub-only'`.
-   *
-   * `agent-only` / `any-node` addons that ARE installed on the hub are
-   * legitimate agent residents and left untouched.
-   *
-   * Matching is by addon DECLARATION id: `$agent.status` reports
-   * `addons[].id` (the decl id), and the hub's `listAddons()` rows expose
-   * the same decl id at `manifest.id`. Package names are NOT used for the
-   * match — a single package can ship multiple addons with distinct ids
-   * and placements.
-   *
-   * All errors are caught and logged so a single bad agent never breaks
-   * the caller (connect handler or boot pass).
-   */
-  async reconcileAgentAddons(agentId: string): Promise<void> {
-    if (!this.addonRegistry) {
-      console.warn(`[agent-registry] Reconcile skipped for ${agentId}: addon registry not wired`)
-      return
-    }
-    try {
-      const broker = this.broker
-      const statusRaw = await broker.call(
-        '$agent.status',
-        {},
-        {
-          nodeID: agentId,
-          timeout: AGENT_RECONCILE_RPC_TIMEOUT_MS,
-        },
-      )
-      const agentAddons = this.extractAgentAddons(statusRaw)
-      if (agentAddons.length === 0) return
-
-      // Build the hub's placement map: decl id → placement. Absence from
-      // this map means "not installed on the hub".
-      const hubPlacements = new Map<string, ReturnType<typeof resolveAddonPlacement>>()
-      for (const row of this.addonRegistry.listAddons()) {
-        const declId = row.manifest.id
-        if (typeof declId !== 'string') continue
-        const decl = row.declaration ?? row.manifest
-        hubPlacements.set(declId, resolveAddonPlacement(decl))
-      }
-
-      const stale = agentAddons.filter((addon) => {
-        const placement = hubPlacements.get(addon.id)
-        // Not installed on the hub → stale.
-        if (placement === undefined) return true
-        // Installed but pinned to the hub → must not run on an agent.
-        return placement === 'hub-only'
-      })
-
-      if (stale.length === 0) {
-        console.log(
-          `[agent-registry] Reconcile ${agentId}: no stale addons (${agentAddons.length} checked)`,
-        )
-        return
-      }
-
-      for (const addon of stale) {
-        const reason = hubPlacements.has(addon.id)
-          ? 'placement is hub-only'
-          : 'not installed on hub'
-        try {
-          await broker.call(
-            '$agent.undeploy',
-            { addonId: addon.id },
-            {
-              nodeID: agentId,
-              timeout: AGENT_RECONCILE_RPC_TIMEOUT_MS,
-            },
-          )
-          console.log(
-            `[agent-registry] Reconcile ${agentId}: undeployed stale addon "${addon.id}" (${reason})`,
-          )
-          this.eventBus.emit({
-            id: randomUUID(),
-            timestamp: new Date(),
-            source: { type: 'core', id: 'agent-registry' },
-            category: EventCategory.AddonUninstalled,
-            data: { addonId: addon.id, agentId, reason },
-          })
-        } catch (err) {
-          console.error(
-            `[agent-registry] Reconcile ${agentId}: failed to undeploy "${addon.id}":`,
-            err instanceof Error ? err.message : String(err),
-          )
-        }
-      }
-    } catch (err) {
-      console.error(
-        `[agent-registry] Reconcile failed for agent ${agentId}:`,
-        err instanceof Error ? err.message : String(err),
-      )
-    }
-  }
-
-  /** Narrow the `$agent.status` response down to its addon list. */
-  private extractAgentAddons(statusRaw: unknown): readonly AgentStatusAddon[] {
-    if (statusRaw === null || typeof statusRaw !== 'object') return []
-    const addons = (statusRaw as { addons?: unknown }).addons
-    if (!Array.isArray(addons)) return []
-    const result: AgentStatusAddon[] = []
-    for (const entry of addons) {
-      if (entry === null || typeof entry !== 'object') continue
-      const id = (entry as { id?: unknown }).id
-      if (typeof id !== 'string' || id.length === 0) continue
-      result.push({ id })
-    }
-    return result
-  }
-
-  /** Log an agent rename (name changes are persisted via $agent.rename RPC). */
-  updateAgentName(nodeId: string, name: string): void {
-    console.log(`[agent-registry] Agent renamed: "${nodeId}" → "${name}"`)
-  }
-
-  async listNodes(): Promise<readonly AgentListItem[]> {
-    // Get child processes for hub via $process.list
-    let hubProcesses: readonly unknown[] = []
-    try {
-      const processes = (await this.broker.call('$process.list')) as readonly Record<
-        string,
-        unknown
-      >[]
-      hubProcesses = processes.map((p) => ({
-        pid: (p.pid as number) ?? 0,
-        name: (p.name as string) ?? '',
-        command: 'moleculer-service',
-        state: (p.state as 'running' | 'stopped' | 'crashed') ?? 'running',
-        cpuPercent: (p.cpuPercent as number) ?? 0,
-        memoryRss: (p.memoryRss as number) ?? 0,
-        uptimeSeconds: (p.uptimeSeconds as number) ?? 0,
-        addonIds: (p.addonIds as readonly string[] | undefined) ?? [],
-        groupId: (p.groupId as string | undefined) ?? null,
-      }))
-    } catch {
-      // $process service may not be ready yet
-    }
-
-    const hubEntry = await this.buildHubEntry(hubProcesses)
-
-    const remoteEntries: AgentListItem[] = []
-    const registry = (this.moleculer.broker as unknown as Record<string, unknown>).registry as
-      | { getNodeList?: (opts: { onlyAvailable: boolean }) => Array<{ id: string }> }
-      | undefined
-    const nodes = registry?.getNodeList?.({ onlyAvailable: true }) ?? []
-
-    for (const node of nodes) {
-      const nodeId = node.id
-      // Skip hub (already included) and child processes (contain '/')
-      if (nodeId === 'hub' || nodeId.includes('/')) continue
-
-      try {
-        const status = (await this.broker.call(
-          '$agent.status',
-          {},
-          {
-            nodeID: nodeId,
-            timeout: 5000,
-          },
-        )) as Record<string, unknown>
-
-        // Get real sub-process stats from the agent's $process.list
-        let subProcesses: readonly unknown[] = []
-        try {
-          const processes = (await this.broker.call(
-            '$process.list',
-            {},
-            {
-              nodeID: nodeId,
-              timeout: 5000,
-            },
-          )) as readonly Record<string, unknown>[]
-          subProcesses = processes.map((p) => ({
-            pid: (p.pid as number) ?? 0,
-            name: (p.name as string) ?? '',
-            command: 'moleculer-service',
-            state: (p.state as 'running' | 'stopped' | 'crashed') ?? 'running',
-            cpuPercent: (p.cpuPercent as number) ?? 0,
-            memoryRss: (p.memoryRss as number) ?? 0,
-            uptimeSeconds: (p.uptimeSeconds as number) ?? 0,
-            addonIds: (p.addonIds as readonly string[] | undefined) ?? [],
-            groupId: (p.groupId as string | undefined) ?? null,
-          }))
-        } catch {
-          // Fall back to addon list from $agent.status (no stats)
-          subProcesses =
-            (status.addons as readonly Record<string, unknown>[] | undefined)?.map((a) => ({
-              pid: 0,
-              name: (a.id as string) ?? '',
-              command: 'moleculer-service',
-              state: ((a.status as string) ?? 'running') as 'running' | 'stopped' | 'crashed',
-              cpuPercent: 0,
-              memoryRss: 0,
-              uptimeSeconds: 0,
-            })) ?? []
-        }
-
-        // Extract addon IDs from $agent.status
-        const agentAddons: readonly string[] =
-          (status.addons as readonly { id: string }[] | undefined)?.map((a) => a.id) ?? []
-
-        const hostname = typeof status.hostname === 'string' ? status.hostname : null
-        const agentName = typeof status.name === 'string' ? status.name : nodeId
-        remoteEntries.push({
-          info: {
-            id: nodeId,
-            name: agentName,
-            hostname: hostname ?? nodeId,
-            capabilities: [],
-            platform: (status.platform as string) ?? 'unknown',
-            arch: (status.arch as string) ?? 'unknown',
-            cpuCores: (status.cpuCores as number) ?? 0,
-            memoryMB: (status.totalMemoryMB as number) ?? 0,
-            cpuModel: status.cpuModel as string | undefined,
-          },
-          localIps: Array.isArray(status.localIps) ? (status.localIps as string[]) : [],
-          status: {
-            activeCameras: 0,
-            cpuPercent: (status.cpuPercent as number) ?? 0,
-            memoryPercent: (status.memoryPercent as number) ?? 0,
-            fps: {},
-            errors: [],
-          },
-          connectedSince:
-            typeof status.uptime === 'number'
-              ? Date.now() - (status.uptime as number) * 1000
-              : Date.now(),
-          isHub: false,
-          subProcesses,
-          agentAddons,
-        })
-      } catch {
-        // Skip nodes without $agent service
-      }
-    }
-
-    // TODO(D3 follow-up): offline-agent history dropped with knownAgents.
-    // Previously, agents that disconnected were kept in a shadow map and
-    // surfaced here as offline rows. listNodes now reflects only live
-    // broker.registry nodes.
-
-    return [hubEntry, ...remoteEntries]
-  }
-
-  private async buildHubEntry(subProcesses: readonly unknown[] = []): Promise<AgentListItem> {
-    const cpus = os.cpus()
-
-    // Get live metrics from the metrics-provider capability (NativeMetricsProvider).
-    // The cap contract only exposes async snapshots; the cached read is cheap
-    // because the addon's background sampler keeps the snapshot warm.
-    let cpuPercent = 0
-    let memoryPercent = 0
-    const registry = this.capabilityService.getRegistry()
-    if (registry) {
-      const metricsProvider = registry.getSingleton<IMetricsProvider>('metrics-provider')
-      if (metricsProvider) {
-        const snapshot = await metricsProvider.getCached()
-        if (snapshot) {
-          cpuPercent = snapshot.cpu.total
-          memoryPercent = snapshot.memory.percent
-        }
-      }
-    }
-
-    return {
-      info: {
-        id: 'hub',
-        name: 'Hub',
-        hostname: os.hostname(),
-        capabilities: [],
-        platform: os.platform(),
-        arch: os.arch(),
-        cpuCores: cpus.length,
-        memoryMB: Math.round(os.totalmem() / 1024 / 1024),
-        cpuModel: cpus[0]?.model,
-      },
-      status: {
-        activeCameras: 0,
-        cpuPercent,
-        memoryPercent,
-        fps: {},
-        errors: [],
-      },
-      connectedSince: this.bootTimestamp,
-      isHub: true,
-      subProcesses,
-    }
-  }
-
-  // ---- Role assignments ----
-
-  getAssignments(cameraId?: number): CameraRoleAssignment[] {
-    const all = [...this.assignments.values()]
-    if (cameraId !== undefined) return all.filter((a) => a.cameraId === cameraId)
-    return all
-  }
-
-  setAssignment(assignment: CameraRoleAssignment): void {
-    const key = `${assignment.cameraId}:${assignment.role}`
-    this.assignments.set(key, { ...assignment })
-  }
-
-  removeAssignment(cameraId: number, role: AgentCapability): void {
-    const key = `${cameraId}:${role}`
-    this.assignments.delete(key)
-  }
-
-  activateBackup(cameraId: number, role: AgentCapability): void {
-    const primaryKey = `${cameraId}:${role}`
-    const primary = this.assignments.get(primaryKey)
-
-    const backup = [...this.assignments.values()].find(
-      (a) => a.cameraId === cameraId && a.role === role && a.priority === 'backup',
-    )
-
-    if (!backup) return
-
-    if (primary) {
-      this.assignments.delete(primaryKey)
-    }
-
-    const promoted: CameraRoleAssignment = { ...backup, priority: 'primary' }
-    this.assignments.set(primaryKey, promoted)
-
-    this.eventBus.emit({
-      id: randomUUID(),
-      timestamp: new Date(),
-      source: { type: 'core', id: 'agent-registry' },
-      category: EventCategory.AgentBackupActivated,
-      data: { cameraId, role, agentId: promoted.agentId },
-    })
-  }
-}