@rapidmx/meet-plugin 0.5.0 → 0.8.0

package/dist/lib/util/RelayHub.js

@@ -0,0 +1,405 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** The version of the relay wire protocol this module implements - the `v` of `hello`/`ready`. */
+export const RELAY_PROTOCOL_VERSION = 1;
+/** The largest binary payload (in bytes, excluding the sender header the server adds) a socket may send; anything
+ * larger or empty is dropped. Matches `@rapidrest/service-core`'s uWS `DEFAULT_WS_OPTIONS.maxPayloadLength` (16 KiB),
+ * which this framework's route registration cannot raise - a larger message closes the socket at the transport. */
+export const RELAY_MAX_PAYLOAD_BYTES = 16 * 1024;
+/** The larger message limit the relay route asks the framework for when the installed `@rapidrest/service-core` lets a
+ * `@WebSocket()` route set one (its 2.4.0 and later): a video key frame then fits in one message instead of several,
+ * with far less fragmenting and reassembly for the client to get wrong. The hub advertises whichever limit applies to
+ * the client in `ready` (`maxMessageBytes`). */
+export const RELAY_LARGE_PAYLOAD_BYTES = 64 * 1024;
+/** How many bytes the framework may hold unsent for one relay socket before it drops further messages to it, when the
+ * installed `@rapidrest/service-core` lets a route set that (its default, 64 KiB, is smaller than one key frame's worth
+ * of headroom and made a briefly slow receiver lose frames constantly). One MiB is roughly two seconds of a 350 kbps
+ * video stream plus audio. */
+export const RELAY_WS_MAX_BACKPRESSURE_BYTES = 1024 * 1024;
+/** The most sockets (registered or still awaiting their `hello`) one room holds at once. */
+export const RELAY_MAX_SOCKETS_PER_ROOM = 16;
+/** The most sockets one authenticated uid may hold in one room at once (several tabs or devices of one account). */
+export const RELAY_MAX_SOCKETS_PER_UID = 4;
+/** Sustained inbound binary budget per socket, in bytes per second (a token bucket refill rate). */
+export const RELAY_RATE_BYTES_PER_SECOND = 512 * 1024;
+/** Burst allowance of a socket's token bucket, in bytes - also the bucket's capacity. */
+export const RELAY_BURST_BYTES = 1024 * 1024;
+/** How long a socket may stay over budget continuously before it is closed with 1008 "Too much data.". */
+export const RELAY_OVER_BUDGET_CLOSE_MS = 10000;
+/** Two over-budget drops further apart than this are separate episodes: a socket is "continuously" over budget only
+ * while it keeps being dropped at least this often. A sender that exceeds its budget by a hair (one drop every few
+ * seconds) is throttled but never closed; one that keeps sending well past it is closed after
+ * `RELAY_OVER_BUDGET_CLOSE_MS`. */
+export const RELAY_OVER_BUDGET_GRACE_MS = 1000;
+/** How long a new socket has to send its `hello` before it is closed with 1008 "Hello timeout.". */
+export const RELAY_HELLO_TIMEOUT_MS = 10000;
+/** The longest peer id, in characters. Its UTF-8 encoding must also fit in the one length byte of a forwarded frame
+ * (255), which `isValidRelayPeer()` enforces too. */
+export const RELAY_MAX_PEER_LENGTH = 128;
+/** The most peers one `want` message may name; further valid entries are ignored. */
+export const RELAY_MAX_WANT_PEERS = 32;
+/** A `RelayBus` that delivers synchronously to the listeners of this one process - see `RelayHub`'s doc comment for
+ * what that means for a deployment with several server replicas. */
+export class InProcessRelayBus {
+    constructor() {
+        this.listeners = new Map();
+    }
+    subscribe(roomId, listener) {
+        let set = this.listeners.get(roomId);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(roomId, set);
+        }
+        set.add(listener);
+        return () => {
+            set.delete(listener);
+            if (set.size === 0 && this.listeners.get(roomId) === set) {
+                this.listeners.delete(roomId);
+            }
+        };
+    }
+    publish(roomId, sender, frame) {
+        for (const listener of this.listeners.get(roomId) ?? []) {
+            listener(sender, frame);
+        }
+    }
+}
+/**
+ * Returns whether `peer` is a well-formed relay peer id: a string of 1 to `RELAY_MAX_PEER_LENGTH` characters with no
+ * whitespace, separator, control or other invisible (Unicode category C or Z) character, whose UTF-8 encoding fits in
+ * the single length byte of a forwarded frame.
+ */
+export function isValidRelayPeer(peer) {
+    return (typeof peer === "string" &&
+        peer.length >= 1 &&
+        peer.length <= RELAY_MAX_PEER_LENGTH &&
+        /^[^\s\p{C}\p{Z}]+$/u.test(peer) &&
+        Buffer.byteLength(peer, "utf8") <= 255);
+}
+/**
+ * Reads the `mail:videoconf:relay:enabled` setting. Environment-variable config arrives as a string ("true", "false",
+ * "0", "1") and nconf may parse it into a boolean or a number, so all of those are accepted; `false`, `0`, `"false"`
+ * and `"0"` (case-insensitive, trimmed) disable the relay and anything else - including an unset or unrecognizable
+ * value - leaves it enabled, the default.
+ */
+export function parseRelayEnabled(value) {
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        return normalized !== "false" && normalized !== "0";
+    }
+    return value !== false && value !== 0;
+}
+function toBuffer(data) {
+    if (typeof data === "string") {
+        return Buffer.from(data, "utf8");
+    }
+    return Buffer.isBuffer(data) ? data : Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+}
+/** A token bucket: `capacity` tokens (bytes), refilled at `rate` per second, starting full. */
+class TokenBucket {
+    constructor(now) {
+        this.tokens = RELAY_BURST_BYTES;
+        this.last = now;
+    }
+    /** Takes `amount` tokens if that many are available; returns whether it did. */
+    take(amount, now) {
+        this.tokens = Math.min(RELAY_BURST_BYTES, this.tokens + ((now - this.last) / 1000) * RELAY_RATE_BYTES_PER_SECOND);
+        this.last = now;
+        if (this.tokens < amount) {
+            return false;
+        }
+        this.tokens -= amount;
+        return true;
+    }
+}
+class Connection {
+    constructor(env, room, uid, socket) {
+        this.env = env;
+        this.room = room;
+        this.uid = uid;
+        this.socket = socket;
+        /** The peer ids this socket wants frames from - see `want`. */
+        this.wanted = new Set();
+        this.closed = false;
+        this.bucket = new TokenBucket(Date.now());
+        this.lastOverBudget = 0;
+        this.helloTimer = setTimeout(() => this.evict("Hello timeout."), RELAY_HELLO_TIMEOUT_MS);
+        this.helloTimer.unref();
+    }
+    message(data, isBinary) {
+        if (this.closed) {
+            return;
+        }
+        if (isBinary) {
+            this.binary(toBuffer(data));
+        }
+        else {
+            this.text(typeof data === "string" ? data : toBuffer(data).toString("utf8"));
+        }
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        clearTimeout(this.helloTimer);
+        this.env.remove(this);
+    }
+    /** Closes the socket from this side with 1008 and `reason`, and forgets it. Only ever called on a live
+     * connection: `message()` ignores a closed one, its hello timer is cleared on close, and a closed one is no
+     * longer in its room's `peers`. */
+    evict(reason) {
+        this.close();
+        this.socket.close(1008, reason);
+    }
+    /** Sends `frame` to this socket. A send the socket reports as dropped, or throws on, is counted and skipped. */
+    forward(frame) {
+        const fail = (err) => {
+            this.env.stats.framesDroppedBackpressure++;
+            this.env.debug(`Dropped a relay frame for ${this.peer} in ${this.room.id}: ${err?.message ?? err}`);
+        };
+        try {
+            this.socket.send(frame, (err) => {
+                if (err) {
+                    fail(err);
+                }
+            });
+            this.env.stats.framesForwarded++;
+        }
+        catch (err) {
+            fail(err);
+        }
+    }
+    /** Sends `text` to this socket, ignoring a failure - a lost `ready` shows as a client that never gets ready. */
+    sendText(text) {
+        try {
+            this.socket.send(text);
+        }
+        catch {
+            // The socket is going away; its close event cleans up.
+        }
+    }
+    text(text) {
+        // A character is at least one byte, so this bounds the parse below by the payload limit.
+        if (text.length > this.env.maxPayloadBytes) {
+            return;
+        }
+        let message;
+        try {
+            message = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        if (!message || typeof message !== "object" || Array.isArray(message)) {
+            return;
+        }
+        if (!this.peer) {
+            if (message.op === "hello") {
+                this.hello(message);
+            }
+        }
+        else if (message.op === "want") {
+            this.want(message);
+        }
+    }
+    hello(message) {
+        if (message.v !== RELAY_PROTOCOL_VERSION) {
+            this.evict("Unsupported version.");
+            return;
+        }
+        const peer = message.peer;
+        if (!isValidRelayPeer(peer) || (peer !== this.uid && !peer.startsWith(`${this.uid}~`))) {
+            this.evict("Invalid peer.");
+            return;
+        }
+        // A reconnecting client's new socket replaces the old one, which may not have noticed it is dead yet.
+        this.room.peers.get(peer)?.evict("Replaced.");
+        this.room.peers.set(peer, this);
+        this.peer = peer;
+        this.peerBytes = Buffer.from(peer, "utf8");
+        clearTimeout(this.helloTimer);
+        this.sendText(JSON.stringify({ op: "ready", v: RELAY_PROTOCOL_VERSION, maxMessageBytes: this.env.maxPayloadBytes }));
+    }
+    want(message) {
+        if (!Array.isArray(message.peers)) {
+            return;
+        }
+        const wanted = new Set();
+        for (const peer of message.peers) {
+            if (wanted.size >= RELAY_MAX_WANT_PEERS) {
+                break;
+            }
+            if (isValidRelayPeer(peer)) {
+                wanted.add(peer);
+            }
+        }
+        this.wanted = wanted;
+    }
+    binary(payload) {
+        if (!this.peer || payload.length === 0 || payload.length > this.env.maxPayloadBytes) {
+            this.env.stats.framesDroppedInvalid++;
+            return;
+        }
+        const now = Date.now();
+        if (!this.bucket.take(payload.length, now)) {
+            this.env.stats.framesDroppedBudget++;
+            if (this.overBudgetSince === undefined || now - this.lastOverBudget > RELAY_OVER_BUDGET_GRACE_MS) {
+                this.overBudgetSince = now;
+            }
+            this.lastOverBudget = now;
+            if (now - this.overBudgetSince > RELAY_OVER_BUDGET_CLOSE_MS) {
+                this.evict("Too much data.");
+            }
+            return;
+        }
+        // Stamped here from the `hello`, never read from the payload: [sender length][sender][payload].
+        const sender = this.peerBytes;
+        const frame = Buffer.allocUnsafe(1 + sender.length + payload.length);
+        frame[0] = sender.length;
+        sender.copy(frame, 1);
+        payload.copy(frame, 1 + sender.length);
+        this.env.bus.publish(this.room.id, this.peer, frame);
+    }
+}
+/**
+ * A fan-out relay of opaque binary frames between the participants of a room (one meeting) - the last-resort tier
+ * for participants whose network allows neither a direct WebRTC connection nor a TURN relay, only a WebSocket to this
+ * server. It knows nothing about meetings, users, HTTP or any framework: a caller authorizes a socket however it
+ * likes, hands it to `attach()` and feeds the returned `RelayConnection` the socket's `message` and `close` events.
+ *
+ * ## Wire protocol (version 1)
+ *
+ * Client to server, the first message must be a text message
+ * `{"op":"hello","v":1,"peer":"<peerId>"}`, sent within `RELAY_HELLO_TIMEOUT_MS`. `peer` is the caller's uid (the `uid`
+ * given to `attach()`) or starts with `<uid>~` - a per-tab or per-device id - and passes `isValidRelayPeer()`. Anything
+ * else closes the socket with 1008 "Invalid peer."; a wrong `v` closes it with 1008 "Unsupported version.". The server
+ * answers with the text message `{"op":"ready","v":1,"maxMessageBytes":<the limit below>}`. A second socket registering an already registered peer in the
+ * same room replaces the older one, which is closed with 1008 "Replaced.".
+ *
+ * After that, `{"op":"want","peers":["<peerId>", ...]}` REPLACES the socket's interest set with the valid entries, at
+ * most `RELAY_MAX_WANT_PEERS` of them; every other or malformed text message is ignored. Binary messages of 1 to
+ * `RelayHubOptions.maxPayloadBytes` bytes (`RELAY_MAX_PAYLOAD_BYTES` unless the route asked for more; opaque to the hub) are forwarded to every other socket of the room whose interest
+ * set contains the sender's peer id; binary before `hello`, empty and oversized messages are dropped.
+ *
+ * Server to client: `{"op":"ready","v":1,"maxMessageBytes":N}` once, then binary messages `[1 byte: UTF-8 length N of the sender's peer
+ * id][N bytes: the sender's peer id][the original payload]`. The sender is stamped by the hub from the `hello`,
+ * never trusted from the payload.
+ *
+ * ## Limits
+ *
+ * At most `RELAY_MAX_SOCKETS_PER_ROOM` sockets per room and `RELAY_MAX_SOCKETS_PER_UID` per uid per room, counting
+ * a socket from `attach()` on (a socket refused for either is closed with 1008 "Room full." / "Too many
+ * connections."). Each socket's inbound binary traffic is metered by a token bucket of `RELAY_RATE_BYTES_PER_SECOND`
+ * sustained with a `RELAY_BURST_BYTES` burst: an over-budget message is dropped silently, and a socket kept over
+ * budget for more than `RELAY_OVER_BUDGET_CLOSE_MS` (see `RELAY_OVER_BUDGET_GRACE_MS`) is closed with 1008 "Too
+ * much data.". A receiver whose `send()` reports the message as dropped (uWS backpressure) simply misses that
+ * frame - counted in `stats`, never queued or retried. Sockets and rooms are released when their socket closes; an
+ * empty room is deleted.
+ *
+ * ## Replicas
+ *
+ * The transport between sockets is the `RelayBus` given to the constructor, `InProcessRelayBus` by default, which
+ * delivers only within this process: **with several server replicas, participants whose sockets landed on different
+ * replicas cannot relay to each other** - a room exists independently on each replica and its members see only the
+ * members connected to the same one. Give the hub a `RedisRelayBus` and frames cross replicas over Redis pub/sub (one
+ * channel per room; `BaseVideoMeetingRoute` does that whenever `datastores:events` is configured); nothing else in the
+ * hub changes for it.
+ *
+ * Every limit above is enforced **per replica**, because a hub only knows its own sockets. A room's capacity across
+ * replicas is therefore up to `replicas x RELAY_MAX_SOCKETS_PER_ROOM` sockets (and `replicas x
+ * RELAY_MAX_SOCKETS_PER_UID` for one uid) in the worst case, where the load balancer spreads a meeting's sockets
+ * evenly. A peer id that registers on two replicas is not detected as a duplicate either (the "Replaced." rule is
+ * per replica), and each frame reaches every socket that wants its sender on every replica.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export class RelayHub {
+    constructor(options = {}) {
+        /** What has happened to frames so far. */
+        this.stats = {
+            framesForwarded: 0,
+            framesDroppedBackpressure: 0,
+            framesDroppedBudget: 0,
+            framesDroppedInvalid: 0,
+        };
+        this.rooms = new Map();
+        this.bus = options.bus ?? new InProcessRelayBus();
+        this.logger = options.logger;
+        this.env = {
+            stats: this.stats,
+            bus: this.bus,
+            maxPayloadBytes: options.maxPayloadBytes ?? RELAY_MAX_PAYLOAD_BYTES,
+            debug: (message) => this.logger?.debug(message),
+            remove: (conn) => this.remove(conn),
+        };
+    }
+    /** The number of rooms that currently hold at least one socket. */
+    get roomCount() {
+        return this.rooms.size;
+    }
+    /** The number of sockets in `roomId` (0 for an unknown room). */
+    socketCount(roomId) {
+        return this.rooms.get(roomId)?.conns.size ?? 0;
+    }
+    /**
+     * Accepts an already-authorized `socket` of `uid` into room `roomId`, or refuses it (closing it with 1008) when
+     * the room or the uid is at its limit. Returns the connection to feed the socket's events to, or `undefined`
+     * when refused.
+     */
+    attach(roomId, uid, socket) {
+        let room = this.rooms.get(roomId);
+        if (room) {
+            if (room.conns.size >= RELAY_MAX_SOCKETS_PER_ROOM) {
+                socket.close(1008, "Room full.");
+                return undefined;
+            }
+            let ofUid = 0;
+            for (const conn of room.conns) {
+                if (conn.uid === uid) {
+                    ofUid++;
+                }
+            }
+            if (ofUid >= RELAY_MAX_SOCKETS_PER_UID) {
+                socket.close(1008, "Too many connections.");
+                return undefined;
+            }
+        }
+        else {
+            room = {
+                id: roomId,
+                conns: new Set(),
+                peers: new Map(),
+                unsubscribe: this.bus.subscribe(roomId, (sender, frame) => this.deliver(roomId, sender, frame)),
+            };
+            this.rooms.set(roomId, room);
+        }
+        const conn = new Connection(this.env, room, uid, socket);
+        room.conns.add(conn);
+        return conn;
+    }
+    /** Forgets `conn`, and its room once that is empty. */
+    remove(conn) {
+        const room = conn.room;
+        room.conns.delete(conn);
+        if (conn.peer && room.peers.get(conn.peer) === conn) {
+            room.peers.delete(conn.peer);
+        }
+        if (room.conns.size === 0 && this.rooms.get(room.id) === room) {
+            room.unsubscribe();
+            this.rooms.delete(room.id);
+        }
+    }
+    /** Hands `frame` from `sender` to every other socket of room `roomId` that wants it. A bus that delivers
+     * asynchronously (across replicas) may deliver a frame for a room that has just emptied; that is ignored. */
+    deliver(roomId, sender, frame) {
+        for (const conn of this.rooms.get(roomId)?.peers.values() ?? []) {
+            if (conn.peer !== sender && conn.wanted.has(sender)) {
+                conn.forward(frame);
+            }
+        }
+    }
+}
+//# sourceMappingURL=RelayHub.js.map

package/dist/lib/util/RelayHub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RelayHub.js","sourceRoot":"","sources":["../../../src/util/RelayHub.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -15,6 +15,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/types/routes/BaseVideoMeetingRoute.d.ts

@@ -98,6 +98,13 @@ export interface VideoMeetingJoinResult {
     /** ISO 8601 instant `token` expires at. Present only when `authenticated` is `false`, exactly when `token`
      * itself is. */
     expiresAt?: string;
+    /** Whether the last-resort WebSocket media relay (`relay()`, the third tier after a direct WebRTC connection and
+     * TURN) is enabled on this server (`mail:videoconf:relay:enabled`). A client only falls back to it when this is
+     * `true`; connecting to a disabled relay is refused anyway. */
+    relayEnabled: boolean;
+    /** Where the video filters' machine-learning runtime and models are hosted, when the administrator hosts them
+     * (`mail:videoconf:effects:assets_url`). Omitted when unset, in which case clients use the public CDNs. */
+    effectsAssetsUrl?: string;
 }
 /**
  * The owner's management of their own `VideoMeeting`s (JWT-authenticated, mailbox-ACL-checked exactly like any
@@ -222,6 +229,27 @@ export interface VideoMeetingJoinResult {
  * 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`.
@@ -261,7 +289,22 @@ export declare abstract class BaseVideoMeetingRoute<VM extends VideoMeeting, VMI
     private turnUsername;
     private turnCredential;
     private turnSharedSecret;
+    /** Whether `relay()` accepts sockets, and `join()` advertises it - read through `isRelayEnabled()`, since a value
+     * set from an environment variable arrives as a string. */
+    private relayEnabledSetting;
+    /** 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. */
+    private 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. */
+    private eventsConfig;
     private logger;
+    /** 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. */
+    private relayHub;
+    /** The Redis bus `relayHub` runs on, when there is one. */
+    private relayBus?;
     /**
      * Exposes the `@Model(...)`-supplied entity class as an instance property so `@Transactional()` on
      * `persistMeeting()` can resolve which datasource to open a transaction against - identical to
@@ -269,6 +312,17 @@ export declare abstract class BaseVideoMeetingRoute<VM extends VideoMeeting, VMI
      * `ModelRoute`, which defines the same getter for its own subclasses).
      */
     get modelClass(): any;
+    /**
+     * 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.
+     */
+    initRelayBus(): Promise<void>;
+    /** 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(): void;
     private init;
     /** Rejects a `403` unless `user` (with its trusted roles stripped - see `util/RouteAccessUtils.ts`) holds
      * `action` on `mailboxUid`, by ownership or an explicit ACL grant. */
@@ -380,4 +434,29 @@ export declare abstract class BaseVideoMeetingRoute<VM extends VideoMeeting, VMI
      * orphaned meeting should still be joinable, just without a host name to show). */
     private hostDisplayName;
     join(token: string, user?: JWTUser): Promise<VideoMeetingJoinResult>;
+    /** Whether the WebSocket media relay is enabled - `mail:videoconf:relay:enabled`, see `parseRelayEnabled()`. */
+    private isRelayEnabled;
+    /**
+     * 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.
+     */
+    private authorizeRelay;
+    /**
+     * 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.
+     */
+    private relayMeetingId;
+    relay(paramId: string | undefined, req: HttpRequest, sock: any, user?: JWTUser): Promise<void>;
 }

package/dist/types/util/EffectsUtils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Reads the `mail:videoconf:effects:assets_url` setting: the base URL an administrator hosts the video filters'
+ * machine-learning runtime and models under, in place of the public CDNs they are otherwise fetched from. It is
+ * handed to every participant's browser, so only an absolute `http(s)` URL or a path on this server is accepted;
+ * anything else (a `javascript:` URL, a typo, nothing at all) is treated as unset. A trailing slash is dropped.
+ *
+ * @param value The setting as configured.
+ * @returns The URL to hand to clients, or `undefined` to have them use the defaults.
+ */
+export declare function parseEffectsAssetsUrl(value: unknown): string | undefined;

package/dist/types/util/IceServerUtils.d.ts

@@ -17,6 +17,17 @@ export interface TurnSettings {
 /** The URLs in a `mail:videoconf:turn:url` value: one, or several separated by commas and/or whitespace (for a TURN server
  * listening on both UDP and TLS, `turn:host:3478,turns:host:5349`). Blank entries are dropped. */
 export declare function parseTurnUrls(value: string): string[];
+/**
+ * Adds the TCP flavour of every plain `turn:` URL that does not name a transport itself. A browser given
+ * `turn:host:3478` speaks only UDP to the TURN server, and UDP is precisely what a restrictive firewall blocks while
+ * still letting outbound TCP through - so a client behind one never reaches a TURN server that was listening on TCP
+ * all along. Offering both lets ICE try UDP first and settle for TCP when UDP goes nowhere. `turns:` URLs are TCP
+ * (TLS) already, and a URL with an explicit `transport=` is the operator's own choice and is left exactly as given.
+ *
+ * @param urls The URLs from `parseTurnUrls()`, in the order the operator wrote them.
+ * @returns The same URLs, each plain `turn:` one followed by its `?transport=tcp` twin, without duplicates.
+ */
+export declare function withTcpFallback(urls: string[]): string[];
 /** Always-available, free public STUN servers - discovery only, no media relay. Two independent providers, so a
  * call still has STUN available if one of them is ever unreachable. */
 export declare const DEFAULT_STUN_SERVERS: readonly IceServerConfig[];
@@ -44,7 +55,7 @@ export declare function turnRestCredential(sharedSecret: string, userPart: strin
 };
 /**
  * Builds the full ICE server list for a join response: the hardcoded public STUN servers, plus a TURN entry when
- * `settings.url` is configured. When a `sharedSecret` is also configured, the TURN entry carries a fresh,
+ * `settings.url` is configured (see `withTcpFallback()` for the URLs it carries). When a `sharedSecret` is also configured, the TURN entry carries a fresh,
  * time-limited credential (`turnRestCredential()`) rather than the static `username`/`credential` pair, which is
  * used verbatim only when no shared secret is set. A TURN url with neither a shared secret nor a static
  * credential is still included with no credentials at all - some self-hosted TURN servers are deliberately run