@nolag/signal

WebRTC signalling over NoLag: peer discovery, offer/answer exchange, and ICE candidate relay.

Overview

WebRTC needs a signalling channel before a peer connection can exist. Two browsers cannot exchange session descriptions or ICE candidates over WebRTC itself, because that is the very thing they are negotiating. Something else has to carry those messages, and it has to know who is in the call.

@nolag/signal is that channel. It handles peer discovery through presence, routes offers, answers and ICE candidates to a specific peer, and tells you when someone joins or leaves. It does not touch RTCPeerConnection: the media is yours, this moves the negotiation.

Key Features

• Peer discovery through room presence, so you know who to call
• Directed offer, answer and ICE candidate delivery
• Join and leave events, including hangup
• Arbitrary metadata per peer, for display names or capabilities
• Automatic reconnection with presence restored

How It Works

NoLagSignal attaches to an injected @nolag/js-sdk client. Joining a room returns a SignalRoom, which subscribes to one topic and advertises the local peer through presence. Every message is addressed to a specific peer id, so a room with several participants does not broadcast negotiation traffic to everyone.

Signalling is deliberately ephemeral. A replayed offer is worse than no offer: by the time it arrives the peer connection it referred to is long gone.

Installation

npm install @nolag/signal @nolag/js-sdk

Quick Start

import { NoLag } from '@nolag/js-sdk'
import { NoLagSignal } from '@nolag/signal'

const client = NoLag(async () => (await (await fetch('/api/nolag-token')).json()).token)

const signal = new NoLagSignal({
  client,
  metadata: { displayName: 'Alice' }
})

await client.connect()
await signal.ready()

const room = signal.joinRoom('standup')

// Someone new arrived: offer them a connection.
room.on('peerJoined', async (peer) => {
  const pc = createPeerConnection(peer.peerId)
  const offer = await pc.createOffer()
  await pc.setLocalDescription(offer)
  room.sendOffer(peer.peerId, offer)
})

// Everything addressed to us arrives here.
room.on('signal', async (message) => {
  const pc = peerConnectionFor(message.from)

  if (message.type === 'offer') {
    await pc.setRemoteDescription(message.payload)
    const answer = await pc.createAnswer()
    await pc.setLocalDescription(answer)
    room.sendAnswer(message.from, answer)
  }

  if (message.type === 'answer') {
    await pc.setRemoteDescription(message.payload)
  }

  if (message.type === 'ice') {
    await pc.addIceCandidate(message.payload)
  }
})

room.on('peerLeft', (peer) => teardown(peer.peerId))

// Trickle ICE as candidates are discovered.
pc.onicecandidate = ({ candidate }) => {
  if (candidate) room.sendIceCandidate(remotePeerId, candidate)
}

// Teardown
room.sendBye(remotePeerId)
signal.detach()
client.disconnect()

API Reference

NoLagSignal

The main class. Attaches to the injected core client and manages the room lifecycle.

Constructor Options

Methods

SignalRoom

Events