rtc_turn/lib.rs
1#![warn(rust_2018_idioms)]
2#![warn(missing_docs)]
3#![allow(dead_code)]
4
5//! TURN for the Sans-I/O WebRTC stack.
6//!
7//! Traversal Using Relays around NAT ([RFC 5766]) with IPv6 support ([RFC 6156]). TURN is
8//! ICE's fallback: when no direct path between two peers can be found, each relays its
9//! media through a server, which allocates a public address on their behalf.
10//!
11//! # Structure
12//!
13//! * [`client`] — the Sans-I/O client: allocate a relayed address, create permissions,
14//! bind channels, and send or receive through the allocation. It owns no sockets.
15//! * [`proto`] — the TURN-specific STUN attributes and methods (`ALLOCATE`,
16//! `CREATE-PERMISSION`, `CHANNEL-BIND`, `XOR-RELAYED-ADDRESS`, ChannelData framing),
17//! built on [`rtc-stun`].
18//!
19//! # Example
20//!
21//! A client is configured with the server to allocate from and the long-term credentials to
22//! authenticate with; driving it is then a matter of feeding it datagrams and polling for
23//! [`Event`](client::Event)s:
24//!
25//! ```
26//! use rtc_turn::client::ClientConfig;
27//! use shared::TransportProtocol;
28//!
29//! let config = ClientConfig {
30//! turn_serv_addr: "turn.example.com:3478".to_owned(),
31//! local_addr: "0.0.0.0:0".parse().unwrap(),
32//! transport_protocol: TransportProtocol::UDP,
33//! username: "user".to_owned(),
34//! password: "pass".to_owned(),
35//! realm: "example.com".to_owned(),
36//! stun_serv_addr: String::new(), // optional: only for Binding requests
37//! software: String::new(),
38//! rto_in_ms: 0, // 0 selects the default retransmission timeout
39//! allocation_refresh_interval_cap: None,
40//! };
41//! assert_eq!(config.turn_serv_addr, "turn.example.com:3478");
42//! ```
43//!
44//! Most applications do not depend on this crate directly — [`rtc-ice`] gathers relay
45//! candidates through it, and the [`rtc`](https://docs.rs/rtc) crate drives that.
46//!
47//! [RFC 5766]: https://datatracker.ietf.org/doc/html/rfc5766
48//! [RFC 6156]: https://datatracker.ietf.org/doc/html/rfc6156
49//! [`rtc-stun`]: https://docs.rs/rtc-stun
50//! [`rtc-ice`]: https://docs.rs/rtc-ice
51
52/// The Sans-I/O TURN client: allocate a relayed address and send through it.
53/// The crypto provider API.
54///
55/// Re-exported because this crate's public constructors take an
56/// [`Arc<dyn RTCCryptoProvider>`](crypto::RTCCryptoProvider), which a caller must be able to name
57/// without adding — and version-matching — a direct `rtc-crypto` dependency.
58pub use crypto;
59
60pub mod client;
61/// The TURN-specific STUN attributes, methods and ChannelData framing.
62pub mod proto;