@camstack/server 0.1.3

package/src/core/lifecycle/lifecycle-state-machine.spec.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { LifecycleStateMachine } from './lifecycle-state-machine'
+import type { IEventBus, SystemEvent } from '@camstack/types'
+import type { IScopedLogger } from '@camstack/types'
+
+const createMockEventBus = (): IEventBus & { emitted: SystemEvent[] } => {
+  const emitted: SystemEvent[] = []
+  return {
+    emitted,
+    emit: vi.fn((event: SystemEvent) => emitted.push(event)),
+    subscribe: vi.fn(() => () => {}),
+    getRecent: vi.fn(() => []),
+  }
+}
+
+const createMockLogger = (): IScopedLogger => ({
+  debug: vi.fn(),
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  child: vi.fn(),
+})
+
+describe('LifecycleStateMachine', () => {
+  let eventBus: ReturnType<typeof createMockEventBus>
+  let logger: IScopedLogger
+  let machine: LifecycleStateMachine
+
+  beforeEach(() => {
+     
+    eventBus = createMockEventBus()
+     
+    logger = createMockLogger()
+    machine = new LifecycleStateMachine('test-element', 'device', eventBus, logger)
+  })
+
+  it('starts in stopped state', () => {
+    expect(machine.state).toBe('stopped')
+    expect(machine.getStatus().state).toBe('stopped')
+    expect(machine.getStatus().restartCount).toBe(0)
+    expect(machine.getStatus().uptime).toBe(0)
+  })
+
+  it('allows valid transition: stopped → starting → running', () => {
+    const result1 = machine.transition('starting')
+    expect(result1).toBe(true)
+    expect(machine.state).toBe('starting')
+
+    const result2 = machine.transition('running')
+    expect(result2).toBe(true)
+    expect(machine.state).toBe('running')
+  })
+
+  it('rejects invalid transition (e.g. stopped → running directly)', () => {
+    const result = machine.transition('running')
+    expect(result).toBe(false)
+    expect(machine.state).toBe('stopped')
+     
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('Invalid state transition'),
+      expect.anything(),
+    )
+  })
+
+  it('emits event on bus for each valid transition', () => {
+    machine.transition('starting')
+    machine.transition('running')
+
+     
+    expect(eventBus.emit).toHaveBeenCalledTimes(2)
+     
+    expect(eventBus.emitted[0]!.category).toBe('device.state.starting')
+     
+    expect(eventBus.emitted[0]!.source).toEqual({ type: 'device', id: 'test-element' })
+     
+    expect(eventBus.emitted[0]!.data).toMatchObject({
+      from: 'stopped',
+      to: 'starting',
+      elementId: 'test-element',
+    })
+     
+    expect(eventBus.emitted[1]!.category).toBe('device.state.running')
+     
+    expect(eventBus.emitted[1]!.data).toMatchObject({
+      from: 'starting',
+      to: 'running',
+    })
+  })
+
+  it('does not emit event on invalid transition', () => {
+    machine.transition('running')
+     
+    expect(eventBus.emit).not.toHaveBeenCalled()
+  })
+
+  it('tracks uptime when running', () => {
+    machine.transition('starting')
+    machine.transition('running')
+
+    const status = machine.getStatus()
+    expect(status.uptime).toBeGreaterThanOrEqual(0)
+    expect(status.startedAt).toBeDefined()
+    expect(status.stoppedAt).toBeUndefined()
+  })
+
+  it('records error message in error state', () => {
+    machine.transition('starting')
+    machine.transition('error', 'connection refused')
+
+    const status = machine.getStatus()
+    expect(status.state).toBe('error')
+    expect(status.error).toBe('connection refused')
+    expect(status.stoppedAt).toBeDefined()
+  })
+
+  it('getStatus returns complete info after full lifecycle', () => {
+    machine.transition('starting')
+    machine.transition('running')
+    machine.transition('stopping')
+    machine.transition('stopped')
+
+    const status = machine.getStatus()
+    expect(status.state).toBe('stopped')
+    expect(status.restartCount).toBe(0)
+    expect(status.stoppedAt).toBeDefined()
+    expect(status.uptime).toBe(0)
+  })
+
+  it('increments restart count only on subsequent starts', () => {
+    // First start
+    machine.transition('starting')
+    machine.transition('running')
+    expect(machine.getStatus().restartCount).toBe(0)
+
+    // Stop and restart
+    machine.transition('stopping')
+    machine.transition('stopped')
+    machine.transition('starting')
+    machine.transition('running')
+    expect(machine.getStatus().restartCount).toBe(1)
+
+    // Error and restart
+    machine.transition('error', 'crash')
+    machine.transition('starting')
+    machine.transition('running')
+    expect(machine.getStatus().restartCount).toBe(2)
+  })
+
+  it('allows disabled state from stopped', () => {
+    const result = machine.transition('disabled')
+    expect(result).toBe(true)
+    expect(machine.state).toBe('disabled')
+  })
+
+  it('requires going through stopped to leave disabled', () => {
+    machine.transition('disabled')
+
+    expect(machine.transition('starting')).toBe(false)
+    expect(machine.transition('stopped')).toBe(true)
+    expect(machine.state).toBe('stopped')
+  })
+
+  it('incrementRestartCount manually increments the counter', () => {
+    machine.incrementRestartCount()
+    machine.incrementRestartCount()
+    expect(machine.getStatus().restartCount).toBe(2)
+  })
+})

package/src/core/lifecycle/lifecycle-state-machine.ts

@@ -0,0 +1,3 @@
+// Re-export from @camstack/core — LifecycleStateMachine is already a plain class
+export { LifecycleStateMachine } from '@camstack/core'
+export type { ElementState, ElementStatus } from '@camstack/core'

package/src/core/logging/log-ring-buffer.ts

@@ -0,0 +1,3 @@
+// Re-export from @camstack/core
+export { LogRingBuffer } from '@camstack/core'
+export type { LogEntry, LogFilter, LogLevel } from '@camstack/core'

package/src/core/logging/logging.service.spec.ts

@@ -0,0 +1,247 @@
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import * as yaml from 'js-yaml'
+import { LogRingBuffer } from './log-ring-buffer'
+import { ScopedLogger } from './scoped-logger'
+import { LoggingService } from './logging.service'
+import { ConfigService } from '../config/config.service'
+import type { ISettingsStore } from '@camstack/kernel'
+import type { LogEntry, ILogDestination } from '@camstack/types'
+
+/**
+ * In-memory settings store used by the test to drive `ConfigService.get`
+ * for the `eventBus.ringBufferSize` key. The bootstrap YAML schema does not
+ * declare `eventBus`, so writing it to the YAML file would be discarded by
+ * `bootstrapSchema.parse`. Wiring an ISettingsStore is the clean path to
+ * feed runtime values into `ConfigService` without casts.
+ */
+class InMemorySettingsStore implements ISettingsStore {
+  private readonly system: Record<string, unknown>
+
+  constructor(seed: Record<string, unknown>) {
+    this.system = { ...seed }
+  }
+
+  getSystem(key: string): unknown { return this.system[key] }
+  setSystem(key: string, value: unknown): void { this.system[key] = value }
+  getAllSystem(): Record<string, unknown> { return { ...this.system } }
+
+  getAllAddon(_addonId: string): Record<string, unknown> { return {} }
+  setAllAddon(_addonId: string, _config: Record<string, unknown>): void { /* no-op */ }
+  getAllProvider(_providerId: string): Record<string, unknown> { return {} }
+  setProvider(_providerId: string, _key: string, _value: unknown): void { /* no-op */ }
+  getAllDevice(_deviceId: string): Record<string, unknown> { return {} }
+  setDevice(_deviceId: string, _key: string, _value: unknown): void { /* no-op */ }
+  getAddonDevice(_addonId: string, _deviceId: string): Record<string, unknown> { return {} }
+  setAddonDevice(_addonId: string, _deviceId: string, _values: Record<string, unknown>): void { /* no-op */ }
+  clearAddonDevice(_addonId: string, _deviceId: string): void { /* no-op */ }
+}
+
+describe('ScopedLogger', () => {
+  it('emits entries with a single scope string', () => {
+    const entries: LogEntry[] = []
+    const writeFn = (entry: LogEntry) => entries.push(entry)
+    const logger = new ScopedLogger('config', writeFn)
+
+    logger.info('loaded config')
+
+    expect(entries).toHaveLength(1)
+    expect(entries[0]!.scope).toBe('config')
+    expect(entries[0]!.level).toBe('info')
+    expect(entries[0]!.message).toBe('loaded config')
+    expect(entries[0]!.timestamp).toBeInstanceOf(Date)
+  })
+
+  it('child() replaces the scope (no hierarchy)', () => {
+    const entries: LogEntry[] = []
+    const writeFn = (entry: LogEntry) => entries.push(entry)
+    const logger = new ScopedLogger('core', writeFn)
+    const child = logger.child('http')
+
+    child.warn('timeout', { meta: { ms: 3000 } })
+
+    expect(entries).toHaveLength(1)
+    expect(entries[0]!.scope).toBe('http')
+    expect(entries[0]!.level).toBe('warn')
+    expect(entries[0]!.meta).toEqual({ ms: 3000 })
+  })
+
+  it('creates entries for all log levels', () => {
+    const entries: LogEntry[] = []
+    const writeFn = (entry: LogEntry) => entries.push(entry)
+    const logger = new ScopedLogger('test', writeFn)
+
+    logger.debug('d')
+    logger.info('i')
+    logger.warn('w')
+    logger.error('e')
+
+    expect(entries.map((e) => e.level)).toEqual(['debug', 'info', 'warn', 'error'])
+  })
+
+  it('omits the scope field when the logger was created without one', () => {
+    const entries: LogEntry[] = []
+    const writeFn = (entry: LogEntry) => entries.push(entry)
+    const logger = new ScopedLogger(undefined, writeFn)
+
+    logger.info('no scope')
+
+    expect(entries).toHaveLength(1)
+    expect(entries[0]!.scope).toBeUndefined()
+  })
+})
+
+describe('LogRingBuffer', () => {
+  it('stores up to capacity and evicts oldest', () => {
+    const buffer = new LogRingBuffer(3)
+
+    const makeEntry = (msg: string): LogEntry => ({
+      timestamp: new Date(),
+      level: 'info',
+      scope: 'test',
+      message: msg,
+    })
+
+    buffer.push(makeEntry('a'))
+    buffer.push(makeEntry('b'))
+    buffer.push(makeEntry('c'))
+    buffer.push(makeEntry('d'))
+
+    const all = buffer.getAll()
+    expect(all).toHaveLength(3)
+    // newest first
+    expect(all[0]!.message).toBe('d')
+    expect(all[1]!.message).toBe('c')
+    expect(all[2]!.message).toBe('b')
+  })
+
+  it('filters by level', () => {
+    const buffer = new LogRingBuffer(100)
+
+    buffer.push({ timestamp: new Date(), level: 'debug', scope: 'test', message: 'a' })
+    buffer.push({ timestamp: new Date(), level: 'error', scope: 'test', message: 'b' })
+    buffer.push({ timestamp: new Date(), level: 'error', scope: 'test', message: 'c' })
+
+    const result = buffer.query({ level: 'error' })
+    expect(result).toHaveLength(2)
+  })
+
+  it('filters by since/until', () => {
+    const buffer = new LogRingBuffer(100)
+    const t1 = new Date('2025-01-01T00:00:00Z')
+    const t2 = new Date('2025-01-02T00:00:00Z')
+    const t3 = new Date('2025-01-03T00:00:00Z')
+
+    buffer.push({ timestamp: t1, level: 'info', scope: 'test', message: 'a' })
+    buffer.push({ timestamp: t2, level: 'info', scope: 'test', message: 'b' })
+    buffer.push({ timestamp: t3, level: 'info', scope: 'test', message: 'c' })
+
+    const result = buffer.query({ since: t2 })
+    expect(result).toHaveLength(2)
+    expect(result.map((e) => e.message)).toEqual(['c', 'b'])
+  })
+
+  it('filters by tags (addonId exact match)', () => {
+    const buffer = new LogRingBuffer(100)
+
+    buffer.push({ timestamp: new Date(), level: 'info', message: 'a', tags: { addonId: 'stream-broker' } })
+    buffer.push({ timestamp: new Date(), level: 'info', message: 'b', tags: { addonId: 'provider-rtsp' } })
+    buffer.push({ timestamp: new Date(), level: 'info', message: 'c', tags: { addonId: 'stream-broker' } })
+
+    const result = buffer.query({ tags: { addonId: 'stream-broker' } })
+    expect(result).toHaveLength(2)
+    expect(result.map((e) => e.message).sort()).toEqual(['a', 'c'])
+  })
+
+  it('respects limit', () => {
+    const buffer = new LogRingBuffer(100)
+
+    for (let i = 0; i < 10; i++) {
+      buffer.push({ timestamp: new Date(), level: 'info', scope: 'test', message: `msg-${i}` })
+    }
+
+    const result = buffer.query({ limit: 3 })
+    expect(result).toHaveLength(3)
+  })
+})
+
+describe('LoggingService', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'camstack-logging-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  const createService = (bufferSize = 100): LoggingService => {
+    const configPath = path.join(tmpDir, 'config.yaml')
+    fs.writeFileSync(
+      configPath,
+      yaml.dump({
+        server: { port: 4443 },
+        auth: { adminPassword: 'secret123' },
+      }),
+      'utf-8',
+    )
+    const configService = new ConfigService(configPath)
+    configService.setSettingsStore(new InMemorySettingsStore({
+      'eventBus.ringBufferSize': bufferSize,
+    }))
+    return new LoggingService(configService)
+  }
+
+  it('routes entries to all destinations', () => {
+    const service = createService()
+    const written: LogEntry[] = []
+    const dest: ILogDestination = {
+      initialize: async () => {},
+      shutdown: async () => {},
+      write: (entry) => written.push(entry),
+    }
+
+    service.addDestination(dest)
+    const logger = service.createLogger('test')
+    logger.info('hello')
+
+    expect(written).toHaveLength(1)
+    expect(written[0]!.message).toBe('hello')
+    expect(written[0]!.scope).toBe('test')
+  })
+
+  it('creates scoped loggers that push to ring buffer', () => {
+    const service = createService()
+    const logger = service.createLogger('myScope')
+    logger.error('boom')
+
+    const entries = service.query({})
+    expect(entries).toHaveLength(1)
+    expect(entries[0]!.message).toBe('boom')
+    expect(entries[0]!.scope).toBe('myScope')
+  })
+
+  it('removes destinations', () => {
+    const service = createService()
+    const written: LogEntry[] = []
+    const dest: ILogDestination = {
+      initialize: async () => {},
+      shutdown: async () => {},
+      write: (entry) => written.push(entry),
+    }
+
+    service.addDestination(dest)
+    service.removeDestination(dest)
+
+    const logger = service.createLogger('test')
+    logger.info('should not reach dest')
+
+    expect(written).toHaveLength(0)
+    // but still in ring buffer
+    expect(service.query({})).toHaveLength(1)
+  })
+})

package/src/core/logging/logging.service.ts

@@ -0,0 +1,129 @@
+import { LogManager } from '@camstack/core'
+import type { IScopedLogger, LogTags } from '@camstack/types'
+import { EventCategory } from '@camstack/types'
+import { ConfigService } from '../config/config.service'
+import type { EventBusService } from '../events/event-bus.service'
+
+/** 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: LogTags = { agentId: 'hub', nodeId: 'hub', pid: process.pid }
+
+export class LoggingService extends 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>`.
+   */
+  private readonly deviceNames = new Map<number, string>()
+
+  constructor(configService: ConfigService) {
+    const bufferSize = configService.get<number>('eventBus.ringBufferSize') ?? 10000
+    super(bufferSize)
+    // 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: ReadonlyArray<{ id: number; name: string }>): void {
+    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: number, name: string | undefined): void {
+    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: number): void {
+    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: EventBusService): void {
+    const selfLogger = this.createLogger('logging').withTags({ addonId: 'logging' })
+    eventBus.subscribe({ category: EventCategory.DeviceRegistered }, (event) => {
+      const data = event.data as { deviceId?: number; name?: string } | undefined
+      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: EventCategory.DeviceUnregistered }, (event) => {
+      const data = event.data as { deviceId?: number } | undefined
+      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).
+   */
+  override createLogger(scope?: string): IScopedLogger {
+    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: {
+    addonId: string
+    nodeId?: string
+    level: string
+    message: string
+    scope?: string
+    tags?: LogTags
+    meta?: Record<string, unknown>
+  }): void {
+    // 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: LogTags = {
+      ...(entry.tags ?? {}),
+      addonId: entry.addonId,
+      ...(nodeId !== undefined ? { nodeId } : {}),
+      ...(agentId !== undefined ? { agentId } : {}),
+    }
+    logger = logger.withTags(mergedTags)
+    const level = entry.level as 'info' | 'warn' | 'error' | 'debug'
+    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)
+    }
+  }
+}

package/src/core/logging/scoped-logger.ts

@@ -0,0 +1,3 @@
+// Re-export from @camstack/core
+export { ScopedLogger } from '@camstack/core'
+export type { IScopedLogger } from '@camstack/core'