@rapidmx/meet-plugin 0.6.0 → 0.8.0

package/dist/apps/shared/webrtc/MeshConnectionManager.js

@@ -61,6 +61,27 @@
  * `presenter-release`) once it observes the winning claim. See `handlePresenterClaim()`.
  *
  * Sharing a screen is `setLocalTrack("video", screenTrack)`; stopping is `setLocalTrack("video", cameraTrack)`.
+ *
+ * ## Three media paths, tried in order
+ *
+ * Each pair of participants reaches for the best path that works, and `MeshParticipant.transport` says which one it
+ * got:
+ *
+ * 1. **Direct peer-to-peer** (`"p2p"`). The `RTCPeerConnection` is given the STUN servers and the TURN server
+ * together, and ICE ranks a direct pair above a relayed one, so this is what a pair gets whenever it can.
+ * 2. **Relayed through the TURN server** (`"turn"`). The same connection, on the relay candidate ICE falls back to
+ * when the direct pairs fail - a participant behind a symmetric NAT or a firewall that blocks direct UDP. Which of
+ * the two ICE picked is read from the selected candidate pair once connected (`RTCPeerConnectionLike.connectionType()`).
+ * 3. **Proxied by this server over a WebSocket** (`"websocket"`, `apps/shared/relay/`). For a participant whose
+ * network lets nothing but ordinary HTTPS out, neither of the above ever connects. A pair whose connection has not
+ * come up within `connectTimeoutMs`, has failed, or has stayed `disconnected` for `disconnectedGraceMs` gives up
+ * on WebRTC and switches to it, telling the other side with a `relay-fallback` message so both switch even when
+ * only one of them noticed. Nothing is renegotiated - the pair simply stops using the `RTCPeerConnection` - and the
+ * relay's stream replaces the one WebRTC would have filled (a `remote-stream` event again). When the relay is
+ * unavailable (turned off by the operator, or a browser without WebCodecs) the pair is marked `"failed"` and stays
+ * in the roster, rather than the participant vanishing with no explanation as it used to.
+ *
+ * A pair never moves back up: once on the relay it stays there for the rest of the call.
  */
 import { REACTION_EMOJIS, } from "./types.js";
 /** The lexicographically smaller uid is always the offerer for that pair - see this module's doc comment. */
@@ -71,6 +92,12 @@ export function isOfferer(selfId, peerId) {
  * misbehaving participant could make this hold for peers that never materialize. */
 const MAX_ORPHAN_PEERS = 32;
 const MAX_ORPHAN_CANDIDATES = 64;
+/** How long a connection may stay in `connecting` before the pair gives up on WebRTC. ICE with an unreachable TURN
+ * server can take the better part of a minute to report `failed`; a person waiting on a call will not. It is still long
+ * enough for a slow TURN allocation and a few round trips of signaling. */
+export const DEFAULT_CONNECT_TIMEOUT_MS = 15000;
+/** How long a connection may stay `disconnected` (ICE lost the path but may still recover) before giving up on it. */
+export const DEFAULT_DISCONNECTED_GRACE_MS = 8000;
 export class MeshConnectionManager {
     constructor(options) {
         this.options = options;
@@ -87,6 +114,8 @@ export class MeshConnectionManager {
             handRaised: false,
             ...options.localState,
         };
+        options.relay?.setLocalTrack("audio", this.localTracks.audio);
+        options.relay?.setLocalTrack("video", this.localTracks.video);
     }
     get participants() {
         return [...this.peers.values()].map((peer) => toParticipant(peer));
@@ -122,11 +151,13 @@ export class MeshConnectionManager {
         this.unsubscribe?.();
         this.unsubscribe = undefined;
         for (const peer of this.peers.values()) {
+            this.clearTimers(peer);
             peer.pc.close();
         }
         this.peers.clear();
         this.orphanCandidates.clear();
         this.listeners.clear();
+        this.options.relay?.close();
     }
     /** Sets the track sent as `kind` (`null` to send nothing) on every connection, now and for every peer that
      * joins later - see this module's doc comment. */
@@ -135,6 +166,7 @@ export class MeshConnectionManager {
         for (const peer of this.peers.values()) {
             void peer.senders[kind]?.replaceTrack(track);
         }
+        this.options.relay?.setLocalTrack(kind, track);
     }
     /** Updates what this participant announces (`audioOn`/`videoOn`/`handRaised`) and tells everyone if anything
      * actually changed. Before `start()` it only records the state, which `hello` then carries. */
@@ -231,6 +263,9 @@ export class MeshConnectionManager {
             case "reaction":
                 this.handleReaction(message);
                 return;
+            case "relay-fallback":
+                this.handleRelayFallback(message.from);
+                return;
         }
     }
     handleHello(message) {
@@ -288,8 +323,13 @@ export class MeshConnectionManager {
         if (!peer) {
             return;
         }
+        this.clearTimers(peer);
         peer.pc.close();
         this.peers.delete(uid);
+        if (peer.transport === "websocket") {
+            this.options.relay?.stopReceivingFrom(uid);
+            this.syncRelaySending();
+        }
         this.emit({ type: "participant-left", uid });
         if (this.currentPresenterUid === uid) {
             this.currentPresenterUid = undefined;
@@ -312,6 +352,9 @@ export class MeshConnectionManager {
             remoteStream: (this.options.createMediaStream ?? (() => new MediaStream()))(),
             remoteDescriptionSet: false,
             pendingCandidates: this.orphanCandidates.get(uid) ?? [],
+            transport: "connecting",
+            connectTimer: undefined,
+            disconnectTimer: undefined,
         };
         this.orphanCandidates.delete(uid);
         this.peers.set(uid, peer);
@@ -326,13 +369,101 @@ export class MeshConnectionManager {
             }
             this.emit({ type: "remote-stream", uid, stream: peer.remoteStream });
         };
-        pc.onconnectionstatechange = () => {
-            if (pc.connectionState === "failed" || pc.connectionState === "closed") {
-                this.handleBye(uid);
-            }
-        };
+        pc.onconnectionstatechange = () => this.handleConnectionState(peer);
+        // Cleared the moment the connection comes up, so this only ever fires for a pair still waiting on WebRTC.
+        peer.connectTimer = setTimeout(() => this.fallBack(peer), this.options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS);
         return peer;
     }
+    /** Reacts to the peer connection's state: notes which path a connected pair got, and gives up on WebRTC for a
+     * pair that failed or stays disconnected - see `fallBack()`. Ignores a pair that already left WebRTC. */
+    handleConnectionState(peer) {
+        if (peer.transport === "websocket" || this.peers.get(peer.uid) !== peer) {
+            return;
+        }
+        switch (peer.pc.connectionState) {
+            case "connected":
+                this.clearTimers(peer);
+                void this.detectTransport(peer);
+                return;
+            case "disconnected":
+                // ICE often recovers from this on its own, so it is only given up on after a grace period.
+                peer.disconnectTimer ?? (peer.disconnectTimer = setTimeout(() => this.fallBack(peer), this.options.disconnectedGraceMs ?? DEFAULT_DISCONNECTED_GRACE_MS));
+                return;
+            case "failed":
+                this.fallBack(peer);
+                return;
+            case "closed":
+                this.handleBye(peer.uid);
+                return;
+        }
+    }
+    /** Records whether a connected pair is direct or relayed through TURN, from the candidate pair ICE selected. */
+    async detectTransport(peer) {
+        let type;
+        try {
+            type = await peer.pc.connectionType();
+        }
+        catch {
+            type = "unknown";
+        }
+        // The pair may have moved on (fallen back, left, or dropped again) while the stats were being read.
+        if (peer.transport !== "websocket" && this.peers.get(peer.uid) === peer && peer.pc.connectionState === "connected") {
+            this.setTransport(peer, type === "turn" ? "turn" : "p2p");
+        }
+    }
+    setTransport(peer, transport) {
+        if (peer.transport !== transport) {
+            peer.transport = transport;
+            this.emit({ type: "participant-updated", participant: toParticipant(peer) });
+        }
+    }
+    clearTimers(peer) {
+        clearTimeout(peer.connectTimer);
+        clearTimeout(peer.disconnectTimer);
+        peer.connectTimer = undefined;
+        peer.disconnectTimer = undefined;
+    }
+    /**
+     * Gives up on WebRTC for `peer` and moves the pair to the WebSocket relay (the third path - see this module's doc
+     * comment), or marks it `"failed"` when there is no relay to move to. `notify` tells the other side, which may not
+     * have noticed yet; a pair told by the other side does not tell it back.
+     */
+    fallBack(peer, notify = true) {
+        if (peer.transport === "websocket" || this.peers.get(peer.uid) !== peer) {
+            return;
+        }
+        this.clearTimers(peer);
+        const relay = this.options.relay;
+        if (!relay?.supported) {
+            this.setTransport(peer, "failed");
+            return;
+        }
+        // Stop listening to the dead connection before closing it, so closing it cannot be mistaken for the peer leaving.
+        peer.pc.onconnectionstatechange = null;
+        peer.pc.onicecandidate = null;
+        peer.pc.ontrack = null;
+        peer.pc.close();
+        peer.transport = "websocket";
+        relay.receiveFrom(peer.uid, (stream) => {
+            peer.remoteStream = stream;
+            this.emit({ type: "remote-stream", uid: peer.uid, stream });
+        });
+        this.syncRelaySending();
+        this.emit({ type: "participant-updated", participant: toParticipant(peer) });
+        if (notify) {
+            this.send({ kind: "relay-fallback", to: peer.uid });
+        }
+    }
+    handleRelayFallback(from) {
+        const peer = this.peers.get(from);
+        if (peer) {
+            this.fallBack(peer, false);
+        }
+    }
+    /** The relay only encodes and uploads the local media while at least one pair is actually using it. */
+    syncRelaySending() {
+        this.options.relay?.setSending([...this.peers.values()].some((peer) => peer.transport === "websocket"));
+    }
     async initiateOffer(peer) {
         const offer = await peer.pc.createOffer();
         await peer.pc.setLocalDescription(offer);
@@ -438,7 +569,7 @@ export class MeshConnectionManager {
     }
 }
 function toParticipant(peer) {
-    return { uid: peer.uid, name: peer.name, audioOn: peer.audioOn, videoOn: peer.videoOn, handRaised: peer.handRaised };
+    return { uid: peer.uid, name: peer.name, audioOn: peer.audioOn, videoOn: peer.videoOn, handRaised: peer.handRaised, transport: peer.transport };
 }
 function sameState(a, b) {
     return a.audioOn === b.audioOn && a.videoOn === b.videoOn && a.handRaised === b.handRaised;

package/dist/apps/shared/webrtc/realPeerConnection.d.ts

@@ -4,4 +4,11 @@
  * module scope, so importing this file is safe during this plugin's page SSR, where `RTCPeerConnection` does not
  * exist at all - it would only throw if actually *called* outside a browser. */
 import type { RTCPeerConnectionFactory } from "./types.js";
+/**
+ * Whether the pair ICE settled on goes through a TURN relay. The selected pair is found the standard way (the
+ * `transport` report's `selectedCandidatePairId`) and, for a browser that does not fill that in, as the succeeded and
+ * nominated `candidate-pair`. A relay on *either* end means the media passes through a TURN server, so it counts as
+ * `"turn"`; `"unknown"` when no pair is reported at all.
+ */
+export declare function selectedConnectionType(pc: Pick<RTCPeerConnection, "getStats">): Promise<"p2p" | "turn" | "unknown">;
 export declare const createBrowserPeerConnection: RTCPeerConnectionFactory;

package/dist/apps/shared/webrtc/realPeerConnection.js

@@ -1,3 +1,22 @@
+/**
+ * Whether the pair ICE settled on goes through a TURN relay. The selected pair is found the standard way (the
+ * `transport` report's `selectedCandidatePairId`) and, for a browser that does not fill that in, as the succeeded and
+ * nominated `candidate-pair`. A relay on *either* end means the media passes through a TURN server, so it counts as
+ * `"turn"`; `"unknown"` when no pair is reported at all.
+ */
+export async function selectedConnectionType(pc) {
+    const reports = new Map();
+    (await pc.getStats()).forEach((report) => reports.set(String(report.id), report));
+    const transport = [...reports.values()].find((report) => report.type === "transport" && report.selectedCandidatePairId);
+    const pair = (transport ? reports.get(String(transport.selectedCandidatePairId)) : undefined) ??
+        [...reports.values()].find((report) => report.type === "candidate-pair" && (report.selected || (report.nominated && report.state === "succeeded")));
+    if (!pair) {
+        return "unknown";
+    }
+    const local = reports.get(String(pair.localCandidateId));
+    const remote = reports.get(String(pair.remoteCandidateId));
+    return local?.candidateType === "relay" || remote?.candidateType === "relay" ? "turn" : "p2p";
+}
 export const createBrowserPeerConnection = (config) => {
     const pc = new RTCPeerConnection(config);
     const like = {
@@ -22,6 +41,7 @@ export const createBrowserPeerConnection = (config) => {
         setRemoteDescription: (description) => pc.setRemoteDescription(description),
         addIceCandidate: (candidate) => pc.addIceCandidate(candidate),
         close: () => pc.close(),
+        connectionType: () => selectedConnectionType(pc),
         onicecandidate: null,
         ontrack: null,
         onconnectionstatechange: null,

package/dist/apps/shared/webrtc/types.d.ts

@@ -28,7 +28,7 @@ export declare const REACTION_EMOJIS: readonly ["👍", "👏", "❤️", "🎉"
  */
 export interface SignalMessage {
     type: "video-meeting-signal";
-    kind: "hello" | "bye" | "offer" | "answer" | "ice-candidate" | "presenter-claim" | "presenter-release" | "state" | "reaction";
+    kind: "hello" | "bye" | "offer" | "answer" | "ice-candidate" | "presenter-claim" | "presenter-release" | "state" | "reaction" | "relay-fallback";
     /** The sender's authenticated uid - the real caller's own uid when `join()` returned `authenticated: true`, else
      * the `guest:<random>` uid `BaseVideoMeetingRoute.join()` minted. The server refuses a published message whose
      * `from` isn't the authenticated caller's uid (it stops one participant speaking as another), so this must be
@@ -39,7 +39,7 @@ export interface SignalMessage {
      * ignored, so it can't name someone else's tab. Absent from a sender that predates it (the participant is then
      * identified by `from`). */
     peer?: string;
-    /** Set only on a point-to-point message (`offer`/`answer`/`ice-candidate`). */
+    /** Set only on a point-to-point message (`offer`/`answer`/`ice-candidate`/`relay-fallback`). */
     to?: string;
     /** `hello` only - the display name the sender chose in the lobby. */
     name?: string;
@@ -99,6 +99,31 @@ export interface RTCPeerConnectionLike {
     }) => void) | null;
     onconnectionstatechange: (() => void) | null;
     connectionState: string;
+    /** Which path the connected pair is using - read from the selected candidate pair once `connectionState` is
+     * `connected`. `"unknown"` when the browser does not report one (treated as direct by the caller). */
+    connectionType(): Promise<"p2p" | "turn" | "unknown">;
+}
+/** Which of the three media paths a participant's audio and video currently take, in the order they are tried:
+ *
+ * - `"p2p"`: a direct peer-to-peer WebRTC connection, the preferred path.
+ * - `"turn"`: still WebRTC, but relayed through the TURN server, for a participant a direct path cannot reach.
+ * - `"websocket"`: not WebRTC at all - encoded frames proxied by this server over a WebSocket (see
+ * `apps/shared/relay/`), the last resort when neither of the above connects.
+ * - `"connecting"`: no path established yet. `"failed"`: every path this browser can try has failed. */
+export type MediaTransport = "connecting" | "p2p" | "turn" | "websocket" | "failed";
+/** What `MeshConnectionManager` needs from the WebSocket media relay (`apps/shared/relay/RelayTransport.ts` implements
+ * it) - declared here so the mesh, and its tests, depend on the shape alone. */
+export interface RelayTransportLike {
+    /** `false` when this browser cannot do it (no WebSocket, no WebCodecs) - the mesh then never falls back to it. */
+    readonly supported: boolean;
+    /** Starts receiving `peerId`'s media. `onStream` is given the `MediaStream` that plays it. */
+    receiveFrom(peerId: string, onStream: (stream: MediaStream) => void): void;
+    stopReceivingFrom(peerId: string): void;
+    /** Starts or stops publishing the local tracks to the relay. */
+    setSending(active: boolean): void;
+    /** Same as `MeshConnectionManager.setLocalTrack()` - `null` sends nothing for that kind. */
+    setLocalTrack(kind: "audio" | "video", track: MediaStreamTrack | null): void;
+    close(): void;
 }
 export type RTCPeerConnectionFactory = (config: {
     iceServers: RTCIceServer[];
@@ -108,6 +133,8 @@ export type RTCPeerConnectionFactory = (config: {
 export interface MeshParticipant extends ParticipantState {
     uid: string;
     name: string;
+    /** How this participant's media currently reaches the local one - see `MediaTransport`. */
+    transport: MediaTransport;
 }
 export type MeshEvent = {
     type: "participant-joined";

package/dist/lib/index.js

@@ -19,6 +19,8 @@ export * from "./models/types.js";
 export * from "./util/BookingIntegrationUtils.js";
 export * from "./util/IceServerUtils.js";
 export * from "./util/PublicUrlUtils.js";
+export * from "./util/RedisRelayBus.js";
+export * from "./util/RelayHub.js";
 export * from "./util/RouteAccessUtils.js";
 export * from "./util/TokenUtils.js";
 export * from "./routes/BaseVideoMeetingRoute.js";

package/dist/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E;;;;;;;;;;;;GAYG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mCAAmC,CAAC;AAClD,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mCAAmC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E;;;;;;;;;;;;GAYG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mCAAmC,CAAC;AAClD,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mCAAmC,CAAC"}

package/dist/lib/routes/BaseVideoMeetingRoute.js

@@ -17,15 +17,30 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import * as crypto from "crypto";
 import { ApiError, JWTUtils, ObjectDecorators } from "@rapidrest/core";
 import { ACLAction, ACLUtils, ApiErrorMessages, ApiErrors, DatabaseDecorators, DocDecorators, ModelUtils, RepoUtils, RouteDecorators, } from "@rapidrest/service-core";
+import { parseEffectsAssetsUrl } from "../util/EffectsUtils.js";
 import { buildIceServers } from "../util/IceServerUtils.js";
 import { buildBaseUrl } from "../util/PublicUrlUtils.js";
+import { RedisRelayBus } from "../util/RedisRelayBus.js";
+import { parseRelayEnabled, RELAY_LARGE_PAYLOAD_BYTES, RELAY_MAX_PAYLOAD_BYTES, RELAY_WS_MAX_BACKPRESSURE_BYTES, RelayHub, } from "../util/RelayHub.js";
 import { stripTrustedRoles } from "../util/RouteAccessUtils.js";
 import { JOIN_TOKEN_PATTERN, PUBLIC_SLUG_PATTERN, mintJoinToken, mintPublicSlug } from "../util/TokenUtils.js";
 import { VideoMeetingStatus, VideoMeetingVisibility } from "../models/types.js";
-const { Config, Inject, Logger } = ObjectDecorators;
+const { Config, Destroy, Init, Inject, Logger } = ObjectDecorators;
 const { Description, Summary } = DocDecorators;
 const { Transactional } = DatabaseDecorators;
-const { Delete, Get, Param, Post, Put, Query, RateLimit, Request, User: AuthUser } = RouteDecorators;
+const { Auth, Delete, Get, Param, Post, Put, Query, RateLimit, Request, Socket, User: AuthUser, WebSocket } = RouteDecorators;
+/** Whether the installed `@rapidrest/service-core` lets a `@WebSocket()` route set its own message and backpressure
+ * limits (its 2.4.0 and later export the option bounds). Without that the framework holds every WebSocket route to
+ * 16 KiB messages, and asking for more would advertise a limit that is not enforced - so the route then keeps 16 KiB. */
+const WS_ROUTE_OPTIONS_SUPPORTED = "MAX_WEBSOCKET_PAYLOAD_LENGTH" in RouteDecorators;
+/** The largest message a relay socket may send: what the route asks the framework for and what `ready` tells the
+ * client. */
+const RELAY_MESSAGE_LIMIT_BYTES = WS_ROUTE_OPTIONS_SUPPORTED ? RELAY_LARGE_PAYLOAD_BYTES : RELAY_MAX_PAYLOAD_BYTES;
+/** The relay route's WebSocket options: bigger messages, so a key frame is one message, and a bigger send buffer, so a
+ * receiver that stalls for a moment loses nothing. `undefined` (the framework's defaults) where it cannot be set. */
+const RELAY_WS_OPTIONS = WS_ROUTE_OPTIONS_SUPPORTED
+    ? { maxPayloadLength: RELAY_LARGE_PAYLOAD_BYTES, maxBackpressure: RELAY_WS_MAX_BACKPRESSURE_BYTES }
+    : undefined;
 /** Upper bounds on caller-supplied text, matching the general shape `booking-plugin`'s `BaseBookingRoute` bounds
  * its own free-text fields with. */
 const MAX_TITLE_LENGTH = 200;
@@ -52,6 +67,13 @@ export const GUEST_UID_PREFIX = "guest:";
 const GUEST_GRANT_MAX_ATTEMPTS = 5;
 /** The `label` of every `CalendarEventAttendeeLink` `persistMeeting()` writes. */
 const ATTENDEE_LINK_LABEL = "Join video call";
+/** The reason `relay()` closes (1008) a socket it refuses for any authorization reason - a caller with no grant, a
+ * meeting that doesn't exist, and one that is cancelled or ended all get exactly this, so a refusal never reveals
+ * whether the meeting exists. */
+const RELAY_NOT_PERMITTED = "Not permitted.";
+/** How many messages `relay()` holds for a socket that sends before its authorization finished (a client's `hello`
+ * can arrive while the meeting is still being looked up); the rest are dropped. */
+const RELAY_MAX_QUEUED_MESSAGES = 8;
 /**
  * The owner's management of their own `VideoMeeting`s (JWT-authenticated, mailbox-ACL-checked exactly like any
  * other mailbox-scoped entity - see `booking-plugin`'s `BaseBookingTypeRoute` for the same "must own or hold a
@@ -175,6 +197,27 @@ const ATTENDEE_LINK_LABEL = "Join video call";
  * now run every loaded meeting through `withJoinUrls()` - the exact same computation `create()` already did,
  * applied uniformly on read instead of only once on write.
  *
+ * ## The last-resort WebSocket media relay (`relay()`)
+ *
+ * Clients connect peer-to-peer over WebRTC, fall back to TURN, and as a third and last resort (a corporate firewall
+ * that allows neither) send media over a WebSocket this server proxies: `relay()`, at `/relay/:id` under the
+ * subclass's own base path (`/api/mail/video-meetings/relay/<meetingUid>`). It is a fan-out of opaque binary
+ * frames between the participants of one meeting - the wire protocol and limits are documented on `RelayHub`, which
+ * does all of the relaying; this class only authorizes a socket and hands it over, and picks how frames travel
+ * between server replicas: when the deployment configures `datastores:events` (the Redis the framework's push system
+ * already uses) frames cross replicas over Redis pub/sub (`RedisRelayBus`), so participants connected to different
+ * replicas reach each other; without it they travel in-process only, with a one-time warning at start-up that relay
+ * does not cross replicas.
+ *
+ * Authorization is the very grant `join()`'s `ensureChannelGrant()` already gives every participant, guest or real:
+ * `READ` and `CREATE` on the meeting's uid, checked with the caller's trusted roles stripped exactly as
+ * `MailPushRoute` does for `/push`, so a trusted administrator with no grant is refused just like there. The meeting must exist and be neither
+ * cancelled nor ended. Every refusal closes the socket with code 1008; a missing meeting and a missing grant are
+ * indistinguishable ("Not permitted."), so a caller learns nothing about meetings they can't join. The whole
+ * thing can be turned off with `mail:videoconf:relay:enabled` (default `true`; `false`/`"false"`/`0`/`"0"` disable
+ * it): a disabled relay closes every socket with 1008 "Relay disabled." and `join()` reports `relayEnabled: false`, so
+ * clients don't try it.
+ *
  * ## Other known limitations
  *
  * **`VideoMeetingInvitee.joinToken` never expires** and has no GC job - identical tradeoff to `Booking.manageToken`.
@@ -200,6 +243,19 @@ export class BaseVideoMeetingRoute {
         this.turnUsername = "";
         this.turnCredential = "";
         this.turnSharedSecret = "";
+        /** Whether `relay()` accepts sockets, and `join()` advertises it - read through `isRelayEnabled()`, since a value
+         * set from an environment variable arrives as a string. */
+        this.relayEnabledSetting = true;
+        /** The base URL the video filters' models are hosted under, when not on the public CDNs - read through
+         * `parseEffectsAssetsUrl()`, which drops anything that isn't a plain URL or path. */
+        this.effectsAssetsUrlSetting = "";
+        /** The deployment's `events` datastore (`datastores:events`) - the Redis the framework's push system publishes
+         * across replicas on; `null` when the deployment has none. Decides how `initRelayBus()` carries relay frames. */
+        this.eventsConfig = null;
+        /** The rooms of this process's relay sockets. One per route instance. It starts out on an in-process bus, which
+         * is what a route that was never initialized (a test's) keeps; `initRelayBus()` swaps in a hub on a Redis bus
+         * when the deployment has one, before any socket can attach. Its socket caps are per server replica. */
+        this.relayHub = new RelayHub({ maxPayloadBytes: RELAY_MESSAGE_LIMIT_BYTES, logger: { debug: (message) => this.logger.debug(message) } });
     }
     /**
      * Exposes the `@Model(...)`-supplied entity class as an instance property so `@Transactional()` on
@@ -210,6 +266,38 @@ export class BaseVideoMeetingRoute {
     get modelClass() {
         return this.constructor.modelClass;
     }
+    /**
+     * Picks how relay frames travel between server replicas, once the route is created: over Redis pub/sub
+     * (`RedisRelayBus`) when `datastores:events` is configured, else in-process only with a single warning that
+     * participants on different replicas cannot relay to each other. A Redis bus that cannot be created (the `redis`
+     * package is missing, an unusable URL) falls back the same way, with the error logged. Runs before the route
+     * serves anything, so no socket is attached to the hub it replaces.
+     */
+    async initRelayBus() {
+        const url = this.eventsConfig?.url;
+        if (!url) {
+            this.logger.warn("The `events` datastore is not configured: the video meeting relay only carries media between participants " +
+                "connected to this server instance, not between server replicas.");
+            return;
+        }
+        const bus = new RedisRelayBus({ url, logger: this.logger });
+        try {
+            await bus.connect();
+        }
+        catch (err) {
+            this.logger.error("Could not create the video meeting relay's Redis bus, so relay only works between participants connected to this " +
+                `server instance: ${err?.message ?? err}`);
+            return;
+        }
+        this.relayBus = bus;
+        this.relayHub = new RelayHub({ bus, maxPayloadBytes: RELAY_MESSAGE_LIMIT_BYTES, logger: { debug: (message) => this.logger.debug(message) } });
+    }
+    /** Disconnects the Redis relay bus, if there is one, when the object factory destroys the route. (The factory
+     * runs one destroy method per object: a subclass declaring its own `@Destroy` must call this one.) */
+    destroyRelayBus() {
+        this.relayBus?.close();
+        this.relayBus = undefined;
+    }
     async init() {
         if (!this.meetingRepo) {
             this.meetingRepo = await this._objectFactory.newInstance(RepoUtils, { name: this.meetingClass.name, args: [this.meetingClass] });
@@ -639,6 +727,8 @@ export class BaseVideoMeetingRoute {
                 throw new ApiError(ApiErrors.NOT_FOUND, 404, ApiErrorMessages.NOT_FOUND);
             }
         }
+        const relayEnabled = this.isRelayEnabled();
+        const effectsAssetsUrl = parseEffectsAssetsUrl(this.effectsAssetsUrlSetting);
         const publicMeeting = {
             uid: meeting.uid,
             title: meeting.title,
@@ -657,7 +747,7 @@ export class BaseVideoMeetingRoute {
         // prefix check is a safe, cheap discriminator - see this class's doc comment and GUEST_UID_PREFIX).
         if (user && !user.uid.startsWith(GUEST_UID_PREFIX)) {
             await this.ensureChannelGrant(meeting.uid, user.uid);
-            return { meeting: publicMeeting, iceServers, authenticated: true, selfUid: user.uid };
+            return { meeting: publicMeeting, iceServers, authenticated: true, selfUid: user.uid, relayEnabled, ...(effectsAssetsUrl && { effectsAssetsUrl }) };
         }
         const { guestUid, token: guestToken, expiresAt } = this.mintGuestToken();
         await this.ensureChannelGrant(meeting.uid, guestUid);
@@ -668,8 +758,107 @@ export class BaseVideoMeetingRoute {
             selfUid: guestUid,
             token: guestToken,
             expiresAt: expiresAt.toISOString(),
+            relayEnabled,
+            ...(effectsAssetsUrl && { effectsAssetsUrl }),
         };
     }
+    /** Whether the WebSocket media relay is enabled - `mail:videoconf:relay:enabled`, see `parseRelayEnabled()`. */
+    isRelayEnabled() {
+        return parseRelayEnabled(this.relayEnabledSetting);
+    }
+    /**
+     * Decides whether `user` may open a relay socket to meeting `id`: the relay must be enabled, `user` must hold BOTH
+     * `READ` and `CREATE` on the meeting's uid - exactly what `ensureChannelGrant()` gives a joined participant, and
+     * what `/push` demands to subscribe and publish - and the meeting must exist and be neither cancelled nor ended.
+     * Returns the reason to close the socket with, or `undefined` when permitted.
+     *
+     * `hasPermission()` gets `user` with its trusted roles stripped (`stripTrustedRoles()`), exactly as
+     * `@rapidmx/restapi`'s `MailPushRoute` does for the same grant on `/push`: without it the framework's "trusted
+     * users always have permission" rule would let any administrator relay in any meeting they hold no grant on, so
+     * a trusted administrator with no grant is refused here exactly as `/push` refuses them. Every authorization
+     * failure gives the same `RELAY_NOT_PERMITTED`, whether the grant, the meeting or its state is what's missing.
+     */
+    async authorizeRelay(id, user) {
+        if (!this.isRelayEnabled()) {
+            return "Relay disabled.";
+        }
+        // `hasPermission()` answers `true` for an empty ACL uid, so an empty id must never reach it.
+        if (!user || !id) {
+            return RELAY_NOT_PERMITTED;
+        }
+        await this.init();
+        const checked = stripTrustedRoles(user, this.trustedRoles);
+        if (!(await this.aclUtils.hasPermission(checked, id, ACLAction.READ)) || !(await this.aclUtils.hasPermission(checked, id, ACLAction.CREATE))) {
+            return RELAY_NOT_PERMITTED;
+        }
+        const meeting = await this.meetingRepo.findOne(id, { ignoreACL: true });
+        if (!meeting || meeting.status === VideoMeetingStatus.CANCELLED || meeting.status === VideoMeetingStatus.ENDED) {
+            return RELAY_NOT_PERMITTED;
+        }
+        return undefined;
+    }
+    /**
+     * The meeting uid a relay socket's URL names. `@Param("id")` is filled in by the Bun router, but NOT by the uWS
+     * router this framework actually serves with: it never populates `req.params` for a WebSocket upgrade (a
+     * `@WebSocket()` route has, so far, never had a path parameter - `BasePushRoute.connect()` has none). So when the
+     * decorated argument is empty this reads the last segment of the request path instead, which the
+     * `/relay/:id` pattern guarantees is the id (the framework also registers the trailing-slash form; the path
+     * never carries the query string). Returns `undefined` when there is none or it isn't valid percent-encoding.
+     */
+    relayMeetingId(paramId, req) {
+        if (typeof paramId === "string" && paramId) {
+            return paramId;
+        }
+        const segments = String(req?.path ?? "").split("/").filter((segment) => segment);
+        try {
+            return decodeURIComponent(segments[segments.length - 1] ?? "") || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async relay(paramId, req, sock, user) {
+        const id = this.relayMeetingId(paramId, req);
+        // Listeners first, before the first await: the client may send its `hello` the moment the socket opens,
+        // while the meeting is still being looked up, and an event with no listener is lost. Whatever arrives until
+        // the socket is admitted is held (a few messages at most) and replayed to it.
+        let conn;
+        let closed = false;
+        const queued = [];
+        sock.on("message", (data, isBinary) => {
+            if (conn) {
+                conn.message(data, isBinary);
+            }
+            else if (queued.length < RELAY_MAX_QUEUED_MESSAGES) {
+                queued.push({ data, isBinary });
+            }
+        });
+        sock.on("close", () => {
+            closed = true;
+            conn?.close();
+        });
+        let refusal;
+        try {
+            refusal = await this.authorizeRelay(id, user);
+        }
+        catch (err) {
+            this.logger.error(`Failed to authorize a relay socket for meeting ${id}: ${err?.message ?? err}`);
+            sock.close(1011, "Relay unavailable.");
+            return;
+        }
+        if (refusal) {
+            sock.close(1008, refusal);
+            return;
+        }
+        // The socket closed while it was being authorized: nothing to attach, and nothing left to clean up.
+        if (closed) {
+            return;
+        }
+        conn = this.relayHub.attach(id, user.uid, sock);
+        for (const message of queued) {
+            conn?.message(message.data, message.isBinary);
+        }
+    }
 }
 __decorate([
     Inject(ACLUtils),
@@ -703,10 +892,34 @@ __decorate([
     Config("mail:videoconf:turn:shared_secret", ""),
     __metadata("design:type", String)
 ], BaseVideoMeetingRoute.prototype, "turnSharedSecret", void 0);
+__decorate([
+    Config("mail:videoconf:relay:enabled", true),
+    __metadata("design:type", Object)
+], BaseVideoMeetingRoute.prototype, "relayEnabledSetting", void 0);
+__decorate([
+    Config("mail:videoconf:effects:assets_url", ""),
+    __metadata("design:type", String)
+], BaseVideoMeetingRoute.prototype, "effectsAssetsUrlSetting", void 0);
+__decorate([
+    Config("datastores:events", null),
+    __metadata("design:type", Object)
+], BaseVideoMeetingRoute.prototype, "eventsConfig", void 0);
 __decorate([
     Logger,
     __metadata("design:type", Object)
 ], BaseVideoMeetingRoute.prototype, "logger", void 0);
+__decorate([
+    Init,
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], BaseVideoMeetingRoute.prototype, "initRelayBus", null);
+__decorate([
+    Destroy,
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", void 0)
+], BaseVideoMeetingRoute.prototype, "destroyRelayBus", null);
 __decorate([
     Transactional(),
     __metadata("design:type", Function),
@@ -795,4 +1008,25 @@ __decorate([
     __metadata("design:paramtypes", [String, Object]),
     __metadata("design:returntype", Promise)
 ], BaseVideoMeetingRoute.prototype, "join", null);
+__decorate([
+    Summary("Relays media over a WebSocket."),
+    Description("The last-resort media path for a participant whose network blocks both a direct WebRTC connection and TURN: " +
+        "a WebSocket at /relay/<meetingUid> carrying opaque binary frames between the meeting's participants " +
+        "(see RelayHub for the protocol: a 'hello' text message first, then 'want' to choose whose media to " +
+        "receive, then binary frames of at most the 'maxMessageBytes' the server's 'ready' reply names: 64 KiB, or 16 KiB on a framework that cannot raise its limit). Requires a JWT (a real user's, or the guest token " +
+        "join() minted) holding READ and CREATE on the meeting - the grant join() gives - and an existing, " +
+        "unended, uncancelled meeting; anything else, or a disabled relay, closes the socket with code 1008. When " +
+        "the server runs several replicas and the events datastore (Redis) is configured, media is relayed " +
+        "between participants connected to different replicas too; without it, only between participants " +
+        "connected to the same replica. The socket limits apply per replica."),
+    Auth(["jwt"]),
+    WebSocket("/relay/:id", RELAY_WS_OPTIONS),
+    __param(0, Param("id")),
+    __param(1, Request),
+    __param(2, Socket),
+    __param(3, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, Object, Object]),
+    __metadata("design:returntype", Promise)
+], BaseVideoMeetingRoute.prototype, "relay", null);
 //# sourceMappingURL=BaseVideoMeetingRoute.js.map