@zero-server/sdk 0.9.10 → 1.0.1

package/lib/webrtc/room.js

@@ -72,6 +72,23 @@ class Room
 
         /** @type {boolean} `true` once `.open()` has been called. */
         this.isOpen = false;
+
+        /**
+         * Currently advertised topology for this room. `mesh` until the
+         * hub promotes it (in `auto` mode) or until the application calls
+         * `setTopology()`. Broadcast to peers via `room-topology` so client
+         * SDKs can switch between p2p / SFU transports without a rejoin.
+         * @type {'mesh'|'sfu'|'mcu'}
+         */
+        this.topology = 'mesh';
+
+        /**
+         * Original topology preference inherited from the hub at room
+         * creation time. `auto` means the hub may promote/demote between
+         * `mesh` and `sfu` based on `maxMeshPeers`.
+         * @type {'mesh'|'sfu'|'mcu'|'auto'}
+         */
+        this.topologyMode = 'auto';
     }
 
     // -- Configuration (fluent) --
@@ -139,6 +156,8 @@ class Room
     {
         this._peers.add(peer);
         peer.room = this;
+        if (this.hub && typeof this.hub._onRoomMembershipChange === 'function')
+            this.hub._onRoomMembershipChange(this, 'add', peer);
     }
 
     /** Internal - hub uses this; do not call from application code. */
@@ -147,6 +166,29 @@ class Room
         if (!this._peers.has(peer)) return;
         this._peers.delete(peer);
         if (peer.room === this) peer.room = null;
+        if (this.hub && typeof this.hub._onRoomMembershipChange === 'function')
+            this.hub._onRoomMembershipChange(this, 'remove', peer);
+    }
+
+    /**
+     * Force the room's topology and broadcast the change to every peer.
+     * Pure signaling: the hub does not redirect media; client SDKs are
+     * responsible for switching transports when the new topology is
+     * received via `room-topology`.
+     * @param {'mesh'|'sfu'|'mcu'} topology
+     */
+    setTopology(topology)
+    {
+        if (topology !== 'mesh' && topology !== 'sfu' && topology !== 'mcu')
+            throw new SignalingError('Room.setTopology: topology must be mesh|sfu|mcu');
+        if (this.topology === topology) return this;
+        const previous = this.topology;
+        this.topology = topology;
+        for (const p of this._peers)
+            p.send('room-topology', { room: this.name, topology, previous });
+        if (this.hub)
+            this.hub.emit('topology:changed', { room: this, topology, previous });
+        return this;
     }
 
     // -- Fan-out --

package/lib/webrtc/sfu/index.js

@@ -116,6 +116,135 @@ class SfuAdapter
         throw new WebRTCError('SfuAdapter.stats() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
     }
 
+    // -- Consumer-side BWE / quality knobs --
+
+    /**
+     * Switch a consumer to the given simulcast spatial / temporal layer.
+     * @param {string} consumerId
+     * @param {{spatialLayer:number, temporalLayer?:number}} layers
+     */
+    async setConsumerPreferredLayers(_consumerId, _layers)
+    {
+        throw new WebRTCError('SfuAdapter.setConsumerPreferredLayers() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /**
+     * Set consumer priority (1-255, higher = more bandwidth budget under
+     * congestion).
+     */
+    async setConsumerPriority(_consumerId, _priority)
+    {
+        throw new WebRTCError('SfuAdapter.setConsumerPriority() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /** Ask the SFU to forward a PLI/FIR to the producer the consumer is bound to. */
+    async requestKeyFrame(_consumerId)
+    {
+        throw new WebRTCError('SfuAdapter.requestKeyFrame() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /** Pause an individual consumer (stop forwarding to a single subscriber). */
+    async pauseConsumer(_consumerId)
+    {
+        throw new WebRTCError('SfuAdapter.pauseConsumer() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /** Resume a previously paused consumer. */
+    async resumeConsumer(_consumerId)
+    {
+        throw new WebRTCError('SfuAdapter.resumeConsumer() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    // -- Transport-level BWE caps --
+
+    /**
+     * Apply incoming/outgoing bitrate hints to a transport.
+     * @param {string} transportId
+     * @param {{initial?:number, min?:number, max?:number, maxIncoming?:number, maxOutgoing?:number}} opts
+     */
+    async setTransportBitrates(_transportId, _opts)
+    {
+        throw new WebRTCError('SfuAdapter.setTransportBitrates() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    // -- Data channels --
+
+    /** Create an SCTP data producer on a transport. */
+    async produceData(_transport, _opts)
+    {
+        throw new WebRTCError('SfuAdapter.produceData() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /** Create an SCTP data consumer bound to `dataProducerId`. */
+    async consumeData(_transport, _dataProducerId, _opts)
+    {
+        throw new WebRTCError('SfuAdapter.consumeData() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    // -- Observers --
+
+    /**
+     * Start an audio-level observer on a router. Emits `audio-level` adapter
+     * events. Returns `{ id, close() }`.
+     * @param {string} routerId
+     * @param {{interval?:number, threshold?:number, maxEntries?:number}} [opts]
+     */
+    async observeAudioLevels(_routerId, _opts)
+    {
+        throw new WebRTCError('SfuAdapter.observeAudioLevels() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /**
+     * Start an active-speaker observer. Emits `active-speaker` adapter
+     * events. Returns `{ id, close() }`.
+     */
+    async observeActiveSpeaker(_routerId, _opts)
+    {
+        throw new WebRTCError('SfuAdapter.observeActiveSpeaker() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    // -- Cross-router cascade (SFU mesh) --
+
+    /**
+     * Pipe a producer from this adapter's local router into another router
+     * (possibly on a remote SFU node). Returns
+     * `{ pipeProducerId, pipeConsumerId, localRouterId, remoteRouterId }`.
+     * @param {{producerId:string, localRouterId:string, remoteRouter:object}} opts
+     */
+    async pipeToRouter(_opts)
+    {
+        throw new WebRTCError('SfuAdapter.pipeToRouter() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    // -- Targeted stats (Phase 2 surface; coarse stats() remains for back-compat) --
+
+    /** Return native stats for a single producer. */
+    async getProducerStats(_producerId)
+    {
+        throw new WebRTCError('SfuAdapter.getProducerStats() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /** Return native stats for a single consumer. */
+    async getConsumerStats(_consumerId)
+    {
+        throw new WebRTCError('SfuAdapter.getConsumerStats() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /** Return native stats for a single transport. */
+    async getTransportStats(_transportId)
+    {
+        throw new WebRTCError('SfuAdapter.getTransportStats() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
+    /**
+     * Toggle low-level trace event emission on a router (mediasoup `trace`
+     * events: 'probation', 'bwe', 'rtp', 'keyframe', etc.).
+     */
+    async enableTraceEvent(_routerId, _types)
+    {
+        throw new WebRTCError('SfuAdapter.enableTraceEvent() not implemented', { code: 'WEBRTC_SFU_NOT_IMPLEMENTED' });
+    }
+
     /**
      * Register a handler invoked as `(event, payload)` for adapter-level
      * events ('producer-new', 'producer-pause', 'consumer-new',

package/lib/webrtc/sfu/livekit.js

@@ -283,6 +283,310 @@ class LiveKitSfuAdapter extends SfuAdapter
             rooms,
         };
     }
+
+    // ----- Room / participant REST passthroughs -----
+
+    /**
+     * Fetch one room from LiveKit by name.  Returns the matching entry
+     * from `client.listRooms([name])` or `null`.
+     */
+    async getRoomInfo(routerId)
+    {
+        if (typeof this._client.listRooms !== 'function') return null;
+        try
+        {
+            const list = await this._client.listRooms([routerId]);
+            if (Array.isArray(list) && list.length) return list[0];
+            return null;
+        }
+        catch (_) { return null; }
+    }
+
+    async listParticipants(routerId)
+    {
+        if (typeof this._client.listParticipants !== 'function') return [];
+        return this._client.listParticipants(routerId);
+    }
+
+    async removeParticipant(routerId, identity)
+    {
+        if (typeof this._client.removeParticipant !== 'function')
+        {
+            throw new WebRTCError('removeParticipant: LiveKit client missing removeParticipant()', { code: 'WEBRTC_SFU_NOT_SUPPORTED' });
+        }
+        await this._client.removeParticipant(routerId, identity);
+        this._emit('peer-removed', { routerId, identity });
+    }
+
+    async updateRoomMetadata(routerId, metadata)
+    {
+        if (typeof this._client.updateRoomMetadata !== 'function')
+        {
+            throw new WebRTCError('updateRoomMetadata: LiveKit client missing updateRoomMetadata()', { code: 'WEBRTC_SFU_NOT_SUPPORTED' });
+        }
+        await this._client.updateRoomMetadata(routerId, typeof metadata === 'string' ? metadata : JSON.stringify(metadata));
+        this._emit('router-metadata', { routerId, metadata });
+    }
+
+    async sendData(routerId, payload, opts)
+    {
+        if (typeof this._client.sendData !== 'function')
+        {
+            throw new WebRTCError('sendData: LiveKit client missing sendData()', { code: 'WEBRTC_SFU_NOT_SUPPORTED' });
+        }
+        const o = opts || {};
+        const data = Buffer.isBuffer(payload) ? payload
+            : (payload instanceof Uint8Array ? Buffer.from(payload)
+                : Buffer.from(typeof payload === 'string' ? payload : JSON.stringify(payload)));
+        await this._client.sendData(routerId, data, o.kind || 0, o.destinationIdentities || o.destinations || undefined);
+    }
+
+    // ----- Egress (recording / RTMP / HLS) -----
+
+    _egressClient()
+    {
+        if (this._egress) return this._egress;
+        if (!this._livekit.EgressClient)
+        {
+            try { this._livekit = { ...this._livekit, ...require('livekit-server-sdk') }; }
+            catch (_) { /* fall through */ }
+        }
+        const C = this._livekit.EgressClient;
+        if (!C)
+        {
+            throw new WebRTCError(
+                "egress requires 'livekit-server-sdk' with EgressClient support",
+                { code: 'WEBRTC_SFU_NOT_INSTALLED' },
+            );
+        }
+        this._egress = new C(this._url, this._apiKey, this._apiSecret);
+        return this._egress;
+    }
+
+    async startRoomCompositeEgress(routerId, opts)
+    {
+        const e = this._egressClient();
+        const o = opts || {};
+        const res = await e.startRoomCompositeEgress(routerId, o.output || o, o.options);
+        this._emit('egress-start', { kind: 'room-composite', routerId, egressId: res && res.egressId });
+        return res;
+    }
+
+    async startTrackEgress(routerId, trackId, opts)
+    {
+        const e = this._egressClient();
+        const o = opts || {};
+        const res = await e.startTrackEgress(routerId, o.output || o, trackId);
+        this._emit('egress-start', { kind: 'track', routerId, trackId, egressId: res && res.egressId });
+        return res;
+    }
+
+    async stopEgress(egressId)
+    {
+        const e = this._egressClient();
+        const res = await e.stopEgress(egressId);
+        this._emit('egress-stop', { egressId });
+        return res;
+    }
+
+    async listEgress(opts)
+    {
+        const e = this._egressClient();
+        if (typeof e.listEgress !== 'function') return [];
+        return e.listEgress(opts || {});
+    }
+
+    // ----- Ingress (WHIP / RTMP / URL pull) -----
+
+    _ingressClient()
+    {
+        if (this._ingress) return this._ingress;
+        const C = this._livekit.IngressClient;
+        if (!C)
+        {
+            throw new WebRTCError(
+                "ingress requires 'livekit-server-sdk' with IngressClient support",
+                { code: 'WEBRTC_SFU_NOT_INSTALLED' },
+            );
+        }
+        this._ingress = new C(this._url, this._apiKey, this._apiSecret);
+        return this._ingress;
+    }
+
+    async createIngress(opts)
+    {
+        const i = this._ingressClient();
+        const o = opts || {};
+        const inputType = o.inputType || o.type || 'RTMP_INPUT';
+        const res = await i.createIngress(inputType, o);
+        this._emit('ingress-start', { ingressId: res && res.ingressId, inputType, room: o.roomName });
+        return res;
+    }
+
+    async deleteIngress(ingressId)
+    {
+        const i = this._ingressClient();
+        const res = await i.deleteIngress(ingressId);
+        this._emit('ingress-stop', { ingressId });
+        return res;
+    }
+
+    // ----- SfuAdapter Phase-2 surface (LiveKit owns media, so most are
+    //       client-side and surface as cooperative no-ops or REST mute hints) -----
+
+    async setConsumerPreferredLayers(consumerId, _layers)
+    {
+        if (!this._consumers.has(consumerId))
+            throw new WebRTCError('setConsumerPreferredLayers: unknown consumer', { code: 'WEBRTC_SFU_NO_CONSUMER' });
+        // LiveKit drives layer selection client-side (UpdateSubscription
+        // / SetSubscriptionPermissions); no server REST call is required.
+        this._emit('consumer-layers-change', { consumerId, layers: _layers || null });
+    }
+
+    async setConsumerPriority(consumerId, priority)
+    {
+        if (!this._consumers.has(consumerId))
+            throw new WebRTCError('setConsumerPriority: unknown consumer', { code: 'WEBRTC_SFU_NO_CONSUMER' });
+        this._emit('consumer-priority', { consumerId, priority });
+    }
+
+    async requestKeyFrame(consumerId)
+    {
+        if (!this._consumers.has(consumerId))
+            throw new WebRTCError('requestKeyFrame: unknown consumer', { code: 'WEBRTC_SFU_NO_CONSUMER' });
+        // LiveKit clients PLI through their own RTCP; no-op here.
+    }
+
+    async pauseConsumer(consumerId)
+    {
+        const c = this._consumers.get(consumerId);
+        if (!c)
+            throw new WebRTCError('pauseConsumer: unknown consumer', { code: 'WEBRTC_SFU_NO_CONSUMER' });
+        c.paused = true;
+        this._emit('consumer-pause', { consumerId });
+    }
+
+    async resumeConsumer(consumerId)
+    {
+        const c = this._consumers.get(consumerId);
+        if (!c)
+            throw new WebRTCError('resumeConsumer: unknown consumer', { code: 'WEBRTC_SFU_NO_CONSUMER' });
+        c.paused = false;
+        this._emit('consumer-resume', { consumerId });
+    }
+
+    async setTransportBitrates(transportId, bitrates)
+    {
+        if (!this._transports.has(transportId))
+            throw new WebRTCError('setTransportBitrates: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        // LiveKit BWE is end-to-end inside its own client; we record the
+        // request so callers can read it back and emit so observers can
+        // count clamps.
+        const t = this._transports.get(transportId);
+        t.bitrates = bitrates || {};
+        this._emit('transport-bitrates', { transportId, bitrates: t.bitrates });
+    }
+
+    async produceData(transport, opts)
+    {
+        if (!transport || !this._transports.has(transport.id))
+            throw new WebRTCError('produceData: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        const id = this._nextId('dataProducer');
+        const o  = opts || {};
+        const dp = {
+            id, dataProducerId: id, transportId: transport.id,
+            label: o.label || '', protocol: o.protocol || '',
+            ordered: o.ordered !== false,
+        };
+        this._dataProducers = this._dataProducers || new Map();
+        this._dataProducers.set(id, dp);
+        this._emit('data-producer-new', { dataProducerId: id, transportId: transport.id, label: dp.label });
+        return dp;
+    }
+
+    async consumeData(transport, dataProducerId, opts)
+    {
+        if (!transport || !this._transports.has(transport.id))
+            throw new WebRTCError('consumeData: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        const id = this._nextId('dataConsumer');
+        const o  = opts || {};
+        const dc = {
+            id, dataConsumerId: id, transportId: transport.id, dataProducerId,
+            label: '', protocol: '', ordered: o.ordered !== false,
+        };
+        this._dataConsumers = this._dataConsumers || new Map();
+        this._dataConsumers.set(id, dc);
+        this._emit('data-consumer-new', { dataConsumerId: id, transportId: transport.id, dataProducerId });
+        return dc;
+    }
+
+    async observeAudioLevels(routerId, _opts)
+    {
+        if (!this._rooms.has(routerId))
+            throw new WebRTCError('observeAudioLevels: unknown router', { code: 'WEBRTC_SFU_NO_ROUTER' });
+        // LiveKit emits "active_speakers_changed" via the room webhook /
+        // server-events channel; expose a tiny handle that pushes those
+        // through our adapter `_emit` once the caller wires them.
+        const id = this._nextId('audioObserver');
+        const self = this;
+        const handle = {
+            id, kind: 'audio-level', routerId, closed: false,
+            close: async () => { handle.closed = true; self._emit('observer-close', { observerId: id, kind: 'audio-level' }); },
+            emit:  (levels) => { if (!handle.closed) self._emit('audio-level', { observerId: id, routerId, levels }); },
+        };
+        this._emit('observer-new', { observerId: id, kind: 'audio-level', routerId });
+        return handle;
+    }
+
+    async observeActiveSpeaker(routerId, _opts)
+    {
+        if (!this._rooms.has(routerId))
+            throw new WebRTCError('observeActiveSpeaker: unknown router', { code: 'WEBRTC_SFU_NO_ROUTER' });
+        const id = this._nextId('speakerObserver');
+        const self = this;
+        const handle = {
+            id, kind: 'active-speaker', routerId, closed: false,
+            close: async () => { handle.closed = true; self._emit('observer-close', { observerId: id, kind: 'active-speaker' }); },
+            emit:  (producerId) => { if (!handle.closed) self._emit('active-speaker', { observerId: id, routerId, producerId }); },
+        };
+        this._emit('observer-new', { observerId: id, kind: 'active-speaker', routerId });
+        return handle;
+    }
+
+    async pipeToRouter(_opts)
+    {
+        // LiveKit handles cross-node fanout itself across its cluster;
+        // application-level pipe is not part of the public REST surface.
+        throw new WebRTCError('pipeToRouter: not supported by LiveKit provider', { code: 'WEBRTC_SFU_NOT_SUPPORTED' });
+    }
+
+    async getProducerStats(producerId)
+    {
+        if (!this._producers.has(producerId))
+            throw new WebRTCError('getProducerStats: unknown producer', { code: 'WEBRTC_SFU_NO_PRODUCER' });
+        return [];
+    }
+
+    async getConsumerStats(consumerId)
+    {
+        if (!this._consumers.has(consumerId))
+            throw new WebRTCError('getConsumerStats: unknown consumer', { code: 'WEBRTC_SFU_NO_CONSUMER' });
+        return [];
+    }
+
+    async getTransportStats(transportId)
+    {
+        if (!this._transports.has(transportId))
+            throw new WebRTCError('getTransportStats: unknown transport', { code: 'WEBRTC_SFU_NO_TRANSPORT' });
+        return [];
+    }
+
+    async enableTraceEvent(routerId, types)
+    {
+        if (!this._rooms.has(routerId))
+            throw new WebRTCError('enableTraceEvent: unknown router', { code: 'WEBRTC_SFU_NO_ROUTER' });
+        this._emit('trace-enabled', { routerId, types: Array.isArray(types) ? types : [] });
+    }
 }
 
 /**