Crate rust_p2p_core 

rustp2p-core - Core NAT Traversal Library

rustp2p-core provides the foundational building blocks for peer-to-peer networking, including NAT traversal, hole punching, routing, and tunnel management. This crate is the underlying engine that powers the higher-level rustp2p library.

Features

• NAT Detection: Automatically detects NAT type using STUN
• Hole Punching: UDP and TCP hole punching for direct peer connections
• Route Management: Dynamic routing with multi-path support
• Tunnel Management: Unified management of UDP and TCP tunnels
• STUN Protocol: Built-in STUN client for NAT traversal
• Socket Management: Advanced socket handling with multi-interface support

Architecture

The library is organized into several key modules:

• nat - NAT type detection and information
• punch - Hole punching for NAT traversal
• route - Routing and path selection
• socket - Low-level socket management
• stun - STUN protocol implementation
• tunnel - Tunnel abstraction for UDP/TCP

Quick Start

Creating a Simple Tunnel

use rust_p2p_core::tunnel::{TunnelConfig, new_tunnel_component};

// Create a tunnel configuration
let config = TunnelConfig::default();

// Create tunnel components
let (dispatcher, puncher) = new_tunnel_component(config)?;

// Use dispatcher to handle incoming connections
while let Ok(tunnel) = dispatcher.dispatch().await {
    tokio::spawn(async move {
        // Handle the tunnel
    });
}

NAT Type Detection

Detect your NAT type using STUN servers:

use rust_p2p_core::stun::stun_test_nat;

let stun_servers = vec![
    "stun.l.google.com:19302".to_string(),
    "stun1.l.google.com:19302".to_string(),
];

let (nat_type, public_ips, port_range) =
    stun_test_nat(stun_servers, None).await?;

println!("NAT Type: {:?}", nat_type);
println!("Public IPs: {:?}", public_ips);
println!("Port Range: {}", port_range);

Hole Punching

Perform UDP hole punching to establish direct connections:

use rust_p2p_core::punch::{Puncher, PunchInfo};
use std::net::SocketAddr;

// Create punch info for the target peer
let punch_info = PunchInfo::default();

// Attempt to punch through NAT
puncher.punch_now(None, b"punch", punch_info).await?;

Route Management

The routing system automatically manages paths between peers:

use rust_p2p_core::route::{Route, RouteKey};
use std::net::SocketAddr;

// Routes are managed automatically by the tunnel system
// You can query route information using RouteKey

Socket Management

Low-level socket creation and management:

use rust_p2p_core::socket::{create_udp_socket, LocalInterface};
use std::net::{SocketAddr, Ipv4Addr};

let addr = SocketAddr::from((Ipv4Addr::UNSPECIFIED, 0));
let socket = create_udp_socket(addr, None)?;

UDP vs TCP Tunnels

The library supports both UDP and TCP tunnels:

• UDP Tunnels: Low latency, suitable for real-time communication
• TCP Tunnels: Reliable, ordered delivery

Both tunnel types provide a unified interface through the Tunnel enum.

Advanced Features

Custom Punch Policies

Implement custom NAT traversal strategies by providing your own punch policy.

Multi-Interface Support

Bind to specific network interfaces for more control over routing.

Route Metrics

The routing system considers metrics like latency and packet loss when selecting the best path.

Thread Safety

All public types are thread-safe and can be shared across async tasks. The library uses Tokio for async runtime.

See Also

• rustp2p - High-level P2P library built on top of this crate
• rustp2p-reliable - Reliable transport using KCP

Modules

extend

idle

nat

NAT (Network Address Translation) detection and information.

punch

NAT hole punching for establishing direct peer-to-peer connections.

route

Routing logic for selecting optimal paths between peers.

socket

Low-level socket creation and management.

stun

STUN (Session Traversal Utilities for NAT) protocol implementation.

tunnel

Tunnel management for UDP and TCP connections.