@camstack/server 0.1.6 → 0.1.8

package/src/__tests__/uds-addon-call-wiring.spec.ts

@@ -0,0 +1,237 @@
+/**
+ * F3 backend wiring — forked-addon routes + custom actions over UDS.
+ *
+ * Verifies the production wiring `AddonRegistryService` builds, end-to-end over
+ * a REAL LocalChildRegistry + LocalChildClient pair, with the child running the
+ * REAL addon-runner-side dispatcher (`createChildAddonCallDispatch`):
+ *
+ *   - Custom actions: a `CustomActionRegistry` whose dispatcher is the F3
+ *     `callAddonOnChild({target:'custom', action, args})` reaches the child's
+ *     real custom-action handler and returns its result (the path
+ *     `registerForkedAddonCustomActions` builds via `dispatchForkedCustomAction`).
+ *   - Routes: `callAddonOnChild({target:'routes'})` returns handler-stripped
+ *     descriptors; the per-route bridge handler dispatches through the
+ *     `addon-routes` `invoke()` cap method (the path `mountForkedAddonRoutes`
+ *     builds), and the captured envelope round-trips.
+ *
+ * The child-side `onAddonCall` handler is a faithful inline of the addon-runner
+ * dispatcher (resolve route provider / custom registry; strip route handlers).
+ */
+
+import { describe, it, expect, afterEach } from 'vitest'
+import { z } from 'zod'
+import {
+  LocalChildRegistry,
+  LocalChildClient,
+  CustomActionRegistry,
+  createLocalTransport,
+} from '@camstack/kernel'
+import type { AddonCallInput } from '@camstack/kernel'
+import { buildAddonRouteProvider, customAction, defineCustomActions } from '@camstack/types'
+import type { IAddonHttpRoute, CustomActionsSpec } from '@camstack/types'
+
+const nid = (): string => `f3-wiring-${process.pid}-${Math.random().toString(36).slice(2)}`
+
+describe('F3 — forked-addon routes + custom actions over UDS (backend wiring)', () => {
+  let registry: LocalChildRegistry | null = null
+  const clients: LocalChildClient[] = []
+
+  afterEach(async () => {
+    for (const c of clients) await c.close().catch(() => {})
+    clients.length = 0
+    await registry?.close().catch(() => {})
+    registry = null
+  })
+
+  /** Stand up a hub-side registry + a child running the real addon-call dispatcher. */
+  async function standUp(opts: {
+    addonId: string
+    routes?: readonly IAddonHttpRoute[]
+    catalog?: CustomActionsSpec
+    handlers?: Record<string, (input: unknown) => Promise<unknown>>
+  }): Promise<{ childCustomActions: CustomActionRegistry }> {
+    const nodeId = nid()
+    registry = new LocalChildRegistry(createLocalTransport().createServer(nodeId))
+    await registry.start()
+
+    // The runner-side custom-action registry — populated as the addon-runner does.
+    const childCustomActions = new CustomActionRegistry()
+    if (opts.catalog && opts.handlers) {
+      const handlers = opts.handlers
+      childCustomActions.registerAddon(opts.addonId, opts.catalog, (action, input) => {
+        const fn = handlers[action]
+        if (!fn) throw new Error(`no handler for ${action}`)
+        return fn(input)
+      })
+    }
+
+    const routeProvider = opts.routes ? buildAddonRouteProvider(opts.addonId, opts.routes) : null
+
+    const child = new LocalChildClient({
+      nodeId,
+      childId: opts.addonId,
+      caps: [{ capName: 'addon-routes', mode: 'collection' }],
+      // Cap dispatch — resolve the `addon-routes` cap's `invoke`/`getRoutes`
+      // method on the live route provider (mirrors the runner's
+      // createChildCapDispatch resolving allSingletonProviders['addon-routes']).
+      dispatch: async (call) => {
+        if (call.capName === 'addon-routes' && routeProvider !== null) {
+          const fn = Reflect.get(routeProvider, call.method)
+          if (typeof fn === 'function') return fn.call(routeProvider, call.args)
+        }
+        return null
+      },
+    })
+    // Inline addon-runner dispatcher: routes → handler-stripped descriptors,
+    // custom → the child custom-action registry. Mirrors
+    // `createChildAddonCallDispatch` in the kernel.
+    child.onAddonCall(async (call: AddonCallInput) => {
+      if (call.target === 'routes') {
+        if (routeProvider === null) throw new Error(`addon "${call.addonId}" has no routes`)
+        const live = routeProvider.getRoutes()
+        return live.map((r) => ({
+          method: r.method,
+          path: r.path,
+          ...(r.access !== undefined ? { access: r.access } : {}),
+          ...(r.description !== undefined ? { description: r.description } : {}),
+        }))
+      }
+      const action = call.action
+      if (typeof action !== 'string') throw new Error('missing action')
+      const entry = childCustomActions.resolve(call.addonId, action)
+      if (entry === null) throw new Error(`no custom action "${action}"`)
+      return entry.handler(call.args)
+    })
+    clients.push(child)
+    await child.start()
+
+    return { childCustomActions }
+  }
+
+  it('custom action: the registerForkedAddonCustomActions dispatch path reaches the child handler', async () => {
+    const catalog = defineCustomActions({
+      runBenchmark: customAction(
+        z.object({ iterations: z.number() }),
+        z.object({ ran: z.number() }),
+        { kind: 'mutation' },
+      ),
+    })
+    await standUp({
+      addonId: 'benchmark',
+      catalog,
+      handlers: {
+        runBenchmark: async (input) => {
+          const args = input as { iterations: number }
+          return { ran: args.iterations }
+        },
+      },
+    })
+
+    // Hub-side registry — the dispatcher mirrors `dispatchForkedCustomAction`.
+    const hubRegistry = new CustomActionRegistry()
+    hubRegistry.registerAddon('benchmark', catalog, (action, input) =>
+      registry!.callAddonOnChild('benchmark', {
+        addonId: 'benchmark',
+        target: 'custom',
+        action,
+        args: input,
+      }),
+    )
+
+    const entry = hubRegistry.resolve('benchmark', 'runBenchmark')
+    expect(entry).not.toBeNull()
+    const result = await entry!.handler({ iterations: 9 })
+    expect(result).toEqual({ ran: 9 })
+  })
+
+  it('routes: callAddonOnChild(routes) returns stripped descriptors and invoke() round-trips', async () => {
+    const routes: IAddonHttpRoute[] = [
+      {
+        method: 'GET',
+        path: '/hello/:name',
+        access: 'public',
+        handler: async (req, reply) => {
+          reply.code(200)
+          reply.send({ greeting: `hi ${req.params.name}` })
+        },
+      },
+    ]
+    await standUp({ addonId: 'export-alexa', routes })
+
+    // (a) routes come back handler-stripped (the `mountForkedAddonRoutes` fetch).
+    const rawRoutes = await registry!.callAddonOnChild('export-alexa', {
+      addonId: 'export-alexa',
+      target: 'routes',
+    })
+    expect(rawRoutes).toEqual([{ method: 'GET', path: '/hello/:name', access: 'public' }])
+
+    // (b) dispatch through the addon-routes cap proxy's `invoke` cap method —
+    // the bridge handler `mountForkedAddonRoutes` synthesizes calls this.
+    const routesCapProxy = {
+      invoke: (input: unknown) =>
+        registry!.callCapOnChild('export-alexa', {
+          capName: 'addon-routes',
+          method: 'invoke',
+          args: input,
+        }),
+    }
+    const envelope = await routesCapProxy.invoke({
+      method: 'GET',
+      path: '/hello/world',
+      params: { name: 'world' },
+      query: {},
+      body: undefined,
+      headers: {},
+    })
+    expect(envelope).toMatchObject({ status: 200, body: { greeting: 'hi world' } })
+  })
+
+  it('auth-oidc shape: a forked addon with a SYNC array getRoutes + async handlers mounts via the strip path without serializing a function', async () => {
+    // Reproduces the regression: `auth-oidc` declares a manual route provider
+    // `{ id, getRoutes: () => routes }` (NO `buildAddonRouteProvider`, NO
+    // `invoke`). It forks like every non-core addon, so the hub resolves an
+    // async UDS cap proxy whose `getRoutes()` returns a Promise. The mount path
+    // MUST NOT register that proxy directly (→ `getRoutes(...).map is not a
+    // function`) nor dispatch its `getRoutes` cap method over UDS (the child's
+    // `getRoutes()` returns the live array WITH async `handler` functions →
+    // MsgPack "Unrecognized object: [object AsyncFunction]"). It uses the
+    // handler-stripped `callAddonOnChild(target:'routes')` bridge instead.
+    const routes: IAddonHttpRoute[] = [
+      {
+        method: 'GET',
+        path: '/:providerId/start',
+        access: 'public',
+        description: 'Begin OIDC redirect login flow',
+        handler: async (req, reply) => {
+          reply.code(302)
+          reply.send('')
+        },
+      },
+      {
+        method: 'GET',
+        path: '/:providerId/callback',
+        access: 'public',
+        handler: async (req, reply) => {
+          reply.code(200)
+          reply.send('ok')
+        },
+      },
+    ]
+    await standUp({ addonId: 'auth-oidc', routes })
+
+    // The handler-stripped descriptors cross the real UDS pair. If the strip
+    // path leaked a `handler` function, MsgPack `encodeFrame` would throw
+    // "Unrecognized object: [object AsyncFunction]" before this resolves.
+    const rawRoutes = await registry!.callAddonOnChild('auth-oidc', {
+      addonId: 'auth-oidc',
+      target: 'routes',
+    })
+    expect(rawRoutes).toEqual([
+      { method: 'GET', path: '/:providerId/start', access: 'public', description: 'Begin OIDC redirect login flow' },
+      { method: 'GET', path: '/:providerId/callback', access: 'public' },
+    ])
+    // Coarse reachability gate the route-mount fallback uses: the child is
+    // connected even though we only checked the addon-call surface.
+    expect(registry!.isChildKnown('auth-oidc')).toBe(true)
+  })
+})

package/src/__tests__/uds-log-ingest.spec.ts

@@ -0,0 +1,183 @@
+/**
+ * UDS child log ingest — unit test for Task B2.
+ *
+ * Verifies that wiring `LocalChildRegistry.onChildLog` to
+ * `LoggingService.writeFromWorker` correctly maps a `ChildLogMessage`
+ * produced over a UDS channel to the `writeFromWorker` entry shape.
+ *
+ * We test the helper `udsChildLogToWorkerEntry` (extracted from the
+ * hub/agent wiring) directly, plus the full registry+handler pairing so
+ * the glue code exercises the real `onChildLog` callback path.
+ */
+import { describe, it, expect, vi } from 'vitest'
+import type { ChildLogMessage } from '@camstack/kernel'
+import { udsChildLogToWorkerEntry } from '@camstack/kernel'
+
+// --------------------------------------------------------------------------
+// Minimal `WriteFromWorkerEntry` shape mirrored from LoggingService signature
+// --------------------------------------------------------------------------
+interface WriteFromWorkerEntry {
+  addonId: string
+  nodeId?: string
+  level: string
+  message: string
+  scope?: string
+  tags?: Record<string, string | number | undefined>
+  meta?: Record<string, unknown>
+}
+
+// --------------------------------------------------------------------------
+// Helper: build a minimal ChildLogMessage
+// --------------------------------------------------------------------------
+function makeLogMessage(overrides?: Partial<ChildLogMessage>): ChildLogMessage {
+  return {
+    kind: 'log',
+    level: 'info',
+    message: 'hello from child',
+    addonId: 'stream-broker',
+    ...overrides,
+  }
+}
+
+// --------------------------------------------------------------------------
+// Tests for udsChildLogToWorkerEntry
+// --------------------------------------------------------------------------
+
+describe('udsChildLogToWorkerEntry', () => {
+  it('maps the required fields — addonId, level, message', () => {
+    const entry = makeLogMessage()
+    const result = udsChildLogToWorkerEntry('stream-broker', entry)
+
+    expect(result.addonId).toBe('stream-broker')
+    expect(result.level).toBe('info')
+    expect(result.message).toBe('hello from child')
+  })
+
+  it('uses entry.nodeId when present', () => {
+    const entry = makeLogMessage({ nodeId: 'hub/stream-broker' })
+    const result = udsChildLogToWorkerEntry('stream-broker', entry)
+
+    expect(result.nodeId).toBe('hub/stream-broker')
+  })
+
+  it('falls back to childId when nodeId is absent', () => {
+    const entry = makeLogMessage()
+    const result = udsChildLogToWorkerEntry('stream-broker', entry)
+
+    expect(result.nodeId).toBe('stream-broker')
+  })
+
+  it('omits scope when not present in entry', () => {
+    const entry = makeLogMessage()
+    const result = udsChildLogToWorkerEntry('stream-broker', entry)
+
+    expect(Object.prototype.hasOwnProperty.call(result, 'scope')).toBe(false)
+  })
+
+  it('includes scope when present in entry', () => {
+    const entry = makeLogMessage({ scope: 'rtsp' })
+    const result = udsChildLogToWorkerEntry('stream-broker', entry)
+
+    expect(result.scope).toBe('rtsp')
+  })
+
+  it('omits tags when not present in entry', () => {
+    const entry = makeLogMessage()
+    const result = udsChildLogToWorkerEntry('stream-broker', entry)
+
+    expect(Object.prototype.hasOwnProperty.call(result, 'tags')).toBe(false)
+  })
+
+  it('includes tags when present in entry', () => {
+    const entry = makeLogMessage({ tags: { deviceId: 5, streamId: '5/main' } })
+    const result = udsChildLogToWorkerEntry('stream-broker', entry)
+
+    expect(result.tags).toEqual({ deviceId: 5, streamId: '5/main' })
+  })
+
+  it('omits meta when not present in entry', () => {
+    const entry = makeLogMessage()
+    const result = udsChildLogToWorkerEntry('stream-broker', entry)
+
+    expect(Object.prototype.hasOwnProperty.call(result, 'meta')).toBe(false)
+  })
+
+  it('includes meta when present in entry', () => {
+    const entry = makeLogMessage({ meta: { rtt: 42 } })
+    const result = udsChildLogToWorkerEntry('stream-broker', entry)
+
+    expect(result.meta).toEqual({ rtt: 42 })
+  })
+
+  it('produces the same shape that $hub.log onLog produces', () => {
+    // The existing onLog wiring in moleculer.service.ts maps:
+    //   { addonId, nodeId, level, message, scope?, tags?, meta? }
+    // Verify we produce an identical structure for a fully-populated entry.
+    const entry = makeLogMessage({
+      addonId: 'ptz-provider',
+      nodeId: 'hub/ptz-provider',
+      level: 'warn',
+      message: 'PTZ timeout',
+      scope: 'ptz',
+      tags: { deviceId: 3 },
+      meta: { timeout: 5000 },
+    })
+    const result = udsChildLogToWorkerEntry('hub/ptz-provider', entry)
+
+    const expected: WriteFromWorkerEntry = {
+      addonId: 'ptz-provider',
+      nodeId: 'hub/ptz-provider',
+      level: 'warn',
+      message: 'PTZ timeout',
+      scope: 'ptz',
+      tags: { deviceId: 3 },
+      meta: { timeout: 5000 },
+    }
+    expect(result).toEqual(expected)
+  })
+})
+
+// --------------------------------------------------------------------------
+// Tests for the registry+handler wiring (the onChildLog callback path)
+// --------------------------------------------------------------------------
+
+describe('onChildLog handler wiring', () => {
+  it('calls writeFromWorker when a ChildLogMessage arrives', () => {
+    // Fake logging service — typed minimal interface
+    const fakeLogging = {
+      writeFromWorker: vi.fn<[WriteFromWorkerEntry], void>(),
+    }
+
+    // The actual wiring closure (mirrors hub & agent wiring)
+    const handler = (childId: string, entry: ChildLogMessage): void => {
+      fakeLogging.writeFromWorker(udsChildLogToWorkerEntry(childId, entry))
+    }
+
+    const entry = makeLogMessage({ addonId: 'motion-detector', nodeId: 'hub/motion-detector' })
+    handler('hub/motion-detector', entry)
+
+    expect(fakeLogging.writeFromWorker).toHaveBeenCalledOnce()
+    const called = fakeLogging.writeFromWorker.mock.calls[0]![0]
+    expect(called.addonId).toBe('motion-detector')
+    expect(called.nodeId).toBe('hub/motion-detector')
+    expect(called.level).toBe('info')
+    expect(called.message).toBe('hello from child')
+  })
+
+  it('invokes writeFromWorker once per log entry', () => {
+    const fakeLogging = {
+      writeFromWorker: vi.fn<[WriteFromWorkerEntry], void>(),
+    }
+
+    const handler = (childId: string, entry: ChildLogMessage): void => {
+      fakeLogging.writeFromWorker(udsChildLogToWorkerEntry(childId, entry))
+    }
+
+    handler('child-a', makeLogMessage({ addonId: 'child-a', level: 'debug', message: 'first' }))
+    handler('child-b', makeLogMessage({ addonId: 'child-b', level: 'error', message: 'second' }))
+
+    expect(fakeLogging.writeFromWorker).toHaveBeenCalledTimes(2)
+    expect(fakeLogging.writeFromWorker.mock.calls[0]![0].addonId).toBe('child-a')
+    expect(fakeLogging.writeFromWorker.mock.calls[1]![0].addonId).toBe('child-b')
+  })
+})

package/src/api/addon-upload.ts

@@ -7,6 +7,8 @@ import type { IScopedLogger, TokenScope } from '@camstack/types'
 import { checkScopeAccess } from './trpc/scope-access.js'
 import type { AddonBridgeService } from '../core/addon-bridge/addon-bridge.service'
 import type { AddonRegistryService } from '../core/addon/addon-registry.service'
+import type { AddonPackageService } from '../core/addon/addon-package.service'
+import { isFrameworkPackage } from '../core/addon/addon-package.service.js'
 import type { AuthService } from '../core/auth/auth.service'
 import type { MoleculerService } from '../core/moleculer/moleculer.service'
 
@@ -112,6 +114,7 @@ export async function registerAddonUploadRoute(
   authService: AuthService,
   moleculer: MoleculerService,
   addonRegistry: AddonRegistryService,
+  addonPackageService: AddonPackageService,
   logger: IScopedLogger,
 ): Promise<void> {
   await fastify.register(import('@fastify/multipart'), {
@@ -197,7 +200,7 @@ export async function registerAddonUploadRoute(
     // the package's addons (i.e. anything not marked hub-only). Any other
     // explicit `nodeId` value routes only to that agent via `$agent.deploy`.
     if (!nodeId || nodeId === 'hub') {
-      return installToHub(reply, addonBridge, addonRegistry, moleculer, logger, data.filename, buffer)
+      return installToHub(reply, addonBridge, addonRegistry, addonPackageService, moleculer, logger, data.filename, buffer)
     }
     const agentAddonId = addonIdHint ?? manifest.name
     return deployToAgent(reply, moleculer, nodeId, agentAddonId, buffer)
@@ -330,6 +333,7 @@ async function installToHub(
   reply: FastifyReply,
   addonBridge: AddonBridgeService,
   addonRegistry: AddonRegistryService,
+  addonPackageService: AddonPackageService,
   moleculer: MoleculerService,
   logger: IScopedLogger,
   filename: string,
@@ -360,6 +364,28 @@ async function installToHub(
     const addonsDir = path.resolve(process.env['CAMSTACK_DATA'] ?? 'camstack-data', 'addons')
     fs.writeFileSync(path.join(addonsDir, result.name, '.install-source'), 'upload')
 
+    // Framework / system packages (`camstack.system: true`, e.g. @camstack/core)
+    // ship hub builtins (sqlite-settings, filesystem-storage, …) that CANNOT be
+    // hot-reloaded in place — an in-process `restartAddon` leaves them
+    // uninitialized ("SqliteSettingsBackend not initialized"), breaking auth +
+    // settings. The new code is now on disk; a clean server restart reloads it
+    // and re-runs boot initialization. The 10s restart grace lets this response
+    // flush before the process exits, so the CLI sees a clean confirmation.
+    if (isFrameworkPackage(result.name)) {
+      logger.info('framework package deployed — scheduling server restart', {
+        meta: { packageName: result.name, packageVersion: result.version },
+      })
+      addonPackageService.restartServer(`addon-upload: ${result.name}@${result.version}`)
+      return reply.send({
+        success: true,
+        name: result.name,
+        version: result.version,
+        requiresRestart: true,
+        restarting: true,
+        message: 'Framework package installed — server is restarting to load it',
+      })
+    }
+
     // `addonRegistry.loadNewAddons()` already runs its own fresh filesystem
     // scan, diff'ing against existing `addonEntries` — it updates metadata
     // for known addons without touching their live instances + initializes

package/src/api/capabilities.router.ts

@@ -113,7 +113,7 @@ export function createCapabilitiesRouter(
 
           if (!requiresRestart) {
             // Hot-swap at runtime
-            await registry.setActiveSingleton(capability, addonId, true)
+            await registry.setActiveSingleton(capability, addonId)
           }
 
           // Persist preference

package/src/api/core/__tests__/integration-markers.spec.ts

@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest'
+import { INTEGRATION_CAP_MARKERS } from '../cap-providers.js'
+
+describe('integration cap markers', () => {
+  it('recognises device-adoption (not the old ha-discovery)', () => {
+    expect(INTEGRATION_CAP_MARKERS.has('device-adoption')).toBe(true)
+    expect(INTEGRATION_CAP_MARKERS.has('ha-discovery')).toBe(false)
+    expect(INTEGRATION_CAP_MARKERS.has('device-provider')).toBe(true)
+  })
+})