@zero-server/sdk 0.9.6 → 0.9.8

package/lib/webrtc/sfu/mediasoup.js

@@ -0,0 +1,357 @@
+/**
+ * @module webrtc/sfu/mediasoup
+ * @description mediasoup-backed SFU adapter (peerDependency on
+ *   `mediasoup`). Wraps a `Worker` plus one `Router` per `createRouter()`
+ *   call and delegates produce/consume/pause/resume/close/stats to the
+ *   native objects. Adapter events are uniform via `onEvent`.
+ *
+ * @example | Production setup with custom RTP port range and announced IP
+ *   //   npm install mediasoup
+ *   const { MediasoupSfuAdapter } = require('@zero-server/webrtc');
+ *
+ *   const sfu = new MediasoupSfuAdapter({
+ *       workerSettings: {
+ *           logLevel:   'warn',
+ *           rtcMinPort: 40000,
+ *           rtcMaxPort: 49999,
+ *       },
+ *       webRtcTransportOptions: {
+ *           listenIps:  [{ ip: '0.0.0.0', announcedIp: process.env.PUBLIC_IP }],
+ *           enableUdp:  true,
+ *           enableTcp:  true,
+ *           preferUdp:  true,
+ *           initialAvailableOutgoingBitrate: 800_000,
+ *       },
+ *   });
+ *
+ * @example | One router per room, lazy on first join
+ *   const routersByRoom = new Map();
+ *
+ *   async function getRouter(roomName) {
+ *       let r = routersByRoom.get(roomName);
+ *       if (!r) {
+ *           r = await sfu.createRouter({ room: roomName });
+ *           routersByRoom.set(roomName, r);
+ *       }
+ *       return r;
+ *   }
+ *
+ *   hub.on('join', async ({ peer, room }) => {
+ *       const router    = await getRouter(room.name);
+ *       const transport = await sfu.createTransport(router, peer);
+ *       peer.send('sfu-ready', { transportId: transport.id });
+ *   });
+ *
+ * @example | Inject a stub for unit tests
+ *   const stubMediasoup = {
+ *       createWorker: async () => ({
+ *           createRouter: async () => fakeRouter,
+ *           close: () => {},
+ *       }),
+ *   };
+ *   const sfu = new MediasoupSfuAdapter({ mediasoup: stubMediasoup });
+ */
+'use strict';
+
+const { SfuAdapter } = require('./index');
+const { WebRTCError } = require('../../errors');
+
+const DEFAULT_MEDIA_CODECS = [
+    { kind: 'audio', mimeType: 'audio/opus', clockRate: 48000, channels: 2 },
+    { kind: 'video', mimeType: 'video/VP8',  clockRate: 90000 },
+];
+
+const DEFAULT_WEBRTC_TRANSPORT_OPTS = {
+    listenIps:  [{ ip: '0.0.0.0', announcedIp: null }],
+    enableUdp:  true,
+    enableTcp:  true,
+    preferUdp:  true,
+};
+
+class MediasoupSfuAdapter extends SfuAdapter
+{
+    /**
+     * @param {object} [opts]
+     * @param {object} [opts.mediasoup]              Injected mediasoup module (testing); defaults to `require('mediasoup')`.
+     * @param {object} [opts.worker]                 Pre-created `mediasoup.Worker`; bypasses the lazy worker bootstrap.
+     * @param {object} [opts.workerSettings]         Forwarded to `mediasoup.createWorker(...)`.
+     * @param {Array}  [opts.mediaCodecs]            Default router media codecs.
+     * @param {object} [opts.webRtcTransportOptions] Default `router.createWebRtcTransport(...)` options.
+     */
+    constructor(opts)
+    {
+        super();
+        const o = opts || {};
+
+        this._mediasoup = o.mediasoup || _tryRequireMediasoup();
+        this._workerSettings    = o.workerSettings    || {};
+        this._mediaCodecs       = o.mediaCodecs       || DEFAULT_MEDIA_CODECS;
+        this._webRtcTransportOpts = o.webRtcTransportOptions || DEFAULT_WEBRTC_TRANSPORT_OPTS;
+        this._worker            = o.worker || null;
+        this._workerPromise     = null;
+
+        this._routers    = new Map(); // routerId    -> native router
+        this._transports = new Map(); // transportId -> native transport
+        this._producers  = new Map(); // producerId  -> native producer
+        this._consumers  = new Map(); // consumerId  -> native consumer
+        this._routerOf   = new Map(); // transportId -> routerId
+    }
+
+    /**
+     * Lazily create (or return) the single shared mediasoup Worker.
+     * Returns the native Worker handle.
+     */
+    async _ensureWorker()
+    {
+        if (this._worker) return this._worker;
+        if (!this._workerPromise)
+        {
+            this._workerPromise = Promise.resolve(this._mediasoup.createWorker(this._workerSettings))
+                .then((w) =>
+                {
+                    this._worker = w;
+                    if (typeof w.on === 'function')
+                    {
+                        w.on('died', (err) => this._emit('worker-died', { error: err && err.message }));
+                    }
+                    return w;
+                });
+        }
+        return this._workerPromise;
+    }
+
+    async createRouter(opts)
+    {
+        const worker = await this._ensureWorker();
+        const mediaCodecs = (opts && opts.mediaCodecs) || this._mediaCodecs;
+        const router = await worker.createRouter({ mediaCodecs });
+        this._routers.set(router.id, router);
+        if (typeof router.observer === 'object' && router.observer && typeof router.observer.on === 'function')
+        {
+            router.observer.on('close', () =>
+            {
+                this._routers.delete(router.id);
+                this._emit('router-close', { routerId: router.id });
+            });
+        }
+        this._emit('router-new', { routerId: router.id });
+        return {
+            id:                 router.id,
+            routerId:           router.id,
+            rtpCapabilities:    router.rtpCapabilities,
+            _native:            router,
+        };
+    }
+
+    async createTransport(router, peer)
+    {
+        const routerId = router && router.id;
+        const native = routerId && this._routers.get(routerId);
+        if (!native)
+        {
+            throw new WebRTCError('createTransport: unknown router', { code: 'WEBRTC_SFU_NO_ROUTER' });
+        }
+        const transport = await native.createWebRtcTransport({
+            ...this._webRtcTransportOpts,
+            appData: { peer: peer || null },
+        });
+        this._transports.set(transport.id, transport);
+        this._routerOf.set(transport.id, routerId);
+        if (typeof transport.observer === 'object' && transport.observer && typeof transport.observer.on === 'function')
+        {
+            transport.observer.on('close', () =>
+            {
+                this._transports.delete(transport.id);
+                this._routerOf.delete(transport.id);
+                this._emit('transport-close', { transportId: transport.id });
+            });
+        }
+        this._emit('transport-new', { transportId: transport.id, routerId, peerId: peer && peer.id });
+        return {
+            id:              transport.id,
+            transportId:     transport.id,
+            routerId,
+            peer:            peer || null,
+            iceParameters:   transport.iceParameters,
+            iceCandidates:   transport.iceCandidates,
+            dtlsParameters:  transport.dtlsParameters,
+            sctpParameters:  transport.sctpParameters || null,
+            _native:         transport,
+        };
+    }
+
+    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 native = transport && this._transports.get(transport.id);
+        if (!native)
+        {
+            throw new WebRTCError('produce: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        }
+        const producer = await native.produce({ kind, rtpParameters });
+        this._producers.set(producer.id, producer);
+        if (typeof producer.on === 'function')
+        {
+            producer.on('transportclose', () =>
+            {
+                this._producers.delete(producer.id);
+                this._emit('producer-close', { producerId: producer.id, reason: 'transport-close' });
+            });
+        }
+        this._emit('producer-new', { producerId: producer.id, transportId: transport.id, kind });
+        return {
+            id:           producer.id,
+            producerId:   producer.id,
+            transportId:  transport.id,
+            kind,
+            rtpParameters,
+            paused:       !!producer.paused,
+            _native:      producer,
+        };
+    }
+
+    async consume(transport, producerId, rtpCapabilities)
+    {
+        const native = transport && this._transports.get(transport.id);
+        if (!native)
+        {
+            throw new WebRTCError('consume: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        }
+        const routerId = this._routerOf.get(transport.id);
+        const router   = routerId && this._routers.get(routerId);
+        if (router && typeof router.canConsume === 'function'
+            && !router.canConsume({ producerId, rtpCapabilities }))
+        {
+            throw new WebRTCError('consume: router cannot consume producer with given rtpCapabilities',
+                { code: 'WEBRTC_SFU_CANNOT_CONSUME' });
+        }
+        let consumer;
+        try
+        {
+            consumer = await native.consume({ producerId, rtpCapabilities });
+        }
+        catch (err)
+        {
+            throw new WebRTCError(`consume failed: ${err.message}`, { code: 'WEBRTC_SFU_CONSUME_FAILED', cause: err });
+        }
+        this._consumers.set(consumer.id, consumer);
+        if (typeof consumer.on === 'function')
+        {
+            consumer.on('transportclose', () =>
+            {
+                this._consumers.delete(consumer.id);
+                this._emit('consumer-close', { consumerId: consumer.id, reason: 'transport-close' });
+            });
+            consumer.on('producerclose', () =>
+            {
+                this._consumers.delete(consumer.id);
+                this._emit('consumer-close', { consumerId: consumer.id, reason: 'producer-close' });
+            });
+        }
+        this._emit('consumer-new', { consumerId: consumer.id, transportId: transport.id, producerId });
+        return {
+            id:            consumer.id,
+            consumerId:    consumer.id,
+            transportId:   transport.id,
+            producerId,
+            kind:          consumer.kind,
+            rtpParameters: consumer.rtpParameters,
+            rtpCapabilities,
+            _native:       consumer,
+        };
+    }
+
+    async pauseProducer(producerId)
+    {
+        const p = this._producers.get(producerId);
+        if (!p)
+        {
+            throw new WebRTCError('pauseProducer: unknown producer', { code: 'WEBRTC_SFU_NO_PRODUCER' });
+        }
+        await p.pause();
+        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' });
+        }
+        await p.resume();
+        this._emit('producer-resume', { producerId });
+    }
+
+    async closeRouter(routerId)
+    {
+        const r = this._routers.get(routerId);
+        if (!r) return;
+        // Native router.close() cascades to its transports; the observer
+        // 'close' handlers we registered in createTransport/createRouter
+        // emit transport-close / router-close events for us.  Avoid
+        // emitting here to prevent duplicates.
+        await r.close();
+    }
+
+    async stats(scope)
+    {
+        if (scope && this._routers.has(scope))
+        {
+            const r = this._routers.get(scope);
+            const native = typeof r.getStats === 'function' ? await r.getStats() : null;
+            return { kind: 'router', routerId: scope, native };
+        }
+        if (scope && this._transports.has(scope))
+        {
+            const t = this._transports.get(scope);
+            const native = typeof t.getStats === 'function' ? await t.getStats() : null;
+            return { kind: 'transport', transportId: scope, routerId: this._routerOf.get(scope), native };
+        }
+        return {
+            kind:       'global',
+            routers:    this._routers.size,
+            transports: this._transports.size,
+            producers:  this._producers.size,
+            consumers:  this._consumers.size,
+        };
+    }
+
+    /**
+     * Best-effort shutdown: closes every router, then the worker if we own it.
+     */
+    async close()
+    {
+        for (const id of [...this._routers.keys()])
+        {
+            try { await this.closeRouter(id); } catch (_) { /* swallow */ }
+        }
+        if (this._worker && typeof this._worker.close === 'function')
+        {
+            try { await this._worker.close(); } catch (_) { /* swallow */ }
+        }
+        this._worker = null;
+        this._workerPromise = null;
+    }
+}
+
+/**
+ * @private
+ * Try to `require('mediasoup')`; throw a clean install hint when missing.
+ */
+function _tryRequireMediasoup()
+{
+    try { return require('mediasoup'); }
+    catch (err)
+    {
+        throw new WebRTCError(
+            "SFU adapter 'mediasoup' requires the 'mediasoup' peerDependency: npm install mediasoup",
+            { code: 'WEBRTC_SFU_NOT_INSTALLED', cause: err },
+        );
+    }
+}
+
+module.exports = { MediasoupSfuAdapter };

package/lib/webrtc/sfu/memory.js

@@ -0,0 +1,221 @@
+/**
+ * @module webrtc/sfu/memory
+ * @description In-process "memory" SFU adapter. Bookkeeping-only
+ *   passthrough that records producers/consumers and emits adapter events
+ *   without forwarding media packets. Ideal for unit tests, CI, and local
+ *   dev — use a native adapter for real media plane work.
+ *
+ * @example | Use the memory adapter inside a vitest suite
+ *   const { MemorySfuAdapter } = require('@zero-server/webrtc');
+ *   const sfu = new MemorySfuAdapter();
+ *
+ *   const events = [];
+ *   sfu.onEvent((event, payload) => events.push({ event, payload }));
+ *
+ *   const router    = await sfu.createRouter({ room: 'lobby' });
+ *   const transport = await sfu.createTransport(router, { id: 'peer-1' });
+ *   const producer  = await sfu.produce(transport, 'audio', { codec: 'opus' });
+ *   const consumer  = await sfu.consume(transport, producer.id, {});
+ *
+ *   expect(events).toEqual([
+ *       { event: 'router-new',   payload: { routerId: router.id } },
+ *       { event: 'transport-new', payload: expect.any(Object) },
+ *       { event: 'producer-new',  payload: expect.objectContaining({ kind: 'audio' }) },
+ *       { event: 'consumer-new',  payload: expect.objectContaining({ producerId: producer.id }) },
+ *   ]);
+ *
+ * @example | Drive it through `loadSfuAdapter`
+ *   const sfu = loadSfuAdapter('memory');
+ *   const stats = await sfu.stats();
+ *   console.log(stats); // { routers, transports, producers, consumers }
+ */
+'use strict';
+
+const { SfuAdapter } = require('./index');
+const { WebRTCError } = require('../../errors');
+
+class MemorySfuAdapter extends SfuAdapter
+{
+    constructor(opts)
+    {
+        super();
+        this._opts = opts || {};
+        this._counter = 0;
+        this._routers    = new Map(); // routerId    -> { id, opts, transports:Set, closed }
+        this._transports = new Map(); // transportId -> { id, routerId, peer, producers:Set, consumers:Set, closed }
+        this._producers  = new Map(); // producerId  -> { id, transportId, kind, rtpParams, paused, closed }
+        this._consumers  = new Map(); // consumerId  -> { id, transportId, producerId, rtpCaps, closed }
+    }
+
+    _nextId(prefix)
+    {
+        this._counter += 1;
+        return `${prefix}-${this._counter}`;
+    }
+
+    async createRouter(opts)
+    {
+        const id = this._nextId('router');
+        const router = { id, opts: opts || {}, transports: new Set(), closed: false };
+        this._routers.set(id, router);
+        this._emit('router-new', { routerId: id });
+        return { id, routerId: id };
+    }
+
+    async createTransport(router, peer)
+    {
+        const routerId = router && router.id;
+        const r = routerId && this._routers.get(routerId);
+        if (!r || r.closed)
+        {
+            throw new WebRTCError('createTransport: unknown router', { code: 'WEBRTC_SFU_NO_ROUTER' });
+        }
+        const id = this._nextId('transport');
+        const t = {
+            id,
+            transportId: id,
+            routerId,
+            peer:        peer || null,
+            producers:   new Set(),
+            consumers:   new Set(),
+            closed:      false,
+            iceParameters:  { usernameFragment: id, password: id },
+            dtlsParameters: { role: 'auto', fingerprints: [] },
+        };
+        this._transports.set(id, t);
+        r.transports.add(id);
+        this._emit('transport-new', { transportId: id, routerId, peerId: peer && peer.id });
+        return t;
+    }
+
+    async produce(transport, kind, rtpParams)
+    {
+        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 || t.closed)
+        {
+            throw new WebRTCError('produce: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        }
+        const id = this._nextId('producer');
+        const p = { id, producerId: id, transportId: t.id, kind, rtpParams: rtpParams || {}, paused: false, closed: false };
+        this._producers.set(id, p);
+        t.producers.add(id);
+        this._emit('producer-new', { producerId: id, transportId: t.id, kind });
+        return p;
+    }
+
+    async consume(transport, producerId, rtpCaps)
+    {
+        const t = transport && this._transports.get(transport.id);
+        if (!t || t.closed)
+        {
+            throw new WebRTCError('consume: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        }
+        const prod = this._producers.get(producerId);
+        if (!prod || prod.closed)
+        {
+            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,
+            rtpParams:   prod.rtpParams,
+            rtpCaps:     rtpCaps || {},
+            closed:      false,
+        };
+        this._consumers.set(id, c);
+        t.consumers.add(id);
+        this._emit('consumer-new', { consumerId: id, transportId: t.id, producerId });
+        return c;
+    }
+
+    async pauseProducer(producerId)
+    {
+        const p = this._producers.get(producerId);
+        if (!p || p.closed)
+        {
+            throw new WebRTCError('pauseProducer: unknown producer', { code: 'WEBRTC_SFU_NO_PRODUCER' });
+        }
+        if (!p.paused)
+        {
+            p.paused = true;
+            this._emit('producer-pause', { producerId });
+        }
+    }
+
+    async resumeProducer(producerId)
+    {
+        const p = this._producers.get(producerId);
+        if (!p || p.closed)
+        {
+            throw new WebRTCError('resumeProducer: unknown producer', { code: 'WEBRTC_SFU_NO_PRODUCER' });
+        }
+        if (p.paused)
+        {
+            p.paused = false;
+            this._emit('producer-resume', { producerId });
+        }
+    }
+
+    async closeRouter(routerId)
+    {
+        const r = this._routers.get(routerId);
+        if (!r) return;
+        for (const tid of r.transports)
+        {
+            const t = this._transports.get(tid);
+            if (!t) continue;
+            for (const pid of t.producers)
+            {
+                const p = this._producers.get(pid);
+                if (p) { p.closed = true; this._emit('producer-close', { producerId: pid }); }
+                this._producers.delete(pid);
+            }
+            for (const cid of t.consumers)
+            {
+                const c = this._consumers.get(cid);
+                if (c) { c.closed = true; this._emit('consumer-close', { consumerId: cid }); }
+                this._consumers.delete(cid);
+            }
+            t.closed = true;
+            this._emit('transport-close', { transportId: tid });
+            this._transports.delete(tid);
+        }
+        r.closed = true;
+        this._emit('router-close', { routerId });
+        this._routers.delete(routerId);
+    }
+
+    async stats(scope)
+    {
+        if (scope && this._routers.has(scope))
+        {
+            const r = this._routers.get(scope);
+            return { kind: 'router', routerId: scope, transports: r.transports.size };
+        }
+        if (scope && this._transports.has(scope))
+        {
+            const t = this._transports.get(scope);
+            return {
+                kind: 'transport', transportId: scope, routerId: t.routerId,
+                producers: t.producers.size, consumers: t.consumers.size,
+            };
+        }
+        return {
+            kind:       'global',
+            routers:    this._routers.size,
+            transports: this._transports.size,
+            producers:  this._producers.size,
+            consumers:  this._consumers.size,
+        };
+    }
+}
+
+module.exports = { MemorySfuAdapter };