zero-query 1.1.1 → 1.2.0

package/src/webrtc/sdp.js

@@ -0,0 +1,302 @@
+/**
+ * src/webrtc/sdp.js - minimal read-only SDP helpers
+ *
+ * A trimmed port of the server-side `@zero-server/webrtc` SDP module.
+ * The client only needs to read a few keys out of an SDP (for stats,
+ * ICE bookkeeping, and a sanity check before sending it through
+ * signaling); full RFC 8866 conformance lives on the server.
+ *
+ * Surface:
+ *   - `parseSdp(text)`     -> structured `{ version, origin, sessionName, media: [...] }`
+ *   - `validateSdp(text)`  -> throws `SdpError` if the SDP would be rejected by the hub
+ *                            (missing `UDP/TLS/RTP/SAVPF` proto, `ice-ufrag`, `ice-pwd`,
+ *                            or `fingerprint` on any non-rejected m-section).
+ *
+ * Pure functions, no globals, SSR-safe.
+ */
+
+import { SdpError } from './errors.js';
+
+
+/** Max SDP size accepted by the server. */
+const DEFAULT_MAX_BYTES = 65_536;
+
+/** Required transport protocol per server validator. */
+const REQUIRED_PROTO = 'UDP/TLS/RTP/SAVPF';
+
+/** Valid SDP direction attributes (RFC 8866 §6.7). */
+export const SDP_DIRECTIONS = Object.freeze(['sendrecv', 'sendonly', 'recvonly', 'inactive']);
+
+
+/**
+ * Parse an SDP document into a minimal, structured form.
+ *
+ * Only the fields the client needs are lifted onto named keys; everything
+ * else is preserved verbatim on `attributes`/`media[i].attributes` so the
+ * caller can still inspect unusual lines without losing information.
+ *
+ * @param {string} text
+ * @param {object} [opts]
+ * @param {number} [opts.maxBytes=65536]
+ * @returns {{
+ *   version: number,
+ *   origin: ?object,
+ *   sessionName: string,
+ *   attributes: Array<{key:string,value:string}>,
+ *   media: Array<{
+ *     kind: string,
+ *     port: number,
+ *     proto: string,
+ *     fmts: string[],
+ *     mid?: string,
+ *     iceUfrag?: string,
+ *     icePwd?: string,
+ *     fingerprint?: { algorithm: string, value: string },
+ *     setup?: string,
+ *     direction?: string,
+ *     rtcpMux: boolean,
+ *     candidates: string[],
+ *     rtpmaps: Array<{ payload: number, codec: string, clockRate: number, channels?: number }>,
+ *     attributes: Array<{key:string,value:string}>,
+ *   }>,
+ * }}
+ */
+export function parseSdp(text, opts = {}) {
+    if (typeof text !== 'string') {
+        throw new SdpError('parseSdp: input must be a string', { code: 'ZQ_WEBRTC_SDP_PARSE' });
+    }
+    const maxBytes = typeof opts.maxBytes === 'number' ? opts.maxBytes : DEFAULT_MAX_BYTES;
+    if (text.length > maxBytes) {
+        throw new SdpError(`parseSdp: payload exceeds ${maxBytes} bytes`, { code: 'ZQ_WEBRTC_SDP_TOO_LARGE' });
+    }
+    if (text.length === 0) {
+        throw new SdpError('parseSdp: empty input', { code: 'ZQ_WEBRTC_SDP_PARSE' });
+    }
+
+    const lines = text.replace(/\r\n/g, '\n').split('\n').filter((l) => l.length > 0);
+    if (lines.length === 0) {
+        throw new SdpError('parseSdp: no non-empty lines', { code: 'ZQ_WEBRTC_SDP_PARSE' });
+    }
+
+    const session = {
+        version:     0,
+        origin:      null,
+        sessionName: '',
+        attributes:  [],
+        media:       [],
+    };
+
+    let current = session;
+    let currentMedia = null;
+
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        const eq  = raw.indexOf('=');
+        if (eq < 1) {
+            throw new SdpError(`parseSdp: malformed line ${i + 1}`, {
+                code: 'ZQ_WEBRTC_SDP_PARSE',
+                context: { line: i + 1 },
+            });
+        }
+        const type = raw.slice(0, eq);
+        const val  = raw.slice(eq + 1);
+
+        if (i === 0 && type !== 'v') {
+            throw new SdpError('parseSdp: SDP must start with v=', {
+                code: 'ZQ_WEBRTC_SDP_PARSE',
+                context: { line: 1 },
+            });
+        }
+
+        switch (type) {
+            case 'v':
+                session.version = Number(val);
+                break;
+            case 'o':
+                session.origin = _parseOrigin(val);
+                break;
+            case 's':
+                session.sessionName = val;
+                break;
+            case 'm': {
+                currentMedia = _newMedia(val);
+                session.media.push(currentMedia);
+                current = currentMedia;
+                break;
+            }
+            case 'a':
+                _applyAttribute(current, val);
+                break;
+            default:
+                // ignore the lines we don't need for the client subset
+                break;
+        }
+    }
+
+    return session;
+}
+
+
+/**
+ * Validate that the SDP would survive the server-side hub's strict checks.
+ * Throws `SdpError` on missing required attributes; returns the parsed
+ * structure on success so callers can chain.
+ *
+ * Required, per `@zero-server/webrtc` signaling validator:
+ *   - at least one m-line
+ *   - non-rejected m-lines (port != 0) must use `UDP/TLS/RTP/SAVPF`
+ *   - each non-rejected m-line must carry `ice-ufrag`, `ice-pwd`, and
+ *     a `fingerprint` attribute (session-level fallback is honored).
+ *
+ * @param {string} text
+ * @returns {ReturnType<typeof parseSdp>}
+ */
+export function validateSdp(text) {
+    const parsed = parseSdp(text);
+    if (parsed.media.length === 0) {
+        throw new SdpError('validateSdp: SDP has no m-lines', { code: 'ZQ_WEBRTC_SDP_NO_MEDIA' });
+    }
+
+    // Session-level fallbacks: ice-ufrag / ice-pwd / fingerprint can appear
+    // once at the session level and apply to every m-section.
+    const sessIceUfrag    = _findAttr(parsed.attributes, 'ice-ufrag');
+    const sessIcePwd      = _findAttr(parsed.attributes, 'ice-pwd');
+    const sessFingerprint = _findAttr(parsed.attributes, 'fingerprint');
+
+    for (let i = 0; i < parsed.media.length; i++) {
+        const m = parsed.media[i];
+        if (m.port === 0) continue;
+        if (m.proto !== REQUIRED_PROTO) {
+            throw new SdpError(
+                `validateSdp: m-line ${i} proto "${m.proto}" must be "${REQUIRED_PROTO}"`,
+                { code: 'ZQ_WEBRTC_SDP_BAD_PROTO', context: { index: i, proto: m.proto } }
+            );
+        }
+        const ufrag = m.iceUfrag || sessIceUfrag;
+        const pwd   = m.icePwd   || sessIcePwd;
+        const fp    = m.fingerprint || sessFingerprint;
+        if (!ufrag) {
+            throw new SdpError(`validateSdp: m-line ${i} missing ice-ufrag`, {
+                code: 'ZQ_WEBRTC_SDP_NO_ICE_UFRAG', context: { index: i },
+            });
+        }
+        if (!pwd) {
+            throw new SdpError(`validateSdp: m-line ${i} missing ice-pwd`, {
+                code: 'ZQ_WEBRTC_SDP_NO_ICE_PWD', context: { index: i },
+            });
+        }
+        if (!fp) {
+            throw new SdpError(`validateSdp: m-line ${i} missing fingerprint`, {
+                code: 'ZQ_WEBRTC_SDP_NO_FINGERPRINT', context: { index: i },
+            });
+        }
+    }
+
+    return parsed;
+}
+
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+/** @param {string} val */
+function _parseOrigin(val) {
+    const t = val.split(/\s+/);
+    if (t.length < 6) return null;
+    return {
+        username:       t[0],
+        sessionId:      t[1],
+        sessionVersion: Number(t[2]),
+        netType:        t[3],
+        addrType:       t[4],
+        address:        t[5],
+    };
+}
+
+/** @param {string} val - the part after `m=` */
+function _newMedia(val) {
+    const t = val.split(/\s+/);
+    return {
+        kind:        t[0] || '',
+        port:        Number(t[1]) || 0,
+        proto:       t[2] || '',
+        fmts:        t.slice(3),
+        mid:         undefined,
+        iceUfrag:    undefined,
+        icePwd:      undefined,
+        fingerprint: undefined,
+        setup:       undefined,
+        direction:   undefined,
+        rtcpMux:     false,
+        candidates:  [],
+        rtpmaps:     [],
+        attributes:  [],
+    };
+}
+
+/**
+ * Apply a single `a=...` line to the current section (session or media).
+ * @param {object} section
+ * @param {string} val
+ */
+function _applyAttribute(section, val) {
+    const colon = val.indexOf(':');
+    const key = colon === -1 ? val : val.slice(0, colon);
+    const value = colon === -1 ? '' : val.slice(colon + 1);
+    section.attributes.push({ key, value });
+
+    switch (key) {
+        case 'mid':         if ('mid'         in section) section.mid = value; break;
+        case 'ice-ufrag':   if ('iceUfrag'    in section) section.iceUfrag = value; break;
+        case 'ice-pwd':     if ('icePwd'      in section) section.icePwd = value; break;
+        case 'setup':       if ('setup'       in section) section.setup = value; break;
+        case 'rtcp-mux':    if ('rtcpMux'     in section) section.rtcpMux = true; break;
+        case 'fingerprint': {
+            const sp = value.indexOf(' ');
+            const fp = sp === -1
+                ? { algorithm: value, value: '' }
+                : { algorithm: value.slice(0, sp), value: value.slice(sp + 1) };
+            if ('fingerprint' in section) section.fingerprint = fp;
+            break;
+        }
+        case 'candidate':
+            if ('candidates' in section) section.candidates.push(`candidate:${value}`);
+            break;
+        case 'rtpmap': {
+            if (!('rtpmaps' in section)) break;
+            const sp = value.indexOf(' ');
+            if (sp === -1) break;
+            const payload = Number(value.slice(0, sp));
+            const desc    = value.slice(sp + 1).split('/');
+            section.rtpmaps.push({
+                payload,
+                codec:     desc[0] || '',
+                clockRate: Number(desc[1]) || 0,
+                channels:  desc[2] ? Number(desc[2]) : undefined,
+            });
+            break;
+        }
+        case 'sendrecv':
+        case 'sendonly':
+        case 'recvonly':
+        case 'inactive':
+            if ('direction' in section) section.direction = key;
+            break;
+        default:
+            // unknown attribute - already preserved on attributes[]
+            break;
+    }
+}
+
+/**
+ * Find the first attribute value for `key` in an attribute list, or `undefined`.
+ * @param {Array<{key:string,value:string}>} list
+ * @param {string} key
+ */
+function _findAttr(list, key) {
+    for (let i = 0; i < list.length; i++) {
+        if (list[i].key === key) return list[i].value || true;
+    }
+    return undefined;
+}

package/src/webrtc/sfu/index.js

@@ -0,0 +1,43 @@
+/**
+ * src/webrtc/sfu/index.js
+ *
+ * SFU adapter registry. Adapters are dynamic-imported so the (optional)
+ * peer dependencies (`mediasoup-client`, `livekit-client`) only load
+ * when actually used.
+ *
+ * Public surface:
+ *   - `loadSfuAdapter(name, opts?)` → `Promise<SfuAdapter>`
+ */
+
+import { SfuError } from '../errors.js';
+import { createMediasoupAdapter } from './mediasoup.js';
+import { createLivekitAdapter } from './livekit.js';
+
+
+/**
+ * @typedef {object} SfuAdapter
+ * @property {'mediasoup'|'livekit'} name
+ * @property {(joinOpts: any) => Promise<any>} join
+ */
+
+
+/**
+ * Load an SFU adapter by name. The adapter's peer dependency must be
+ * installed by the consuming app.
+ *
+ * @param {'mediasoup'|'livekit'} name
+ * @param {object} [opts]
+ * @returns {Promise<SfuAdapter>}
+ */
+export async function loadSfuAdapter(name, opts = {}) {
+    if (name === 'mediasoup') {
+        return createMediasoupAdapter(opts);
+    }
+    if (name === 'livekit') {
+        return createLivekitAdapter(opts);
+    }
+    throw new SfuError(`unknown SFU adapter: ${name}`, {
+        code: 'ZQ_WEBRTC_SFU_UNKNOWN',
+        context: { name },
+    });
+}

package/src/webrtc/sfu/livekit.js

@@ -0,0 +1,131 @@
+/**
+ * src/webrtc/sfu/livekit.js
+ *
+ * Thin wrapper around the optional `livekit-client` peer dependency.
+ *
+ *   - `livekit-client` is intentionally NOT bundled. Apps that want it
+ *     must `npm install livekit-client` themselves.
+ *   - If it isn't installed, `createLivekitAdapter()` throws
+ *     `ZQ_WEBRTC_SFU_PEER_MISSING` with an actionable message.
+ *   - The adapter exposes a LiveKit `Room` instance plus `connect()` /
+ *     `disconnect()` helpers. The higher-level zQuery `Room` mapping
+ *     lives in the consuming app for now; calling `.join()` throws
+ *     `ZQ_WEBRTC_SFU_JOIN_UNAVAILABLE`.
+ */
+
+import { SfuError } from '../errors.js';
+
+
+/**
+ * Dynamically import `livekit-client`. Returns the module's exports.
+ * Throws `SfuError(ZQ_WEBRTC_SFU_PEER_MISSING)` if the package is absent.
+ *
+ * @returns {Promise<any>}
+ */
+async function _importLivekitClient() {
+    try {
+        // Compose the package name at runtime so static bundlers (Vite,
+        // Rollup, esbuild) don't try to resolve the optional peer dep.
+        const pkg = ['livekit', 'client'].join('-');
+        return await import(/* @vite-ignore */ pkg);
+    } catch (cause) {
+        throw new SfuError(
+            'livekit-client peer dependency is not installed; run `npm install livekit-client`',
+            { code: 'ZQ_WEBRTC_SFU_PEER_MISSING', cause },
+        );
+    }
+}
+
+
+/**
+ * Build a LiveKit-client adapter.
+ *
+ * @param {object} [opts]
+ * @param {any}    [opts.client]       Pre-imported livekit-client module (test hook).
+ * @param {object} [opts.roomOptions]  Forwarded to `new Room(...)`.
+ * @returns {Promise<import('./index.js').SfuAdapter>}
+ */
+export async function createLivekitAdapter(opts = {}) {
+    const mod    = opts.client || await _importLivekitClient();
+    const RoomCtor = mod.Room || (mod.default && mod.default.Room);
+    if (typeof RoomCtor !== 'function') {
+        throw new SfuError('livekit-client module did not expose a Room constructor', {
+            code: 'ZQ_WEBRTC_SFU_BAD_MODULE',
+        });
+    }
+
+    let room;
+    try {
+        room = new RoomCtor(opts.roomOptions || {});
+    } catch (cause) {
+        throw new SfuError('failed to construct livekit-client Room', {
+            code: 'ZQ_WEBRTC_SFU_ROOM_FAILED',
+            cause,
+        });
+    }
+
+    let connected = false;
+
+    return {
+        name: 'livekit',
+        room,
+
+        /** Has `connect()` resolved at least once and not been undone by disconnect? */
+        get connected() {
+            return connected;
+        },
+
+        /**
+         * Connect to a LiveKit server.
+         * @param {string} url            LiveKit signaling URL (`wss://...`).
+         * @param {string} token          Room access token (JWT) minted server-side.
+         * @param {object} [connectOpts]  Forwarded to `room.connect(...)`.
+         * @returns {Promise<void>}
+         */
+        async connect(url, token, connectOpts) {
+            if (typeof url !== 'string' || !url) {
+                throw new SfuError('connect(url, token): url required', {
+                    code: 'ZQ_WEBRTC_SFU_BAD_URL',
+                });
+            }
+            if (typeof token !== 'string' || !token) {
+                throw new SfuError('connect(url, token): token required', {
+                    code: 'ZQ_WEBRTC_SFU_BAD_TOKEN',
+                });
+            }
+            try {
+                await room.connect(url, token, connectOpts);
+                connected = true;
+            } catch (cause) {
+                throw new SfuError('livekit-client Room.connect() failed', {
+                    code: 'ZQ_WEBRTC_SFU_CONNECT_FAILED',
+                    cause,
+                });
+            }
+        },
+
+        /** Disconnect from the LiveKit server (best effort). */
+        async disconnect() {
+            if (!connected) return;
+            try {
+                await room.disconnect();
+            } finally {
+                connected = false;
+            }
+        },
+
+        /**
+         * Reserved for the higher-level join flow that maps a LiveKit `Room`
+         * to a zQuery `Room`. Not implemented yet.
+         *
+         * @param {any} _joinOpts
+         * @returns {Promise<never>}
+         */
+        async join(_joinOpts) {
+            throw new SfuError(
+                'livekit adapter.join() not implemented; use connect(url, token) and the underlying livekit-client Room directly',
+                { code: 'ZQ_WEBRTC_SFU_JOIN_UNAVAILABLE' },
+            );
+        },
+    };
+}

package/src/webrtc/sfu/mediasoup.js

@@ -0,0 +1,150 @@
+/**
+ * src/webrtc/sfu/mediasoup.js
+ *
+ * Thin wrapper around the optional `mediasoup-client` peer dependency.
+ *
+ *   - `mediasoup-client` is intentionally NOT bundled. Apps that want it
+ *     must `npm install mediasoup-client` themselves.
+ *   - If it isn't installed, `createMediasoupAdapter()` throws
+ *     `ZQ_WEBRTC_SFU_PEER_MISSING` with an actionable message.
+ *   - The adapter exposes the lower-level mediasoup `Device` plus
+ *     helpers for `load(routerRtpCapabilities)`, `canProduce(kind)`,
+ *     `createSendTransport(params)`, `createRecvTransport(params)`.
+ *   - The higher-level `adapter.join(joinOpts)` requires SFU-specific
+ *     signaling (request → response over a data channel or HTTP). That
+ *     glue lives in the consuming app for now; calling `.join()` throws
+ *     `ZQ_WEBRTC_SFU_JOIN_UNAVAILABLE` so the limitation is explicit.
+ */
+
+import { SfuError } from '../errors.js';
+
+
+/**
+ * Dynamically import `mediasoup-client`. Returns the module's exports.
+ * Throws `SfuError(ZQ_WEBRTC_SFU_PEER_MISSING)` if the package is absent.
+ *
+ * @returns {Promise<any>}
+ */
+async function _importMediasoupClient() {
+    try {
+        // The package name is computed at runtime so static bundlers (Vite,
+        // Rollup, esbuild) don't try to resolve the optional peer dep at
+        // build time and fail the build when it isn't installed.
+        const pkg = ['mediasoup', 'client'].join('-');
+        return await import(/* @vite-ignore */ pkg);
+    } catch (cause) {
+        throw new SfuError(
+            'mediasoup-client peer dependency is not installed; run `npm install mediasoup-client`',
+            { code: 'ZQ_WEBRTC_SFU_PEER_MISSING', cause },
+        );
+    }
+}
+
+
+/**
+ * Build a mediasoup-client adapter.
+ *
+ * @param {object} [opts]
+ * @param {any}    [opts.client]         Pre-imported mediasoup-client module (test hook).
+ * @param {object} [opts.deviceOptions]  Forwarded to `new Device(...)`.
+ * @returns {Promise<import('./index.js').SfuAdapter>}
+ */
+export async function createMediasoupAdapter(opts = {}) {
+    const mod    = opts.client || await _importMediasoupClient();
+    const Device = mod.Device || (mod.default && mod.default.Device);
+    if (typeof Device !== 'function') {
+        throw new SfuError('mediasoup-client module did not expose a Device constructor', {
+            code: 'ZQ_WEBRTC_SFU_BAD_MODULE',
+        });
+    }
+
+    let device;
+    try {
+        device = new Device(opts.deviceOptions || {});
+    } catch (cause) {
+        throw new SfuError('failed to construct mediasoup-client Device', {
+            code: 'ZQ_WEBRTC_SFU_DEVICE_FAILED',
+            cause,
+        });
+    }
+
+    return {
+        name: 'mediasoup',
+        device,
+
+        /** Has `device.load({ routerRtpCapabilities })` been called yet? */
+        get loaded() {
+            return !!device.loaded;
+        },
+
+        /**
+         * Load the device with the SFU router's RTP capabilities.
+         * @param {any} routerRtpCapabilities
+         * @returns {Promise<void>}
+         */
+        async load(routerRtpCapabilities) {
+            if (!routerRtpCapabilities || typeof routerRtpCapabilities !== 'object') {
+                throw new SfuError('load(routerRtpCapabilities): routerRtpCapabilities required', {
+                    code: 'ZQ_WEBRTC_SFU_BAD_RTP_CAPS',
+                });
+            }
+            if (device.loaded) return;
+            try {
+                await device.load({ routerRtpCapabilities });
+            } catch (cause) {
+                throw new SfuError('device.load() failed', {
+                    code: 'ZQ_WEBRTC_SFU_LOAD_FAILED',
+                    cause,
+                });
+            }
+        },
+
+        /**
+         * @param {'audio'|'video'} kind
+         * @returns {boolean}
+         */
+        canProduce(kind) {
+            if (!device.loaded) {
+                throw new SfuError('canProduce(): device not loaded yet', {
+                    code: 'ZQ_WEBRTC_SFU_NOT_LOADED',
+                });
+            }
+            return !!device.canProduce(kind);
+        },
+
+        /** @param {any} params */
+        createSendTransport(params) {
+            if (!device.loaded) {
+                throw new SfuError('createSendTransport(): device not loaded yet', {
+                    code: 'ZQ_WEBRTC_SFU_NOT_LOADED',
+                });
+            }
+            return device.createSendTransport(params);
+        },
+
+        /** @param {any} params */
+        createRecvTransport(params) {
+            if (!device.loaded) {
+                throw new SfuError('createRecvTransport(): device not loaded yet', {
+                    code: 'ZQ_WEBRTC_SFU_NOT_LOADED',
+                });
+            }
+            return device.createRecvTransport(params);
+        },
+
+        /**
+         * Reserved for the higher-level join flow once SFU-specific signaling
+         * is wired through `Room`. Today, callers should use the device and
+         * transport helpers above directly.
+         *
+         * @param {any} _joinOpts
+         * @returns {Promise<never>}
+         */
+        async join(_joinOpts) {
+            throw new SfuError(
+                'mediasoup adapter.join() not implemented; use device + createSendTransport/createRecvTransport with your SFU signaling layer',
+                { code: 'ZQ_WEBRTC_SFU_JOIN_UNAVAILABLE' },
+            );
+        },
+    };
+}