@zero-server/sdk 0.9.10 → 1.0.1

package/lib/webrtc/cluster.js

@@ -16,6 +16,7 @@ const crypto = require('node:crypto');
 // --- Channel naming ---
 
 const CH_ANNOUNCE = 'zs:rtc:announce';
+const CH_LOAD     = 'zs:rtc:load';
 const chRoom = (name) => `zs:rtc:room:${name}`;
 const chNode = (id) => `zs:rtc:node:${id}`;
 
@@ -38,6 +39,18 @@ class ClusterCoordinator
      * @param {object} [opts]
      * @param {string} [opts.nodeId] - Stable id for this node.  Defaults to
      *                                  a random 8-byte hex string.
+     * @param {string} [opts.region] - Region tag (e.g. `'us-east'`).  Surfaces
+     *                                  in load announcements and lets the
+     *                                  cascade's bridge selector prefer
+     *                                  same-region peers.
+     * @param {Function} [opts.loadProbe] - `() => { cpu?:number, producers?:number,
+     *                                  consumers?:number, bandwidthIn?:number,
+     *                                  bandwidthOut?:number, custom?:object }`.
+     *                                  Sync or async.  When provided, the
+     *                                  coordinator publishes a load snapshot
+     *                                  every `opts.loadIntervalMs` ms.
+     * @param {number} [opts.loadIntervalMs=5000] - 0 disables the periodic timer
+     *                                  (callers can call `publishLoad()` manually).
      */
     constructor(hub, adapter, opts = {})
     {
@@ -47,6 +60,12 @@ class ClusterCoordinator
         this.adapter = adapter;
         /** @type {string} */
         this.nodeId = opts.nodeId || crypto.randomBytes(8).toString('hex');
+        /** @type {string|null} */
+        this.region = opts.region || null;
+        /** @type {Function|null} */
+        this._loadProbe = typeof opts.loadProbe === 'function' ? opts.loadProbe : null;
+        /** @type {number} */
+        this._loadIntervalMs = opts.loadIntervalMs == null ? 5000 : opts.loadIntervalMs;
 
         /**
          * Remote peer directory.  `peerId -> { nodeId, room }`.
@@ -54,6 +73,14 @@ class ClusterCoordinator
          */
         this._remotePeers = new Map();
 
+        /**
+         * Remote node directory.  `nodeId -> { region, load, lastSeen }`.
+         * Populated from `zs:rtc:load` and `hello` announcements.
+         * @type {Map<string, {region:string|null, load:object|null, lastSeen:number}>}
+         */
+        this._nodes = new Map();
+        this._nodes.set(this.nodeId, { region: this.region, load: null, lastSeen: Date.now() });
+
         /** @type {Map<string, Function|null>} */
         this._roomSubs = new Map();
 
@@ -63,6 +90,9 @@ class ClusterCoordinator
         /** @type {boolean} */
         this._closed = false;
 
+        /** @type {NodeJS.Timeout|null} */
+        this._loadTimer = null;
+
         this._wire();
     }
 
@@ -71,14 +101,16 @@ class ClusterCoordinator
     {
         const offAnnounce = this.adapter.subscribe(CH_ANNOUNCE, (m) => this._onAnnounce(m));
         const offNode     = this.adapter.subscribe(chNode(this.nodeId), (m) => this._onNodeMsg(m));
+        const offLoad     = this.adapter.subscribe(CH_LOAD,     (m) => this._onLoad(m));
         if (typeof offAnnounce === 'function') this._unsubs.push(offAnnounce);
         if (typeof offNode === 'function')     this._unsubs.push(offNode);
+        if (typeof offLoad === 'function')     this._unsubs.push(offLoad);
 
         this._onJoin = ({ peer, room }) =>
         {
             this._ensureRoomSub(room.name);
             this._safePub(CH_ANNOUNCE, {
-                kind: 'join', nodeId: this.nodeId, peerId: peer.id, room: room.name,
+                kind: 'join', nodeId: this.nodeId, region: this.region, peerId: peer.id, room: room.name,
             });
         };
         this._onLeave = ({ peer, room }) =>
@@ -91,7 +123,14 @@ class ClusterCoordinator
         this.hub.on('leave', this._onLeave);
 
         // Ask existing nodes to rebroadcast their directory.
-        this._safePub(CH_ANNOUNCE, { kind: 'hello', nodeId: this.nodeId });
+        this._safePub(CH_ANNOUNCE, { kind: 'hello', nodeId: this.nodeId, region: this.region });
+
+        // Periodic load broadcast.
+        if (this._loadProbe && this._loadIntervalMs > 0)
+        {
+            this._loadTimer = setInterval(() => { this.publishLoad().catch(() => {}); }, this._loadIntervalMs);
+            if (this._loadTimer && typeof this._loadTimer.unref === 'function') this._loadTimer.unref();
+        }
     }
 
     /** @private */
@@ -106,6 +145,7 @@ class ClusterCoordinator
     _onAnnounce(m)
     {
         if (!m || m.nodeId === this.nodeId || this._closed) return;
+        if (m.region !== undefined) this._touchNode(m.nodeId, { region: m.region });
         if (m.kind === 'join')
         {
             this._remotePeers.set(m.peerId, { nodeId: m.nodeId, room: m.room });
@@ -124,13 +164,36 @@ class ClusterCoordinator
                 if (peer.room)
                 {
                     this._safePub(CH_ANNOUNCE, {
-                        kind: 'join', nodeId: this.nodeId, peerId: peer.id, room: peer.room.name,
+                        kind: 'join', nodeId: this.nodeId, region: this.region, peerId: peer.id, room: peer.room.name,
                     });
                 }
             }
+            // Also replay our latest load so the newcomer's selector works immediately.
+            const me = this._nodes.get(this.nodeId);
+            if (me && me.load)
+            {
+                this._safePub(CH_LOAD, { nodeId: this.nodeId, region: this.region, load: me.load, at: Date.now() });
+            }
         }
     }
 
+    /** @private */
+    _onLoad(m)
+    {
+        if (!m || !m.nodeId || m.nodeId === this.nodeId || this._closed) return;
+        this._touchNode(m.nodeId, { region: m.region == null ? null : m.region, load: m.load || null });
+    }
+
+    /** @private */
+    _touchNode(nodeId, patch)
+    {
+        const cur = this._nodes.get(nodeId) || { region: null, load: null, lastSeen: 0 };
+        if (patch.region !== undefined) cur.region = patch.region;
+        if (patch.load   !== undefined) cur.load   = patch.load;
+        cur.lastSeen = Date.now();
+        this._nodes.set(nodeId, cur);
+    }
+
     /** @private */
     _onNodeMsg(m)
     {
@@ -199,11 +262,91 @@ class ClusterCoordinator
         });
     }
 
+    /**
+     * Publish a load snapshot now.  Returns the snapshot that was sent.
+     * Called automatically on the configured interval when `loadProbe`
+     * is set, but can also be invoked manually (e.g. from tests, or to
+     * publish immediately after a producer count changes).
+     */
+    async publishLoad()
+    {
+        if (!this._loadProbe || this._closed) return null;
+        let load;
+        try { load = await this._loadProbe(); }
+        catch (err) { this.hub.emit('clusterError', err); return null; }
+        if (!load || typeof load !== 'object') return null;
+        this._touchNode(this.nodeId, { load });
+        this._safePub(CH_LOAD, { nodeId: this.nodeId, region: this.region, load, at: Date.now() });
+        return load;
+    }
+
+    /**
+     * Snapshot of every known node (including self).
+     * @returns {Array<{nodeId:string, region:string|null, load:object|null, lastSeen:number}>}
+     */
+    nodes()
+    {
+        const out = [];
+        for (const [nodeId, n] of this._nodes)
+            out.push({ nodeId, region: n.region, load: n.load, lastSeen: n.lastSeen });
+        return out;
+    }
+
+    /**
+     * Pick a node for a new bridge using one of the built-in selectors
+     * or a custom comparator.  Returns the chosen `nodeId` (which may be
+     * this node's own id when it wins).
+     *
+     * @param {object} [opts]
+     * @param {'local-only'|'least-loaded'|'region-aware'|'region-aware-least-loaded'} [opts.strategy='region-aware-least-loaded']
+     * @param {string} [opts.preferRegion] - Override the local region preference.
+     * @param {(a, b) => number} [opts.compare] - Custom comparator; smaller wins.
+     * @returns {string} nodeId
+     */
+    selectBridge(opts)
+    {
+        const o = opts || {};
+        const strategy = o.strategy || 'region-aware-least-loaded';
+        if (strategy === 'local-only') return this.nodeId;
+        const preferRegion = o.preferRegion !== undefined ? o.preferRegion : this.region;
+        const candidates = this.nodes();
+        if (candidates.length === 0) return this.nodeId;
+        const loadScore = (n) =>
+        {
+            const l = n.load;
+            if (!l) return Number.POSITIVE_INFINITY;
+            if (typeof l.cpu === 'number') return l.cpu;
+            if (typeof l.producers === 'number') return l.producers;
+            return Number.POSITIVE_INFINITY;
+        };
+        let compare;
+        if (typeof o.compare === 'function') compare = o.compare;
+        else if (strategy === 'least-loaded') compare = (a, b) => loadScore(a) - loadScore(b);
+        else if (strategy === 'region-aware')
+            compare = (a, b) =>
+            {
+                const aHit = a.region && a.region === preferRegion ? 0 : 1;
+                const bHit = b.region && b.region === preferRegion ? 0 : 1;
+                return aHit - bHit;
+            };
+        else /* region-aware-least-loaded (default) */
+            compare = (a, b) =>
+            {
+                const aHit = a.region && a.region === preferRegion ? 0 : 1;
+                const bHit = b.region && b.region === preferRegion ? 0 : 1;
+                if (aHit !== bHit) return aHit - bHit;
+                return loadScore(a) - loadScore(b);
+            };
+        const sorted = candidates.slice().sort(compare);
+        return sorted[0].nodeId;
+    }
+
     /** Tear down all subscriptions and clear remote state. */
     close()
     {
         if (this._closed) return;
         this._closed = true;
+        if (this._loadTimer) { try { clearInterval(this._loadTimer); } catch { /* ignore */ } this._loadTimer = null; }
         try { this.hub.off('join',  this._onJoin);  } catch { /* ignore */ }
         try { this.hub.off('leave', this._onLeave); } catch { /* ignore */ }
         for (const off of this._unsubs) { try { off(); } catch { /* ignore */ } }
@@ -214,6 +357,7 @@ class ClusterCoordinator
         this._unsubs.length = 0;
         this._roomSubs.clear();
         this._remotePeers.clear();
+        this._nodes.clear();
         if (this.hub._cluster === this) this.hub._cluster = null;
     }
 
@@ -335,4 +479,6 @@ module.exports = {
     useCluster,
     ClusterCoordinator,
     MemoryClusterAdapter,
+    CH_ANNOUNCE,
+    CH_LOAD,
 };

package/lib/webrtc/index.js

@@ -117,6 +117,10 @@ const {
 const {
     useCluster, ClusterCoordinator, MemoryClusterAdapter,
 } = require('./cluster');
+const { useCascade, CascadeCoordinator, CH_CASCADE } = require('./cascade');
+const { McuAdapter, MemoryMcuAdapter } = require('./mcu');
+const { FfmpegMcuAdapter } = require('./mcu/ffmpeg');
+const { RecordingManager, IngressManager } = require('./recording');
 const { runWebRTCCommand } = require('./cli');
 const { SfuAdapter, loadSfuAdapter } = require('./sfu');
 const { MemorySfuAdapter } = require('./sfu/memory');
@@ -125,22 +129,66 @@ const { LiveKitSfuAdapter }   = require('./sfu/livekit');
 const { spawnBotPeer }        = require('./bot');
 
 /**
- * @private
- * Sentinel for surfaces that are intentionally not exported yet.  Reserved
- * for future top-level shortcuts; current consumers should construct a
- * `SignalingHub` directly and use `bindObservability(hub, { app })`.
+ * One-call WebRTC wiring: build a `SignalingHub`, optionally mount an SFU
+ * adapter, optionally bind a metrics registry / tracer, and attach a WS
+ * route to `app` so peers can connect at `opts.path` (default `/rtc`).
+ *
+ * @param {object} app                            Zero Server app handle (must expose `app.ws(path, handler)`).
+ * @param {object} [opts]                         {@link SignalingHubOptions} plus the extras below.
+ * @param {string} [opts.path='/rtc']             WS mount point for signaling.
+ * @param {object|string} [opts.sfu]              SfuAdapter instance or spec (`memory` | `mediasoup` | `livekit` | package).
+ * @param {object} [opts.sfuOpts]                 Forwarded when `opts.sfu` is a string.
+ * @param {'mesh'|'sfu'|'mcu'|'auto'} [opts.topology='auto']
+ * @param {number} [opts.maxMeshPeers=4]
+ * @param {object} [opts.metrics]                 Prometheus-compatible registry.
+ * @param {object} [opts.tracer]                  OTel-shaped tracer.
+ * @returns {SignalingHub}
+ *
+ * @example | Drop-in wiring
+ *   const app = createApp();
+ *   const hub = createWebRTC(app, {
+ *       joinTokenSecret: process.env.WEBRTC_JWT_SECRET,
+ *       topology:        'auto',
+ *       sfu:             'memory',
+ *       metrics:         app.metrics,
+ *   });
+ *   app.listen(3000);
  */
-const notImplemented = (name) =>
+function createWebRTC(app, opts = {})
 {
-    throw new WebRTCError(
-        `${name} is not implemented yet - construct \`new SignalingHub(opts)\` directly and wire it via \`app.ws()\`.`,
-        { code: 'WEBRTC_NOT_IMPLEMENTED' },
-    );
-};
+    if (!app || typeof app.ws !== 'function')
+    {
+        throw new WebRTCError(
+            'createWebRTC requires a Zero Server app exposing `app.ws(path, handler)`',
+            { code: 'WEBRTC_INVALID_APP' },
+        );
+    }
+    const path     = opts.path || '/rtc';
+    const hubOpts  = { ...opts };
+    delete hubOpts.path;
+    delete hubOpts.metrics;
+    delete hubOpts.tracer;
+    const hub = new SignalingHub(hubOpts);
+    if (opts.metrics || opts.tracer)
+    {
+        bindObservability(hub, { metrics: opts.metrics, tracer: opts.tracer });
+    }
+    app.ws(path, (ws, req) =>
+    {
+        const peer = hub.attach(ws, {
+            user:   req && req.user,
+            ip:     req && req.ip,
+            origin: req && req.headers && req.headers.origin,
+        });
+        if (ws && typeof ws.on === 'function')
+            ws.on('close', () => peer.close());
+    });
+    return hub;
+}
 
 module.exports = {
     // Signaling
-    createWebRTC:          () => notImplemented('createWebRTC'),
+    createWebRTC,
     SignalingHub,
     Room,
     Peer,
@@ -203,6 +251,20 @@ module.exports = {
     ClusterCoordinator,
     MemoryClusterAdapter,
 
+    // Cross-node SFU cascade
+    useCascade,
+    CascadeCoordinator,
+    CH_CASCADE,
+
+    // MCU (multipoint control unit) mixers
+    McuAdapter,
+    MemoryMcuAdapter,
+    FfmpegMcuAdapter,
+
+    // Recording / egress / ingress facade
+    RecordingManager,
+    IngressManager,
+
     // CLI
     runWebRTCCommand,
 

package/lib/webrtc/mcu/ffmpeg.js

@@ -0,0 +1,172 @@
+/**
+ * @module webrtc/mcu/ffmpeg
+ * @description Spawns one ffmpeg child process per mix and implements the
+ *   {@link McuAdapter} contract. The integrator wires mediasoup
+ *   `PlainTransport` RTP feeds into ffmpeg via `opts.inputs` and consumes
+ *   ffmpeg's output via `opts.outputs`; the adapter only owns the child
+ *   lifecycle.
+ *
+ *   Gated on `ffmpeg-static` (or an explicit `{ ffmpegPath }`) so missing
+ *   binaries fail loudly. For a fully managed equivalent prefer LiveKit
+ *   egress via {@link LiveKitSfuAdapter}.
+ *
+ * @example | Spawn an audio mix
+ *   const mcu = new FfmpegMcuAdapter({ sfu });
+ *   const mix = await mcu.mix('lobby', {
+ *       producerIds: ['p1', 'p2'],
+ *       inputs:      [{ sdp: '/tmp/in1.sdp' }, { sdp: '/tmp/in2.sdp' }],
+ *       outputs:     [{ url: 'rtp://127.0.0.1:5004' }],
+ *       kind:        'audio',
+ *   });
+ *   await mcu.unmix(mix.mixedProducerId);
+ */
+
+'use strict';
+
+const { McuAdapter } = require('./index');
+const { WebRTCError } = require('../../errors');
+
+// --- FfmpegMcuAdapter ---
+
+/**
+ * ffmpeg-backed MCU adapter.
+ *
+ * @class
+ * @section MCU
+ */
+class FfmpegMcuAdapter extends McuAdapter
+{
+    /**
+     * @constructor
+     * @param {object} [opts]
+     * @param {object} [opts.sfu]
+     * @param {string} [opts.ffmpegPath] - Overrides the `ffmpeg-static` lookup.
+     * @param {Function} [opts.spawn]    - Injected for tests (defaults to `child_process.spawn`).
+     */
+    constructor(opts)
+    {
+        super(opts);
+        const o = opts || {};
+        this._ffmpegPath = o.ffmpegPath || null;
+        if (!this._ffmpegPath)
+        {
+            try
+            {
+                // eslint-disable-next-line global-require
+                this._ffmpegPath = require('ffmpeg-static');
+            }
+            catch
+            {
+                throw new WebRTCError(
+                    'FfmpegMcuAdapter requires `ffmpeg-static` (npm i ffmpeg-static) or { ffmpegPath } in options',
+                    { code: 'WEBRTC_MCU_NO_FFMPEG' },
+                );
+            }
+        }
+        this._spawn   = o.spawn || require('child_process').spawn;
+        this._mixes   = new Map();
+        this._nextId  = 0;
+    }
+
+    /**
+     * Spawn an ffmpeg process to mix the given producers.  The caller is
+     * responsible for wiring the SFU's PlainTransport RTP feeds into
+     * ffmpeg via `opts.inputs` (an array of `{ producerId, sdp, host, port }`)
+     * and consuming ffmpeg's output via `opts.outputs`.
+     *
+     * @param {string} roomId
+     * @param {object} opts  - `{ producerIds, inputs, outputs, kind, layout, args? }`
+     * @section Mixing
+     */
+    async mix(roomId, opts)
+    {
+        const o = opts || {};
+        if (!roomId) throw new WebRTCError('mix: roomId required', { code: 'WEBRTC_MCU_BAD_ARGS' });
+        const id = `mcu-ffmpeg:${roomId}:${++this._nextId}`;
+        const args = this._buildArgs(o);
+        const child = this._spawn(this._ffmpegPath, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        const entry = {
+            id, room: roomId, kind: o.kind || 'audio', layout: o.layout || 'grid',
+            sources: new Set(Array.isArray(o.producerIds) ? o.producerIds : []),
+            child, exited: false,
+        };
+        child.once('exit', (code, signal) => { entry.exited = true; entry.exitCode = code; entry.exitSignal = signal; });
+        this._mixes.set(id, entry);
+        return { mixedProducerId: id, kind: entry.kind, layout: entry.layout, sources: [...entry.sources], pid: child.pid };
+    }
+
+    async unmix(mixedProducerId)
+    {
+        const m = this._mixes.get(mixedProducerId);
+        if (!m) return false;
+        this._mixes.delete(mixedProducerId);
+        try { m.child.kill('SIGTERM'); } catch { /* swallow */ }
+        return true;
+    }
+
+    async setLayout(mixedProducerId, layout)
+    {
+        const m = this._mixes.get(mixedProducerId);
+        if (!m) throw new WebRTCError('setLayout: unknown mix', { code: 'WEBRTC_MCU_NO_MIX' });
+        // ffmpeg can't change filter graph on the fly without restart.
+        m.layout = typeof layout === 'string' ? layout : (layout && layout.name) || m.layout;
+        return m.layout;
+    }
+
+    async addSource(mixedProducerId, producerId)
+    {
+        const m = this._mixes.get(mixedProducerId);
+        if (!m) throw new WebRTCError('addSource: unknown mix', { code: 'WEBRTC_MCU_NO_MIX' });
+        m.sources.add(producerId);
+        return m.sources.size;
+    }
+
+    async removeSource(mixedProducerId, producerId)
+    {
+        const m = this._mixes.get(mixedProducerId);
+        if (!m) throw new WebRTCError('removeSource: unknown mix', { code: 'WEBRTC_MCU_NO_MIX' });
+        m.sources.delete(producerId);
+        return m.sources.size;
+    }
+
+    stats()
+    {
+        const mixes = [];
+        for (const m of this._mixes.values())
+        {
+            mixes.push({ id: m.id, room: m.room, sources: [...m.sources], layout: m.layout, kind: m.kind, pid: m.child && m.child.pid, exited: m.exited });
+        }
+        return { mixes };
+    }
+
+    async close()
+    {
+        for (const id of [...this._mixes.keys()]) await this.unmix(id);
+    }
+
+    _buildArgs(opts)
+    {
+        const o = opts || {};
+        if (Array.isArray(o.args)) return o.args;
+        const inputs = Array.isArray(o.inputs) ? o.inputs : [];
+        const args = ['-y', '-loglevel', 'warning'];
+        for (const inp of inputs)
+        {
+            if (inp.sdp)         args.push('-protocol_whitelist', 'pipe,udp,rtp', '-f', 'sdp', '-i', inp.sdp);
+            else if (inp.url)    args.push('-i', inp.url);
+        }
+        if (o.kind === 'audio' || !o.kind)
+            args.push('-filter_complex', `amix=inputs=${Math.max(inputs.length, 1)}`, '-c:a', 'libopus');
+        else
+            args.push('-filter_complex', `xstack=inputs=${Math.max(inputs.length, 1)}`, '-c:v', 'libvpx');
+        const outputs = Array.isArray(o.outputs) ? o.outputs : [];
+        for (const out of outputs)
+        {
+            if (out.url) args.push('-f', out.format || 'rtp', out.url);
+            else if (out.file) args.push('-f', out.format || 'mp4', out.file);
+        }
+        return args;
+    }
+}
+
+module.exports = { FfmpegMcuAdapter };