@camstack/server 0.1.6 → 0.1.7

package/src/api/trpc/trpc.middleware.ts

@@ -3,8 +3,12 @@ import superjson from 'superjson'
 import { METHOD_ACCESS_MAP } from '@camstack/types'
 import type { TrpcContext } from './trpc.context'
 import { checkScopeAccess } from './scope-access.js'
+import { formatTrpcError } from './cap-route-error-formatter.js'
 
-const t = initTRPC.context<TrpcContext>().create({ transformer: superjson })
+const t = initTRPC.context<TrpcContext>().create({
+  transformer: superjson,
+  errorFormatter: formatTrpcError,
+})
 
 // ---------------------------------------------------------------------------
 // Async-generator subscription helpers (tRPC v11 — replaces deprecated observable)

package/src/api/trpc/trpc.router.ts

@@ -30,6 +30,7 @@ import {
   platformProbeCapability,
   decoderCapability,
   localNetworkCapability,
+  webrtcSessionCapability,
 } from '@camstack/types'
 import {
   // The auto-mount covers ~75 caps. The handful re-imported below back
@@ -51,6 +52,7 @@ import {
   createCapRouter_integrations,
   createCapRouter_nodes,
   createCapRouter_addons,
+  createCapRouter_webrtcSession,
 } from './generated-cap-routers'
 import { mountAllCaps } from './generated-cap-mounts.js'
 import {
@@ -74,6 +76,7 @@ import { createCapabilitiesRouter } from '../core/capabilities.router.js'
 import { createStreamProbeRouter } from '../core/stream-probe.router.js'
 import { createHwAccelRouter } from '../core/hwaccel.router.js'
 import { requireSingleton, firstSupported, anySupports } from './cap-mount-helpers.js'
+import type { TrpcContext } from './trpc.context.js'
 import type { AuthService } from '../../core/auth/auth.service'
 import type { ConfigService } from '../../core/config/config.service'
 import type { FeatureService } from '../../core/feature/feature.service'
@@ -108,6 +111,28 @@ export interface RouterServices {
   streamProbe: StreamProbeService | null
 }
 
+type WebrtcSessionProvider = InferProvider<typeof webrtcSessionCapability>
+
+/**
+ * Relay-only forcing for remote viewers is DISABLED (2026-05-26).
+ *
+ * It was meant to give CGNAT/4G viewers a clean relay↔relay path, but werift's
+ * TURN media-forward is unreliable between two real TURN servers (relay↔relay
+ * connects yet media never arrives → connected-but-black), and forcing relay
+ * ALSO kills the direct LAN/Tailscale host pair — which carries full native
+ * quality with no relay. We now offer ALL candidates (host incl. the hub's
+ * advertised Tailscale address, srflx, relay) and let ICE nominate the best
+ * reachable pair: direct when possible, relay only as a fallback. The
+ * `relayOnly` cap field + broker support remain for when relay media-forward
+ * is fixed; this wrapper is a pass-through for now.
+ */
+function wrapWebrtcSessionProviderWithRelay(
+  provider: WebrtcSessionProvider,
+  _ctx: TrpcContext,
+): WebrtcSessionProvider {
+  return provider
+}
+
 /**
  * Build the AppRouter. Mounts every codegen'd cap router via the auto-
  * mount entrypoint and overrides the handful that need service-backed
@@ -183,6 +208,7 @@ function buildCapabilityRouters(services: RouterServices) {
         services.moleculer,
         services.configService,
         ctx,
+        services.eventBus,
       ),
     ),
 
@@ -253,6 +279,25 @@ function buildCapabilityRouters(services: RouterServices) {
       },
     ),
 
+    // ── Cap override: server-detected remote → relay-only ────────────
+    // The broker (a forked addon) can't see the HTTP request, so it
+    // can't tell a LAN viewer from a remote one. We override only the
+    // `getProvider` accessor to return a per-request provider whose
+    // `createSession` carries a server-computed `relayOnly` flag derived
+    // from the client IP in `ctx.req`. Remote (CGNAT/4G) viewers force
+    // TURN-relay-only ICE; LAN viewers keep the direct host/srflx path.
+    // All other methods delegate straight through, and the cross-node
+    // remote-proxy routing is preserved (forked/agent-hosted brokers).
+    webrtcSession: createCapRouter_webrtcSession(
+      (ctx) => {
+        const provider = services.capabilityRegistry
+          ?.getSingleton<WebrtcSessionProvider>('webrtc-session') ?? null
+        return provider ? wrapWebrtcSessionProviderWithRelay(provider, ctx) : null
+      },
+      (capName, nodeId) =>
+        services.moleculer.createCapabilityProxy(capName, nodeId) as WebrtcSessionProvider | null,
+    ),
+
     // NOT MOUNTED — legacy provider shapes (positional args / sync
     // returns) that don't match the codegen routers' {input}-object +
     // Promise<T> contract. Tracked by `LEGACY_SHAPE_SKIP` in

package/src/core/addon/addon-call-gateway.ts

@@ -0,0 +1,157 @@
+/**
+ * `AddonCallGateway` — the SINGLE hub-side router for addon-LEVEL calls (the
+ * surfaces the removed per-addon Moleculer broker used to carry: routes,
+ * custom-actions, settings — see `AddonCallTarget`).
+ *
+ * Why this exists: that routing decision (is the addon running in-process on
+ * the hub, as a forked hub-local CHILD reachable over UDS, or on a REMOTE
+ * agent over Moleculer?) used to be duplicated per surface — routes/custom in
+ * `addon-registry.service.ts`, settings in `addon-settings-provider.ts`. When
+ * the UDS migration ported routes+custom to `callAddonOnChild`, settings was
+ * left on the dead `<addonId>.settings.<method>` Moleculer path because nothing
+ * centralised "dispatch an addon-level call to wherever the addon runs". Every
+ * forked hub-local addon's settings panel silently went empty for months.
+ *
+ * Now every addon-level surface routes through `callForked` here. Combined with
+ * the exhaustive `AddonCallTarget` union (a `never`-checked dispatch in
+ * `createChildAddonCallDispatch`), a future surface can't be half-wired without
+ * a compile error — the class of "missed link" is closed.
+ */
+import type { AddonCallInput, LocalChildRegistry } from '@camstack/kernel'
+
+/** An addon-level call minus its `addonId` — the gateway merges that in. */
+export type AddonCallSurface = Omit<AddonCallInput, 'addonId'>
+
+/**
+ * Minimal structural view of the Moleculer broker (remote-agent leg) — typed
+ * locally because the lint type-checker can't resolve Moleculer's
+ * `ServiceBroker` (mirrors the pattern in `addon-settings-provider.ts`).
+ */
+export interface AddonCallBroker {
+  readonly registry: unknown
+  call(
+    action: string,
+    params: Record<string, unknown>,
+    opts?: { readonly nodeID?: string; readonly timeout?: number },
+  ): Promise<unknown>
+}
+
+/** Where an addon physically runs — the routing decision, made in one place. */
+export type AddonCallDestination =
+  | { readonly kind: 'in-process' }
+  | { readonly kind: 'hub-local-child' }
+  | { readonly kind: 'remote-agent'; readonly baseNodeId: string }
+
+export interface AddonCallGatewayDeps {
+  /** This hub's node id (for the local short-circuit). */
+  readonly hubNodeId: string
+  /** Which node hosts a given addon ('hub' / hubNodeId = on this hub). */
+  readonly resolveNode: (addonId: string) => string
+  /** UDS registry of forked hub-local children (null before it's wired). */
+  readonly getChildRegistry: () => LocalChildRegistry | null
+  /** Moleculer broker for the remote-agent leg. */
+  readonly broker: AddonCallBroker
+}
+
+const REMOTE_TIMEOUT_MS = 10_000
+
+export class AddonCallGateway {
+  constructor(private readonly deps: AddonCallGatewayDeps) {}
+
+  /**
+   * Classify where an addon runs. `nodeId: 'hub'` from a caller means "the hub
+   * cluster", NOT "force in-process" — a forked hub-local addon is still a
+   * `hub-local-child` (UDS), never the in-process path (which is only the
+   * `@camstack/core` builtins that have no forked runner).
+   */
+  classify(addonId: string, explicitNodeId?: string): AddonCallDestination {
+    const resolved = this.deps.resolveNode(addonId)
+    const onHub = resolved === 'hub' || resolved === this.deps.hubNodeId
+    if (onHub) {
+      const childRegistry = this.deps.getChildRegistry()
+      if (childRegistry !== null && childRegistry.isChildKnown(addonId)) {
+        return { kind: 'hub-local-child' }
+      }
+      return { kind: 'in-process' }
+    }
+    const onThisHub = explicitNodeId === 'hub' || explicitNodeId === this.deps.hubNodeId
+    const baseNodeId = explicitNodeId && !onThisHub ? explicitNodeId : resolved
+    return { kind: 'remote-agent', baseNodeId }
+  }
+
+  /** True when the addon is an in-process hub builtin (caller invokes directly). */
+  isInProcess(addonId: string, explicitNodeId?: string): boolean {
+    return this.classify(addonId, explicitNodeId).kind === 'in-process'
+  }
+
+  /**
+   * Dispatch a forked addon-level call to wherever the addon runs:
+   *   - `hub-local-child` → UDS `LocalChildRegistry.callAddonOnChild`
+   *   - `remote-agent`    → Moleculer `broker.call`
+   * Throws for `in-process` — that addon has no forked surface, so the caller
+   * must invoke the in-process instance directly (the invocation is
+   * surface-specific; only the ROUTING is centralised here).
+   */
+  async callForked(addonId: string, input: AddonCallSurface, explicitNodeId?: string): Promise<unknown> {
+    const dest = this.classify(addonId, explicitNodeId)
+    const fullInput: AddonCallInput = { ...input, addonId }
+    switch (dest.kind) {
+      case 'hub-local-child': {
+        const childRegistry = this.deps.getChildRegistry()
+        if (childRegistry === null) {
+          throw new Error(`AddonCallGateway: child registry unavailable for "${addonId}"`)
+        }
+        return childRegistry.callAddonOnChild(addonId, fullInput)
+      }
+      case 'remote-agent':
+        return this.callRemoteAgent(addonId, dest.baseNodeId, fullInput)
+      case 'in-process':
+        throw new Error(`AddonCallGateway: addon "${addonId}" runs in-process — invoke it directly`)
+      default: {
+        const _exhaustive: never = dest
+        throw new Error(`AddonCallGateway: unhandled destination ${JSON.stringify(_exhaustive)}`)
+      }
+    }
+  }
+
+  /** Map an addon-level call to the remote agent's Moleculer action. */
+  private async callRemoteAgent(addonId: string, baseNodeId: string, input: AddonCallInput): Promise<unknown> {
+    const workerNodeId = this.resolveWorkerNodeId(addonId, baseNodeId)
+    const opts = workerNodeId
+      ? { nodeID: workerNodeId, timeout: REMOTE_TIMEOUT_MS }
+      : { timeout: REMOTE_TIMEOUT_MS }
+    if (input.target === 'settings') {
+      if (input.method == null) {
+        throw new Error(`AddonCallGateway: settings call to "${addonId}" missing method`)
+      }
+      return this.deps.broker.call(
+        `${addonId}.settings.${input.method}`,
+        (input.args ?? {}) as Record<string, unknown>,
+        opts,
+      )
+    }
+    // routes/custom are hub-local-child surfaces (mounted / invoked on the
+    // owning node); they are not proxied to a remote agent through this gateway.
+    throw new Error(`AddonCallGateway: target "${input.target}" not supported for remote agent "${baseNodeId}"`)
+  }
+
+  /**
+   * Resolve the Moleculer nodeID that actually hosts an addon's service.
+   * Forkable addons register under `${baseNodeId}/${addonId}`; in-process
+   * addons under the base nodeId. The registry is the ground truth — baseNodeId
+   * is a hint. (Moved verbatim from `addon-settings-provider.ts`.)
+   */
+  private resolveWorkerNodeId(addonId: string, baseNodeId: string): string | null {
+    const registry = this.deps.broker.registry
+    const services = (registry as unknown as {
+      getServiceList: (opts: { onlyAvailable: boolean }) => readonly { name: string; nodeID: string }[]
+    }).getServiceList({ onlyAvailable: true })
+    const exactNode = `${baseNodeId}/${addonId}`
+    const preferred = services.find((s) => s.name === addonId && s.nodeID === exactNode)
+    if (preferred) return preferred.nodeID
+    const anyForBase = services.find((s) => s.name === addonId && s.nodeID === baseNodeId)
+    if (anyForBase) return anyForBase.nodeID
+    const anyWithName = services.find((s) => s.name === addonId)
+    return anyWithName?.nodeID ?? null
+  }
+}

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

@@ -1022,6 +1022,7 @@ export class AddonPackageService {
     readonly packageName: string
     readonly version?: string
     readonly requestedBy?: string
+    readonly deferRestart?: boolean
   }): Promise<{
     packageName: string
     fromVersion: string
@@ -1052,6 +1053,14 @@ export class AddonPackageService {
     const args = ['install', '--prefix', appRoot, spec, '--no-save', ...buildNpmRegistryArgs(registry)]
     await execFileAsync('npm', args, { timeout: 180_000 })
 
+    if (input.deferRestart === true) {
+      this.logger.info(
+        `updateFrameworkPackage(${packageName}@${toVersion}): install done, restart deferred`,
+      )
+      // Sentinel: 0 signals "no restart scheduled" to the caller
+      return { packageName, fromVersion, toVersion, restartingAt: 0 }
+    }
+
     const restartingAt = Date.now()
     const markerPayload: PendingRestartMarkerPayload = {
       kind: 'framework-update',