Crate rustp2p_reliable 

rustp2p-reliable - Reliable Transport over UDP

rustp2p-reliable provides reliable, ordered transport over UDP using the KCP protocol. It combines the low latency of UDP with the reliability of TCP, making it ideal for real-time applications that require guaranteed delivery.

Features

• KCP Protocol: Fast and reliable UDP transport
• TCP Fallback: Automatic fallback to TCP when needed
• NAT Traversal: Built-in hole punching support
• Automatic Maintenance: Connection health monitoring and recovery
• Unified Interface: Same API for both KCP and TCP tunnels

Quick Start

Creating a Reliable Tunnel Listener

use rustp2p_reliable::{from_config, Config};

let config = Config::default();
let (mut listener, puncher) = from_config(config).await?;

// Accept incoming connections
while let Ok(tunnel) = listener.accept().await {
    tokio::spawn(async move {
        // Handle the reliable tunnel
        while let Ok(data) = tunnel.next().await {
            println!("Received: {} bytes", data.len());
        }
    });
}

Basic Usage

Sending Data

use rustp2p_reliable::ReliableTunnel;
use bytes::BytesMut;

let data = BytesMut::from(&b"Hello, world!"[..]);
tunnel.send(data).await?;

Receiving Data

use rustp2p_reliable::ReliableTunnel;

loop {
    match tunnel.next().await {
        Ok(data) => {
            println!("Received {} bytes", data.len());
        }
        Err(e) => {
            eprintln!("Error: {}", e);
            break;
        }
    }
}

NAT Traversal with Puncher

Use the Puncher to establish connections through NATs:

use rustp2p_reliable::{Puncher, PunchInfo};

// Get your NAT information
let nat_info = puncher.nat_info();
println!("NAT Type: {:?}", nat_info.nat_type);
println!("Public IPs: {:?}", nat_info.public_ips);

// Punch through NAT to reach a peer
let punch_info = PunchInfo::default();
puncher.punch(punch_info).await?;

KCP vs TCP

The library automatically selects between KCP and TCP based on network conditions:

• KCP: Used for direct UDP connections (low latency, good for real-time data)
• TCP: Used when UDP is blocked or unreliable (guaranteed delivery)

You can check the tunnel type:

use rustp2p_reliable::{ReliableTunnel, ReliableTunnelType};

match tunnel.tunnel_type() {
    ReliableTunnelType::Kcp => println!("Using KCP (fast UDP)"),
    ReliableTunnelType::Tcp => println!("Using TCP (reliable)"),
}

Configuration

Configure the reliable transport layer:

use rustp2p_reliable::Config;
use rust_p2p_core::tunnel::TunnelConfig;

let config = Config {
    tunnel_config: TunnelConfig::default(),
    tcp_stun_servers: vec![
        "stun.l.google.com:19302".to_string(),
    ],
    udp_stun_servers: vec![
        "stun1.l.google.com:19302".to_string(),
    ],
};

Advanced Features

Custom KCP Conversation IDs

For applications that need multiple independent KCP streams:

use rustp2p_reliable::Puncher;

let kcp_conv = 12345;
let punch_info = Default::default();
puncher.punch_conv(kcp_conv, punch_info).await?;

Raw Data Sending

Send raw UDP data without KCP protocol overhead:

use rustp2p_reliable::ReliableTunnel;
use bytes::BytesMut;

let data = BytesMut::from(&b"raw data"[..]);
tunnel.send_raw(data).await?;

Connection Information

Get information about the connection:

use rustp2p_reliable::ReliableTunnel;

println!("Local address: {}", tunnel.local_addr());
println!("Remote address: {}", tunnel.remote_addr());
println!("Tunnel type: {:?}", tunnel.tunnel_type());

Thread Safety

All types are designed to work with Tokio’s async runtime and can be safely shared across tasks using Arc when needed.

See Also

• rustp2p - High-level P2P library
• rustp2p-core - Core NAT traversal functionality

Structs

BytesCodec

The default byte encoder/decoder; using this is no different from directly using a TCP reliable.

BytesInitCodec

Config

KcpMessageHub

LengthPrefixedCodec

Fixed-length prefix encoder/decoder.

LengthPrefixedInitCodec

NatInfo

Comprehensive NAT information about the local network.

PunchConsultInfo

PunchInfo

PunchModel

PunchPolicySet

This is middle representation for inner

Puncher

NAT traversal puncher for establishing direct connections.

ReliableTunnelListener

Listener for accepting reliable tunnel connections.

TcpMessageHub

TcpTunnelConfig

TunnelConfig

UdpTunnelConfig

Enums

LoadBalance

PunchPolicy

PunchRole

ReliableTunnel

A reliable tunnel connection (either KCP or TCP).

ReliableTunnelType

The type of reliable tunnel (KCP or TCP).

Traits

Decoder

Encoder

InitCodec

Functions

from_config

Creates a reliable tunnel system from configuration.