Scaling large rooms
Standard WebRTC rooms connect every browser directly to every other browser. For small sessions up to roughly 10 peers, a full mesh gives the lowest latency and smallest bundle. Once rooms grow to dozens of participants, maintaining an all-to-all mesh taxes per-device CPU, bandwidth, and socket limits.
Enabling scale()
The experimental scale() plugin builds a multi-hop overlay
for cooperative rooms with dozens of peers (tested up to 48 concurrent
browser instances and 250+ simulated peers). Projects that do not import
scale tree-shake the overlay code out of their bundle (~10.6
KB compressed when included).
import {joinRoom, scale} from 'trystero'
const room = joinRoom(
{appId: 'canvas.example.com', use: [scale()]},
'plaza-1'
)Topology behavior
- Small groups stay direct. With
maxDirectPeers + 1or fewer peers in the room (7 at the default of 6), everyone connects in a full mesh with no overlay framing. - Larger groups form a multi-hop overlay. Beyond that
threshold, each browser maintains roughly
maxDirectPeersdirect WebRTC links and forwards messages, RPC, and state across hops. - Room APIs stay identical.
makeUserState,makeState,makeAction,addStream,replaceTrack,ping, presence callbacks,getUsers(), androles()work the same across one hop or several.
Configuring maxDirectPeers
Set maxDirectPeers (4 to 32, default 6) to trade per-peer
connection count against average hop count.
const room = joinRoom(
{
appId: 'canvas.example.com',
use: [
scale({
maxDirectPeers: 8 // target direct WebRTC neighbors per peer (4..32)
})
]
},
'plaza-1'
) maxDirectPeers bounds direct WebRTC neighbor links per
endpoint, not total room membership. To limit unique users in the room,
pass maxUsers to
joinRoom().
Media and large binary transfers
Forwarding video streams or large files through intermediate browsers
would consume bystander upload bandwidth and add latency, so
scale() separates traffic by payload type:
- Messages, RPC, and state (≤ 16 KiB) travel over the multi-hop overlay, with end-to-end encryption on targeted unicast frames.
- Media streams and chunked transfers (> 16 KiB) promote target peers to direct 1-hop WebRTC connections on demand.
-
Because media bypasses intermediate hops, a presenter streaming video to
20 viewers still opens 20 direct connections, temporarily exceeding
maxDirectPeers. Awaitroom.addStream(…)oraction.send(…)to catch promotion errors.
Inspecting topology
When scale() is loaded, room.getTopology()
returns the local node's direct neighbors, reachable remote peers, routing
table, and packet counters. Await room.ready first if you
need the local peerId populated.
await room.ready
const topology = room.getTopology()
console.log({
myPeerId: topology.peerId,
directNeighbors: topology.directPeerIds,
remotePeers: topology.roomPeerIds,
routes: topology.routes, // {[peerId]: {nextHop, hops}}
stats: topology.stats // {messagesSent, messagesReceived, messagesForwarded, ...}
})
// Per-peer hop distance is also included on getPeers()
for (const [peerId, {direct, hops}] of Object.entries(room.getPeers())) {
console.log(peerId, direct ? 'direct' : `${hops} hops away`)
}Overlay design
- Room-salted multi-ring expander. Above
maxDirectPeers + 1peers, endpoints arrange acrossfloor(maxDirectPeers / 2)independent permuted Hamiltonian cycles, giving a symmetric target degree of at mostmaxDirectPeersandO(log N)diameter. During rapid join bursts, neighbor counts may temporarily exceed the target due to soft inbound ceilings and component-bridge admissions. - Mutually confirmed link state. Peers advertise signed link-state descriptors (180 s TTL, refreshed by heartbeats and verified traffic, with a 1.2 s churn grace window). Routes only traverse edges confirmed by both endpoints and apply a hop ceiling derived from the verified roster size.
- Frame signatures and unicast encryption. Each peer
generates ephemeral ECDSA P-256 signing and ECDH P-256 encryption keys.
Link descriptors, leave notices, broadcasts, and unicast headers are
signed and bound to
appId,roomId, and a per-origin sequence counter with replay-window deduplication and 60-second freshness bounds. Targeted frames are encrypted end to end between sender and recipient with ECDH + AES-256-GCM. - Cooperative forwarding model. Signatures, replay
windows, and unicast confidentiality hold even across untrusted
intermediate peers, though a modified client can drop packets routed
through it or open extra connections up to per-user and room caps. Pair
passwordwithroles()androom.ban()when moderating untrusted rooms.