Crate preach

Platform independent data channels

Preach provides an abstraction for WebRTC data channels that runs on both native and web platforms. Preach manages the exchange of session descriptions and ICE candidates, making channel creation straightforward. Further, Preach offers a simple synchronous and asynchronous interface for exchanging messages, making it well-suited for a variety of purposes.

To create a WebRTC connection, one must first exchange information with the remote peer through a signaling server. Because signaling servers vary with use case, Preach does not provide a signaling server implementation. However, Preach does automatically dictate the information that should be sent to the signaling server.

Usage

For a complete example, see the tests.

To use Preach, a signaling server implementation must be supplied. This is accomplished by implementing the RtcNegotiationHandler trait:

/// Negotiates a connection with the remote peer during the initial connection process,
/// exchanging messages with the signaling server. 
pub trait RtcNegotiationHandler {
    /// Sends a negotiation message to the remote peer through a signaling implementation.
    fn send(&mut self, message: RtcNegotiationMessage) -> Pin<Box<dyn '_ + Future<Output = Result<(), RtcPeerConnectionError>>>>;
    /// Checks the signaling server for new negotiation messages from the remote peer.
    fn receive(&mut self) -> Pin<Box<dyn '_ + Future<Output = Result<Vec<RtcNegotiationMessage>, RtcPeerConnectionError>>>>;
}

This trait should be implemented so that any messages sent from one peer are received by the other, through the use of a signaling server. The server may otherwise function however the end user desires - for example, it could be implemented as a REST API.

Once a signaling mechanism is provided, creating a new set of channels is easy:

let ice_configuation = IceConfiguration {
    ice_servers: vec!(RtcIceServer { urls: vec!("stun:stun.l.google.com:19302".to_string()), ..Default::default() }),
    ice_transport_policy: RtcIceTransportPolicy::All
};
 
let negotiation_handler = ...; // Implementation of RtcNegotiationHandler
 
// Boths peers must use the same set of RtcDataChannelConfigurations for a connection to be created.
let channel = RtcDataChannel::connect(&ice_configuation, negotiation_handler,
    &[RtcDataChannelConfiguration { label: "chan".to_string(), ..Default::default() }]
).await.expect("An error occured during channel creation.")[0];
 
let msg = b"test msg";
 
// Send messages.
channel.send(&msg[..]).expect("Could not send message.");
 
// Receive messages.
assert_eq!(&msg[..], &channel.receive_async().await.expect("An error occurred on the channel.")[..]);

Optional features

vendored - Builds libdatachannel and OpenSSL statically on desktop platforms, bundling them into the build. wasm_main_executor - Allows for creating data channels within WASM web workers, and sharing them between threads. By default, restrictions on workers prevent them from instantiating and working with peer channels. This feature sidesteps said restrictions by deferring work to the main browser thread. When using this feature, wasm_main_executor::initialize() must be called before creating any data channels.

Structs

IceConfiguration

Describes the set of ICE servers and protocols that should be employed during connection establishment.

RtcDataChannel

A channel across which messages may be exchanged with a remote peer.

RtcDataChannelConfiguration

Describes how a channel should be created.

RtcIceCandidate

Describes a possible way to connect to a remote peer.

RtcIceServer

Describes a server that may be utilized for peer-to-peer route discovery or communication.

RtcSessionDescription

Describes a remote peer’s session.

Enums

RtcDataChannelError

Describes an error that occurred with an active data channel.

RtcDataChannelReadyState

Describes the current connection state of a channel.

RtcIceTransportPolicy

Determines the subset of ICE functionality that should be considered.

RtcNegotiationMessage

Provides data about a potential connection route to a remote peer.

RtcPeerConnectionError

Describes an error that occurred while attempting to establish a peer connection.

RtcReliabilityMode

Describes the guarantees that a data channel should make regarding how data is forwarded to the other side.

Traits

RtcNegotiationHandler

Negotiates a connection with the remote peer during the initial connection process, exchanging messages with the signaling server.