rust_p2p_core/
lib.rs

1//! # rustp2p-core - Core NAT Traversal Library
2//!
3//! `rustp2p-core` provides the foundational building blocks for peer-to-peer networking,
4//! including NAT traversal, hole punching, routing, and tunnel management. This crate is
5//! the underlying engine that powers the higher-level `rustp2p` library.
6//!
7//! ## Features
8//!
9//! - **NAT Detection**: Automatically detects NAT type using STUN
10//! - **Hole Punching**: UDP and TCP hole punching for direct peer connections
11//! - **Route Management**: Dynamic routing with multi-path support
12//! - **Tunnel Management**: Unified management of UDP and TCP tunnels
13//! - **STUN Protocol**: Built-in STUN client for NAT traversal
14//! - **Socket Management**: Advanced socket handling with multi-interface support
15//!
16//! ## Architecture
17//!
18//! The library is organized into several key modules:
19//!
20//! - [`nat`] - NAT type detection and information
21//! - [`punch`] - Hole punching for NAT traversal
22//! - [`route`] - Routing and path selection
23//! - [`socket`] - Low-level socket management
24//! - [`stun`] - STUN protocol implementation
25//! - [`tunnel`] - Tunnel abstraction for UDP/TCP
26//!
27//! ## Quick Start
28//!
29//! ### Creating a Simple Tunnel
30//!
31//! ```rust,no_run
32//! use rust_p2p_core::tunnel::{TunnelConfig, new_tunnel_component};
33//!
34//! # #[tokio::main]
35//! # async fn main() -> std::io::Result<()> {
36//! // Create a tunnel configuration
37//! let config = TunnelConfig::default();
38//!
39//! // Create tunnel components
40//! let (dispatcher, puncher) = new_tunnel_component(config)?;
41//!
42//! // Use dispatcher to handle incoming connections
43//! while let Ok(tunnel) = dispatcher.dispatch().await {
44//!     tokio::spawn(async move {
45//!         // Handle the tunnel
46//!     });
47//! }
48//! # Ok(())
49//! # }
50//! ```
51//!
52//! ## NAT Type Detection
53//!
54//! Detect your NAT type using STUN servers:
55//!
56//! ```rust,no_run
57//! use rust_p2p_core::stun::stun_test_nat;
58//!
59//! # #[tokio::main]
60//! # async fn main() -> std::io::Result<()> {
61//! let stun_servers = vec![
62//!     "stun.l.google.com:19302".to_string(),
63//!     "stun1.l.google.com:19302".to_string(),
64//! ];
65//!
66//! let (nat_type, public_ips, port_range) =
67//!     stun_test_nat(stun_servers, None).await?;
68//!
69//! println!("NAT Type: {:?}", nat_type);
70//! println!("Public IPs: {:?}", public_ips);
71//! println!("Port Range: {}", port_range);
72//! # Ok(())
73//! # }
74//! ```
75//!
76//! ## Hole Punching
77//!
78//! Perform UDP hole punching to establish direct connections:
79//!
80//! ```rust,no_run
81//! use rust_p2p_core::punch::{Puncher, PunchInfo};
82//! use std::net::SocketAddr;
83//!
84//! # async fn example(puncher: Puncher) -> std::io::Result<()> {
85//! // Create punch info for the target peer
86//! let punch_info = PunchInfo::default();
87//!
88//! // Attempt to punch through NAT
89//! puncher.punch_now(None, b"punch", punch_info).await?;
90//! # Ok(())
91//! # }
92//! ```
93//!
94//! ## Route Management
95//!
96//! The routing system automatically manages paths between peers:
97//!
98//! ```rust,no_run
99//! use rust_p2p_core::route::{Route, RouteKey};
100//! use std::net::SocketAddr;
101//!
102//! # fn example() {
103//! // Routes are managed automatically by the tunnel system
104//! // You can query route information using RouteKey
105//! # }
106//! ```
107//!
108//! ## Socket Management
109//!
110//! Low-level socket creation and management:
111//!
112//! ```rust,no_run
113//! use rust_p2p_core::socket::{create_udp_socket, LocalInterface};
114//! use std::net::{SocketAddr, Ipv4Addr};
115//!
116//! # #[tokio::main]
117//! # async fn main() -> std::io::Result<()> {
118//! let addr = SocketAddr::from((Ipv4Addr::UNSPECIFIED, 0));
119//! let socket = create_udp_socket(addr, None)?;
120//! # Ok(())
121//! # }
122//! ```
123//!
124//! ## UDP vs TCP Tunnels
125//!
126//! The library supports both UDP and TCP tunnels:
127//!
128//! - **UDP Tunnels**: Low latency, suitable for real-time communication
129//! - **TCP Tunnels**: Reliable, ordered delivery
130//!
131//! Both tunnel types provide a unified interface through the `Tunnel` enum.
132//!
133//! ## Advanced Features
134//!
135//! ### Custom Punch Policies
136//!
137//! Implement custom NAT traversal strategies by providing your own punch policy.
138//!
139//! ### Multi-Interface Support
140//!
141//! Bind to specific network interfaces for more control over routing.
142//!
143//! ### Route Metrics
144//!
145//! The routing system considers metrics like latency and packet loss when
146//! selecting the best path.
147//!
148//! ## Thread Safety
149//!
150//! All public types are thread-safe and can be shared across async tasks.
151//! The library uses Tokio for async runtime.
152//!
153//! ## See Also
154//!
155//! - [`rustp2p`](../rustp2p/index.html) - High-level P2P library built on top of this crate
156//! - [`rustp2p-reliable`](../rustp2p_reliable/index.html) - Reliable transport using KCP
157
158pub mod extend;
159pub mod idle;
160pub mod nat;
161pub mod punch;
162pub mod route;
163pub mod socket;
164pub mod stun;
165pub mod tunnel;
rust_p2p_core/lib.rs

rust_p2p_core/
lib.rs
