turn_client_proto/
lib.rs

1// Copyright (C) 2025 Matthew Waters <matthew@centricular.com>
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8//
9// SPDX-License-Identifier: MIT OR Apache-2.0
10
11//! # turn-client-proto
12//!
13//! `turn-client-proto` provides a sans-IO API for a TURN client communicating with a TURN server.
14//!
15//! Relevant standards:
16//! - [RFC5766]: Traversal Using Relays around NAT (TURN).
17//! - [RFC6062]: Traversal Using Relays around NAT (TURN) Extensions for TCP Allocations
18//! - [RFC6156]: Traversal Using Relays around NAT (TURN) Extension for IPv6
19//! - [RFC8656]: Traversal Using Relays around NAT (TURN): Relay Extensions to Session
20//!   Traversal Utilities for NAT (STUN)
21//!
22//! [RFC5766]: https://datatracker.ietf.org/doc/html/rfc5766
23//! [RFC6062]: https://tools.ietf.org/html/rfc6062
24//! [RFC6156]: https://tools.ietf.org/html/rfc6156
25//! [RFC8656]: https://tools.ietf.org/html/rfc8656
26//!
27//! # Getting Started
28//!
29//! The entry point for starting with a TURN client implementation depends on the transport
30//! protocol that you are looking to use. For UDP connections, you should start in the [`udp`]
31//! module, for TCP connections, the [`tcp`] module. (D)TLS functionality is contained within
32//! extension crates. e.g.
33//! - For TLS connections over TCP, the [`turn-client-rustls`], or [`turn-client-openssl`] crates
34//!   are available.
35//! - For DTLS connections over UDP, the [`turn-client-dimpl`] or [`turn-client-openssl`] crates
36//!   are available.
37//!
38//! From there, the [`api`] module provides the interface that all of the TURN clients implement and
39//! the [`client`] module can be used to combine one of the above options into a single value for
40//! selection based on the underlying TURN client.
41//!
42//! [`turn-client-rustls`]: https://docs.rs/turn-client-rustls
43//! [`turn-client-openssl`]: https://docs.rs/turn-client-openssl
44//! [`turn-client-dimpl`]: https://docs.rs/turn-client-dimpl
45//!
46//! # Examples
47//!
48//! ```
49//! use turn_client_proto::udp::TurnClientUdp;
50//! use turn_client_proto::api::TurnConfig;
51//! let turn_server_address = "127.0.0.1:3478".parse().unwrap();
52//! let local_address = "127.0.0.1:1000".parse().unwrap();
53//! let credentials = turn_types::TurnCredentials::new("username", "password");
54//! let config = TurnConfig::new(credentials);
55//!
56//! let client = TurnClientUdp::allocate(
57//!     local_address,
58//!     turn_server_address,
59//!     config,
60//! );
61//! ```
62
63#![deny(missing_debug_implementations)]
64#![deny(missing_docs)]
65#![cfg_attr(docsrs, feature(doc_cfg))]
66#![deny(clippy::std_instead_of_core)]
67#![deny(clippy::std_instead_of_alloc)]
68#![no_std]
69
70extern crate alloc;
71
72#[cfg(any(feature = "std", test))]
73extern crate std;
74
75pub use stun_proto as stun;
76pub use turn_types as types;
77pub mod api;
78pub mod client;
79mod protocol;
80pub mod tcp;
81pub mod udp;
82
83/// Public prelude.
84pub mod prelude {
85    pub use crate::api::TurnClientApi;
86    pub use turn_types::prelude::DelayedTransmitBuild;
87}
88
89#[cfg(test)]
90mod tests {
91    use tracing::subscriber::DefaultGuard;
92    use tracing_subscriber::layer::SubscriberExt;
93    use tracing_subscriber::Layer;
94
95    pub(crate) fn test_init_log() -> DefaultGuard {
96        turn_types::debug_init();
97        let level_filter = std::env::var("TURN_LOG")
98            .or(std::env::var("RUST_LOG"))
99            .ok()
100            .and_then(|var| var.parse::<tracing_subscriber::filter::Targets>().ok())
101            .unwrap_or(
102                tracing_subscriber::filter::Targets::new().with_default(tracing::Level::TRACE),
103            );
104        let registry = tracing_subscriber::registry().with(
105            tracing_subscriber::fmt::layer()
106                .with_file(true)
107                .with_line_number(true)
108                .with_level(true)
109                .with_target(false)
110                .with_test_writer()
111                .with_filter(level_filter),
112        );
113        tracing::subscriber::set_default(registry)
114    }
115}
turn_client_proto/lib.rs

turn_client_proto/
lib.rs
