Signalisation WebRTC

bext gère uniquement la signalisation WebRTC — l'échange d'offres/réponses SDP et de candidats ICE dont les pairs ont besoin pour établir une connexion directe. bext ne relaie pas les médias et n'agit pas comme un serveur STUN/TURN.

La signalisation WebRTC fait partie de bext-realtime. Aucun indicateur de fonctionnalité supplémentaire n'est requis au-delà du module temps réel de base.

Comment ça marche#

1. Les pairs se connectent à bext via WebSocket (ou SSE).
2. Ils rejoignent une salle de signalisation par leur nom.
3. bext relaie les messages SDP et ICE entre pairs dans la pièce.
4. Une fois que les pairs échangent suffisamment d’informations, ils se connectent directement (P2P).
5. bext ne se trouve plus dans le chemin de données.

   Peer A ──ws──▶ bext ◀──ws── Peer B
      │                          │
      └──── direct P2P ─────────┘

Salles de signalisation#

Les chambres isolent le trafic de signalisation. Une salle est créée lorsque le premier pair rejoint et détruite lorsque le dernier pair part.

const ws = new WebSocket("wss://example.com/__bext/rtc/room-42");

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  switch (msg.type) {
    case "PeerJoined":
      startOffer(msg.peerId);
      break;
    case "Offer":
      handleOffer(msg.peerId, msg.sdp);
      break;
    case "Answer":
      handleAnswer(msg.peerId, msg.sdp);
      break;
    case "IceCandidate":
      addCandidate(msg.peerId, msg.candidate);
      break;
    case "PeerLeft":
      removePeer(msg.peerId);
      break;
  }
};

Les noms de salles sont des chaînes arbitraires. Utilisez-les pour étendre la signalisation à un appel, à un lobby de jeu ou à une session de transfert de fichiers.

Types de messages#

Tous les messages sont au format JSON avec un champ type :

Rejoint par les pairs#

Envoyé aux pairs existants lorsqu’un nouveau pair entre dans la salle.

{
  "type": "PeerJoined",
  "peerId": "abc-123",
  "metadata": { "name": "Alice" }
}

Offre#

Une offre SDP transmise d’un homologue à un autre.

{
  "type": "Offer",
  "peerId": "abc-123",
  "targetPeerId": "def-456",
  "sdp": "v=0\r\no=- ..."
}

Répondre#

Une réponse SDP en réponse à une offre.

{
  "type": "Answer",
  "peerId": "def-456",
  "targetPeerId": "abc-123",
  "sdp": "v=0\r\no=- ..."
}

Candidat à la glace#

Un filet de candidat ICE relayé entre pairs.

{
  "type": "IceCandidate",
  "peerId": "abc-123",
  "targetPeerId": "def-456",
  "candidate": {
    "candidate": "candidate:1 1 UDP ...",
    "sdpMLineIndex": 0,
    "sdpMid": "0"
  }
}

PairGauche#

Envoyé aux pairs restants lorsque quelqu'un se déconnecte.

{
  "type": "PeerLeft",
  "peerId": "abc-123"
}

Configuration#

[realtime.signaling]
enabled = true
max_room_size = 50
room_idle_timeout_secs = 300

Pas d'étourdissement/retour#

bext achemine uniquement les messages de signalisation. Il n'implémente pas les serveurs STUN ou TURN. Pour les homologues derrière des NAT symétriques, vous avez besoin d'un serveur TURN externe. Dirigez les clients vers ce dernier dans la configuration RTCPeerConnection :

const pc = new RTCPeerConnection({
  iceServers: [
    { urls: "stun:stun.example.com:3478" },
    { urls: "turn:turn.example.com:3478", username: "u", credential: "p" },
  ],
});

Cas d'utilisation#

• Appels vocaux et vidéo — échangez SDP contre des pistes multimédias, puis diffusez en streaming directement entre les navigateurs.
• Transfert de fichiers — négociez un DataChannel, transférez des fichiers P2P sans coût de la bande passante du serveur.
• Jeux multijoueurs — DataChannels pour une synchronisation de l'état du jeu à faible latence entre joueurs.
• Partage d'écran — ajoutez une piste de capture d'écran à un homologue existant connexion.

Authentification#

Les connexions de signalisation WebSocket passent par le middleware d'authentification standard de bext. Exiger une authentification sur le point de terminaison de signalisation pour empêcher tout accès non autorisé à la salle :

[[routes]]
path = "/__bext/rtc/*"
auth = "required"

Les métadonnées des pairs (comme le nom d'affichage) sont jointes lors de la jointure et transférées dans Messages PeerJoined permettant aux autres pairs d'identifier qui se trouve dans la pièce.

Métrique#

En rapport#

• WebSockets — le transport utilisé pour les connexions de signalisation
• Événements envoyés par le serveur — transport alternatif pour les messages de signalisation unidirectionnels
• WebTransport — Transport à faible latence basé sur HTTP/3 pour les cas d'utilisation adjacents aux médias
• Capacité d'authentification — sécurisation des points de terminaison de signalisation avec des clés JWT ou API
• Comprend : En temps réel — primitives temps réel de niveau supérieur dans bext

Links#

• webrtc.org — Site du projet WebRTC et ressources pour les développeurs
• RFC 8829 — Protocole d'établissement de session JavaScript (JSEP) — définit l'échange d'offre/réponse SDP utilisé dans la signalisation WebRTC