@rapidmx/meet-plugin 0.5.0 → 0.8.0

package/dist/apps/shared/relay/RelayClient.d.ts

@@ -0,0 +1,65 @@
+import type { RelaySocket } from "./relayEnv.js";
+/** The largest binary message an older server accepts - it closes the socket on a larger one (uWS's default limit).
+ * Assumed until the server's `ready` announces a different `maxMessageBytes`. */
+export declare const MAX_MESSAGE_BYTES = 16384;
+/** A `maxMessageBytes` below this is not believed (nothing useful fits), and one above
+ * `MAX_NEGOTIATED_MESSAGE_BYTES` is clamped to it. */
+export declare const MIN_NEGOTIATED_MESSAGE_BYTES = 1024;
+export declare const MAX_NEGOTIATED_MESSAGE_BYTES: number;
+/** The most senders the server lets one socket `want`. */
+export declare const MAX_WANTED_PEERS = 32;
+/** A media send is dropped, not queued, while more than this many bytes are still waiting to leave - the
+ * connection is slower than the media, and queueing would only add latency to the frames that are still fresh. */
+export declare const MAX_BUFFERED_BYTES: number;
+/** Reconnect delay: about a second after the first failure, doubling to a ceiling, jittered so a server restart
+ * doesn't bring every client back in the same instant. */
+export declare const RELAY_BACKOFF_BASE_MS = 1000;
+export declare const RELAY_BACKOFF_MAX_MS = 15000;
+/** How long a socket may take to become `ready` before it is abandoned and retried (a server that accepts the
+ * upgrade but never answers the hello would otherwise hang the tier forever). */
+export declare const RELAY_HANDSHAKE_TIMEOUT_MS = 10000;
+export interface RelayClientOptions {
+    url: string;
+    peerId: string;
+    createSocket: (url: string) => RelaySocket;
+    random: () => number;
+    /** Called with the sender's peer id (as stamped by the server) and the original payload. */
+    onMedia: (peerId: string, payload: Uint8Array) => void;
+}
+export declare class RelayClient {
+    private readonly options;
+    private socket;
+    private closed;
+    private started;
+    private isReady;
+    private messageLimit;
+    private attempt;
+    private wanted;
+    private reconnectTimer;
+    private handshakeTimer;
+    private readonly decoder;
+    constructor(options: RelayClientOptions);
+    /** True once the server has answered the hello on the current socket, i.e. media may be sent. */
+    get ready(): boolean;
+    /** The largest message `sendMedia()` will send: what the server announced in `ready` (validated and clamped), or
+     * `MAX_MESSAGE_BYTES` before that, without one, and again after every disconnect until the next `ready`. The
+     * frame fragmenter sizes its fragments from this. */
+    get maxMessageBytes(): number;
+    /** Opens the socket (and keeps it open, reconnecting as needed) until `close()`. Idempotent. */
+    start(): void;
+    /** Replaces the set of senders to receive from. Sent now if the socket is ready, and again after each reconnect. */
+    setWanted(peers: Iterable<string>): void;
+    /** Sends one media message. Returns whether it was handed to the socket - `false` (dropped) when the socket is
+     * not ready, is backed up, or the message is too large for the server to accept. */
+    sendMedia(bytes: Uint8Array): boolean;
+    /** Closes the socket and stops reconnecting for good. Idempotent. */
+    close(): void;
+    private openSocket;
+    private handleMessage;
+    private handleText;
+    private handleClose;
+    /** Detaches and closes the current socket, if any, so its late events can't reach this client. */
+    private detach;
+    private scheduleReconnect;
+    private sendText;
+}

package/dist/apps/shared/relay/RelayClient.js

@@ -0,0 +1,236 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The WebSocket to the server's media relay - the transport under the last-resort tier of a call, used for a pair of
+ * participants whose WebRTC connection could not be made to work at all.
+ *
+ * ## Wire protocol (fixed by the server)
+ *
+ * - The first message is text JSON `{"op":"hello","v":1,"peer":"<peerId>"}`; the server answers `{"op":"ready","v":1}`,
+ * plus `"maxMessageBytes"` - the largest client-to-server message it accepts - on a current server (absent on an
+ * older one, which accepts `MAX_MESSAGE_BYTES`). Nothing else may be sent before `ready`.
+ * - `{"op":"want","peers":[...]}` REPLACES the set of senders this socket receives from (the server accepts at most
+ * `MAX_WANTED_PEERS`). It has to be re-sent after every reconnect, because the server's set dies with the socket.
+ * - A binary message from the client is an opaque payload of at most `maxMessageBytes`. The server forwards it to
+ * every socket that wants this sender as `[1 byte N][N bytes UTF-8 sender peer id][payload]`, stamping the sender
+ * itself so a peer cannot speak as another.
+ * - Binary messages may be dropped under backpressure and the socket may close at any moment, so this client
+ * reconnects with exponential backoff and treats every media send as best effort.
+ *
+ * Authentication is the `jwt` cookie already in place (see `GuestSignalingClient`), so this client sets no cookie.
+ */
+import { DEFAULT_MESSAGE_BYTES } from "./frames.js";
+/** The largest binary message an older server accepts - it closes the socket on a larger one (uWS's default limit).
+ * Assumed until the server's `ready` announces a different `maxMessageBytes`. */
+export const MAX_MESSAGE_BYTES = DEFAULT_MESSAGE_BYTES;
+/** A `maxMessageBytes` below this is not believed (nothing useful fits), and one above
+ * `MAX_NEGOTIATED_MESSAGE_BYTES` is clamped to it. */
+export const MIN_NEGOTIATED_MESSAGE_BYTES = 1024;
+export const MAX_NEGOTIATED_MESSAGE_BYTES = 1024 * 1024;
+/** The most senders the server lets one socket `want`. */
+export const MAX_WANTED_PEERS = 32;
+/** A media send is dropped, not queued, while more than this many bytes are still waiting to leave - the
+ * connection is slower than the media, and queueing would only add latency to the frames that are still fresh. */
+export const MAX_BUFFERED_BYTES = 256 * 1024;
+/** Reconnect delay: about a second after the first failure, doubling to a ceiling, jittered so a server restart
+ * doesn't bring every client back in the same instant. */
+export const RELAY_BACKOFF_BASE_MS = 1000;
+export const RELAY_BACKOFF_MAX_MS = 15000;
+/** How long a socket may take to become `ready` before it is abandoned and retried (a server that accepts the
+ * upgrade but never answers the hello would otherwise hang the tier forever). */
+export const RELAY_HANDSHAKE_TIMEOUT_MS = 10000;
+const SOCKET_OPEN = 1;
+/** Views `data` as bytes when it is binary (an `ArrayBuffer` or a typed array), else `undefined`. Uses
+ * `Object.prototype.toString` rather than `instanceof` so it works for a buffer from another realm too. */
+function toBytes(data) {
+    if (ArrayBuffer.isView(data)) {
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    }
+    if (Object.prototype.toString.call(data) === "[object ArrayBuffer]") {
+        return new Uint8Array(data);
+    }
+    return undefined;
+}
+export class RelayClient {
+    constructor(options) {
+        this.options = options;
+        this.closed = false;
+        this.started = false;
+        this.isReady = false;
+        this.messageLimit = MAX_MESSAGE_BYTES;
+        this.attempt = 0;
+        this.wanted = [];
+        this.decoder = new TextDecoder();
+    }
+    /** True once the server has answered the hello on the current socket, i.e. media may be sent. */
+    get ready() {
+        return this.isReady;
+    }
+    /** The largest message `sendMedia()` will send: what the server announced in `ready` (validated and clamped), or
+     * `MAX_MESSAGE_BYTES` before that, without one, and again after every disconnect until the next `ready`. The
+     * frame fragmenter sizes its fragments from this. */
+    get maxMessageBytes() {
+        return this.messageLimit;
+    }
+    /** Opens the socket (and keeps it open, reconnecting as needed) until `close()`. Idempotent. */
+    start() {
+        if (this.started || this.closed) {
+            return;
+        }
+        this.started = true;
+        this.openSocket();
+    }
+    /** Replaces the set of senders to receive from. Sent now if the socket is ready, and again after each reconnect. */
+    setWanted(peers) {
+        this.wanted = [...peers].slice(0, MAX_WANTED_PEERS);
+        if (this.isReady) {
+            this.sendText({ op: "want", peers: this.wanted });
+        }
+    }
+    /** Sends one media message. Returns whether it was handed to the socket - `false` (dropped) when the socket is
+     * not ready, is backed up, or the message is too large for the server to accept. */
+    sendMedia(bytes) {
+        const socket = this.socket;
+        if (!socket ||
+            !this.isReady ||
+            socket.readyState !== SOCKET_OPEN ||
+            socket.bufferedAmount > MAX_BUFFERED_BYTES ||
+            bytes.length > this.messageLimit) {
+            return false;
+        }
+        try {
+            socket.send(bytes);
+            return true;
+        }
+        catch {
+            // The close that follows a dead socket reconnects.
+            return false;
+        }
+    }
+    /** Closes the socket and stops reconnecting for good. Idempotent. */
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.isReady = false;
+        this.messageLimit = MAX_MESSAGE_BYTES;
+        clearTimeout(this.reconnectTimer);
+        clearTimeout(this.handshakeTimer);
+        this.reconnectTimer = this.handshakeTimer = undefined;
+        this.detach();
+    }
+    openSocket() {
+        let socket;
+        try {
+            socket = this.options.createSocket(this.options.url);
+        }
+        catch {
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        socket.binaryType = "arraybuffer";
+        socket.onopen = () => this.sendText({ op: "hello", v: 1, peer: this.options.peerId });
+        socket.onmessage = (event) => this.handleMessage(socket, event.data);
+        socket.onclose = () => this.handleClose(socket);
+        socket.onerror = () => undefined;
+        this.handshakeTimer = setTimeout(() => {
+            this.handshakeTimer = undefined;
+            // Give up on this attempt as if the socket had closed; the close event of a socket we abandon is ignored.
+            this.handleClose(socket);
+        }, RELAY_HANDSHAKE_TIMEOUT_MS);
+    }
+    handleMessage(socket, data) {
+        if (socket !== this.socket) {
+            return;
+        }
+        if (typeof data === "string") {
+            this.handleText(data);
+            return;
+        }
+        const bytes = toBytes(data);
+        if (!bytes || !this.isReady) {
+            return;
+        }
+        const idLength = bytes.length > 0 ? bytes[0] : 0;
+        if (idLength === 0 || bytes.length < 1 + idLength) {
+            return;
+        }
+        // A malformed id decodes to replacement characters, which match no receiver, so it needs no separate check.
+        const peerId = this.decoder.decode(bytes.subarray(1, 1 + idLength));
+        this.options.onMedia(peerId, bytes.subarray(1 + idLength));
+    }
+    handleText(text) {
+        let message;
+        try {
+            message = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        if (!message || typeof message !== "object" || message.op !== "ready" || this.isReady) {
+            return;
+        }
+        this.isReady = true;
+        this.attempt = 0;
+        const announced = message.maxMessageBytes;
+        if (typeof announced === "number" && Number.isInteger(announced) && announced >= MIN_NEGOTIATED_MESSAGE_BYTES) {
+            this.messageLimit = Math.min(announced, MAX_NEGOTIATED_MESSAGE_BYTES);
+        }
+        clearTimeout(this.handshakeTimer);
+        this.handshakeTimer = undefined;
+        // The server's wanted set is per socket, so it starts empty on every (re)connect.
+        this.sendText({ op: "want", peers: this.wanted });
+    }
+    handleClose(socket) {
+        if (socket !== this.socket) {
+            return;
+        }
+        this.isReady = false;
+        // The next server might be a different one (a rolling upgrade), so the limit is learned afresh.
+        this.messageLimit = MAX_MESSAGE_BYTES;
+        clearTimeout(this.handshakeTimer);
+        this.handshakeTimer = undefined;
+        this.detach();
+        this.scheduleReconnect();
+    }
+    /** Detaches and closes the current socket, if any, so its late events can't reach this client. */
+    detach() {
+        const socket = this.socket;
+        this.socket = undefined;
+        if (!socket) {
+            return;
+        }
+        socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
+        try {
+            socket.close(1000, "closing");
+        }
+        catch {
+            // Already gone.
+        }
+    }
+    scheduleReconnect() {
+        const ceiling = Math.min(RELAY_BACKOFF_MAX_MS, RELAY_BACKOFF_BASE_MS * 2 ** Math.min(this.attempt, 10));
+        const delay = ceiling / 2 + (this.options.random() * ceiling) / 2;
+        this.attempt += 1;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            this.openSocket();
+        }, delay);
+    }
+    sendText(message) {
+        const socket = this.socket;
+        if (!socket || socket.readyState !== SOCKET_OPEN) {
+            return;
+        }
+        try {
+            socket.send(JSON.stringify(message));
+        }
+        catch {
+            // The close that follows a dead socket reconnects and re-sends.
+        }
+    }
+}

package/dist/apps/shared/relay/RelayReceiver.d.ts

@@ -0,0 +1,21 @@
+import type { AudioContextLike, RelayEnv } from "./relayEnv.js";
+/**
+ * One remote participant as seen through the relay: reassembles their fragments, decodes them, and exposes the result
+ * as an ordinary `MediaStream` (`stream`) so the UI plays a relayed peer exactly like a WebRTC one.
+ *
+ * The stream exists, with both tracks, from construction - silent and blank until media arrives - so the caller can
+ * attach it to an element straight away and never has to swap a stream in later. Audio goes through a
+ * `MediaStreamAudioDestinationNode` on the shared playback context; video is drawn to a canvas and captured.
+ */
+export declare class RelayReceiver {
+    readonly stream: MediaStream;
+    private readonly audioFrames;
+    private readonly videoFrames;
+    private readonly audio;
+    private readonly video;
+    constructor(env: RelayEnv, playbackContext: AudioContextLike);
+    /** Handles one relayed payload from this sender (a media fragment). Anything malformed is ignored. */
+    handleMedia(payload: Uint8Array): void;
+    /** Releases the decoders and ends the stream's tracks. */
+    close(): void;
+}

package/dist/apps/shared/relay/RelayReceiver.js

@@ -0,0 +1,59 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { AudioPlayer } from "./AudioPlayer.js";
+import { decodeFragment, FrameReassembler, KIND_AUDIO } from "./frames.js";
+import { VideoPlayer } from "./VideoPlayer.js";
+/** The canvas is sized to the first decoded picture; until then it is this size. */
+const INITIAL_CANVAS_WIDTH = 320;
+const INITIAL_CANVAS_HEIGHT = 240;
+/** The frame rate `captureStream()` samples the canvas at, matching what the sender produces. */
+const CAPTURE_FPS = 15;
+/**
+ * One remote participant as seen through the relay: reassembles their fragments, decodes them, and exposes the result
+ * as an ordinary `MediaStream` (`stream`) so the UI plays a relayed peer exactly like a WebRTC one.
+ *
+ * The stream exists, with both tracks, from construction - silent and blank until media arrives - so the caller can
+ * attach it to an element straight away and never has to swap a stream in later. Audio goes through a
+ * `MediaStreamAudioDestinationNode` on the shared playback context; video is drawn to a canvas and captured.
+ */
+export class RelayReceiver {
+    constructor(env, playbackContext) {
+        this.audioFrames = new FrameReassembler();
+        this.videoFrames = new FrameReassembler();
+        const destination = playbackContext.createMediaStreamDestination();
+        this.audio = new AudioPlayer(env, playbackContext, destination);
+        const canvas = env.createCanvas();
+        canvas.width = INITIAL_CANVAS_WIDTH;
+        canvas.height = INITIAL_CANVAS_HEIGHT;
+        const context = canvas.getContext("2d");
+        this.video = context ? new VideoPlayer(env, canvas, context) : undefined;
+        this.stream = env.createMediaStream([...destination.stream.getAudioTracks(), ...canvas.captureStream(CAPTURE_FPS).getVideoTracks()]);
+    }
+    /** Handles one relayed payload from this sender (a media fragment). Anything malformed is ignored. */
+    handleMedia(payload) {
+        const fragment = decodeFragment(payload);
+        if (!fragment) {
+            return;
+        }
+        const frame = (fragment.kind === KIND_AUDIO ? this.audioFrames : this.videoFrames).push(fragment);
+        if (!frame) {
+            return;
+        }
+        if (frame.kind === KIND_AUDIO) {
+            this.audio.push(frame);
+        }
+        else {
+            this.video?.push(frame);
+        }
+    }
+    /** Releases the decoders and ends the stream's tracks. */
+    close() {
+        this.audio.close();
+        this.video?.close();
+        for (const track of this.stream.getTracks()) {
+            track.stop();
+        }
+    }
+}

package/dist/apps/shared/relay/RelaySender.d.ts

@@ -0,0 +1,34 @@
+import type { RelayEnv } from "./relayEnv.js";
+import type { PublishFrame } from "./senderCommon.js";
+/** Numbers and fragments the frames of one sender. The counters belong to the transport rather than to a capture
+ * session, so stopping and restarting sending never resets `seq` - a receiver still holding the old value would
+ * otherwise treat the restarted stream as older than what it has already seen. */
+export declare class FramePublisher {
+    private readonly send;
+    private readonly maxMessageBytes;
+    private readonly seqs;
+    /** `send` returns whether one message was accepted by the socket. */
+    /** `maxMessageBytes` is the largest message the socket may send right now (it changes when the server's `ready`
+     * announces a limit), so it is read for every frame rather than fixed at construction. */
+    constructor(send: (message: Uint8Array) => boolean, maxMessageBytes?: () => number);
+    /** Fragments and sends one frame, stopping at the first fragment the socket refuses (the rest could not be
+     * used without it). Returns whether the whole frame went out. */
+    publish: PublishFrame;
+}
+export interface RelaySenderOptions {
+    env: RelayEnv;
+    send: (message: Uint8Array) => boolean;
+    canSend: () => boolean;
+    /** The socket's current message limit; defaults to what an older server accepts. */
+    maxMessageBytes?: () => number;
+}
+/** The publishing half of the relay: the two capture paths plus the frame numbering they share. */
+export declare class RelaySender {
+    private readonly audio;
+    private readonly video;
+    constructor(options: RelaySenderOptions);
+    /** Starts or stops encoding whatever tracks are set. Stopping releases the encoders and audio nodes. */
+    setActive(active: boolean): void;
+    /** `null` sends nothing for that kind. Safe before or after `setActive`. */
+    setTrack(kind: "audio" | "video", track: MediaStreamTrack | null): void;
+}

package/dist/apps/shared/relay/RelaySender.js

@@ -0,0 +1,54 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { AudioSender } from "./AudioSender.js";
+import { DEFAULT_MESSAGE_BYTES, fragmentFrame, KIND_AUDIO, KIND_VIDEO } from "./frames.js";
+import { VideoSender } from "./VideoSender.js";
+const SEQ_MODULUS = 0x10000;
+/** Numbers and fragments the frames of one sender. The counters belong to the transport rather than to a capture
+ * session, so stopping and restarting sending never resets `seq` - a receiver still holding the old value would
+ * otherwise treat the restarted stream as older than what it has already seen. */
+export class FramePublisher {
+    /** `send` returns whether one message was accepted by the socket. */
+    /** `maxMessageBytes` is the largest message the socket may send right now (it changes when the server's `ready`
+     * announces a limit), so it is read for every frame rather than fixed at construction. */
+    constructor(send, maxMessageBytes = () => DEFAULT_MESSAGE_BYTES) {
+        this.send = send;
+        this.maxMessageBytes = maxMessageBytes;
+        this.seqs = { [KIND_AUDIO]: 0, [KIND_VIDEO]: 0 };
+        /** Fragments and sends one frame, stopping at the first fragment the socket refuses (the rest could not be
+         * used without it). Returns whether the whole frame went out. */
+        this.publish = (kind, keyFrame, data, timestampMs) => {
+            const seq = this.seqs[kind];
+            this.seqs[kind] = (seq + 1) % SEQ_MODULUS;
+            const fragments = fragmentFrame(kind, keyFrame, seq, timestampMs, data, this.maxMessageBytes());
+            if (fragments.length === 0) {
+                return false;
+            }
+            for (const fragment of fragments) {
+                if (!this.send(fragment)) {
+                    return false;
+                }
+            }
+            return true;
+        };
+    }
+}
+/** The publishing half of the relay: the two capture paths plus the frame numbering they share. */
+export class RelaySender {
+    constructor(options) {
+        const deps = { env: options.env, publish: new FramePublisher(options.send, options.maxMessageBytes).publish, canSend: options.canSend };
+        this.audio = new AudioSender(deps);
+        this.video = new VideoSender(deps);
+    }
+    /** Starts or stops encoding whatever tracks are set. Stopping releases the encoders and audio nodes. */
+    setActive(active) {
+        this.audio.setActive(active);
+        this.video.setActive(active);
+    }
+    /** `null` sends nothing for that kind. Safe before or after `setActive`. */
+    setTrack(kind, track) {
+        (kind === "audio" ? this.audio : this.video).setTrack(track);
+    }
+}

package/dist/apps/shared/relay/RelayTransport.d.ts

@@ -0,0 +1,38 @@
+import { type RelayEnv } from "./relayEnv.js";
+export interface RelayTransport {
+    /** false when this browser lacks WebSocket, AudioEncoder/AudioDecoder/VideoEncoder/VideoDecoder, VideoFrame,
+     * AudioContext or canvas.captureStream - the mesh then never falls back to the relay. */
+    readonly supported: boolean;
+    /** Start receiving `peerId`'s media (opens/keeps the socket, adds to `want`). `onStream` gets a MediaStream that
+     * plays that peer (one audio + one video track). Called at most once per stream creation; calling receiveFrom
+     * again for the same peer is a no-op. */
+    receiveFrom(peerId: string, onStream: (stream: MediaStream) => void): void;
+    stopReceivingFrom(peerId: string): void;
+    /** Start/stop publishing the local tracks (encode + send). Only encodes while active; stopping releases the
+     * encoders and audio nodes. */
+    setSending(active: boolean): void;
+    /** Same semantics as `MeshConnectionManager.setLocalTrack`: null = send nothing for that kind. Safe to call
+     * before or after `setSending`. */
+    setLocalTrack(kind: "audio" | "video", track: MediaStreamTrack | null): void;
+    /** Closes the socket, all coders, streams and timers. Idempotent. */
+    close(): void;
+}
+export interface RelayTransportOptions {
+    meetingUid: string;
+    /** This participant's peer id on the meeting's signaling channel - the id the server stamps on what it sends. */
+    peerId: string;
+    /** Overrides the socket URL (default: `relayUrl(meetingUid)`). */
+    url?: string;
+    /** Overrides every browser API the relay uses (default: `detectRelayEnv()`), so a test can drive it with fakes. */
+    env?: RelayEnv;
+}
+/** The relay WebSocket's URL for a meeting: this deployment's origin (the API origin when the UI is served from a
+ * different one, else the page's own), `http` becoming `ws` - the same derivation `pushUrl()` uses for `/push`.
+ * `undefined` when there is no origin at all (not running in a browser). */
+export declare function relayUrl(meetingUid: string): string | undefined;
+/**
+ * Creates the relay transport for one meeting. Returns an inert transport (`supported: false`) when the browser lacks
+ * something the relay needs, so the caller can simply check `supported` once and never fall back to it.
+ * No socket is opened until the first `receiveFrom()` or `setSending(true)`.
+ */
+export declare function createRelayTransport(options: RelayTransportOptions): RelayTransport;

package/dist/apps/shared/relay/RelayTransport.js

@@ -0,0 +1,142 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The last-resort media tier of a call: when two participants' WebRTC connection cannot be made at all (typically a
+ * network that blocks UDP and TURN alike), their audio and video travel over a WebSocket to the server, which fans
+ * each participant's frames out to whoever asked for them. This module is the facade the mesh manager talks to; the
+ * pieces behind it are:
+ *
+ * - `RelayClient` - the socket: hello/ready/want, reconnection, dropping media it cannot send promptly.
+ * - `frames` - the fragment format inside each WebSocket message and the reassembly of it.
+ * - `RelaySender` (`AudioSender`, `VideoSender`) - capture and encode the local tracks (Opus and VP8 via WebCodecs).
+ * - `RelayReceiver` (`AudioPlayer`, `VideoPlayer`) - decode a remote participant back into a `MediaStream`.
+ *
+ * There is one transport (one socket) per meeting, however many peers use it, and the codecs are fixed - there is no
+ * negotiation, because both ends are this same code.
+ */
+import { apiOrigin } from "@rapidmx/react-shared/util/api.js";
+import { PLAYBACK_SAMPLE_RATE } from "./AudioPlayer.js";
+import { resumeAudioContext } from "./audioResume.js";
+import { RelayClient } from "./RelayClient.js";
+import { detectRelayEnv } from "./relayEnv.js";
+import { RelayReceiver } from "./RelayReceiver.js";
+import { RelaySender } from "./RelaySender.js";
+/** The relay WebSocket's URL for a meeting: this deployment's origin (the API origin when the UI is served from a
+ * different one, else the page's own), `http` becoming `ws` - the same derivation `pushUrl()` uses for `/push`.
+ * `undefined` when there is no origin at all (not running in a browser). */
+export function relayUrl(meetingUid) {
+    const origin = apiOrigin() || (typeof window !== "undefined" ? window.location.origin : "");
+    return origin ? `${origin.replace(/^http/i, "ws")}/api/mail/video-meetings/relay/${encodeURIComponent(meetingUid)}` : undefined;
+}
+/** What `createRelayTransport()` returns on a browser that cannot run the relay: every call is a no-op. */
+const UNSUPPORTED_TRANSPORT = {
+    supported: false,
+    receiveFrom: () => undefined,
+    stopReceivingFrom: () => undefined,
+    setSending: () => undefined,
+    setLocalTrack: () => undefined,
+    close: () => undefined,
+};
+class WebSocketRelayTransport {
+    constructor(env, url, peerId) {
+        this.env = env;
+        this.supported = true;
+        this.receivers = new Map();
+        this.closed = false;
+        this.client = new RelayClient({
+            url,
+            peerId,
+            createSocket: (target) => env.createSocket(target),
+            random: () => env.random(),
+            onMedia: (sender, payload) => this.receivers.get(sender)?.handleMedia(payload),
+        });
+        this.sender = new RelaySender({
+            env,
+            send: (message) => this.client.sendMedia(message),
+            canSend: () => this.client.ready,
+            maxMessageBytes: () => this.client.maxMessageBytes,
+        });
+    }
+    receiveFrom(peerId, onStream) {
+        if (this.closed || this.receivers.has(peerId)) {
+            return;
+        }
+        const receiver = this.createReceiver();
+        if (!receiver) {
+            return;
+        }
+        this.receivers.set(peerId, receiver);
+        this.client.start();
+        this.client.setWanted(this.receivers.keys());
+        onStream(receiver.stream);
+    }
+    stopReceivingFrom(peerId) {
+        const receiver = this.receivers.get(peerId);
+        if (!receiver) {
+            return;
+        }
+        this.receivers.delete(peerId);
+        receiver.close();
+        this.client.setWanted(this.receivers.keys());
+    }
+    setSending(active) {
+        if (this.closed) {
+            return;
+        }
+        if (active) {
+            this.client.start();
+        }
+        this.sender.setActive(active);
+    }
+    setLocalTrack(kind, track) {
+        if (!this.closed) {
+            this.sender.setTrack(kind, track);
+        }
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.sender.setActive(false);
+        for (const receiver of this.receivers.values()) {
+            receiver.close();
+        }
+        this.receivers.clear();
+        this.client.close();
+        this.stopResume?.();
+        // `close()` rejects for a context that is already closed; nothing to do about it.
+        this.playback?.close().catch(() => undefined);
+        this.playback = undefined;
+    }
+    /** A receiver on the shared playback context, or `undefined` if this browser will not build one (the peer then
+     * simply has no relayed media). */
+    createReceiver() {
+        try {
+            if (!this.playback) {
+                this.playback = this.env.createAudioContext(PLAYBACK_SAMPLE_RATE);
+                // Nothing the user just did created this context, so it may start suspended - see `resumeAudioContext`.
+                this.stopResume = resumeAudioContext(this.playback, this.env.document);
+            }
+            return new RelayReceiver(this.env, this.playback);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/**
+ * Creates the relay transport for one meeting. Returns an inert transport (`supported: false`) when the browser lacks
+ * something the relay needs, so the caller can simply check `supported` once and never fall back to it.
+ * No socket is opened until the first `receiveFrom()` or `setSending(true)`.
+ */
+export function createRelayTransport(options) {
+    const env = options.env ?? detectRelayEnv();
+    const url = options.url ?? relayUrl(options.meetingUid);
+    if (!env || !url) {
+        return UNSUPPORTED_TRANSPORT;
+    }
+    return new WebSocketRelayTransport(env, url, options.peerId);
+}