@rapidmx/meet-plugin 0.6.0 → 0.8.1

package/dist/lib/util/RedisRelayBus.js

@@ -0,0 +1,241 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import * as crypto from "crypto";
+import { attachRedisErrorHandler, importRedis } from "@rapidrest/service-core";
+/** The prefix of the Redis pub/sub channel a room's frames travel on: `videoconf:relay:<roomId>`. */
+export const REDIS_RELAY_CHANNEL_PREFIX = "videoconf:relay:";
+/** The length, in bytes, of the random id every `RedisRelayBus` stamps on what it publishes. */
+export const REDIS_RELAY_ORIGIN_BYTES = 16;
+/** The least time between two `warn` messages about failing Redis commands; the failures in between are logged at
+ * `debug`, so a Redis outage cannot flood the log at the rate media frames arrive. */
+export const REDIS_RELAY_WARN_INTERVAL_MS = 30000;
+/** The channel a room's frames are published to. */
+export function redisRelayChannel(roomId) {
+    return REDIS_RELAY_CHANNEL_PREFIX + roomId;
+}
+/**
+ * A `RelayBus` that also carries frames between server replicas over Redis pub/sub, so participants whose relay
+ * sockets landed on different replicas still reach each other. The Redis is the deployment's `datastores:events` one,
+ * the same the framework's push system (`BasePushRoute`) uses across replicas.
+ *
+ * ## How
+ *
+ * The bus owns exactly two Redis clients for the whole process, however many sockets and rooms there are: a
+ * publisher, and one shared subscriber (a client in subscriber mode cannot publish). Both come from
+ * `importRedis()` and `attachRedisErrorHandler()` of `@rapidrest/service-core`, exactly as `BasePushRoute` obtains its
+ * clients - see `connect()`.
+ *
+ * Each room has a channel, `videoconf:relay:<roomId>`. The bus counts the local listeners of every room: the first
+ * one to arrive makes it SUBSCRIBE and the last one to leave makes it UNSUBSCRIBE, so a replica receives only the
+ * rooms it has sockets in. Subscriptions use the client's BUFFER mode, so media bytes are never decoded as text.
+ *
+ * `publish()` delivers to this process's listeners synchronously, exactly as `InProcessRelayBus` does - local
+ * delivery never goes through Redis - and, when the publisher is connected, also publishes the frame to the room's
+ * channel without waiting for it. Every message carries the id of the bus that published it and a bus ignores its own,
+ * so nothing is delivered twice on the replica of origin, while every other replica delivers it to its own listeners.
+ *
+ * ## Wire format of a Redis message
+ *
+ * `[16 bytes: origin bus id][1 byte: N][N bytes: the sender's peer id, UTF-8][the frame]`, where `frame` is what the
+ * `RelayHub` gave `publish()` (its own `[sender length][sender][payload]` header included). The origin id is random
+ * per bus instance. A message that is shorter than that, whose length byte is 0 or overruns it, or that carries no
+ * frame, is dropped; parsing never throws.
+ *
+ * ## Failure behaviour
+ *
+ * Redis being down or slow never affects local delivery and never throws into the hub: `publish()` is fire-and-forget,
+ * is skipped outright while the publisher is not connected (its offline queue is disabled, so an outage cannot pile
+ * frames up in memory), and every failed command is caught and counted. Failures are logged at `warn` at most once per
+ * `REDIS_RELAY_WARN_INTERVAL_MS` and at `debug` otherwise; connection errors themselves are logged by
+ * `attachRedisErrorHandler()` (one error per outage). The clients keep node-redis's default reconnect strategy
+ * (retry forever with backoff), and on reconnect node-redis re-issues SUBSCRIBE for every channel the subscriber held
+ * (`resubscribe()` in the client's socket initiator), so the bus needs no re-subscribe logic of its own - relay
+ * between replicas resumes by itself when Redis comes back, and frames sent during the outage are simply lost, which
+ * media tolerates. A bus used before `connect()`, after `close()`, or whose Redis is unavailable behaves as an
+ * `InProcessRelayBus`.
+ *
+ * ## Bandwidth
+ *
+ * Every relayed frame is published once, whatever the number of receivers, and Redis delivers it to every replica
+ * subscribed to that room - including replicas whose sockets there do not `want` the sender at all (the hub filters
+ * after the bus). A room's cross-replica traffic is therefore roughly its total relayed upload times the number of
+ * OTHER replicas holding sockets of it, and each of those replicas' subscribers reads all of it. A single-replica
+ * room costs a publish per frame and no receiving. Redis pub/sub buffers nothing for a slow subscriber beyond the
+ * server's client-output-buffer limit for pub/sub, after which Redis drops that connection (the client then
+ * reconnects and resubscribes).
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export class RedisRelayBus {
+    constructor(options) {
+        this.options = options;
+        /** What the bus has done so far. */
+        this.stats = { published: 0, publishSkipped: 0, failures: 0, received: 0, receivedDropped: 0 };
+        this.id = crypto.randomBytes(REDIS_RELAY_ORIGIN_BYTES);
+        this.rooms = new Map();
+        this.lastWarn = Number.NEGATIVE_INFINITY;
+    }
+    /** Whether frames are currently being published to Redis: `connect()` was called, the bus is not closed and the
+     * publisher's connection is up. */
+    get connected() {
+        return this.publisher?.isReady === true;
+    }
+    /**
+     * Creates the publisher and the shared subscriber and starts connecting them, then returns without waiting for
+     * either connection - a Redis that is down at start-up delays cross-replica relay, not the server, and the
+     * clients keep retrying. Rooms subscribed to before this call are not caught up (the route calls it before it
+     * exposes the bus). Does nothing when already connected. Throws when the `redis` package is not installed or the
+     * URL is unusable; nothing is left open then.
+     */
+    async connect() {
+        if (this.publisher) {
+            return;
+        }
+        const { createClient } = await importRedis();
+        // The publisher must never queue commands while disconnected: a frame is only worth sending right now.
+        const publisher = attachRedisErrorHandler(createClient({ url: this.options.url, disableOfflineQueue: true }), this.options.logger, "events (relay publisher)");
+        let subscriber;
+        try {
+            subscriber = attachRedisErrorHandler(createClient({ url: this.options.url }), this.options.logger, "events (relay subscriber)");
+        }
+        catch (err) {
+            publisher.destroy();
+            throw err;
+        }
+        this.publisher = publisher;
+        this.subscriber = subscriber;
+        this.run("connect the publisher", () => publisher.connect());
+        this.run("connect the subscriber", () => subscriber.connect());
+    }
+    /**
+     * Shuts the bus down: destroys both clients (which ends their connections, and with them every subscription) and
+     * stops publishing. Local delivery keeps working, as after a failed `connect()`. Safe to call repeatedly.
+     * Nothing is unsubscribed one by one: the connection going away does that server-side, and an UNSUBSCRIBE could
+     * only stall behind a Redis that is down.
+     */
+    close() {
+        const clients = [this.publisher, this.subscriber];
+        this.publisher = undefined;
+        this.subscriber = undefined;
+        for (const client of clients) {
+            try {
+                client?.destroy();
+            }
+            catch (err) {
+                this.report("destroy a client", err);
+            }
+        }
+    }
+    subscribe(roomId, listener) {
+        let room = this.rooms.get(roomId);
+        if (!room) {
+            room = { listeners: new Set() };
+            this.rooms.set(roomId, room);
+            this.redisSubscribe(roomId, room);
+        }
+        const current = room;
+        current.listeners.add(listener);
+        return () => {
+            current.listeners.delete(listener);
+            if (current.listeners.size === 0 && this.rooms.get(roomId) === current) {
+                this.rooms.delete(roomId);
+                this.redisUnsubscribe(roomId, current);
+            }
+        };
+    }
+    publish(roomId, sender, frame) {
+        this.publishToRedis(roomId, sender, frame);
+        for (const listener of this.rooms.get(roomId)?.listeners ?? []) {
+            listener(sender, frame);
+        }
+    }
+    publishToRedis(roomId, sender, frame) {
+        const publisher = this.publisher;
+        const senderBytes = Buffer.from(sender, "utf8");
+        if (!publisher?.isReady || senderBytes.length === 0 || senderBytes.length > 255) {
+            this.stats.publishSkipped++;
+            return;
+        }
+        const message = Buffer.allocUnsafe(REDIS_RELAY_ORIGIN_BYTES + 1 + senderBytes.length + frame.length);
+        this.id.copy(message, 0);
+        message[REDIS_RELAY_ORIGIN_BYTES] = senderBytes.length;
+        senderBytes.copy(message, REDIS_RELAY_ORIGIN_BYTES + 1);
+        frame.copy(message, REDIS_RELAY_ORIGIN_BYTES + 1 + senderBytes.length);
+        this.stats.published++;
+        this.run("publish a frame", () => publisher.publish(redisRelayChannel(roomId), message));
+    }
+    redisSubscribe(roomId, room) {
+        const subscriber = this.subscriber;
+        if (!subscriber) {
+            return;
+        }
+        const onMessage = (message) => this.receive(roomId, message);
+        room.onMessage = onMessage;
+        this.run("subscribe to a room", () => subscriber.subscribe(redisRelayChannel(roomId), onMessage, true));
+    }
+    redisUnsubscribe(roomId, room) {
+        const subscriber = this.subscriber;
+        if (!subscriber || !room.onMessage) {
+            return;
+        }
+        const onMessage = room.onMessage;
+        this.run("unsubscribe from a room", () => subscriber.unsubscribe(redisRelayChannel(roomId), onMessage, true));
+    }
+    /** Handles one message of a room's channel: parses it defensively and hands its frame to the local listeners,
+     * unless this very bus published it. Never throws - it runs inside the Redis client's own message dispatch. */
+    receive(roomId, message) {
+        try {
+            const listeners = this.rooms.get(roomId)?.listeners;
+            const parsed = listeners ? this.parse(message) : undefined;
+            if (!listeners || !parsed) {
+                this.stats.receivedDropped++;
+                return;
+            }
+            this.stats.received++;
+            for (const listener of listeners) {
+                listener(parsed.sender, parsed.frame);
+            }
+        }
+        catch (err) {
+            this.report("deliver a frame", err);
+        }
+    }
+    /** Splits a Redis message into its sender and frame; `undefined` for a garbled one or this bus's own. */
+    parse(message) {
+        if (!Buffer.isBuffer(message) || message.length < REDIS_RELAY_ORIGIN_BYTES + 3) {
+            return undefined;
+        }
+        if (message.subarray(0, REDIS_RELAY_ORIGIN_BYTES).equals(this.id)) {
+            return undefined;
+        }
+        const senderLength = message[REDIS_RELAY_ORIGIN_BYTES];
+        const frameStart = REDIS_RELAY_ORIGIN_BYTES + 1 + senderLength;
+        // A peer id is never empty and the frame carries at least its own header.
+        if (senderLength === 0 || frameStart >= message.length) {
+            return undefined;
+        }
+        return { sender: message.toString("utf8", REDIS_RELAY_ORIGIN_BYTES + 1, frameStart), frame: message.subarray(frameStart) };
+    }
+    /** Runs a Redis command without waiting for it: a failure, thrown or rejected, is only counted and logged. */
+    run(what, command) {
+        (async () => {
+            await command();
+        })().catch((err) => this.report(what, err));
+    }
+    /** Counts a failure and logs it - at `warn` once per `REDIS_RELAY_WARN_INTERVAL_MS`, at `debug` in between. */
+    report(what, err) {
+        this.stats.failures++;
+        const message = `Relay redis bus failed to ${what}: ${err?.message ?? err}`;
+        const now = Date.now();
+        if (now - this.lastWarn >= REDIS_RELAY_WARN_INTERVAL_MS) {
+            this.lastWarn = now;
+            this.options.logger.warn(message);
+        }
+        else {
+            this.options.logger.debug(message);
+        }
+    }
+}
+//# sourceMappingURL=RedisRelayBus.js.map

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

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

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