Skip to main content

Module peer_connection

rtc

Module peer_connection 

Source
Expand description

Peer-to-peer connections

This module implements the RTCPeerConnection interface as defined in the W3C WebRTC specification. It provides the core functionality for establishing peer-to-peer connections, negotiating media capabilities, and managing data channels.

§Overview

RTCPeerConnection is the central interface in WebRTC. It handles:

  • Signaling: Creating and exchanging SDP offers/answers
  • ICE: Gathering candidates and establishing connectivity
  • Media: Managing audio/video tracks and transceivers
  • Data: Creating and managing data channels
  • Security: DTLS encryption for all communication

§Architecture

This is a sans-I/O implementation, meaning it separates protocol logic from I/O operations. The application is responsible for:

  • Transmitting/receiving network packets
  • Managing the event loop
  • Handling signaling channel communication

§Sans-I/O Benefits

  • Flexibility: Works with any I/O runtime (tokio, async-std, blocking, etc.)
  • Testability: Protocol logic can be tested without network I/O
  • Control: Application has full control over threading and scheduling

§Connection Establishment

The typical WebRTC connection flow:

Peer A (Offerer)              Signaling Server              Peer B (Answerer)
════════════════              ════════════════              ═══════════════════
     │                               │                               │
     │ 1. create_offer()             │                               │
     │─────────────────┐             │                               │
     │                 │             │                               │
     │<────────────────┘             │                               │
     │                               │                               │
     │ 2. set_local_description()    │                               │
     │─────────────────┐             │                               │
     │                 │             │                               │
     │<────────────────┘             │                               │
     │                               │                               │
     │ 3. send offer (via signaling) │                               │
     │──────────────────────────────>│──────────────────────────────>│
     │                               │                               │
     │                               │  4. set_remote_description()  │
     │                               │                  ┌────────────┤
     │                               │                  │            │
     │                               │                  └───────────>│
     │                               │                               │
     │                               │       5. create_answer()      │
     │                               │                  ┌────────────┤
     │                               │                  │            │
     │                               │                  └───────────>│
     │                               │                               │
     │                               │  6. set_local_description()   │
     │                               │                  ┌────────────┤
     │                               │                  │            │
     │                               │                  └───────────>│
     │                               │                               │
     │ 7. receive answer             │<──────────────────────────────│
     │<──────────────────────────────┤                               │
     │                               │                               │
     │ 8. set_remote_description()   │                               │
     │─────────────────┐             │                               │
     │                 │             │                               │
     │<────────────────┘             │                               │
     │                               │                               │
     │ 9. ICE candidates exchanged   │                               │
     │<─────────────────────────────────────────────────────────────>│
     │                               │                               │
     │ 10. Media/data flows directly │                               │
     │<═════════════════════════════════════════════════════════════>│

§Examples

§Creating a Peer Connection

use rtc::peer_connection::RTCPeerConnectionBuilder;

// Create with default configuration
let mut pc = RTCPeerConnectionBuilder::new().build(Instant::now())?;

§Creating an Offer (Initiating Peer)

use rtc::peer_connection::RTCPeerConnectionBuilder;

let mut pc = RTCPeerConnectionBuilder::new().build(Instant::now())?;

// Add media track or data channel first
// pc.add_track(audio_track)?;

// Create offer
let offer = pc.create_offer(None)?;

// Set as local description
pc.set_local_description(Instant::now(), offer.clone())?;

// Send offer.sdp to remote peer via signaling channel
// signaling_channel.send(offer.sdp)?;

§Answering an Offer (Responding Peer)

use rtc::peer_connection::RTCPeerConnectionBuilder;
use rtc::peer_connection::sdp::RTCSessionDescription;

let mut pc = RTCPeerConnectionBuilder::new().build(Instant::now())?;

// Receive offer from remote peer
let offer = RTCSessionDescription::offer(remote_offer_sdp)?;

// Set as remote description
pc.set_remote_description(Instant::now(), offer)?;

// Create answer
let answer = pc.create_answer(None)?;

// Set as local description
pc.set_local_description(Instant::now(), answer.clone())?;

// Send answer.sdp to remote peer via signaling channel
// signaling_channel.send(answer.sdp)?;

§Adding Media Tracks

use rtc::peer_connection::RTCPeerConnectionBuilder;
use rtc::media_stream::MediaStreamTrack;
use rtc::rtp_transceiver::rtp_sender::RtpCodecKind;

let mut pc = RTCPeerConnectionBuilder::new().build(Instant::now())?;

// Add an audio track
let sender_id = pc.add_track(audio_track)?;

// Or add a transceiver for receiving
let transceiver_id = pc.add_transceiver_from_kind(RtpCodecKind::Video, None)?;

§Creating Data Channels

use rtc::peer_connection::RTCPeerConnectionBuilder;
use rtc::data_channel::RTCDataChannelInit;

let mut pc = RTCPeerConnectionBuilder::new().build(Instant::now())?;

// Create a reliable, ordered data channel
let init = RTCDataChannelInit {
    ordered: true,
    max_retransmits: None,
    ..Default::default()
};

let channel_id = pc.create_data_channel("my-channel", Some(init))?;

§ICE Candidate Exchange

use rtc::peer_connection::{RTCPeerConnection, RTCPeerConnectionBuilder};
use rtc::peer_connection::transport::RTCIceCandidateInit;

// When local candidates are gathered, send to remote peer
// (In sans-I/O, you'd poll for events to get candidates)

// When receiving remote candidate from signaling channel
let remote_candidate = RTCIceCandidateInit {
    candidate: "candidate:1 1 UDP 2130706431 192.168.1.100 54321 typ host".to_string(),
    ..Default::default()
};

pc.add_remote_candidate(remote_candidate)?;

§State Management

The peer connection maintains several state machines:

  • Signaling State: SDP negotiation progress (stable, have-local-offer, etc.)
  • ICE Connection State: Network connectivity status
  • ICE Gathering State: Candidate gathering progress
  • Connection State: Overall connection health

Monitor these states through the event system (sans-I/O polling).

§Thread Safety

RTCPeerConnection is not thread-safe. The application must ensure exclusive access or use appropriate synchronization primitives.

§Specification

Modules§

certificate
X.509 certificate management for WebRTC DTLS authentication.
configuration
WebRTC peer connection configuration module.
event
WebRTC peer connection event types.
message
WebRTC message types for media and data transport.
sdp
Session Description Protocol (SDP) types and utilities.
state
WebRTC connection state types.
transport
WebRTC transport layer types for ICE, DTLS, and SCTP.

Structs§

RTCPeerConnection
The RTCPeerConnection interface represents a WebRTC connection between the local computer and a remote peer. It provides methods to connect to a remote peer, maintain and monitor the connection, and close the connection once it’s no longer needed.
RTCPeerConnectionBuilder
Builder for creating RTCPeerConnection instances.