@camstack/server 0.1.3

package/src/__tests__/lifecycle-e2e.test.ts

@@ -0,0 +1,140 @@
+ 
+import { describe, it, expect, vi } from 'vitest'
+import { CapabilityRegistry, isInfraCapability } from '@camstack/kernel'
+import type { IScopedLogger } from '@camstack/types'
+
+// ─── Mock helpers ────────────────────────────────────────────────────
+//
+// PipelineOrchestrator phase-transition + result-flow tests used to live
+// in this file (importing from the now-deleted server/backend/src/core/
+// orchestrator/ directory). They have been migrated into the runner package
+// (`packages/addon-pipeline-runner/src/__tests__/runner.spec.ts`) which
+// is the canonical home of the scheduler core.
+
+function createMockLogger(): IScopedLogger {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  } as unknown as IScopedLogger
+}
+
+function createRegistry(configReader?: (cap: string) => string | undefined): CapabilityRegistry {
+  const registry = new CapabilityRegistry(createMockLogger())
+  if (configReader) {
+    registry.setConfigReader(configReader)
+  }
+  registry.ready()
+  return registry
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────
+
+describe('Full Lifecycle E2E (mock, no external services)', () => {
+  describe('CapabilityRegistry boot sequence', () => {
+    it('registers singleton and collection capabilities correctly', () => {
+      const registry = createRegistry()
+
+      registry.declareCapability({ name: 'storage', scope: 'system', mode: 'singleton', methods: {} })
+      registry.declareCapability({ name: 'log-destination', scope: 'system', mode: 'collection', methods: {} })
+      registry.declareCapability({ name: 'streaming-engine', scope: 'system', mode: 'singleton', methods: {} })
+      registry.declareCapability({ name: 'analysis-pipeline', scope: 'system', mode: 'singleton', methods: {} })
+      registry.declareCapability({ name: 'device-provider', scope: 'system', mode: 'collection', methods: {} })
+      registry.declareCapability({ name: 'admin-ui', scope: 'system', mode: 'singleton', methods: {} })
+
+      const mockStorage = { id: 'sqlite' }
+      const mockLogger = { id: 'winston' }
+      const mockStreaming = { id: 'go2rtc' }
+      const mockAnalysis = { id: 'pipeline-analysis' }
+      const mockProvider = { id: 'frigate' }
+
+      registry.registerProvider('storage', 'sqlite-storage', mockStorage)
+      registry.registerProvider('log-destination', 'winston-logging', mockLogger)
+      registry.registerProvider('streaming-engine', 'go2rtc', mockStreaming)
+      registry.registerProvider('analysis-pipeline', 'pipeline-analysis', mockAnalysis)
+      registry.registerProvider('device-provider', 'provider-frigate', mockProvider)
+
+      expect(registry.getSingleton('storage')).toBe(mockStorage)
+      expect(registry.getCollection('log-destination')).toEqual([mockLogger])
+      expect(registry.getSingleton('streaming-engine')).toBe(mockStreaming)
+      expect(registry.getSingleton('analysis-pipeline')).toBe(mockAnalysis)
+      expect(registry.getCollection('device-provider')).toEqual([mockProvider])
+
+      const caps = registry.listCapabilities()
+      expect(caps.length).toBeGreaterThanOrEqual(5)
+    })
+
+    it('infra capabilities are identified correctly', () => {
+      expect(isInfraCapability('storage')).toBe(true)
+      expect(isInfraCapability('log-destination')).toBe(true)
+      expect(isInfraCapability('streaming-engine')).toBe(false)
+    })
+  })
+
+  // Note: PipelineOrchestrator phase transition + detection result flow tests
+  // moved to packages/addon-pipeline-runner/src/__tests__/runner.spec.ts
+  // when the scheduler was extracted into the addon-pipeline-runner package.
+
+  describe('Singleton swap', () => {
+    it('swapping analysis provider changes getSingleton result', async () => {
+      const registry = createRegistry()
+      registry.declareCapability({ name: 'analysis-pipeline', scope: 'system', mode: 'singleton', methods: {} })
+
+      const analysisA = { id: 'analysis-a', processFrame: vi.fn() }
+      const analysisB = { id: 'analysis-b', processFrame: vi.fn() }
+
+      registry.registerProvider('analysis-pipeline', 'addon-a', analysisA)
+      expect(registry.getSingleton('analysis-pipeline')).toBe(analysisA)
+
+      registry.registerProvider('analysis-pipeline', 'addon-b', analysisB)
+
+      await registry.setActiveSingleton('analysis-pipeline', 'addon-b', true)
+      expect(registry.getSingleton('analysis-pipeline')).toBe(analysisB)
+    })
+  })
+
+  describe('Collection capability add/remove', () => {
+    it('adding and removing device providers', () => {
+      const registry = createRegistry()
+      registry.declareCapability({ name: 'device-provider', scope: 'system', mode: 'collection', methods: {} })
+
+      const frigate = { id: 'frigate', type: 'frigate' }
+      const onvif = { id: 'onvif', type: 'onvif' }
+
+      registry.registerProvider('device-provider', 'addon-frigate', frigate)
+      expect(registry.getCollection('device-provider')).toHaveLength(1)
+
+      registry.registerProvider('device-provider', 'addon-onvif', onvif)
+      expect(registry.getCollection('device-provider')).toHaveLength(2)
+
+      registry.unregisterProvider('device-provider', 'addon-frigate')
+      expect(registry.getCollection('device-provider')).toHaveLength(1)
+    })
+  })
+
+  describe('Capability introspection', () => {
+    it('listCapabilities returns full info', () => {
+      const registry = createRegistry()
+      registry.declareCapability({ name: 'storage', scope: 'system', mode: 'singleton', methods: {} })
+      registry.declareCapability({ name: 'device-provider', scope: 'system', mode: 'collection', methods: {} })
+
+      registry.registerProvider('storage', 'sqlite', { id: 'sqlite' })
+      registry.registerProvider('device-provider', 'frigate', { id: 'frigate' })
+      registry.registerProvider('device-provider', 'onvif', { id: 'onvif' })
+
+      const caps = registry.listCapabilities()
+
+      const storage = caps.find((c) => c.name === 'storage')
+      expect(storage).toBeDefined()
+      expect(storage!.mode).toBe('singleton')
+      expect(storage!.providers).toContain('sqlite')
+      expect(storage!.activeProvider).toBe('sqlite')
+
+      const providers = caps.find((c) => c.name === 'device-provider')
+      expect(providers).toBeDefined()
+      expect(providers!.mode).toBe('collection')
+      expect(providers!.providers).toHaveLength(2)
+    })
+  })
+})

package/src/__tests__/live-events-subscription.spec.ts

@@ -0,0 +1,150 @@
+/**
+ * Live events subscription — unit + in-process e2e test.
+ *
+ * Proves that an event emitted on `EventBusService` is delivered to a
+ * consumer that went through `live.onEvent` → `iterableSubscription`.
+ * This is the same path UI components use via the WS client (AlertBell,
+ * EngineTab). If this test passes but the UI still doesn't receive
+ * events, the bug is downstream in the WS adapter, not in the routing.
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { SystemEventBus } from '@camstack/core'
+import { createLiveEventsRouter } from '../api/core/live-events.router.js'
+import { makeCtx } from './cap-routers/harness.js'
+import type { EventBusService } from '../core/events/event-bus.service.js'
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function makeEvent(category: string, data: Record<string, unknown> = {}) {
+  return {
+    id: `evt-${Math.random().toString(36).slice(2, 8)}`,
+    timestamp: new Date(),
+    source: { type: 'pipeline' as const, id: 'benchmark' },
+    category,
+    data: { type: `pipeline.${category}`, ...data },
+  }
+}
+
+describe('live events subscription', () => {
+  it('delivers events emitted AFTER subscription', async () => {
+    const bus = new SystemEventBus() as unknown as EventBusService
+    const router = createLiveEventsRouter(
+      bus,
+      { getDeviceRegistry: () => ({ getAll: () => [], getAllForAddon: () => [] }) } as never,
+    )
+    const caller = router.createCaller(makeCtx('admin'))
+
+    const iter = await caller.onEvent({ category: 'benchmark.progress' })
+
+    // Collect received events concurrently while emitting.
+    const received: Array<{ category: string; data: Record<string, unknown> }> = []
+    const collector = (async () => {
+      for await (const ev of iter) {
+        received.push({ category: ev.category, data: ev.data })
+        if (received.length >= 3) return
+      }
+    })()
+
+    // Give the async generator a tick to wire up its internal promise.
+    await sleep(10)
+
+    bus.emit(makeEvent('benchmark.progress', { iteration: 1, totalMs: 50 }))
+    bus.emit(makeEvent('benchmark.progress', { iteration: 2, totalMs: 48 }))
+    bus.emit(makeEvent('other.category', { ignored: true }))
+    bus.emit(makeEvent('benchmark.progress', { iteration: 3, totalMs: 52 }))
+
+    await collector
+
+    expect(received).toHaveLength(3)
+    expect(received.map((r) => r.data.iteration)).toEqual([1, 2, 3])
+  })
+
+  it('filters events that do not match the requested category', async () => {
+    const bus = new SystemEventBus() as unknown as EventBusService
+    const router = createLiveEventsRouter(
+      bus,
+      { getDeviceRegistry: () => ({ getAll: () => [], getAllForAddon: () => [] }) } as never,
+    )
+    const caller = router.createCaller(makeCtx('admin'))
+
+    const iter = await caller.onEvent({ category: 'benchmark.progress' })
+
+    const received: string[] = []
+    const stop = vi.fn()
+    const collector = (async () => {
+      for await (const ev of iter) {
+        received.push(ev.category)
+        if (received.length >= 2) { stop(); return }
+      }
+    })()
+
+    await sleep(10)
+
+    // Emit a mix — only 'benchmark.progress' should pass.
+    bus.emit(makeEvent('alert.created', {}))
+    bus.emit(makeEvent('benchmark.progress', { iteration: 1 }))
+    bus.emit(makeEvent('benchmark.heartbeat', {}))
+    bus.emit(makeEvent('alert.updated', {}))
+    bus.emit(makeEvent('benchmark.progress', { iteration: 2 }))
+
+    await collector
+
+    expect(received).toEqual(['benchmark.progress', 'benchmark.progress'])
+    expect(stop).toHaveBeenCalledOnce()
+  })
+
+  it('receives recent events via recentSystemEvents query', async () => {
+    const bus = new SystemEventBus() as unknown as EventBusService
+    const router = createLiveEventsRouter(
+      bus,
+      { getDeviceRegistry: () => ({ getAll: () => [], getAllForAddon: () => [] }) } as never,
+    )
+    const caller = router.createCaller(makeCtx('admin'))
+
+    bus.emit(makeEvent('benchmark.progress', { iteration: 1 }))
+    bus.emit(makeEvent('alert.created', {}))
+    bus.emit(makeEvent('benchmark.progress', { iteration: 2 }))
+
+    const recent = await caller.recentSystemEvents({ category: 'benchmark.progress', limit: 10 })
+    expect(recent).toHaveLength(2)
+    // recentSystemEvents returns newest-first
+    const iterations = recent.map((e) => e.data.iteration as number).sort((a, b) => a - b)
+    expect(iterations).toEqual([1, 2])
+  })
+
+  it('delivers bursts — multiple events queued before the consumer drains', async () => {
+    // Reproduces the benchmark scenario where runBenchmark emits 3 events
+    // back-to-back; the subscription should buffer them and deliver all 3.
+    const bus = new SystemEventBus() as unknown as EventBusService
+    const router = createLiveEventsRouter(
+      bus,
+      { getDeviceRegistry: () => ({ getAll: () => [], getAllForAddon: () => [] }) } as never,
+    )
+    const caller = router.createCaller(makeCtx('admin'))
+
+    const iter = await caller.onEvent({ category: 'benchmark.progress' })
+
+    const received: number[] = []
+    const collector = (async () => {
+      for await (const ev of iter) {
+        received.push(ev.data.iteration as number)
+        if (received.length >= 5) return
+      }
+    })()
+
+    // Let the generator body run through its first `await`, registering the
+    // bus subscription. Without this tick subscribe() hasn't attached yet.
+    await sleep(20)
+
+    // Emit 5 events synchronously — no awaits between.
+    for (let i = 1; i <= 5; i++) {
+      bus.emit(makeEvent('benchmark.progress', { iteration: i }))
+    }
+
+    await collector
+
+    expect(received).toEqual([1, 2, 3, 4, 5])
+  })
+})

package/src/__tests__/moleculer-register-node-idempotency.spec.ts

@@ -0,0 +1,229 @@
+/**
+ * MoleculerService.applyNodeManifest re-handshake idempotency (D3).
+ *
+ * Pre-existing bug: `applyNodeManifest` ran on EVERY `$hub.registerNode`
+ * and called `registry.registerProvider(cap, key, proxy)` unconditionally
+ * for every cap in the manifest. The D3 protocol legitimately re-handshakes
+ * (a node sends its COMPLETE manifest again — e.g. the post-device-restore
+ * `nativeCaps` re-handshake). `CapabilityRegistry.registerProvider` throws
+ * on a duplicate `(cap, addonId)` pair (the guard is CORRECT — it catches an
+ * addon double-`initialize()`), so the second handshake threw, the
+ * registering node's retry loop retried forever, and the cluster entered a
+ * registration storm.
+ *
+ * The fix makes `applyNodeManifest` diff-based: it honours the CLAUDE.md
+ * invariant "`registerNode` replaces the node's entire cap set atomically".
+ * A re-handshake with the SAME manifest is a no-op; a re-handshake that
+ * drops a cap unregisters exactly that cap; a re-handshake that adds a cap
+ * registers only the new one. No throw, no churn.
+ *
+ * These specs drive the genuine `MoleculerService` registration path twice
+ * for the same `nodeId` against a REAL `CapabilityRegistry` (with its real
+ * duplicate guard) and assert idempotency.
+ */
+import { describe, it, expect, beforeEach } from 'vitest'
+import { z } from 'zod'
+import { CapabilityRegistry } from '@camstack/kernel'
+import type { RegisterNodeParams } from '@camstack/kernel'
+import type { CapabilityDefinition, IScopedLogger, SystemEvent } from '@camstack/types'
+import { MoleculerService } from '../core/moleculer/moleculer.service.js'
+import type { EventBusService } from '../core/events/event-bus.service.js'
+import type { ConfigService } from '../core/config/config.service.js'
+import type { LoggingService } from '../core/logging/logging.service.js'
+import type { CapabilityService } from '../core/capability/capability.service.js'
+import type { StreamProbeService } from '../core/streaming/stream-probe.service.js'
+
+/**
+ * Test-only view of `MoleculerService` exposing:
+ *  - the genuine private registration entrypoint `onRegisterNode` — the
+ *    same closure the `$hub.registerNode` Moleculer action invokes in
+ *    production. Driving it directly exercises the real
+ *    `nodeRegistry.registerNode` + `applyNodeManifest` path without
+ *    standing up a TCP broker.
+ *  - the public `createCapabilityProxy` method used to assert whether a
+ *    dropped capability's call-routing entry was correctly removed from
+ *    `nodeCallFns` after a reduced re-handshake.
+ */
+interface RegisterNodeDriver {
+  onRegisterNode: (params: RegisterNodeParams) => void
+  createCapabilityProxy: (capabilityName: string, nodeId: string) => Record<string, (params: unknown) => Promise<unknown>> | null
+}
+
+/** A minimal real `CapabilityDefinition` so `getDefinition`/`expandCapMethods` resolve. */
+function makeCapDef(name: string): CapabilityDefinition {
+  return {
+    name,
+    scope: 'system',
+    mode: 'collection',
+    methods: {
+      ping: {
+        input: z.object({}),
+        output: z.object({}),
+        kind: 'query',
+        auth: 'protected',
+      },
+    },
+  }
+}
+
+function makeLogger(): IScopedLogger {
+  const logger = {
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+    debug: () => undefined,
+    trace: () => undefined,
+    fatal: () => undefined,
+    child: (() => logger) as IScopedLogger['child'],
+  }
+  return logger as unknown as IScopedLogger
+}
+
+interface Harness {
+  readonly driver: RegisterNodeDriver
+  readonly registry: CapabilityRegistry
+  readonly capNames: readonly string[]
+}
+
+/**
+ * Build a real `MoleculerService` (constructor only — no broker start) wired
+ * to a real `CapabilityRegistry` pre-declaring `capNames`. Returns the
+ * service viewed through `RegisterNodeDriver` plus the registry to assert on.
+ *
+ * The broker is never started, so there is nothing to stop in teardown —
+ * no `afterEach` teardown is needed.
+ */
+function createHarness(capNames: readonly string[]): Harness {
+  const registry = new CapabilityRegistry(makeLogger())
+  for (const name of capNames) {
+    registry.declareCapability(makeCapDef(name))
+  }
+  // Boot-complete state — `getAllProviders` returns [] until `ready()`.
+  registry.ready()
+
+  const fakeEventBus = {
+    emit: (_event: SystemEvent) => undefined,
+    // `ReadinessRegistry` (built in the MoleculerService constructor)
+    // subscribes to `system.ready-state` + `agent.offline`. A no-op
+    // subscription returning an unsubscribe fn keeps the constructor happy.
+    subscribe: () => () => undefined,
+    getRecent: () => [],
+  } as unknown as EventBusService
+
+  const fakeConfig = {
+    get: () => undefined,
+    getAddonConfig: () => ({}),
+  } as unknown as ConfigService
+
+  const fakeLogging = {
+    createLogger: () => makeLogger(),
+    writeFromWorker: () => undefined,
+  } as unknown as LoggingService
+
+  const fakeCapability = {
+    getRegistry: () => registry,
+  } as unknown as CapabilityService
+
+  const fakeStreamProbe = {} as unknown as StreamProbeService
+
+  const service = new MoleculerService(
+    fakeEventBus,
+    fakeConfig,
+    fakeLogging,
+    fakeCapability,
+    fakeStreamProbe,
+  )
+
+  return {
+    driver: service as unknown as RegisterNodeDriver,
+    registry,
+    capNames,
+  }
+}
+
+/** Provider count for a cap on the registry — counts every registered key. */
+function providerCount(registry: CapabilityRegistry, capName: string): number {
+  return registry.getAllProviders(capName).length
+}
+
+describe('MoleculerService.applyNodeManifest — re-handshake idempotency', () => {
+  let harness: Harness
+
+  beforeEach(() => {
+    harness = createHarness(['cap-alpha', 'cap-beta'])
+  })
+
+  it('a re-handshake with the IDENTICAL manifest does not throw and leaves each provider registered exactly once', () => {
+    const manifest: RegisterNodeParams = {
+      nodeId: 'hub/reolink',
+      addons: [{ addonId: 'reolink', capabilities: ['cap-alpha', 'cap-beta'] }],
+    }
+
+    // First handshake.
+    harness.driver.onRegisterNode(manifest)
+    expect(providerCount(harness.registry, 'cap-alpha')).toBe(1)
+    expect(providerCount(harness.registry, 'cap-beta')).toBe(1)
+
+    // Re-handshake — the documented post-device-restore re-handshake.
+    // BEFORE the fix this threw `provider already registered for capability`.
+    expect(() => harness.driver.onRegisterNode(manifest)).not.toThrow()
+
+    // No duplicate, no loss — exactly one provider per cap.
+    expect(providerCount(harness.registry, 'cap-alpha')).toBe(1)
+    expect(providerCount(harness.registry, 'cap-beta')).toBe(1)
+    expect(harness.registry.getProviderByAddon('cap-alpha', 'reolink')).not.toBeNull()
+    expect(harness.registry.getProviderByAddon('cap-beta', 'reolink')).not.toBeNull()
+  })
+
+  it('three handshakes survive without throwing (registration storm regression guard)', () => {
+    const manifest: RegisterNodeParams = {
+      nodeId: 'hub/reolink',
+      addons: [{ addonId: 'reolink', capabilities: ['cap-alpha', 'cap-beta'] }],
+    }
+
+    expect(() => {
+      harness.driver.onRegisterNode(manifest)
+      harness.driver.onRegisterNode(manifest)
+      harness.driver.onRegisterNode(manifest)
+    }).not.toThrow()
+
+    expect(providerCount(harness.registry, 'cap-alpha')).toBe(1)
+    expect(providerCount(harness.registry, 'cap-beta')).toBe(1)
+  })
+
+  it('a re-handshake that DROPS one capability unregisters that provider while the others remain', () => {
+    const fullManifest: RegisterNodeParams = {
+      nodeId: 'hub/reolink',
+      addons: [{ addonId: 'reolink', capabilities: ['cap-alpha', 'cap-beta'] }],
+    }
+    const reducedManifest: RegisterNodeParams = {
+      nodeId: 'hub/reolink',
+      addons: [{ addonId: 'reolink', capabilities: ['cap-alpha'] }],
+    }
+
+    // First: full manifest — both caps registered.
+    harness.driver.onRegisterNode(fullManifest)
+    expect(providerCount(harness.registry, 'cap-alpha')).toBe(1)
+    expect(providerCount(harness.registry, 'cap-beta')).toBe(1)
+
+    // Second: identical full manifest — still idempotent, no throw.
+    expect(() => harness.driver.onRegisterNode(fullManifest)).not.toThrow()
+    expect(providerCount(harness.registry, 'cap-alpha')).toBe(1)
+    expect(providerCount(harness.registry, 'cap-beta')).toBe(1)
+
+    // Third: reduced manifest — cap-beta dropped, cap-alpha kept.
+    expect(() => harness.driver.onRegisterNode(reducedManifest)).not.toThrow()
+    expect(providerCount(harness.registry, 'cap-alpha')).toBe(1)
+    expect(providerCount(harness.registry, 'cap-beta')).toBe(0)
+    expect(harness.registry.getProviderByAddon('cap-alpha', 'reolink')).not.toBeNull()
+    expect(harness.registry.getProviderByAddon('cap-beta', 'reolink')).toBeNull()
+
+    // Verify that the call-routing entry for the dropped cap was removed
+    // from `nodeCallFns`. `createCapabilityProxy` is the public seam that
+    // delegates to `findCallFn` internally — a null return means no entry
+    // exists for that (nodeId, cap) pair, confirming the delete ran.
+    expect(harness.driver.createCapabilityProxy('cap-beta', 'hub/reolink')).toBeNull()
+    // The still-present cap must remain routable.
+    expect(harness.driver.createCapabilityProxy('cap-alpha', 'hub/reolink')).not.toBeNull()
+  })
+})