1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517
//! datachannel-facade is a library that abstracts over platform-specific WebRTC DataChannel implementations.
//!
//! It works both in the browser and natively (via [libdatachannel](https://libdatachannel.org)).
//!
//! The following docs are from [MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API).
mod sys;
pub mod platform;
/// The property RTCSessionDescription.type is a read-only string value which describes the description's type.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum SdpType {
/// The session description object describes the initial proposal in an offer/answer exchange. The session
/// negotiation process begins with an offer being sent from the caller to the callee.
Offer,
/// The SDP contained in the sdp property is the definitive choice in the exchange. In other words, this session
/// description describes the agreed-upon configuration, and is being sent to finalize negotiation.
Answer,
/// The session description object describes a provisional answer; that is, a response to a previous offer that is
/// not the final answer. It is usually employed by legacy hardware.
Pranswer,
/// This special type with an empty session description is used to roll back to the previous stable state.
Rollback,
}
/// The RTCSessionDescription interface describes one end of a connection—or potential connection—and how it's
/// configured. Each RTCSessionDescription consists of a description type indicating which part of the offer/answer
/// negotiation process it describes and of the SDP descriptor of the session.
///
/// The process of negotiating a connection between two peers involves exchanging RTCSessionDescription objects back and
/// forth, with each description suggesting one combination of connection configuration options that the sender of the
/// description supports. Once the two peers agree upon a configuration for the connection, negotiation is complete.
#[derive(Clone, Debug)]
pub struct Description {
/// An enum describing the session description's type.
pub type_: SdpType,
/// A string containing the SDP describing the session.
pub sdp: String,
}
/// An object providing configuration options for the data channel. It can contain the following fields:
pub struct DataChannelOptions {
/// Indicates whether or not messages sent on the RTCDataChannel are required to arrive at their destination in the
/// same order in which they were sent (true), or if they're allowed to arrive out-of-order (false). Default: true.
pub ordered: bool,
/// The maximum number of milliseconds that attempts to transfer a message may take in unreliable mode. While this
/// value is a 16-bit unsigned number, each user agent may clamp it to whatever maximum it deems appropriate.
/// Default: null.
pub max_packet_life_time: Option<u16>,
/// The maximum number of times the user agent should attempt to retransmit a message which fails the first time in
/// unreliable mode. While this value is a 16-bit unsigned number, each user agent may clamp it to whatever maximum
// it deems appropriate. Default: null.
pub max_retransmits: Option<u16>,
/// The name of the sub-protocol being used on the RTCDataChannel, if any; otherwise, the empty string ("").
/// Default: empty string (""). This string may not be longer than 65,535 bytes.
pub protocol: String,
/// By default (false), data channels are negotiated in-band, where one side calls createDataChannel, and the other
/// side listens to the RTCDataChannelEvent event using the ondatachannel event handler. Alternatively (true), they
/// can be negotiated out of-band, where both sides call createDataChannel with an agreed-upon ID. Default: false.
pub negotiated: bool,
/// A 16-bit numeric ID for the channel; permitted values are 0 to 65534. If you don't include this option, the user
/// agent will select an ID for you.
pub id: Option<u16>,
}
impl Default for DataChannelOptions {
fn default() -> Self {
Self {
ordered: true,
max_packet_life_time: None,
max_retransmits: None,
protocol: "".to_string(),
negotiated: false,
id: None,
}
}
}
/// The read-only connectionState property of the RTCPeerConnection interface indicates the current state of the peer
/// connection by returning one of the following string values: new, connecting, connected, disconnected, failed, or
/// closed.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PeerConnectionState {
/// At least one of the connection's ICE transports (RTCIceTransport or RTCDtlsTransport objects) is in the new
/// state, and none of them are in one of the following states: connecting, checking, failed, disconnected, or all
// of the connection's transports are in the closed state.
New,
/// One or more of the ICE transports are currently in the process of establishing a connection; that is, their
/// iceConnectionState is either checking or connected, and no transports are in the failed state.
Connecting,
/// Every ICE transport used by the connection is either in use (state connected or completed) or is closed (state
/// closed); in addition, at least one transport is either connected or completed.
Connected,
/// At least one of the ICE transports for the connection is in the disconnected state and none of the other
/// transports are in the states: failed, connecting, or checking.
Disconnected,
/// One or more of the ICE transports on the connection is in the failed state.
Failed,
/// The RTCPeerConnection is closed.
Closed,
}
/// The read-only property RTCPeerConnection.iceGatheringState returns a string that describes the connection's ICE
/// gathering state. This lets you detect, for example, when collection of ICE candidates has finished.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum IceGatheringState {
/// The peer connection was just created and hasn't done any networking yet.
New,
/// The ICE agent is in the process of gathering candidates for the connection.
Gathering,
/// The ICE agent has finished gathering candidates. If something happens that requires collecting new candidates,
/// such as a new interface being added or the addition of a new ICE server, the state will revert to gathering to
/// gather those candidates.
Complete,
}
/// A string representing the current ICE transport policy. Possible values are:
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum IceTransportPolicy {
/// All ICE candidates will be considered. This is the default value.
#[default]
All,
/// Only ICE candidates whose IP addresses are being relayed, such as those being passed through a TURN server, will
/// be considered.
Relay,
}
/// A server which may be used by the ICE agent; these are typically STUN and/or TURN servers.
#[derive(Debug, Clone)]
pub struct IceServer {
/// This required property is either a single string or an array of strings, each specifying a URL which can be used
/// to connect to the server.
pub urls: Vec<String>,
/// If the object represents a TURN server, then this is the username to use during the authentication.
pub username: Option<String>,
/// The credential to use when logging into the server. This is only used if the object represents a TURN server.
pub credential: Option<String>,
}
/// An object providing options to configure the new connection:
#[derive(Debug, Default, Clone)]
pub struct Configuration {
/// An array of objects, each describing one server which may be used by the ICE agent; these are typically STUN
/// and/or TURN servers. If this isn't specified, the connection attempt will be made with no STUN or TURN server
/// available, which limits the connection to local peers. Each object may have the following properties:
pub ice_servers: Vec<IceServer>,
/// A string representing the current ICE transport policy. Possible values are:
pub ice_transport_policy: IceTransportPolicy,
sys: sys::Configuration,
}
/// An underlying platform error.
#[derive(thiserror::Error, Debug)]
#[error("{0}")]
pub struct Error(Box<dyn std::error::Error + Send + Sync + 'static>);
/// 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.
pub struct PeerConnection {
inner: sys::PeerConnection,
}
impl PeerConnection {
/// Returns a new RTCPeerConnection, representing a connection between the local device and a remote peer.
pub fn new(config: Configuration) -> Result<Self, Error> {
Ok(Self {
inner: sys::PeerConnection::new(config)?,
})
}
/// Closes the current peer connection.
pub fn close(&self) -> Result<(), Error> {
self.inner.close()
}
/// The RTCPeerConnection method setLocalDescription() changes the local description associated with the connection.
/// This description specifies the properties of the local end of the connection, including the media format. The
/// method takes a single parameter—the session description—and it returns a Promise which is fulfilled once the
/// description has been changed, asynchronously.
///
/// <div class="warning">
/// In datachannel-facade, this will also perform createOffer/createAnswer behind the scenes. The resulting
/// description can be retrieved by calling PeerConnection::local_description.
/// </div>
pub async fn set_local_description(&self, type_: SdpType) -> Result<(), Error> {
self.inner.set_local_description(type_).await
}
/// The RTCPeerConnection method setRemoteDescription() sets the specified session description as the remote peer's
/// current offer or answer. The description specifies the properties of the remote end of the connection, including
/// the media format. The method takes a single parameter—the session description—and it returns a Promise which is
/// fulfilled once the description has been changed, asynchronously.
///
/// This is typically called after receiving an offer or answer from another peer over the signaling server. Keep in
/// mind that if setRemoteDescription() is called while a connection is already in place, it means renegotiation is
/// underway (possibly to adapt to changing network conditions).
///
// Because descriptions will be exchanged until the two peers agree on a configuration, the description submitted by
// calling setRemoteDescription() does not immediately take effect. Instead, the current connection configuration
// remains in place until negotiation is complete. Only then does the agreed-upon configuration take effect.
pub async fn set_remote_description(&self, description: &Description) -> Result<(), Error> {
self.inner.set_remote_description(description).await
}
/// The read-only property RTCPeerConnection.localDescription returns an RTCSessionDescription describing the
/// session for the local end of the connection. If it has not yet been set, this is null.
pub fn local_description(&self) -> Result<Option<Description>, Error> {
self.inner.local_description()
}
/// The read-only property RTCPeerConnection.remoteDescription returns a RTCSessionDescription describing the
/// session (which includes configuration and media information) for the remote end of the connection. If this
/// hasn't been set yet, this is null.
///
/// The returned value typically reflects a remote description which has been received over the signaling server (as
/// either an offer or an answer) and then put into effect by your code calling
/// RTCPeerConnection.setRemoteDescription() in response.
pub fn remote_description(&self) -> Result<Option<Description>, Error> {
self.inner.remote_description()
}
/// Adds a new remote candidate to the RTCPeerConnection's remote description, which describes the state of the
/// remote end of the connection.
pub async fn add_ice_candidate(&self, cand: Option<&str>) -> Result<(), Error> {
self.inner.add_ice_candidate(cand).await
}
/// An icecandidate event is sent to an RTCPeerConnection when:
///
/// - An RTCIceCandidate has been identified and added to the local peer by a call to
/// RTCPeerConnection.setLocalDescription(),
///
/// - Every RTCIceCandidate correlated with a particular username fragment and password combination (a generation)
/// has been so identified and added, and
///
/// - All ICE gathering on all transports is complete.
///
/// In the first two cases, the event handler should transmit the candidate to the remote peer over the signaling
/// channel so the remote peer can add it to its set of remote candidates.
pub fn set_on_ice_candidate(
&mut self,
cb: Option<impl Fn(Option<&str>) + Send + Sync + 'static>,
) {
self.inner.set_on_ice_candidate(cb)
}
/// The icegatheringstatechange event is sent to the onicegatheringstatechange event handler on an RTCPeerConnection
/// when the state of the ICE candidate gathering process changes. This signifies that the value of the connection's
/// iceGatheringState property has changed.
///
/// When ICE first starts to gather connection candidates, the value changes from new to gathering to indicate that
/// the process of collecting candidate configurations for the connection has begun. When the value changes to
/// complete, all of the transports that make up the RTCPeerConnection have finished gathering ICE candidates.
pub fn set_on_ice_gathering_state_change(
&mut self,
cb: Option<impl Fn(IceGatheringState) + Send + Sync + 'static>,
) {
self.inner.set_on_ice_gathering_state_change(cb)
}
/// The connectionstatechange event is sent to the onconnectionstatechange event handler on an RTCPeerConnection
/// object after a new track has been added to an RTCRtpReceiver which is part of the connection. The new connection
/// state can be found in connectionState, and is one of the string values: new, connecting, connected,
/// disconnected, failed, or closed.
pub fn set_on_connection_state_change(
&mut self,
cb: Option<impl Fn(PeerConnectionState) + Send + Sync + 'static>,
) {
self.inner.set_on_connection_state_change(cb)
}
/// A datachannel event is sent to an RTCPeerConnection instance when an RTCDataChannel has been added to the
/// connection, as a result of the remote peer calling RTCPeerConnection.createDataChannel().
pub fn set_on_data_channel(
&mut self,
cb: Option<impl Fn(DataChannel) + Send + Sync + 'static>,
) {
self.inner
.set_on_data_channel(cb.map(|cb| move |dc| cb(DataChannel { inner: dc })))
}
/// The createDataChannel() method on the RTCPeerConnection interface creates a new channel linked with the remote
/// peer, over which any kind of data may be transmitted. This can be useful for back-channel content, such as
/// images, file transfer, text chat, game update packets, and so forth.
pub fn create_data_channel(
&self,
label: &str,
options: DataChannelOptions,
) -> Result<DataChannel, Error> {
Ok(DataChannel {
inner: self.inner.create_data_channel(label, options)?,
})
}
}
/// The RTCDataChannel interface represents a network channel which can be used for bidirectional peer-to-peer transfers
/// of arbitrary data. Every data channel is associated with an RTCPeerConnection, and each peer connection can have up
/// to a theoretical maximum of 65,534 data channels (the actual limit may vary from browser to browser).
///
/// To create a data channel and ask a remote peer to join you, call the RTCPeerConnection's createDataChannel() method.
/// The peer being invited to exchange data receives a datachannel event (which has type RTCDataChannelEvent) to let it
/// know the data channel has been added to the connection.
pub struct DataChannel {
inner: sys::DataChannel,
}
impl DataChannel {
/// The WebRTC open event is sent to an RTCDataChannel object's onopen event handler when the underlying transport
/// used to send and receive the data channel's messages is opened or reopened.
pub fn set_on_open(&mut self, cb: Option<impl Fn() + Send + Sync + 'static>) {
self.inner.set_on_open(cb)
}
/// The close event is sent to the onclose event handler on an RTCDataChannel instance when the data transport for
/// the data channel has closed. Before any further data can be transferred using RTCDataChannel, a new
/// 'RTCDataChannel' instance must be created.
pub fn set_on_close(&mut self, cb: Option<impl Fn() + Send + Sync + 'static>) {
self.inner.set_on_close(cb)
}
/// A bufferedamountlow event is sent to an RTCDataChannel when the number of bytes currently in the outbound data
/// transfer buffer falls below the threshold specified in bufferedAmountLowThreshold. bufferedamountlow events
/// aren't sent if bufferedAmountLowThreshold is 0.
pub fn set_on_buffered_amount_low(&mut self, cb: Option<impl Fn() + Send + Sync + 'static>) {
self.inner.set_on_buffered_amount_low(cb)
}
/// A WebRTC error event is sent to an RTCDataChannel object's onerror event handler when an error occurs on the
/// data channel.
pub fn set_on_error(&mut self, cb: Option<impl Fn(Error) + Send + Sync + 'static>) {
self.inner.set_on_error(cb)
}
/// The WebRTC message event is sent to the onmessage event handler on an RTCDataChannel object when a message has
/// been received from the remote peer.
pub fn set_on_message(&mut self, cb: Option<impl Fn(&[u8]) + Send + Sync + 'static>) {
self.inner.set_on_message(cb)
}
/// The RTCDataChannel property bufferedAmountLowThreshold is used to specify the number of bytes of buffered
/// outgoing data that is considered "low." The default value is 0. When the number of buffered outgoing bytes, as
/// indicated by the bufferedAmount property, falls to or below this value, a bufferedamountlow event is fired. This
/// event may be used, for example, to implement code which queues more messages to be sent whenever there's room to
/// buffer them. Listeners may be added with onbufferedamountlow or addEventListener().
///
/// The user agent may implement the process of actually sending data in any way it chooses; this may be done
/// periodically during the event loop or truly asynchronously. As messages are actually sent, this value is reduced
/// accordingly.
pub fn set_buffered_amount_low_threshold(&self, value: u32) -> Result<(), crate::Error> {
self.inner.set_buffered_amount_low_threshold(value)
}
/// The read-only RTCDataChannel property bufferedAmount returns the number of bytes of data currently queued to be
/// sent over the data channel. The queue may build up as a result of calls to the send() method. This only includes
/// data buffered by the user agent itself; it doesn't include any framing overhead or buffering done by the
/// operating system or network hardware.
///
/// The user agent may implement the process of actually sending data in any way it chooses; this may be done
/// periodically during the event loop or truly asynchronously. As messages are actually sent, this value is reduced
/// accordingly.
pub fn buffered_amount(&self) -> Result<u32, crate::Error> {
self.inner.buffered_amount()
}
/// The RTCDataChannel.close() method closes the RTCDataChannel. Either peer is permitted to call this method to
/// initiate closure of the channel.
///
/// Closure of the data channel is not instantaneous. Most of the process of closing the connection is handled
/// asynchronously; you can detect when the channel has finished closing by watching for a close event on the data
/// channel.
pub fn close(&self) -> Result<(), crate::Error> {
self.inner.close()
}
/// The send() method of the RTCDataChannel interface sends data across the data channel to the remote peer. This
/// can be done any time except during the initial process of creating the underlying transport channel. Data sent
/// before connecting is buffered if possible (or an error occurs if it's not possible), and is also buffered if
/// sent while the connection is closing or closed.
pub fn send(&self, buf: &[u8]) -> Result<(), crate::Error> {
self.inner.send(buf)
}
}
#[cfg(test)]
mod test {
use super::*;
cfg_if::cfg_if! {
if #[cfg(target_arch = "wasm32")] {
wasm_bindgen_test::wasm_bindgen_test_configure!(run_in_browser);
}
}
#[cfg_attr(not(target_arch = "wasm32"), pollster::test)]
#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
pub async fn test_peer_connection_new() {
let pc = PeerConnection::new(Default::default()).unwrap();
pc.create_data_channel("test", Default::default()).unwrap();
}
#[cfg_attr(not(target_arch = "wasm32"), pollster::test)]
#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
pub async fn test_peer_connection_communicate() {
let mut pc1 = PeerConnection::new(Default::default()).unwrap();
let pc1_gathered = std::sync::Arc::new(async_notify::Notify::new());
pc1.set_on_ice_gathering_state_change(Some({
let pc1_gathered = std::sync::Arc::clone(&pc1_gathered);
move |ice_gathering_state| {
if ice_gathering_state == IceGatheringState::Complete {
pc1_gathered.notify();
}
}
}));
let mut dc1 = pc1
.create_data_channel(
"test",
DataChannelOptions {
negotiated: true,
id: Some(1),
..Default::default()
},
)
.unwrap();
let dc1_open = std::sync::Arc::new(async_notify::Notify::new());
dc1.set_on_open(Some({
let dc1_open = std::sync::Arc::clone(&dc1_open);
move || {
dc1_open.notify();
}
}));
pc1.set_local_description(SdpType::Offer).await.unwrap();
pc1_gathered.notified().await;
let mut pc2 = PeerConnection::new(Default::default()).unwrap();
let pc2_gathered = std::sync::Arc::new(async_notify::Notify::new());
pc2.set_on_ice_gathering_state_change(Some({
let pc2_gathered = std::sync::Arc::clone(&pc2_gathered);
move |ice_gathering_state| {
if ice_gathering_state == IceGatheringState::Complete {
pc2_gathered.notify();
}
}
}));
let mut dc2 = pc2
.create_data_channel(
"test",
DataChannelOptions {
negotiated: true,
id: Some(1),
..Default::default()
},
)
.unwrap();
let dc2_open = std::sync::Arc::new(async_notify::Notify::new());
dc2.set_on_open(Some({
let dc2_open = std::sync::Arc::clone(&dc2_open);
move || {
dc2_open.notify();
}
}));
let (tx1, rx1) = async_channel::bounded(1);
dc1.set_on_message(Some(move |msg: &[u8]| {
tx1.try_send(msg.to_vec()).unwrap();
}));
let (tx2, rx2) = async_channel::bounded(1);
dc2.set_on_message(Some(move |msg: &[u8]| {
tx2.try_send(msg.to_vec()).unwrap();
}));
pc2.set_remote_description(&pc1.local_description().unwrap().unwrap())
.await
.unwrap();
pc2.set_local_description(SdpType::Answer).await.unwrap();
pc2_gathered.notified().await;
pc1.set_remote_description(&pc2.local_description().unwrap().unwrap())
.await
.unwrap();
dc1_open.notified().await;
dc2_open.notified().await;
dc1.send(b"hello world!").unwrap();
assert_eq!(rx2.recv().await.unwrap(), b"hello world!");
dc2.send(b"goodbye world!").unwrap();
assert_eq!(rx1.recv().await.unwrap(), b"goodbye world!");
}
}