Drivers route signaling messages between peers over any transport
(MQTT, NATS, SSE, etc.). Implement subscribe, unsubscribe, and
publish to handle message routing by namespace. The active
property reflects the connection state.
Peerix minimizes signaling overhead by migrating connections to a
dedicated data channel after handshake, using binary messages,
debouncing ICE candidates, compressing payloads, and supporting
built-in namespace hashing and encryption of messages between peers.
%%{init:{"theme":"dark"}}%%
sequenceDiagram
Peer A -->> Peer B: broadcast announce
Peer B ->> Peer A: invoke
Peer A ->> Peer B: SDP offer
Peer B ->> Peer A: SDP answer
Peer B <<->> Peer A: ICE candidates
%%{init:{"theme":"default"}}%%
sequenceDiagram
Peer A -->> Peer B: broadcast announce
Peer B ->> Peer A: invoke
Peer A ->> Peer B: SDP offer
Peer B ->> Peer A: SDP answer
Peer B <<->> Peer A: ICE candidates
sequenceDiagram
Peer A -->> Peer B: broadcast announce
Peer B ->> Peer A: invoke
Peer A ->> Peer B: SDP offer
Peer B ->> Peer A: SDP answer
Peer B <<->> Peer A: ICE candidates
This flow runs automatically. Connecting two peers takes about
4 messages per peer, roughly 1 KB with compression and
encryption enabled.
Signaling Type
Sent Size
Overhead
Raw Signaling
1468 bytes
0%
Encrypted Signaling
1551 bytes
+6%
Compressed Signaling
806 bytes
-45%
Compressed & Encrypted
891 bytes
-39%
Sometimes the built-in signaling drivers may not fit your specific use case or
requirements. In such cases you can implement your own custom driver by extending
this class and overriding subscribe, unsubscribe, and publish. This
example wraps a generic pub/sub client:
asyncsubscribe(namespace, handler) { super.subscribe(namespace, handler); lethandlers = this.#handlers.get(namespace); if (handlers) { handlers.add(handler); return; } handlers = newSet([handler]); this.#handlers.set(namespace, handlers); try { // One client subscription per namespace, shared by its handlers. awaitthis.#client.subscribe(namespace, (data) => { this.#handlers.get(namespace)?.forEach((h) =>h(data)); }); } catch (err) { // Otherwise later subscribers would find the namespace and skip joining. if (this.#handlers.get(namespace) === handlers) { this.#handlers.delete(namespace); } throwerr; } }
asyncunsubscribe(namespace, handler) { super.unsubscribe(namespace, handler); consthandlers = this.#handlers.get(namespace); if (!handlers?.delete(handler) || handlers.size) return; // Another room on this driver may still use the namespace. this.#handlers.delete(namespace); awaitthis.#client.unsubscribe(namespace); }
Set this.active to reflect the connection. Messages are only published while the driver is active, and switching back to active makes joined rooms announce themselves again. A namespace that fails on its own shouldn't turn the driver inactive: retry it, and call this.emit("active") once it is subscribed again, so that rooms announce themselves to the peers they missed.
data is the encoded message as an array of byte values (number[]), so it survives JSON-based transports. Deliver the same array to the handler on the receiving side.
The super calls emit the driver's subscribe, unsubscribe, and publish events, as the built-in drivers do.
Several handlers may subscribe to the same namespace, for example two rooms with the same ID on one driver, so keep the transport subscription until the last one unsubscribes.
Drivers route signaling messages between peers over any transport (MQTT, NATS, SSE, etc.). Implement
subscribe,unsubscribe, andpublishto handle message routing by namespace. Theactiveproperty reflects the connection state.Peerix minimizes signaling overhead by migrating connections to a dedicated data channel after handshake, using binary messages, debouncing ICE candidates, compressing payloads, and supporting built-in namespace hashing and encryption of messages between peers.
This flow runs automatically. Connecting two peers takes about 4 messages per peer, roughly 1 KB with compression and encryption enabled.
Sometimes the built-in signaling drivers may not fit your specific use case or requirements. In such cases you can implement your own custom driver by extending this class and overriding
subscribe,unsubscribe, andpublish. This example wraps a generic pub/sub client:this.activeto reflect the connection. Messages are only published while the driver is active, and switching back to active makes joined rooms announce themselves again. A namespace that fails on its own shouldn't turn the driver inactive: retry it, and callthis.emit("active")once it is subscribed again, so that rooms announce themselves to the peers they missed.datais the encoded message as an array of byte values (number[]), so it survives JSON-based transports. Deliver the same array to the handler on the receiving side.supercalls emit the driver'ssubscribe,unsubscribe, andpublishevents, as the built-in drivers do.destroy().Then use it: