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//! };
40//! assert_eq!(config.turn_serv_addr, "turn.example.com:3478");
41//! ```
42//!
43//! Most applications do not depend on this crate directly — [`rtc-ice`] gathers relay
44//! candidates through it, and the [`rtc`](https://docs.rs/rtc) crate drives that.
45//!
46//! [RFC 5766]: https://datatracker.ietf.org/doc/html/rfc5766
47//! [RFC 6156]: https://datatracker.ietf.org/doc/html/rfc6156
48//! [`rtc-stun`]: https://docs.rs/rtc-stun
49//! [`rtc-ice`]: https://docs.rs/rtc-ice
50
51/// The Sans-I/O TURN client: allocate a relayed address and send through it.
52pub mod client;
53/// The TURN-specific STUN attributes, methods and ChannelData framing.
54pub mod proto;