@camstack/server 0.1.3

package/src/api/trpc/cap-mount-helpers.ts

@@ -0,0 +1,225 @@
+/**
+ * Small helpers for wiring capability routers to the `CapabilityRegistry`
+ * in `trpc.router.ts`. These functions don't generate code — they just
+ * remove boilerplate from the mount lambdas we pass to `createCapRouter_X`.
+ *
+ * When to use what:
+ *   - `requireSingleton(registry, name)` — singleton caps with no custom
+ *     composition. Returns the active provider or null (the codegen'd
+ *     router itself throws PRECONDITION_FAILED when null).
+ *   - `concatCollection(providers, method)` — collection caps whose
+ *     methods return arrays and where the desired behaviour is "union of
+ *     every provider's contribution" (e.g. `turn-provider.getTurnServers`).
+ *   - `firstSupported(providers, probe, action)` — collection caps where
+ *     exactly one provider should handle each request, selected by a
+ *     probe method (e.g. `snapshot-provider.supportsDevice`).
+ *
+ * Collections that route by an input key (e.g. `webrtc` picking the
+ * provider responsible for a given `streamId`) are NOT covered here —
+ * they have app-specific routing logic that belongs in the mount.
+ */
+import { TRPCError } from '@trpc/server'
+import type { CapabilityRegistry } from '@camstack/kernel'
+import type { CapabilityProviderMap } from '@camstack/types'
+
+/**
+ * Fetch the currently active singleton provider for a capability.
+ * Returns null if no provider is registered; the downstream codegen'd
+ * router surfaces this as `PRECONDITION_FAILED` to the caller.
+ */
+export function requireSingleton<K extends keyof CapabilityProviderMap>(
+  registry: CapabilityRegistry | null,
+  capName: K,
+): CapabilityProviderMap[K] | null {
+  return registry?.getSingleton(capName) ?? null
+}
+
+/**
+ * Build a per-device dispatcher that satisfies the singleton-provider
+ * shape but resolves the actual implementation lazily via
+ * `registry.getNativeProvider(capName, deviceId)` on every method call.
+ *
+ * Use for device-scoped caps that have NO system-level wrapper (PTZ,
+ * reboot, doorbell, brightness, motion-trigger, switch, …) — drivers
+ * register per-device native providers via
+ * `DeviceContext.registerNativeCap`, and this helper bridges the cap-
+ * router's "fetch a singleton then call methods on it" flow into a
+ * "resolve native by deviceId per call" flow.
+ *
+ * Method input MUST carry `deviceId: number`. Methods without that
+ * field (auto-injected `getStatus({deviceId})` for caps with a status
+ * block, every business method that follows the cap-definition
+ * convention) work transparently.
+ *
+ * Throws PRECONDITION_FAILED with a device-specific message when no
+ * native provider exists for the requested deviceId — much friendlier
+ * than the singleton fallthrough's "no provider" generic error.
+ */
+export function requireDeviceScoped<K extends keyof CapabilityProviderMap>(
+  registry: CapabilityRegistry | null,
+  capName: K,
+): CapabilityProviderMap[K] | null {
+  if (!registry) return null
+  // The Proxy is the singleton stand-in. Each property access returns
+  // a function that, on call, looks up the per-device native and
+  // forwards the call. No caching — the lookup is cheap (Map.get) and
+  // re-doing it per call lets devices come/go without stale refs.
+  const dispatcher = new Proxy({}, {
+    get(_target, prop: string | symbol) {
+      if (typeof prop !== 'string') return undefined
+      return async (input: { deviceId?: number } & Record<string, unknown>) => {
+        const deviceId = input?.deviceId
+        if (typeof deviceId !== 'number') {
+          throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: `${String(capName)}.${prop}: input must carry numeric "deviceId"`,
+          })
+        }
+        const native = registry.getNativeProvider<Record<string, (i: unknown) => unknown>>(
+          capName,
+          deviceId,
+        )
+        if (!native) {
+          throw new TRPCError({
+            code: 'PRECONDITION_FAILED',
+            message: `Capability "${String(capName)}" not registered for device ${deviceId}`,
+          })
+        }
+        const fn = native[prop]
+        if (typeof fn !== 'function') {
+          throw new TRPCError({
+            code: 'NOT_IMPLEMENTED',
+            message: `Capability "${String(capName)}" provider for device ${deviceId} does not implement "${prop}"`,
+          })
+        }
+        return fn.call(native, input)
+      }
+    },
+  })
+  return dispatcher as unknown as CapabilityProviderMap[K]
+}
+
+// ── Method-on-provider callable types ────────────────────────────────
+
+/** A key on T whose value is a function with array / promise-array return. */
+type ArrayReturningMethodKey<T> = {
+  [K in keyof T]: T[K] extends (...args: infer _A) => readonly unknown[] | Promise<readonly unknown[]>
+    ? K
+    : never
+}[keyof T]
+
+/** A key on T whose value is a function returning boolean / promise-boolean. */
+type BoolReturningMethodKey<T> = {
+  [K in keyof T]: T[K] extends (...args: infer _A) => boolean | Promise<boolean>
+    ? K
+    : never
+}[keyof T]
+
+/**
+ * Build a method that fan-outs a call to every provider in a collection
+ * and concatenates their array results. Useful for contribution-style
+ * caps where each provider adds to a shared pool.
+ */
+export function concatCollection<
+  T extends object,
+  K extends ArrayReturningMethodKey<T>,
+>(
+  providers: readonly T[],
+  method: K,
+): T[K] extends (...args: infer A) => readonly (infer R)[] | Promise<readonly (infer R)[]>
+  ? (...args: A) => Promise<readonly R[]>
+  : never {
+  const wrapper = async (...args: unknown[]): Promise<readonly unknown[]> => {
+    const results = await Promise.all(
+      providers.map(async (p): Promise<readonly unknown[]> => {
+        const member = Reflect.get(p, method)
+        if (typeof member !== 'function') return []
+        // `Reflect.apply` returns `any`; funnel through unknown.
+        const out: unknown = await Reflect.apply(member, p, args)
+        if (!Array.isArray(out)) return []
+        const arr: readonly unknown[] = out
+        return arr
+      }),
+    )
+    return results.flat()
+  }
+  // Type-level bridge: the runtime wrapper signature (unknown → Promise<unknown[]>)
+  // matches the declared generic conditional return; TypeScript's
+  // conditional types can't be narrowed inside a function body, so this
+  // boundary assertion is required.
+  return wrapper as T[K] extends (...args: infer A) => readonly (infer R)[] | Promise<readonly (infer R)[]>
+    ? (...args: A) => Promise<readonly R[]>
+    : never
+}
+
+/**
+ * Iterate a collection asking each provider "do you handle this?" via a
+ * probe method, then call an action on the first one that answers yes.
+ * Each provider is tried in registration order; errors are swallowed and
+ * the next provider is attempted. Returns null if no provider matches or
+ * if every matching provider's action throws/returns null.
+ */
+export function firstSupported<
+  T extends object,
+  Probe extends BoolReturningMethodKey<T>,
+  Action extends keyof T,
+>(
+  providers: readonly T[],
+  probe: Probe,
+  action: Action,
+): T[Action] extends (...args: infer A) => infer R
+  ? (...args: A) => Promise<Awaited<R> | null>
+  : never {
+  const wrapper = async (...args: unknown[]): Promise<unknown> => {
+    const [first] = args
+    for (const p of providers) {
+      try {
+        const probeMember = Reflect.get(p, probe)
+        if (typeof probeMember !== 'function') continue
+        const supported: unknown = await Reflect.apply(probeMember, p, [first])
+        if (supported !== true) continue
+        const actionMember = Reflect.get(p, action)
+        if (typeof actionMember !== 'function') continue
+        const result: unknown = await Reflect.apply(actionMember, p, args)
+        if (result !== null && result !== undefined) return result
+      } catch {
+        // try next provider
+      }
+    }
+    return null
+  }
+  // Type-level bridge — see concatCollection for the same pattern.
+  return wrapper as T[Action] extends (...args: infer A) => infer R
+    ? (...args: A) => Promise<Awaited<R> | null>
+    : never
+}
+
+/**
+ * Convenience for collection caps that want a "logical OR of probes"
+ * (e.g. `supportsDevice` across every snapshot-provider).
+ */
+export function anySupports<
+  T extends object,
+  K extends BoolReturningMethodKey<T>,
+>(
+  providers: readonly T[],
+  probe: K,
+): T[K] extends (...args: infer A) => boolean | Promise<boolean>
+  ? (...args: A) => Promise<boolean>
+  : never {
+  const wrapper = async (...args: unknown[]): Promise<boolean> => {
+    for (const p of providers) {
+      const member = Reflect.get(p, probe)
+      if (typeof member !== 'function') continue
+      try {
+        const result: unknown = await Reflect.apply(member, p, args)
+        if (result === true) return true
+      } catch { /* next */ }
+    }
+    return false
+  }
+  // Type-level bridge — see concatCollection for the same pattern.
+  return wrapper as T[K] extends (...args: infer A) => boolean | Promise<boolean>
+    ? (...args: A) => Promise<boolean>
+    : never
+}

package/src/api/trpc/core-cap-bridge.ts

@@ -0,0 +1,152 @@
+/**
+ * Core-capability mesh bridge.
+ *
+ * The hub's CORE routers — hand-written single-impl routers plus the
+ * handful of service-backed cap routers — are mounted only as the hub's
+ * tRPC `appRouter`. No addon registers a provider for them, so
+ * `addon-service-factory` never publishes a Moleculer service exposing
+ * their actions. A forked addon calling `ctx.api.<coreCap>.<method>`
+ * therefore falls through `localProviderLink` into `brokerTransportLink`,
+ * whose load-balanced discovery wait has no deadline — the call hangs
+ * forever (this was the `export-alexa` `redetectHubUrl` hang).
+ *
+ * `buildCoreCapService` walks the appRouter, picks the core namespaces,
+ * and wraps each query/mutation as a `$core-caps.<kebab-cap>.<method>`
+ * Moleculer action invoked through a trusted-mesh tRPC caller. With the
+ * service mounted on the hub node, `brokerTransportLink` resolves and
+ * routes the call exactly like any addon-provided cap.
+ */
+import type { ServiceSchema } from 'moleculer'
+import { createCoreCapService, type CoreCapAction } from '@camstack/kernel'
+import { createCallerFactory } from './trpc.middleware.js'
+import { createMeshTrpcContext } from './trpc.context.js'
+import type { AppRouter } from './trpc.router.js'
+
+/**
+ * appRouter namespaces that back the CORE API surface and must be
+ * reachable cross-process. This is the core-router list from
+ * `trpc.router.ts` (`buildCapabilityRouters`) minus the deliberate
+ * exclusions below.
+ *
+ * Excluded on purpose:
+ *  - `auth` — issuing service / scoped tokens over the trusted mesh
+ *    would let any forked addon mint admin credentials. Addons must
+ *    not perform authentication operations; this stays hub-local.
+ *  - `live`, `systemEvents` — listed in `NEVER_BRIDGED_CAPS`
+ *    (`trpc-links.ts`). They are hub-only push streams, not
+ *    request/reply, and the worker side fast-fails on them by design.
+ */
+const CORE_NAMESPACES: ReadonlySet<string> = new Set<string>([
+  // Service-backed cap routers (no addon provider).
+  'system',
+  'toast',
+  'integrations',
+  'nodes',
+  'addons',
+  // Hand-written single-impl core routers.
+  'capabilities',
+  'notifications',
+  'logs',
+  'hwaccel',
+  'streamProbe',
+  'settingsBackend',
+  'eventBusProxy',
+  'repl',
+  'addonSettingsRaw',
+])
+
+/**
+ * camelCase → kebab-case. Mirrors `toKebab` in `trpc-links.ts` so the
+ * action name matches what `brokerTransportLink` derives from `op.path`.
+ */
+function toKebab(name: string): string {
+  return name.replace(/[A-Z]/g, (m, i: number) => (i > 0 ? '-' : '') + m.toLowerCase())
+}
+
+/** A tRPC procedure node — distinguished from a router by `_def.procedure`. */
+interface ProcedureNode {
+  readonly _def: { readonly procedure?: unknown; readonly type?: unknown }
+}
+
+function isProcedureNode(value: unknown): value is ProcedureNode {
+  // A built tRPC procedure is a callable object — `_def.procedures`
+  // stores the procedure function directly, not a wrapper object.
+  if (value === null || (typeof value !== 'object' && typeof value !== 'function')) return false
+  const def: unknown = (value as { _def?: unknown })._def
+  return def !== null && typeof def === 'object' && (def as { procedure?: unknown }).procedure === true
+}
+
+interface DiscoveredProcedure {
+  readonly path: string
+  readonly type: string
+}
+
+/**
+ * Recursively flatten a tRPC router record to dotted procedure paths.
+ * Robust to both layouts tRPC v11 may use for `_def.procedures`: a
+ * nested record of sub-routers, or a flat record already keyed by
+ * dotted path (a flat key simply yields its key verbatim).
+ */
+function collectProcedures(
+  record: Readonly<Record<string, unknown>>,
+  prefix: string,
+  out: DiscoveredProcedure[],
+): void {
+  for (const [key, value] of Object.entries(record)) {
+    const path = prefix.length > 0 ? `${prefix}.${key}` : key
+    if (isProcedureNode(value)) {
+      const type = value._def.type
+      out.push({ path, type: typeof type === 'string' ? type : 'query' })
+    } else if (value !== null && typeof value === 'object') {
+      collectProcedures(value as Readonly<Record<string, unknown>>, path, out)
+    }
+  }
+}
+
+type ProcedureInvoker = (input: unknown) => Promise<unknown>
+
+/**
+ * Navigate the decorated caller record (a recursive proxy) to the
+ * procedure function at `path`. Every node on the proxy is callable,
+ * so navigation uses `Reflect.get` across both objects and functions.
+ */
+function resolveInvoker(caller: unknown, path: string): ProcedureInvoker | null {
+  let node: unknown = caller
+  for (const segment of path.split('.')) {
+    if (node === null || (typeof node !== 'object' && typeof node !== 'function')) return null
+    // Documented boundary: `node` is an object or function past the
+    // guard above; `Reflect.get` is typed for `object` targets.
+    node = Reflect.get(node as object, segment)
+  }
+  return typeof node === 'function' ? (node as ProcedureInvoker) : null
+}
+
+/**
+ * Build the `$core-caps` Moleculer service schema from the hub
+ * appRouter. Query + mutation procedures in {@link CORE_NAMESPACES} are
+ * exposed; subscriptions are skipped (the broker transport is
+ * request/reply only).
+ */
+export function buildCoreCapService(appRouter: AppRouter): ServiceSchema {
+  const meshCaller: unknown = createCallerFactory(appRouter)(createMeshTrpcContext())
+
+  const discovered: DiscoveredProcedure[] = []
+  collectProcedures(appRouter._def.procedures, '', discovered)
+
+  const actions: CoreCapAction[] = []
+  for (const { path, type } of discovered) {
+    const dot = path.indexOf('.')
+    if (dot < 0) continue
+    const namespace = path.slice(0, dot)
+    if (!CORE_NAMESPACES.has(namespace)) continue
+    if (type === 'subscription') continue
+
+    const invoke = resolveInvoker(meshCaller, path)
+    if (invoke === null) continue
+
+    const method = path.slice(dot + 1)
+    actions.push({ actionName: `${toKebab(namespace)}.${method}`, invoke })
+  }
+
+  return createCoreCapService({ actions })
+}