turn-client-proto 0.7.1

TURN protocol in a sans-IO fashion
Documentation 
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

// Copyright (C) 2025 Matthew Waters <matthew@centricular.com>
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.
//
// SPDX-License-Identifier: MIT OR Apache-2.0

//! # turn-client-proto
//!
//! `turn-client-proto` provides a sans-IO API for a TURN client communicating with a TURN server.
//!
//! Relevant standards:
//! - [RFC5766]: Traversal Using Relays around NAT (TURN).
//! - [RFC6062]: Traversal Using Relays around NAT (TURN) Extensions for TCP Allocations
//! - [RFC6156]: Traversal Using Relays around NAT (TURN) Extension for IPv6
//! - [RFC8656]: Traversal Using Relays around NAT (TURN): Relay Extensions to Session
//!   Traversal Utilities for NAT (STUN)
//!
//! [RFC5766]: https://datatracker.ietf.org/doc/html/rfc5766
//! [RFC6062]: https://tools.ietf.org/html/rfc6062
//! [RFC6156]: https://tools.ietf.org/html/rfc6156
//! [RFC8656]: https://tools.ietf.org/html/rfc8656
//!
//! # Getting Started
//!
//! The entry point for starting with a TURN client implementation depends on the transport
//! protocol that you are looking to use. For UDP connections, you should start in the [`udp`]
//! module, for TCP connections, the [`tcp`] module. (D)TLS functionality is contained within
//! extension crates. e.g.
//! - For TLS connections over TCP, the [`turn-client-rustls`], or [`turn-client-openssl`] crates
//!   are available.
//! - For DTLS connections over UDP, the [`turn-client-dimpl`] or [`turn-client-openssl`] crates
//!   are available.
//!
//! From there, the [`api`] module provides the interface that all of the TURN clients implement and
//! the [`client`] module can be used to combine one of the above options into a single value for
//! selection based on the underlying TURN client.
//!
//! [`turn-client-rustls`]: https://docs.rs/turn-client-rustls
//! [`turn-client-openssl`]: https://docs.rs/turn-client-openssl
//! [`turn-client-dimpl`]: https://docs.rs/turn-client-dimpl
//!
//! # Examples
//!
//! ```
//! use turn_client_proto::udp::TurnClientUdp;
//! use turn_client_proto::api::TurnConfig;
//! let turn_server_address = "127.0.0.1:3478".parse().unwrap();
//! let local_address = "127.0.0.1:1000".parse().unwrap();
//! let credentials = turn_types::TurnCredentials::new("username", "password");
//! let config = TurnConfig::new(credentials);
//!
//! let client = TurnClientUdp::allocate(
//!     local_address,
//!     turn_server_address,
//!     config,
//! );
//! ```

#![deny(missing_debug_implementations)]
#![deny(missing_docs)]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![deny(clippy::std_instead_of_core)]
#![deny(clippy::std_instead_of_alloc)]
#![no_std]

extern crate alloc;

#[cfg(any(feature = "std", test))]
extern crate std;

pub use stun_proto as stun;
pub use turn_types as types;
pub mod api;
pub mod client;
mod protocol;
pub mod tcp;
pub mod udp;

/// Public prelude.
pub mod prelude {
    pub use crate::api::TurnClientApi;
    pub use turn_types::prelude::DelayedTransmitBuild;
}

#[cfg(test)]
mod tests {
    use tracing::subscriber::DefaultGuard;
    use tracing_subscriber::layer::SubscriberExt;
    use tracing_subscriber::Layer;

    pub(crate) fn test_init_log() -> DefaultGuard {
        turn_types::debug_init();
        let level_filter = std::env::var("TURN_LOG")
            .or(std::env::var("RUST_LOG"))
            .ok()
            .and_then(|var| var.parse::<tracing_subscriber::filter::Targets>().ok())
            .unwrap_or(
                tracing_subscriber::filter::Targets::new().with_default(tracing::Level::TRACE),
            );
        let registry = tracing_subscriber::registry().with(
            tracing_subscriber::fmt::layer()
                .with_file(true)
                .with_line_number(true)
                .with_level(true)
                .with_target(false)
                .with_test_writer()
                .with_filter(level_filter),
        );
        tracing::subscriber::set_default(registry)
    }
}