Module Rooms

Room-based WebRTC peer-to-peer communication with pluggable signaling drivers.

The Room class manages peer connections, media streams, and data channels, coordinating signaling through a driver backend (NATS, MQTT, SSE, etc.) and supporting extendable add-ons for additional capabilities.

The following diagram provides a high-level overview of the Peerix architecture and its components:

graph TD
  PX{{Room}} --> SD(Signaling Drivers)
  SD --> SS[Signaling Servers]
  PX --> ICE[STUN/TURN Servers]
  PX --> PC(Peers)
  PC --> LCE(Lifecycle Events)
  PC --> MS(Media Streams)
  PC --> DC(Data Channels)
  PX --> ADD(Add-ons)

Signaling drivers extend Driver to bridge Peerix with a messaging backend (MQTT, NATS, SSE, SocketIo, Centrifuge, Supabase, BroadcastChannel, or in-memory). Drivers receive a pre-configured client via the constructor and never import external libraries. Signaling messages are protobuf-encoded with optional compression and AES-GCM encryption, exchanged over two namespaces — one for broadcast peer discovery and one scoped to each peer ID.

import { MqttDriver } from "peerix";
import { connect } from "mqtt";
const client = connect("ws://localhost:9001/mqtt");
const driver = new MqttDriver({ client });
Copy

Peer connections are represented by Peer instances that wrap RTCPeerConnection. The Room creates them automatically on peer discovery, handling SDP negotiation, ICE candidate exchange with configurable debouncing, and offer-collision resolution using polite semantics. Connections transition through states — new, connecting, connected, disconnected, failed, closed — with an optional timeout for failure recovery.

import { Room } from "peerix";
const room = new Room({ id: "my-room", driver });
await room.join({ name: "Alice" });
// await room.leave();
Copy

Data channels provide reliable, ordered messaging over RTCDataChannel. Large payloads are chunked (~16 KB MTU) and reassembled transparently. Four payload types are supported — text, JSON, Blob/File, and raw bytes — with back-pressure management, transfer progress tracking, and abort support via AbortSignal. Channels are opened via Room.open and use string labels for identification.

await room.open({ label: "chat" });
await room.send("Hello, world!", { label: "chat" });
Copy

Media streams are published by label using Room.share. You can configure encoding parameters (bitrate, framerate, scale factor, priority) and control track lifecycle with the managed flag. Stream replacements trigger re-negotiation so remote peers receive updated media seamlessly.

const stream = await navigator.mediaDevices.getUserMedia({
  video: true, audio: true
});
await room.share({ stream, label: "camera" });
// await room.unshare({ label: "camera" });
Copy

Lifecycle events cover connection state changes (connection:connected, connection:closed, etc.), data channel activity (channel:open, channel:message, etc.), stream modifications (stream:add, stream:remove), track changes (track:add, track:remove), and errors. Each event carries a Peer reference for easy correlation.

room.on("connection", (e) => {
  const { peer, state } = e;
  console.log(peer, state);
});
room.on("stream", (e) => {
  const { peer, stream, label } = e;
  console.log(peer, stream, label);
});
room.on("channel:message", async (e) => {
  const { peer, data } = e;
  const message = await data;
  console.log(peer, message);
});
Copy

ICE servers (STUN/TURN) are used for NAT traversal and peer discovery. STUN servers help peers discover their public address, while TURN servers relay media when direct connections fail. Pass an array of server configs via the iceServers option — without them, only local network connections are possible. Use iceTransportPolicy: "relay" to force TURN usage.

const room = new Room({
  id: "my-room",
  iceServers: [
    { urls: "stun:stun.l.google.com:19302" },
  ],
  iceTransportPolicy: "all",
});
Copy