DEV Community

Peerix
Peerix

Posted on

Signalling as a driver: how we built a transport-agnostic WebRTC library

#opensource #javascript #typescript #webdev

If you've ever tried to build a peer-to-peer app in the browser, you've probably noticed something: every WebRTC library makes the signalling decision for you.

PeerJS bundles its own broker. simple-peer leaves signalling entirely up to you. Most libraries in between hardcode one transport and build the API around it. Change your mind about signalling later, and you're rewriting a lot of code.
Peerix takes a different approach. The signalling layer is a driver — pluggable, swappable, and completely separate from the peer logic.

Two concerns, one library

WebRTC has two distinct problems mixed into one specification.
The first is signalling: how peers find each other and exchange the SDP offers, answers, and ICE candidates needed to set up a connection. This is a transport problem. You can solve it with WebSockets, NATS, BroadcastChannel between tabs, or anything else that can move a message from A to B.

The second is peer logic: managing the RTCPeerConnection, negotiating tracks, handling data channels, dealing with reconnection, race conditions, and lifecycle events. This is a state machine problem, and it has nothing to do with how the messages get there.

Coupling these two concerns is what makes most WebRTC libraries painful to use. Decouple them, and the API gets a lot simpler.

The driver analogy
Databases solved this years ago. ORMs don't bundle Postgres or MySQL they expose adapters. The same query runs against any backend.
Signalling should work the same way. The same peer code should run whether you're using NATS in production, BroadcastChannel for same-tab testing, or an in-memory driver in your unit tests.

The driver interface

A Peerix driver implements three methods:

jsimport { Driver } from 'peerix';

class MyDriver extends Driver {
  async subscribe(namespace, handler) {
    // listen for messages on a namespace
  }
  async unsubscribe(namespace, handler) {
    // stop listening
  }
  async dispatch(namespace, message) {
    // send a message on a namespace
  }
}
Enter fullscreen mode Exit fullscreen mode

That's the whole contract. If you can implement those three methods on top of your transport, you have a working signalling driver.
Here's a complete in-memory driver, useful for tests:

jsclass MemoryDriver extends Driver {
  constructor() {
    super();
    this.handlers = new Map();
  }
  subscribe(namespace, handler) {
    const k = namespace.join(':');
    if (!this.handlers.has(k)) this.handlers.set(k, new Set());
    this.handlers.get(k).add(handler);
  }
  unsubscribe(namespace, handler) {
    const k = namespace.join(':');
    this.handlers.get(k)?.delete(handler);
  }
  dispatch(namespace, message) {
    const k = namespace.join(':');
    if (!this.handlers.has(k)) return;
    for (const handler of this.handlers.get(k)) {
      setTimeout(() => handler(message), 0);
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Twenty-something lines, and you have a fully working signalling layer for testing.
What that buys you
The peer code never changes when you swap drivers. Here's a complete chat example using BroadcastChannel no backend, no server, just two tabs talking to each other:

jsimport { Peer, BroadcastChannelDriver } from 'peerix';

const driver = new BroadcastChannelDriver();
const peer = new Peer({ driver });

peer.on('channel:open', (e) => {
  const { remote, label } = e;
  remote.send(`Hello, ${remote.metadata.name}!`, { label });
});

peer.on('channel:message', (e) => {
  console.log(`Received from ${e.remote.metadata.name}:`, e.data);
});

peer.open({ label: 'chat' });
peer.join({ room: 'room-id', metadata: { name: 'Guest' } });
Enter fullscreen mode Exit fullscreen mode

Swap BroadcastChannelDriver for NATSDriver and the same code runs across the internet. Swap it for MemoryDriver and it runs inside your test suite.

What Peerix handles for you

Beyond the driver layer, Peerix takes care of the parts of WebRTC most people don't want to write themselves: a single peer connection per peer (multiplexing all media tracks and data channels), automatic negotiation including race conditions and collisions, and lifecycle events for rooms, connections, streams, and channels.
It's not an SFU or MCU, there's no server-side media processing. If you need to record a composite video of fifty people, look at LiveKit or Daily. Peerix is for client-side peer-to-peer.

Try it
There's a live sandbox where you can open multiple tabs and watch peers connect:

👉 Open the sandbox

Docs: https://peerix.dev/docs
GitHub: https://github.com/peerix-dev/peerix

Peerix is GPLv3, with a commercial licence available. It's v0.1.0 early, but usable. I'd like to hear what you think of the driver interface.

Top comments (0)