@zero-server/sdk 0.9.6 → 0.9.8

package/lib/webrtc/sfu/index.js

@@ -0,0 +1,251 @@
+/**
+ * @module webrtc/sfu
+ * @description Pluggable Selective Forwarding Unit (SFU) adapter interface.
+ *   The signaling hub stays media-agnostic; the adapter owns routers,
+ *   transports, producers, and consumers. Ships with `MemorySfuAdapter`,
+ *   `MediasoupSfuAdapter`, and `LiveKitSfuAdapter`. Subclass `SfuAdapter`
+ *   for custom backends.
+ *
+ * @example | Select an adapter at boot via env
+ *   const { loadSfuAdapter } = require('@zero-server/webrtc');
+ *   const sfu = loadSfuAdapter(process.env.SFU_BACKEND || 'memory', {
+ *       // adapter-specific options forwarded verbatim
+ *       workerSettings: { logLevel: 'warn' },
+ *   });
+ *
+ *   sfu.onEvent((event, payload) => log.debug({ event, payload }, 'sfu'));
+ *
+ * @example | Wire an SFU into the signaling hub per room
+ *   const router = await sfu.createRouter({ room: 'lobby' });
+ *
+ *   hub.on('join', async ({ peer, room }) => {
+ *       if (room.name !== 'lobby') return;
+ *       const transport = await sfu.createTransport(router, peer);
+ *       peer.send('sfu-transport', { iceParameters: transport.iceParameters });
+ *   });
+ */
+'use strict';
+
+const { WebRTCError } = require('../../errors');
+
+/**
+ * Base class every SFU adapter inherits from.  Subclasses MUST override
+ * every async method; the default implementations throw
+ * `WEBRTC_SFU_NOT_IMPLEMENTED` so partial adapters fail loudly.
+ *
+ *   The interface is intentionally tiny so a backend can be written in a
+ *   single file:
+ *
+ * @example | Skeleton adapter
+ *   class MyAdapter extends SfuAdapter {
+ *       async createRouter(opts)            { return { id: cuid(), opts }; }
+ *       async createTransport(router, peer) { return { id: cuid(), router, peer }; }
+ *       async produce(transport, kind, rtp) {
+ *           const id = cuid();
+ *           this._emit('producer-new', { id, kind, transportId: transport.id });
+ *           return { id, kind };
+ *       }
+ *       async consume(transport, producerId, _rtpCaps) {
+ *           return { id: cuid(), producerId, transportId: transport.id };
+ *       }
+ *       async pauseProducer(id)  { this._emit('producer-pause', { id }); }
+ *       async resumeProducer(id) { this._emit('producer-resume', { id }); }
+ *       async closeRouter(id)    { this._emit('router-close', { id }); }
+ *       async stats(_scope)      { return { ts: Date.now() }; }
+ *   }
+ *
+ * @example | Subscribe to adapter events
+ *   const off = sfu.onEvent((event, payload) => {
+ *       if (event === 'producer-new')   metrics.producers.inc();
+ *       if (event === 'producer-pause') log.info({ id: payload.id }, 'paused');
+ *   });
+ *   // later: off();
+ */
+class SfuAdapter
+{
+    constructor()
+    {
+        this._handlers = new Set();
+    }
+
+    /** Override to create a routing context for a single room. */
+    async createRouter(_opts)
+    {
+        throw new WebRTCError('SfuAdapter.createRouter() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /** Override to allocate a WebRTC transport for a peer in a router. */
+    async createTransport(_router, _peer)
+    {
+        throw new WebRTCError('SfuAdapter.createTransport() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /** Override to bind a producer ('audio' | 'video') to a transport. */
+    async produce(_transport, _kind, _rtpParams)
+    {
+        throw new WebRTCError('SfuAdapter.produce() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /** Override to bind a consumer of `producerId` to a transport. */
+    async consume(_transport, _producerId, _rtpCaps)
+    {
+        throw new WebRTCError('SfuAdapter.consume() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /** Override to pause a producer (mute upstream forwarding). */
+    async pauseProducer(_producerId)
+    {
+        throw new WebRTCError('SfuAdapter.pauseProducer() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /** Override to resume a previously paused producer. */
+    async resumeProducer(_producerId)
+    {
+        throw new WebRTCError('SfuAdapter.resumeProducer() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /** Override to close a router and cascade-close its transports. */
+    async closeRouter(_routerId)
+    {
+        throw new WebRTCError('SfuAdapter.closeRouter() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /** Override to return adapter stats; `scope` may be a routerId/transportId. */
+    async stats(_scope)
+    {
+        throw new WebRTCError('SfuAdapter.stats() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /**
+     * Register a handler invoked as `(event, payload)` for adapter-level
+     * events ('producer-new', 'producer-pause', 'consumer-new',
+     * 'transport-close', 'router-close', etc.).
+     *
+     * Returns an unsubscribe function.
+     */
+    onEvent(handler)
+    {
+        if (typeof handler !== 'function')
+        {
+            throw new WebRTCError('onEvent() handler must be a function', { code: 'WEBRTC_SFU_INVALID_HANDLER' });
+        }
+        this._handlers.add(handler);
+        return () => this._handlers.delete(handler);
+    }
+
+    /** Emit `event` with `payload` to every registered handler. */
+    _emit(event, payload)
+    {
+        for (const fn of this._handlers)
+        {
+            try { fn(event, payload); }
+            catch (_) { /* swallow handler errors so adapters keep running */ }
+        }
+    }
+}
+
+/**
+ * Lazy-load and instantiate an SFU adapter.
+ *
+ * @param {object|string} spec - one of:
+ *   - an object exposing the SfuAdapter contract (returned as-is),
+ *   - 'memory' | 'mediasoup' | 'livekit' | adapter package id.
+ * @param {object} [opts] - constructor options forwarded to the adapter.
+ * @returns {SfuAdapter}
+ *
+ * @example | Built-in adapter by name
+ *   const sfu = loadSfuAdapter('mediasoup', {
+ *       numWorkers: 4,
+ *       workerSettings: { rtcMinPort: 40000, rtcMaxPort: 49999 },
+ *   });
+ *
+ * @example | Pre-constructed instance (e.g. shared singleton in tests)
+ *   const fake = new MemorySfuAdapter();
+ *   const sfu  = loadSfuAdapter(fake);
+ *   expect(sfu).toBe(fake);
+ *
+ * @example | Third-party adapter package
+ *   //   npm i @acme/zero-server-sfu-janus
+ *   const sfu = loadSfuAdapter('@acme/zero-server-sfu-janus', { wsUrl: 'ws://janus/ws' });
+ */
+function loadSfuAdapter(spec, opts)
+{
+    if (spec && typeof spec === 'object' && typeof spec.createRouter === 'function')
+    {
+        return spec;
+    }
+    if (typeof spec !== 'string' || spec.length === 0)
+    {
+        throw new WebRTCError(
+            'loadSfuAdapter() requires an adapter instance or a name (memory|mediasoup|livekit|<package>)',
+            { code: 'WEBRTC_SFU_INVALID_SPEC' },
+        );
+    }
+
+    if (spec === 'memory')
+    {
+        const { MemorySfuAdapter } = require('./memory');
+        return new MemorySfuAdapter(opts);
+    }
+    if (spec === 'mediasoup')
+    {
+        const Ctor = _tryRequireAdapter('./mediasoup', 'mediasoup');
+        return new Ctor(opts);
+    }
+    if (spec === 'livekit')
+    {
+        const Ctor = _tryRequireAdapter('./livekit', 'livekit-server-sdk');
+        return new Ctor(opts);
+    }
+
+    // External adapter package - must export `default` or a class.
+    let mod;
+    try { mod = require(spec); }
+    catch (err)
+    {
+        throw new WebRTCError(
+            `SFU adapter package '${spec}' is not installed: ${err.message}`,
+            { code: 'WEBRTC_SFU_NOT_INSTALLED', cause: err },
+        );
+    }
+    const Ctor = mod && (mod.default || mod);
+    if (typeof Ctor !== 'function')
+    {
+        throw new WebRTCError(
+            `SFU adapter package '${spec}' does not export a class or default constructor`,
+            { code: 'WEBRTC_SFU_INVALID_PACKAGE' },
+        );
+    }
+    return new Ctor(opts);
+}
+
+/**
+ * @private
+ * Try to load a built-in adapter module; surface a clean install message
+ * when the wrapped peerDependency is missing.
+ */
+function _tryRequireAdapter(localPath, peerPkg)
+{
+    let mod;
+    try { mod = require(localPath); }
+    catch (err)
+    {
+        throw new WebRTCError(
+            `SFU adapter '${peerPkg}' requires the '${peerPkg}' peerDependency: npm install ${peerPkg}`,
+            { code: 'WEBRTC_SFU_NOT_INSTALLED', cause: err },
+        );
+    }
+    // The wrapper itself tries `require(peerPkg)`; rethrow with the install
+    // hint if construction fails for that reason.
+    const Ctor = mod && (mod.default || Object.values(mod).find((v) => typeof v === 'function'));
+    if (typeof Ctor !== 'function')
+    {
+        throw new WebRTCError(
+            `SFU adapter module '${localPath}' did not export a constructor`,
+            { code: 'WEBRTC_SFU_INVALID_ADAPTER' },
+        );
+    }
+    return Ctor;
+}
+
+module.exports = { SfuAdapter, loadSfuAdapter };

package/lib/webrtc/sfu/livekit.js

@@ -0,0 +1,304 @@
+/**
+ * @module webrtc/sfu/livekit
+ * @description LiveKit-backed SFU adapter (peerDependency on
+ *   `livekit-server-sdk`). Maps the `SfuAdapter` contract onto LiveKit's
+ *   remote media plane: `createTransport` mints an AccessToken, mute/close
+ *   delegate to `RoomServiceClient`, and produce/consume are local
+ *   bookkeeping while LiveKit handles media client-side.
+ *
+ * @example | Cloud LiveKit project
+ *   //   npm install livekit-server-sdk
+ *   const { LiveKitSfuAdapter } = require('@zero-server/webrtc');
+ *   const sfu = new LiveKitSfuAdapter({
+ *       host:      'https://my-project.livekit.cloud',
+ *       apiKey:    process.env.LIVEKIT_API_KEY,
+ *       apiSecret: process.env.LIVEKIT_API_SECRET,
+ *       tokenTtl:  '30m',
+ *   });
+ *
+ * @example | Self-hosted LiveKit + handing the JWT to a browser
+ *   const router    = await sfu.createRouter({ room: 'standup' });
+ *   const transport = await sfu.createTransport(router, {
+ *       id:   peer.id,
+ *       user: { id: peer.user.id, name: peer.user.name },
+ *   });
+ *   peer.send('livekit', { url: transport.url, token: transport.token });
+ *
+ * @example | Mute a noisy publisher (REST passthrough)
+ *   await sfu.pauseProducer(producer.id);
+ *   // adapter records the producerId; if it was registered with a
+ *   // { room, identity, trackSid } hint it issues
+ *   // RoomServiceClient.mutePublishedTrack() against LiveKit.
+ */
+'use strict';
+
+const { SfuAdapter } = require('./index');
+const { WebRTCError } = require('../../errors');
+
+const DEFAULT_TOKEN_TTL = '1h';
+
+class LiveKitSfuAdapter extends SfuAdapter
+{
+    /**
+     * @param {object} opts
+     * @param {string} opts.url        LiveKit server URL (wss://...).
+     * @param {string} opts.apiKey     LiveKit API key.
+     * @param {string} opts.apiSecret  LiveKit API secret.
+     * @param {object} [opts.livekit]  Injected `livekit-server-sdk` module (testing).
+     * @param {object} [opts.client]   Pre-built `RoomServiceClient` (testing).
+     * @param {object} [opts.defaultRoomOpts]    Forwarded to `createRoom()` when fields are missing.
+     * @param {object} [opts.defaultGrants]      Default `{canPublish, canSubscribe, ...}` for minted tokens.
+     * @param {string} [opts.tokenTtl='1h']      AccessToken TTL.
+     */
+    constructor(opts)
+    {
+        super();
+        const o = opts || {};
+        if (!o.url || !o.apiKey || !o.apiSecret)
+        {
+            throw new WebRTCError(
+                'LiveKitSfuAdapter requires { url, apiKey, apiSecret }',
+                { code: 'WEBRTC_SFU_INVALID_CONFIG' },
+            );
+        }
+        this._livekit          = o.livekit || _tryRequireLivekit();
+        this._url              = o.url;
+        this._apiKey           = o.apiKey;
+        this._apiSecret        = o.apiSecret;
+        this._defaultRoomOpts  = o.defaultRoomOpts || {};
+        this._defaultGrants    = o.defaultGrants || { canPublish: true, canSubscribe: true };
+        this._tokenTtl         = o.tokenTtl || DEFAULT_TOKEN_TTL;
+
+        this._client = o.client || new this._livekit.RoomServiceClient(this._url, this._apiKey, this._apiSecret);
+
+        this._rooms      = new Map(); // routerId    -> { name, opts }
+        this._transports = new Map(); // transportId -> { identity, room, token }
+        this._producers  = new Map(); // producerId  -> { kind, transportId, room, identity, trackSid? }
+        this._consumers  = new Map(); // consumerId  -> { producerId, transportId }
+
+        this._idSeq = 0;
+    }
+
+    _nextId(prefix)
+    {
+        this._idSeq += 1;
+        return `${prefix}-${this._idSeq}`;
+    }
+
+    /**
+     * Create a LiveKit room.  `opts.name` overrides the auto-generated name.
+     * Returns a router handle whose `id` is the room name.
+     */
+    async createRouter(opts)
+    {
+        const o = { ...this._defaultRoomOpts, ...(opts || {}) };
+        const name = o.name || this._nextId('room');
+        const room = await this._client.createRoom({ ...o, name });
+        const id = room && room.name ? room.name : name;
+        this._rooms.set(id, { name: id, opts: o, native: room });
+        this._emit('router-new', { routerId: id });
+        return { id, routerId: id, name: id, _native: room };
+    }
+
+    /**
+     * Mint an AccessToken for `peer` to join the LiveKit room.  Returns
+     * a transport handle containing the JWT and URL the peer hands to
+     * the LiveKit client SDK.
+     */
+    async createTransport(router, peer)
+    {
+        const routerId = router && router.id;
+        const room = routerId && this._rooms.get(routerId);
+        if (!room)
+        {
+            throw new WebRTCError('createTransport: unknown router', { code: 'WEBRTC_SFU_NO_ROUTER' });
+        }
+        const identity = (peer && peer.id) || this._nextId('peer');
+        const at = new this._livekit.AccessToken(this._apiKey, this._apiSecret, {
+            identity,
+            ttl:  this._tokenTtl,
+            name: (peer && peer.name) || identity,
+        });
+        at.addGrant({ roomJoin: true, room: routerId, ...this._defaultGrants });
+        const token = await at.toJwt();
+        const id = this._nextId('transport');
+        const handle = {
+            id,
+            transportId: id,
+            routerId,
+            peer:        peer || null,
+            identity,
+            url:         this._url,
+            token,
+        };
+        this._transports.set(id, handle);
+        this._emit('transport-new', { transportId: id, routerId, peerId: identity });
+        return handle;
+    }
+
+    async produce(transport, kind, rtpParameters)
+    {
+        if (kind !== 'audio' && kind !== 'video')
+        {
+            throw new WebRTCError('produce: kind must be "audio" or "video"', { code: 'WEBRTC_SFU_INVALID_KIND' });
+        }
+        const t = transport && this._transports.get(transport.id);
+        if (!t)
+        {
+            throw new WebRTCError('produce: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        }
+        const id = this._nextId('producer');
+        const trackSid = (rtpParameters && rtpParameters.trackSid) || null;
+        const p = {
+            id, producerId: id, transportId: t.id, kind,
+            room: t.routerId, identity: t.identity, trackSid,
+            rtpParameters: rtpParameters || {}, paused: false,
+        };
+        this._producers.set(id, p);
+        this._emit('producer-new', { producerId: id, transportId: t.id, kind });
+        return p;
+    }
+
+    async consume(transport, producerId, rtpCapabilities)
+    {
+        const t = transport && this._transports.get(transport.id);
+        if (!t)
+        {
+            throw new WebRTCError('consume: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        }
+        const prod = this._producers.get(producerId);
+        if (!prod)
+        {
+            throw new WebRTCError('consume: unknown producer', { code: 'WEBRTC_SFU_NO_PRODUCER' });
+        }
+        const id = this._nextId('consumer');
+        const c = {
+            id, consumerId: id, transportId: t.id, producerId,
+            kind: prod.kind, rtpParameters: prod.rtpParameters,
+            rtpCapabilities: rtpCapabilities || {},
+        };
+        this._consumers.set(id, c);
+        this._emit('consumer-new', { consumerId: id, transportId: t.id, producerId });
+        return c;
+    }
+
+    async pauseProducer(producerId)
+    {
+        const p = this._producers.get(producerId);
+        if (!p)
+        {
+            throw new WebRTCError('pauseProducer: unknown producer', { code: 'WEBRTC_SFU_NO_PRODUCER' });
+        }
+        if (p.trackSid && typeof this._client.mutePublishedTrack === 'function')
+        {
+            await this._client.mutePublishedTrack(p.room, p.identity, p.trackSid, true);
+        }
+        p.paused = true;
+        this._emit('producer-pause', { producerId });
+    }
+
+    async resumeProducer(producerId)
+    {
+        const p = this._producers.get(producerId);
+        if (!p)
+        {
+            throw new WebRTCError('resumeProducer: unknown producer', { code: 'WEBRTC_SFU_NO_PRODUCER' });
+        }
+        if (p.trackSid && typeof this._client.mutePublishedTrack === 'function')
+        {
+            await this._client.mutePublishedTrack(p.room, p.identity, p.trackSid, false);
+        }
+        p.paused = false;
+        this._emit('producer-resume', { producerId });
+    }
+
+    async closeRouter(routerId)
+    {
+        const room = this._rooms.get(routerId);
+        if (!room) return;
+        try { await this._client.deleteRoom(routerId); }
+        catch (err)
+        {
+            this._emit('router-close-error', { routerId, error: err && err.message });
+        }
+        // Drop every producer / consumer / transport that belonged to this room.
+        for (const [pid, p] of this._producers)
+        {
+            if (p.room === routerId)
+            {
+                this._producers.delete(pid);
+                this._emit('producer-close', { producerId: pid, reason: 'router-close' });
+            }
+        }
+        for (const [cid, c] of this._consumers)
+        {
+            const t = this._transports.get(c.transportId);
+            if (t && t.routerId === routerId)
+            {
+                this._consumers.delete(cid);
+                this._emit('consumer-close', { consumerId: cid, reason: 'router-close' });
+            }
+        }
+        for (const [tid, t] of this._transports)
+        {
+            if (t.routerId === routerId)
+            {
+                this._transports.delete(tid);
+                this._emit('transport-close', { transportId: tid, reason: 'router-close' });
+            }
+        }
+        this._rooms.delete(routerId);
+        this._emit('router-close', { routerId });
+    }
+
+    async stats(scope)
+    {
+        if (scope && this._rooms.has(scope))
+        {
+            let participants = null;
+            if (typeof this._client.listParticipants === 'function')
+            {
+                try { participants = await this._client.listParticipants(scope); }
+                catch (_) { participants = null; }
+            }
+            return { kind: 'router', routerId: scope, participants };
+        }
+        if (scope && this._transports.has(scope))
+        {
+            const t = this._transports.get(scope);
+            return { kind: 'transport', transportId: scope, routerId: t.routerId, identity: t.identity };
+        }
+        let rooms = null;
+        if (typeof this._client.listRooms === 'function')
+        {
+            try { rooms = await this._client.listRooms(); }
+            catch (_) { rooms = null; }
+        }
+        return {
+            kind:       'global',
+            routers:    this._rooms.size,
+            transports: this._transports.size,
+            producers:  this._producers.size,
+            consumers:  this._consumers.size,
+            rooms,
+        };
+    }
+}
+
+/**
+ * @private
+ * Try to `require('livekit-server-sdk')`; throw a clean install hint when missing.
+ */
+function _tryRequireLivekit()
+{
+    try { return require('livekit-server-sdk'); }
+    catch (err)
+    {
+        throw new WebRTCError(
+            "SFU adapter 'livekit' requires the 'livekit-server-sdk' peerDependency: npm install livekit-server-sdk",
+            { code: 'WEBRTC_SFU_NOT_INSTALLED', cause: err },
+        );
+    }
+}
+
+module.exports = { LiveKitSfuAdapter };