@nolag/signal

WebRTC signalling over NoLag: peer discovery, offer and 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 discovers peers through room presence, delivers offers, answers and ICE candidates addressed 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. Your app owns one core NoLag client and injects it into NoLagSignal; the wrapper attaches its behaviour to that connection.

Key Features

• Peer discovery through room presence, so you know who to call
• Offer, answer, ICE candidate, renegotiate and hangup messages addressed to one peer
• Join and leave events driven by presence
• Arbitrary metadata per peer, for display names or capabilities
• Optional broker-side addressing with filters

How It Works

NoLagSignal attaches to an injected @nolag/js-sdk client. Joining a room returns a SignalRoom, which subscribes to one topic, signaling, and advertises the local peer through presence. Every message carries a toPeerId. By default kraken delivers each message to every peer subscribed in the room and each receiver drops anything not addressed to it, which is fine for a handful of participants.

To make the broker do the addressing instead, join with your own peer id as a subscription filter and send with { filter: peer.peerId }. A peer that subscribes with filters no longer receives unfiltered messages, so adopt it on every peer or none. Peers without filters still receive filtered messages. See Filters.

Signalling messages are published with echo: false, so a peer never receives its own offer back. Nothing is stored: a peer that was not connected when an offer was sent never sees it, which is what you want, because the peer connection it referred to is gone.

Topics to grant

Grant these either in kraken's static token file or in a @nolag/core project document. See Static auth and Project document for the full formats.

{
  "tokens": {
    "alice-call-token": {
      "actorTokenId": "alice",
      "projectId": "demo-project",
      "organizationId": "demo-org",
      "actorType": "user",
      "allowedTopics": [
        {
          "pattern": "signal/call-room/signaling",
          "permission": "pubSub",
          "app_id": "signal-app",
          "room_id": "room-call-room",
          "room_slug": "call-room"
        }
      ],
      "allowedLobbies": [{ "lobby_slug": "online", "lobby_id": "signal-online" }]
    }
  }
}

Things that matter with the static file:

• Every peer that should reach the others needs the same app_id.
• Peer discovery is presence, and presence only works in rooms that have a rule carrying both room_slug and room_id. A catch-all rule such as signal/+/signaling lets a token use any room name, but no peer would ever see peerJoined in a room without its own rule.
• Without the allowedLobbies entry the lobby subscribe is refused: the wrapper emits an error (not_authorized) and ready() only resolves after the core SDK's 10 second lobby timeout.

For a call per meeting, a room per call works well with @nolag/core: create the room in core when the meeting is booked (or list it in the project document), and keep it private with grants. See Rooms and Access Control.

Installation

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

Quick Start

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

const client = NoLag('alice-call-token', { url: 'ws://localhost:8080/ws' })

const signal = new NoLagSignal({
  client,
  appName: 'signal', // the App Slug you granted
  metadata: { displayName: 'Alice' },
})

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

const room = signal.joinRoom('call-room')

// One RTCPeerConnection per remote peer, created on demand.
const peers = new Map<string, RTCPeerConnection>()

function peerConnectionFor(peerId: string): RTCPeerConnection {
  let pc = peers.get(peerId)
  if (pc) return pc
  pc = new RTCPeerConnection({ iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] })
  // Trickle ICE as candidates are discovered.
  pc.onicecandidate = ({ candidate }) => {
    if (candidate) room.sendIceCandidate(peerId, candidate.toJSON())
  }
  peers.set(peerId, pc)
  return pc
}

function teardown(peerId: string) {
  peers.get(peerId)?.close()
  peers.delete(peerId)
}

// Someone new arrived: offer them a connection.
room.on('peerJoined', async (peer) => {
  const pc = peerConnectionFor(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.fromPeerId)

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

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

  if (message.type === 'ice-candidate') {
    await pc.addIceCandidate(message.payload as RTCIceCandidateInit)
  }

  // A hangup is a signal, not a presence change: peerLeft does not fire for it.
  if (message.type === 'bye') {
    teardown(message.fromPeerId)
  }
})

// Presence says they are gone (closed tab, lost connection).
room.on('peerLeft', (peer) => teardown(peer.peerId))

// Hang up on everyone, then release the wrapper and close the socket.
function hangUp() {
  for (const peerId of peers.keys()) {
    room.sendBye(peerId)
    teardown(peerId)
  }
  signal.detach()
  client.disconnect()
}

Both sides of a new pair see each other through presence, so in this sketch both may send an offer at the same time ("glare"). Pick one side to offer, for example the peer with the lower peerId, or use the perfect negotiation pattern.

Directed delivery with filters

// Receive only signals addressed to this peer
const directRoom = signal.joinRoom('call-room', { filters: [signal.localPeer!.peerId] })

// Send to one peer and let the broker do the addressing
directRoom.sendOffer(remotePeerId, offer, { filter: remotePeerId })

Every peer in the room has to switch together: a filtered peer stops receiving the unfiltered messages that other peers send.

Reconnects

When the core client reconnects, the wrapper re-subscribes the online lobby, re-sets its presence in every joined room and then emits reconnected. It does not re-subscribe the signaling topic: it was written for a broker that restores subscriptions on its own. Do not rely on that with kraken (see Production); re-issue the subscription yourself:

signal.on('reconnected', () => {
  for (const room of signal.getRooms()) {
    const filters = room.filters.length > 0 ? { filters: room.filters } : {}
    client.setApp('signal').setRoom(room.name).subscribe('signaling', filters)
  }
})

The wrapper's message handler stays registered on the client, so subscribing again is enough. Peer connections that were live before the drop are your own to keep or renegotiate.

API Reference

NoLagSignal

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

Constructor Options

Methods and properties

Events

SignalRoom

opts on every send method accepts filter (one value) or filters (an AND group), so the broker delivers only to peers subscribed with that value, plus any peer subscribed without filters.

Events