@zero-server/webrtc 0.9.7 → 0.9.9

package/lib/webrtc/sfu/index.js

@@ -1,12 +1,28 @@
 /**
  * @module webrtc/sfu
- * @description SFU adapter base interface and discovery loader.
+ * @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.
  *
- *   `SfuAdapter` defines the contract every backend (memory / mediasoup /
- *   livekit / custom) must implement.  `loadSfuAdapter()` resolves either
- *   a pre-constructed instance, a known name ('memory', 'mediasoup',
- *   'livekit'), or a duck-typed object into a concrete adapter, throwing
- *   `WEBRTC_SFU_NOT_INSTALLED` when a native peerDep is missing.
+ * @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';
 
@@ -20,11 +36,30 @@ const { WebRTCError } = require('../../errors');
  *   The interface is intentionally tiny so a backend can be written in a
  *   single file:
  *
- *     class MyAdapter extends SfuAdapter {
- *         async createRouter(opts)            { ... }
- *         async createTransport(router, peer) { ... }
- *         ...
- *     }
+ * @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
 {
@@ -117,6 +152,21 @@ class SfuAdapter
  *   - '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)
 {

package/lib/webrtc/sfu/livekit.js

@@ -1,31 +1,34 @@
 /**
  * @module webrtc/sfu/livekit
- * @description LiveKit-backed SFU adapter (peerDependency on `livekit-server-sdk`).
+ * @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.
  *
- *   LiveKit's media plane is controlled remotely: rooms live on the
- *   LiveKit server, participants connect directly with a signed JWT, and
- *   the server SDK exposes a control-plane REST API.  This adapter maps
- *   the {@link SfuAdapter} contract onto that model:
+ * @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',
+ *   });
  *
- *     - createRouter(opts)          -> RoomServiceClient.createRoom(...)
- *     - createTransport(router,peer) -> mints an AccessToken (the "transport"
- *                                       handle is the URL + JWT the peer
- *                                       uses to connect to LiveKit directly)
- *     - produce / consume           -> local bookkeeping; LiveKit handles
- *                                       the actual media plane client-side
- *     - pauseProducer / resume      -> RoomServiceClient.mutePublishedTrack()
- *                                       when the producer was registered
- *                                       with a `{room, identity, trackSid}`
- *                                       hint; otherwise emits the event
- *                                       without touching the server
- *     - closeRouter(routerId)       -> RoomServiceClient.deleteRoom(...)
- *     - stats()                     -> RoomServiceClient.listRooms() /
- *                                       listParticipants(...) plus local
- *                                       counters
+ * @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 });
  *
- *   `livekit-server-sdk` is loaded lazily.  Tests inject a stub via
- *   `opts.livekit`; in production the constructor `require`s the package
- *   and throws `WEBRTC_SFU_NOT_INSTALLED` if it is missing.
+ * @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';
 

package/lib/webrtc/sfu/mediasoup.js

@@ -1,15 +1,55 @@
 /**
  * @module webrtc/sfu/mediasoup
- * @description mediasoup-backed SFU adapter (peerDependency on `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`.
  *
- *   Wraps a single mediasoup `Worker` and one `Router` per createRouter()
- *   call.  WebRTC transports are created with `router.createWebRtcTransport()`
- *   and produce / consume / pause / resume / close / stats all delegate to
- *   the native mediasoup objects.
+ * @example | Production setup with custom RTP port range and announced IP
+ *   //   npm install mediasoup
+ *   const { MediasoupSfuAdapter } = require('@zero-server/webrtc');
  *
- *   `mediasoup` is loaded lazily.  Tests inject a stub via `opts.mediasoup`;
- *   in production the constructor `require('mediasoup')`s the real package
- *   and throws `WEBRTC_SFU_NOT_INSTALLED` if it is missing.
+ *   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';
 

package/lib/webrtc/sfu/memory.js

@@ -1,16 +1,33 @@
 /**
  * @module webrtc/sfu/memory
- * @description In-process "memory" SFU adapter.
+ * @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.
  *
- *   A passthrough router that never touches the network: every produce()
- *   call records a logical producer, every consume() call records a
- *   logical consumer, and events are emitted via {@link SfuAdapter#onEvent}.
- *   Perfect for unit tests, ≤ 4-peer audio-only rooms, and local dev
- *   where the cost of running mediasoup or LiveKit is unjustified.
+ * @example | Use the memory adapter inside a vitest suite
+ *   const { MemorySfuAdapter } = require('@zero-server/webrtc');
+ *   const sfu = new MemorySfuAdapter();
  *
- *   The adapter does NOT decode or forward media packets - it models
- *   bookkeeping only.  Real packet forwarding lives in native adapters
- *   (mediasoup, LiveKit).
+ *   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';
 

package/lib/webrtc/signaling.js

@@ -1,13 +1,37 @@
 /**
  * @module webrtc/signaling
- * @description WebRTC signaling hub - the central WS broker that owns the
- *              room registry, attaches peers, validates JSEP messages, and
- *              routes offer / answer / ICE traffic between participants.
+ * @description WebRTC signaling hub. Central WS broker that owns the room
+ *   registry, attaches peers, validates JSEP messages, and routes
+ *   offer / answer / ICE traffic. Transport-agnostic — bind to `app.ws()`
+ *   in production, an `EventEmitter` shim in tests.
  *
- *   The hub itself is transport-agnostic: anything that exposes a
- *   `{ send(string), on('message'|'close', cb), close(code?, reason?) }`
- *   surface is acceptable.  `createWebRTC(app, opts)` (PR 9 wiring layer)
- *   binds an `app.ws()` upgrade handler to a `SignalingHub`.
+ * @example | Bind a hub to an `app.ws()` route with all production knobs
+ *   const app = createApp();
+ *   const hub = new SignalingHub({
+ *       joinTokenSecret:        process.env.WEBRTC_JWT_SECRET,
+ *       maxSdpSize:             64 * 1024,
+ *       maxCandidatesPerOffer:  20,
+ *       peerMessageRate:        30,
+ *       maxProtocolErrors:      5,
+ *       ipAttachRate:           60,
+ *       originAllowlist:        ['https://meet.acme.com'],
+ *       autoCreateRooms:        false,
+ *   });
+ *
+ *   hub.room('lobby').open();
+ *
+ *   app.ws('/rtc', (ws, req) => {
+ *       hub.attach(ws, {
+ *           user:   req.user,
+ *           ip:     req.ip,
+ *           origin: req.headers.origin,
+ *       });
+ *   });
+ *
+ * @example | Observe lifecycle events
+ *   hub.on('join',      ({ peer, room }) => log.info({ peer: peer.id, room: room.name }, 'joined'));
+ *   hub.on('leave',     ({ peer, room }) => log.info({ peer: peer.id, room: room.name }, 'left'));
+ *   hub.on('wireError', ({ peer, code })  => log.warn({ peer: peer.id, code }, 'wire-error'));
  */
 
 'use strict';
@@ -59,6 +83,11 @@ function _countCandidatesInSdp(sdp)
  * Validate that an SDP has the required RFC 8829 attributes on every media
  * section and uses DTLS-SRTP transport.  Returns an error code string, or
  * `null` if the SDP is acceptable.
+ *
+ * Accepts both RTP/SAVPF audio/video sections (RFC 8829) and SCTP data-channel
+ * sections (RFC 8841 m=application ... UDP/DTLS/SCTP). When BUNDLE is in use
+ * (every browser since ~2018), only the first m-section is required to carry
+ * iceUfrag/icePwd; other bundled sections inherit them via a=group:BUNDLE.
  */
 function _validateSdpStructure(sdp)
 {
@@ -70,12 +99,36 @@ function _validateSdpStructure(sdp)
         return 'INVALID_SDP';
     }
     if (!desc.media || desc.media.length === 0) return 'INVALID_SDP';
+
+    // BUNDLE: collect bundled mids so per-section ice credentials are optional
+    // on every section except the first (the BUNDLE owner).
+    const bundleMids = new Set();
+    for (const a of desc.attributes || [])
+    {
+        if (a.key !== 'group') continue;
+        const parts = String(a.value || '').split(/\s+/);
+        if (parts[0] !== 'BUNDLE') continue;
+        for (let i = 1; i < parts.length; i++) bundleMids.add(parts[i]);
+    }
+
+    let firstBundleMid = null;
     for (const m of desc.media)
     {
-        if (typeof m.proto !== 'string' || !/^UDP\/TLS\/RTP\/SAVPF?$/i.test(m.proto))
-            return 'INVALID_SDP';
-        if (!m.iceUfrag || !m.icePwd) return 'INVALID_SDP';
+        if (typeof m.proto !== 'string') return 'INVALID_SDP';
+
+        // RTP audio/video (RFC 8829) OR SCTP data channels (RFC 8841).
+        const isRtp  = /^UDP\/TLS\/RTP\/SAVPF?$/i.test(m.proto);
+        const isSctp = /^(UDP|TCP)\/DTLS\/SCTP$/i.test(m.proto);
+        if (!isRtp && !isSctp) return 'INVALID_SDP';
+
         if (!m.fingerprint) return 'INVALID_SDP';
+
+        // ice-ufrag / ice-pwd: required on the BUNDLE owner; optional on
+        // every other bundled section (inherited per RFC 8843 §9.2).
+        const bundled = m.mid && bundleMids.has(m.mid);
+        if (bundled && firstBundleMid === null) firstBundleMid = m.mid;
+        const isBundleOwner = !bundled || m.mid === firstBundleMid;
+        if (isBundleOwner && (!m.iceUfrag || !m.icePwd)) return 'INVALID_SDP';
     }
     return null;
 }
@@ -187,13 +240,33 @@ class SignalingHub extends EventEmitter
 
     /**
      * Attach a transport (WS connection or mock) as a new signaling peer.
-     * Wires up message and close handlers; returns the `Peer`.
+     * Wires up message and close handlers, performs origin / IP-rate
+     * pre-checks, sends a `hello` frame with the new peer id, and returns
+     * the `Peer`.  The returned peer is also registered in `hub.size`.
+     *
+     * Called from your `app.ws()` upgrade handler in production:
+     *
+     * ```js
+     * app.ws('/rtc', (ws, req) => hub.attach(ws, {
+     *     user:   req.user,
+     *     ip:     req.ip,
+     *     origin: req.headers.origin,
+     * }));
+     * ```
      *
      * @param {object} transport - `{ send, on, close }`-shaped object.
      * @param {object} [info]
-     * @param {*}      [info.user] - Authenticated user.
-     * @param {string} [info.ip]   - Remote IP.
+     * @param {*}      [info.user]   - Authenticated user (forwarded to room gates).
+     * @param {string} [info.ip]     - Remote IP for audit + `ipAttachRate`.
+     * @param {string} [info.origin] - Origin header for `originAllowlist`.
      * @returns {Peer}
+     *
+     * @example | Test harness: attach a mock transport
+     *   const mock = new EventEmitter();
+     *   mock.send  = (frame) => mock.emit('out', frame);
+     *   mock.close = ()      => mock.emit('close');
+     *   const peer = hub.attach(mock, { user: { id: 'u1' }, ip: '127.0.0.1' });
+     *   mock.emit('message', JSON.stringify({ type: 'join', room: 'lobby' }));
      */
     attach(transport, info = {})
     {

package/lib/webrtc/stun.js

@@ -1,19 +1,11 @@
 /**
  * @module webrtc/stun
- * @description Zero-dependency RFC 8489 STUN (Session Traversal Utilities for
- *              NAT) client.  Sends a Binding Request over UDP, parses the
- *              Binding Response, and returns the server-reflexive address
- *              decoded from XOR-MAPPED-ADDRESS (or, as a fallback, the
- *              deprecated MAPPED-ADDRESS attribute used by some legacy servers).
- *
- *              Only the parts of RFC 8489 we need for NAT discovery are
- *              implemented: BINDING method, REQUEST and SUCCESS classes,
- *              XOR-MAPPED-ADDRESS / MAPPED-ADDRESS attributes for IPv4 + IPv6.
- *              Authenticated TURN allocations are handled in
- *              `lib/webrtc/turn/`.
+ * @description Zero-dependency RFC 8489 STUN client. Sends a Binding Request
+ *   over UDP, parses the Binding Response, and returns the server-reflexive
+ *   address from XOR-MAPPED-ADDRESS (or legacy MAPPED-ADDRESS). NAT-discovery
+ *   subset only; TURN allocations live in `lib/webrtc/turn/`.
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8489
- * @see https://datatracker.ietf.org/doc/html/rfc5769  (test vectors)
  */
 
 'use strict';

package/lib/webrtc/turn/credentials.js

@@ -1,19 +1,10 @@
 /**
  * @file lib/webrtc/turn/credentials.js
  * @module @zero-server/webrtc/turn/credentials
- * @description RFC 7635 ephemeral TURN credentials.
- *
- *   Generates time-limited username / credential pairs that any
- *   RFC 7635-compatible TURN server (notably `coturn` with
- *   `use-auth-secret` + `static-auth-secret=<S>`) will accept.
- *
- *   Wire format (RFC 7635 §6.2):
- *     username   = "<unix-expiry>:<userId>"
- *     credential = base64( HMAC-SHA1( <secret>, username ) )
- *
- *   The returned object is shaped like an `RTCIceServer` entry so it can
- *   be embedded straight into the ICE-server list a signaling endpoint
- *   serves to browsers.
+ * @description RFC 7635 ephemeral TURN credentials. Generates short-TTL
+ *   username/credential pairs accepted by any compliant TURN server
+ *   (notably `coturn` with `use-auth-secret`). Returns an `RTCIceServer`-
+ *   shaped object ready to hand to browsers.
  */
 
 'use strict';
@@ -53,14 +44,38 @@ const VALID_SCHEMES = ['turn:', 'turns:', 'stun:', 'stuns:'];
  * @returns {TurnCredentials}
  * @throws {TurnError} On missing / invalid input.
  *
- * @example
+ * @example | Hand a fresh credential to a browser before it joins a room
+ *   //   coturn.conf:
+ *   //     use-auth-secret
+ *   //     static-auth-secret=<TURN_SHARED_SECRET>
+ *   //     realm=turn.example.com
+ *   app.get('/rtc/turn', (req, res) => {
+ *       const creds = issueTurnCredentials({
+ *           secret:  process.env.TURN_SHARED_SECRET,
+ *           userId:  req.user.id,
+ *           ttl:     '20m',
+ *           servers: ['turn:turn.example.com:3478?transport=udp'],
+ *       });
+ *       res.json(creds); // { urls, username, credential, ttl }
+ *   });
+ *
+ * @example | Multiple URLs (UDP, TCP, TLS) for failover
  *   const creds = issueTurnCredentials({
  *       secret:  process.env.TURN_SHARED_SECRET,
- *       userId:  req.user.id,
- *       ttl:     '20m',
- *       servers: ['turn:turn.example.com:3478?transport=udp'],
+ *       userId:  'bot-42',
+ *       ttl:     3600,
+ *       servers: [
+ *           'turn:turn.example.com:3478?transport=udp',
+ *           'turn:turn.example.com:3478?transport=tcp',
+ *           'turns:turn.example.com:5349',
+ *           'stun:turn.example.com:3478',
+ *       ],
+ *   });
+ *
+ * @example | Use directly in an RTCPeerConnection (browser side)
+ *   const pc = new RTCPeerConnection({
+ *       iceServers: [creds], // { urls, username, credential } is RTCIceServer-shaped
  *   });
- *   res.json(creds);
  *
  * @section ICE & TURN
  */

package/lib/webrtc/turn/server.js

@@ -1,36 +1,51 @@
 /**
  * @module webrtc/turn/server
- * @description Zero-dependency embedded TURN server (RFC 5766) backing the
- *              `TurnServer` public API.  Implements the long-term-credential
- *              auth flow paired with `issueTurnCredentials` ephemeral
- *              accounts, UDP allocations, permissions, Send / Data
- *              indications, channel bindings, lifetimes, and per-user
- *              quotas.
+ * @description Zero-dependency embedded TURN server (RFC 5766). Pairs with
+ *   `issueTurnCredentials` for long-term-credential auth and implements
+ *   UDP allocations, permissions, Send/Data indications, channel bindings,
+ *   lifetimes, and per-user quotas. TCP/TLS listeners are reserved and
+ *   currently throw `TURN_TRANSPORT_UNSUPPORTED`.
  *
- *   The hot path is intentionally compact: all framing lives in
- *   `lib/webrtc/turn/codec.js` and the server only owns state +
- *   relay-socket multiplexing.  TCP and TLS listeners are reserved in the
- *   constructor surface and will be implemented in a later PR; calling
- *   `start()` against either currently throws `TURN_TRANSPORT_UNSUPPORTED`.
- *
- * @example
+ * @example | Boot an embedded TURN server alongside Zero Server
  *   const { TurnServer, issueTurnCredentials } = require('@zero-server/webrtc');
  *
  *   const turn = new TurnServer({
- *       secret:   process.env.TURN_SECRET,
- *       realm:    'rtc.example.com',
+ *       secret:    process.env.TURN_SECRET,
+ *       realm:     'rtc.example.com',
+ *       relayHost: process.env.PUBLIC_IP || '0.0.0.0',
  *       listeners: [{ proto: 'udp', port: 3478 }],
- *       quotas:   { maxAllocationsPerUser: 4, maxBytesPerMinute: 50_000_000 },
+ *       quotas:    { maxAllocationsPerUser: 4, maxBytesPerMinute: 50_000_000 },
  *   });
  *   await turn.start();
  *
+ *   turn.on('allocate',   ({ user, relay })   => log.info({ user, relay }, 'turn allocate'));
+ *   turn.on('permission', ({ user, peer })    => log.debug({ user, peer }, 'turn permission'));
+ *   turn.on('relay',      ({ user, bytes })   => metrics.turnBytes.inc(bytes));
+ *
+ *   process.on('SIGTERM', () => turn.close());
+ *
+ * @example | Issue creds + return them with the room join payload
+ *   const { TurnServer, issueTurnCredentials } = require('@zero-server/webrtc');
  *   const creds = issueTurnCredentials({
  *       secret:  process.env.TURN_SECRET,
  *       userId:  req.user.id,
  *       servers: ['turn:rtc.example.com:3478'],
  *       ttl:     '20m',
  *   });
- *   res.json(creds);
+ *   res.json({ token, iceServers: [creds] });
+ *
+ * @example | Multi-listener (UDP + future TCP) with tight per-user quotas
+ *   const turn = new TurnServer({
+ *       secret:    process.env.TURN_SECRET,
+ *       realm:     'rtc.example.com',
+ *       listeners: [{ proto: 'udp', port: 3478, host: '0.0.0.0' }],
+ *       quotas:    {
+ *           maxAllocationsPerUser: 2,
+ *           maxBytesPerMinute:     5_000_000, // 5 MB/min per user
+ *       },
+ *       defaultLifetime: 300,
+ *       maxLifetime:     1800,
+ *   });
  */
 
 'use strict';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zero-server/webrtc",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "description": "WebRTC signaling hub, TURN credentials, STUN client, SFU adapter interface.",
   "keywords": [
     "zero-server",
@@ -45,14 +45,14 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@zero-server/realtime": "0.9.7",
-    "@zero-server/auth": "0.9.7",
-    "@zero-server/observe": "0.9.7",
-    "@zero-server/errors": "0.9.7",
-    "@zero-server/middleware": "0.9.7"
+    "@zero-server/realtime": "0.9.9",
+    "@zero-server/auth": "0.9.9",
+    "@zero-server/observe": "0.9.9",
+    "@zero-server/errors": "0.9.9",
+    "@zero-server/middleware": "0.9.9"
   },
   "peerDependencies": {
-    "@zero-server/sdk": ">=0.9.7"
+    "@zero-server/sdk": ">=0.9.9"
   },
   "peerDependenciesMeta": {
     "@zero-server/sdk": {