@zero-server/webrtc 0.9.7

package/lib/webrtc/observe.js

@@ -0,0 +1,229 @@
+/**
+ * @module webrtc/observe
+ * @description Optional metrics + tracing wiring for a {@link SignalingHub}.
+ *              Pass a `MetricsRegistry`, a `Tracer`, or both; the binder
+ *              subscribes to the hub's lifecycle events and exports the six
+ *              standard `zs_webrtc_*` Prometheus series plus per-operation
+ *              OpenTelemetry-compatible spans.
+ */
+
+'use strict';
+
+// --- Helpers ---
+
+/** Extract the first `a=ice-ufrag:` value from an SDP blob. */
+function _extractUfrag(sdp)
+{
+    const m = /^a=ice-ufrag:([^\r\n]+)/m.exec(sdp);
+    return m ? m[1].trim() : null;
+}
+
+// --- Metrics binder ---
+
+function _registerMetrics(registry)
+{
+    return {
+        peersActive: registry.gauge({
+            name:   'zs_webrtc_peers_active',
+            help:   'Number of WebRTC peers currently joined per room.',
+            labels: ['room'],
+        }),
+        roomsActive: registry.gauge({
+            name: 'zs_webrtc_rooms_active',
+            help: 'Number of WebRTC rooms with at least one peer.',
+        }),
+        signalingMessages: registry.counter({
+            name:   'zs_webrtc_signaling_messages_total',
+            help:   'WebRTC signaling messages by type, direction, and outcome.',
+            labels: ['type', 'direction', 'result'],
+        }),
+        offerDuration: registry.histogram({
+            name:    'zs_webrtc_offer_duration_ms',
+            help:    'End-to-end latency between an offer and its matching answer, in ms.',
+            labels:  ['room'],
+            buckets: [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000],
+        }),
+        joinFailures: registry.counter({
+            name:   'zs_webrtc_join_failures_total',
+            help:   'WebRTC room joins rejected by the hub.',
+            labels: ['reason'],
+        }),
+        iceRestart: registry.counter({
+            name:   'zs_webrtc_ice_restart_total',
+            help:   'Detected ICE restarts (ufrag rotation) per room.',
+            labels: ['room'],
+        }),
+    };
+}
+
+function _bindMetrics(hub, m)
+{
+    /** Outstanding offer timestamps: `offererPeerId` -> ms epoch. */
+    const offerStart = new Map();
+    /** Last seen ufrag per peer.id (for ICE-restart detection). */
+    const lastUfrag = new Map();
+
+    hub.on('signal', ({ peer, type }) =>
+    {
+        m.signalingMessages.inc({ type, direction: 'in', result: 'ok' });
+    });
+
+    hub.on('join', ({ peer, room }) =>
+    {
+        const before = m.peersActive.get({ room: room.name });
+        m.peersActive.inc({ room: room.name });
+        // Room newly non-empty?
+        if (before === 0) m.roomsActive.inc();
+    });
+
+    hub.on('leave', ({ peer, room }) =>
+    {
+        m.peersActive.dec({ room: room.name });
+        if (m.peersActive.get({ room: room.name }) <= 0)
+            m.roomsActive.dec();
+    });
+
+    hub.on('joinFailed', ({ reason }) =>
+    {
+        m.joinFailures.inc({ reason: reason || 'UNKNOWN' });
+    });
+
+    hub.on('offer', ({ peer, sdp, room }) =>
+    {
+        offerStart.set(peer.id, Date.now());
+
+        // ICE-restart detection: compare ufrag against last-known for this peer.
+        const ufrag = _extractUfrag(sdp);
+        if (ufrag)
+        {
+            const prev = lastUfrag.get(peer.id);
+            if (prev && prev !== ufrag)
+                m.iceRestart.inc({ room: room.name });
+            lastUfrag.set(peer.id, ufrag);
+        }
+    });
+
+    hub.on('answer', ({ peer, target, room }) =>
+    {
+        // The offer was sent by the original target (now answering back to it).
+        const startedAt = offerStart.get(target.id);
+        if (startedAt !== undefined)
+        {
+            m.offerDuration.observe({ room: room.name }, Date.now() - startedAt);
+            offerStart.delete(target.id);
+        }
+    });
+}
+
+// --- Tracing binder ---
+
+function _bindTracing(hub, tracer)
+{
+    hub.on('signal', ({ peer, type }) =>
+    {
+        const span = tracer.startSpan('webrtc.signal', {
+            kind:       'server',
+            attributes: { 'peer.id': peer.id, 'rtc.type': type },
+        });
+        span.setOk();
+        span.end();
+    });
+
+    hub.on('join', ({ peer, room }) =>
+    {
+        const span = tracer.startSpan('webrtc.join', {
+            kind:       'server',
+            attributes: { 'peer.id': peer.id, 'room.id': room.name },
+        });
+        span.setOk();
+        span.end();
+    });
+
+    hub.on('joinFailed', ({ peer, reason, room }) =>
+    {
+        const span = tracer.startSpan('webrtc.join', {
+            kind:       'server',
+            attributes: { 'peer.id': peer.id, 'room.id': room || '', 'rtc.error': reason },
+        });
+        span.setError(reason);
+        span.end();
+    });
+
+    hub.on('offer', ({ peer, target, room }) =>
+    {
+        const span = tracer.startSpan('webrtc.publish', {
+            kind:       'producer',
+            attributes: { 'peer.id': peer.id, 'room.id': room.name, 'rtc.target': target.id },
+        });
+        span.setOk();
+        span.end();
+    });
+
+    hub.on('publishFailed', ({ peer, reason, room }) =>
+    {
+        const span = tracer.startSpan('webrtc.publish', {
+            kind:       'producer',
+            attributes: { 'peer.id': peer.id, 'room.id': room || '', 'rtc.error': reason },
+        });
+        span.setError(reason);
+        span.end();
+    });
+
+    hub.on('answer', ({ peer, target, room }) =>
+    {
+        const span = tracer.startSpan('webrtc.subscribe', {
+            kind:       'consumer',
+            attributes: { 'peer.id': peer.id, 'room.id': room.name, 'rtc.target': target.id },
+        });
+        span.setOk();
+        span.end();
+    });
+
+    hub.on('subscribeFailed', ({ peer, reason, room }) =>
+    {
+        const span = tracer.startSpan('webrtc.subscribe', {
+            kind:       'consumer',
+            attributes: { 'peer.id': peer.id, 'room.id': room || '', 'rtc.error': reason },
+        });
+        span.setError(reason);
+        span.end();
+    });
+}
+
+// --- Public API ---
+
+/**
+ * Wire a {@link SignalingHub} to a metrics registry and / or a tracer.
+ *
+ * Registers six standard Prometheus series under the `zs_webrtc_` prefix:
+ *
+ * - `zs_webrtc_peers_active{room}`            (gauge)
+ * - `zs_webrtc_rooms_active`                  (gauge)
+ * - `zs_webrtc_signaling_messages_total{type,direction,result}` (counter)
+ * - `zs_webrtc_offer_duration_ms{room}`       (histogram)
+ * - `zs_webrtc_join_failures_total{reason}`   (counter)
+ * - `zs_webrtc_ice_restart_total{room}`       (counter)
+ *
+ * Emits spans named `webrtc.join`, `webrtc.signal`, `webrtc.publish`, and
+ * `webrtc.subscribe`, each annotated with `peer.id` and `room.id`.
+ *
+ * @section Observability
+ *
+ * @param {SignalingHub} hub - The hub to instrument.
+ * @param {object} opts
+ * @param {MetricsRegistry} [opts.metrics] - Prometheus-compatible registry.
+ * @param {Tracer}          [opts.tracer]  - Tracer for span emission.
+ * @returns {SignalingHub} The same hub, for chaining.
+ *
+ * @example | Plug into an existing app
+ *   const hub = new SignalingHub();
+ *   bindObservability(hub, { metrics: app.metrics() });
+ */
+function bindObservability(hub, opts = {})
+{
+    if (opts.metrics) _bindMetrics(hub, _registerMetrics(opts.metrics));
+    if (opts.tracer)  _bindTracing(hub, opts.tracer);
+    return hub;
+}
+
+module.exports = { bindObservability };

package/lib/webrtc/peer.js

@@ -0,0 +1,116 @@
+/**
+ * @module webrtc/peer
+ * @description Per-connection state machine for a WebRTC signaling peer.
+ *
+ *   A `Peer` wraps a transport object (typically a `WebSocketConnection`
+ *   but any duck-typed `{ send, on, close }` works - see the unit tests
+ *   for a minimal in-memory transport) and exposes the JSEP message
+ *   types as ordinary events.  The hub is responsible for routing.
+ */
+
+'use strict';
+
+let _peerCounter = 0;
+
+/**
+ * JSEP signaling state strings, matching RFC 8829 §4.1.
+ * @enum {string}
+ */
+const PEER_STATE = Object.freeze({
+    STABLE:             'stable',
+    HAVE_LOCAL_OFFER:   'have-local-offer',
+    HAVE_REMOTE_OFFER:  'have-remote-offer',
+});
+
+/**
+ * One signaling peer attached to a `SignalingHub` via some transport.
+ *
+ * @class
+ * @section Peers
+ *
+ * @example
+ *   hub.on('join', ({ peer, room }) => {
+ *       peer.send('welcome', { roomSize: room.size });
+ *       peer.on('mute', ev => audit('mute', peer.id, ev.kind));
+ *   });
+ */
+class Peer
+{
+    /**
+     * @constructor
+     * @param {object} transport - Anything with `send(string)`, `on('message'|'close', cb)`, `close(code?, reason?)`.
+     * @param {object} [info]    - Connection metadata.
+     * @param {*}      [info.user] - Authenticated user object (if any).
+     * @param {string} [info.ip]   - Remote IP for audit / rate limits.
+     */
+    constructor(transport, info = {})
+    {
+        /** @type {string} Globally-unique peer id within a hub. */
+        this.id = 'peer_' + (++_peerCounter) + '_' + Date.now().toString(36);
+
+        /** @type {*} Authenticated user object (if any). */
+        this.user = info.user || null;
+
+        /** @type {string|null} Remote IP for audit / rate limits. */
+        this.ip = info.ip || null;
+
+        /** @type {object} Underlying transport (WS connection or mock). */
+        this.transport = transport;
+
+        /** @type {string} Current JSEP state. */
+        this.state = PEER_STATE.STABLE;
+
+        /** @type {import('./room')|null} Current room membership. */
+        this.room = null;
+
+        /** @type {number} Count of malformed frames received - rate-limit material. */
+        this.errors = 0;
+
+        /** @type {number} ms timestamp the peer was created. */
+        this.connectedAt = Date.now();
+
+        /** @type {boolean} */
+        this.closed = false;
+    }
+
+    /**
+     * Send a JSON envelope to this peer.  `type` is added to `payload` and
+     * the result is serialised once.  Silently drops sends after close.
+     * @param {string} type
+     * @param {object} [payload]
+     */
+    send(type, payload)
+    {
+        if (this.closed) return;
+        const frame = Object.assign({ type }, payload || {});
+        try { this.transport.send(JSON.stringify(frame)); }
+        catch { /* transport may already be closed; ignore */ }
+    }
+
+    /**
+     * Send a typed error frame.  Callers SHOULD use this rather than throwing,
+     * because exceptions escape the message handler and tear down the process.
+     * @param {string} code
+     * @param {string} message
+     */
+    sendError(code, message)
+    {
+        this.send('error', { code, message });
+    }
+
+    /**
+     * Close the underlying transport with a WebSocket-style code and reason.
+     * Defaults to 1000 (normal closure).
+     * @param {number} [code=1000]
+     * @param {string} [reason='']
+     */
+    close(code = 1000, reason = '')
+    {
+        if (this.closed) return;
+        this.closed = true;
+        try { this.transport.close(code, reason); }
+        catch { /* already closed */ }
+    }
+}
+
+module.exports = { Peer, PEER_STATE };

package/lib/webrtc/room.js

@@ -0,0 +1,171 @@
+/**
+ * @module webrtc/room
+ * @description Room / channel abstraction for the WebRTC signaling hub.
+ *
+ *   A `Room` holds a set of `Peer`s plus a list of `require()` policy gates
+ *   that decide whether a given peer may join.  Membership is in-process;
+ *   the cluster adapter (PR 8) will fan room state out via pub/sub.
+ */
+
+'use strict';
+
+const { SignalingError } = require('../errors');
+
+/**
+ * One signaling room.
+ *
+ * Constructed lazily by `SignalingHub#room(name)`.  Application code never
+ * calls `new Room()` directly.
+ *
+ * @class
+ * @section Rooms
+ *
+ * @example
+ *   hub.room('lobby').open();
+ *   hub.room('boardroom')
+ *       .require(peer => peer.user && peer.user.role === 'exec')
+ *       .canPublish(peer => peer.user.isHost);
+ */
+class Room
+{
+    /**
+     * @constructor
+     * @param {string} name        - Room name, used as routing key.
+     * @param {object} [opts]
+     * @param {import('./signaling').SignalingHub} [opts.hub] - Owning hub.
+     */
+    constructor(name, opts = {})
+    {
+        if (typeof name !== 'string' || name.length === 0)
+            throw new SignalingError('Room name must be a non-empty string');
+
+        /** @type {string} */
+        this.name = name;
+
+        /** @type {import('./signaling').SignalingHub|null} */
+        this.hub = opts.hub || null;
+
+        /** @type {Set<import('./peer').Peer>} */
+        this._peers = new Set();
+
+        /** @type {Array<(peer:import('./peer').Peer) => boolean>} */
+        this._gates = [];
+
+        /** @type {((peer:import('./peer').Peer) => boolean)|null} */
+        this._canPublish = null;
+
+        /** @type {((peer:import('./peer').Peer) => boolean)|null} */
+        this._canSubscribe = null;
+
+        /** @type {boolean} `true` once `.open()` has been called. */
+        this.isOpen = false;
+    }
+
+    // -- Configuration (fluent) --
+
+    /** Mark the room as public.  Returns `this` for chaining. */
+    open()
+    {
+        this.isOpen = true;
+        return this;
+    }
+
+    /**
+     * Add a policy gate.  Called on every join; first falsy return rejects.
+     * @param {(peer:import('./peer').Peer) => boolean | Promise<boolean>} fn
+     * @returns {Room}
+     */
+    require(fn)
+    {
+        if (typeof fn !== 'function')
+            throw new SignalingError('Room.require(fn) requires a function');
+        this._gates.push(fn);
+        return this;
+    }
+
+    /**
+     * Set the publish-permission check.  Hub calls this before relaying offers.
+     * @param {(peer:import('./peer').Peer) => boolean} fn
+     */
+    canPublish(fn)   { this._canPublish   = fn; return this; }
+
+    /**
+     * Set the subscribe-permission check.  Hub calls this before relaying answers.
+     * @param {(peer:import('./peer').Peer) => boolean} fn
+     */
+    canSubscribe(fn) { this._canSubscribe = fn; return this; }
+
+    // -- Membership --
+
+    /** Current member count. */
+    get size() { return this._peers.size; }
+
+    /** @returns {import('./peer').Peer[]} */
+    peers() { return Array.from(this._peers); }
+
+    /** @returns {boolean} */
+    has(peer) { return this._peers.has(peer); }
+
+    /**
+     * Evaluate every `require()` gate against the candidate peer.
+     * @param {import('./peer').Peer} peer
+     * @returns {boolean}
+     */
+    canJoin(peer)
+    {
+        for (const gate of this._gates)
+        {
+            try { if (!gate(peer)) return false; }
+            catch { return false; }
+        }
+        return true;
+    }
+
+    /** Internal - hub uses this; do not call from application code. */
+    _add(peer)
+    {
+        this._peers.add(peer);
+        peer.room = this;
+    }
+
+    /** Internal - hub uses this; do not call from application code. */
+    _remove(peer)
+    {
+        if (!this._peers.has(peer)) return;
+        this._peers.delete(peer);
+        if (peer.room === this) peer.room = null;
+    }
+
+    // -- Fan-out --
+
+    /**
+     * Send a `{type, ...payload}` JSON frame to every peer in the room.
+     * @param {string} type
+     * @param {object} [payload]
+     * @param {string} [exceptPeerId] - Optional peer id to skip (e.g. the originator).
+     */
+    broadcast(type, payload, exceptPeerId)
+    {
+        for (const p of this._peers)
+        {
+            if (exceptPeerId && p.id === exceptPeerId) continue;
+            p.send(type, payload);
+        }
+        if (this.hub && this.hub._cluster)
+            this.hub._cluster.fanoutRoom(this.name, type, payload, exceptPeerId);
+    }
+
+    /** Kick every peer with code 1001 (going-away) and unregister from the hub. */
+    close(reason = 'room-closed')
+    {
+        for (const p of Array.from(this._peers))
+        {
+            p.send('bye', { reason });
+            p.close(1001, reason);
+        }
+        this._peers.clear();
+        if (this.hub) this.hub._removeRoom(this);
+    }
+}
+
+module.exports = { Room };