peerix - v0.8.0
    Preparing search index...

    Module Drivers

    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:

    import { Driver } from "peerix";

    class MyDriver extends Driver {
    #client;
    #handlers = new Map(); // namespace -> Set of handlers
    #onConnect = () => (this.active = true);
    #onDisconnect = () => (this.active = false);

    constructor({ client }) {
    super();
    this.#client = client;
    client.on("connect", this.#onConnect);
    client.on("disconnect", this.#onDisconnect);
    this.active = client.connected;
    }

    async subscribe(namespace, handler) {
    super.subscribe(namespace, handler);
    let handlers = this.#handlers.get(namespace);
    if (handlers) {
    handlers.add(handler);
    return;
    }
    handlers = new Set([handler]);
    this.#handlers.set(namespace, handlers);
    try {
    // One client subscription per namespace, shared by its handlers.
    await this.#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);
    }
    throw err;
    }
    }

    async unsubscribe(namespace, handler) {
    super.unsubscribe(namespace, handler);
    const handlers = 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);
    await this.#client.unsubscribe(namespace);
    }

    async publish(namespace, data) {
    super.publish(namespace, data);
    await this.#client.publish(namespace, data);
    }

    destroy() {
    super.destroy();
    this.#client.off("connect", this.#onConnect);
    this.#client.off("disconnect", this.#onDisconnect);
    this.#handlers.clear();
    }
    }
    • 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.
    • Release the client's listeners in destroy().

    Then use it:

    const driver = new MyDriver({ client });
    
    BroadcastChannelDriver
    CentrifugeDriver
    Driver
    MemoryDriver
    MqttDriver
    NatsDriver
    NostrDriver
    SocketIoDriver
    SseDriver
    SupabaseDriver
    DriverEvents