tcp-uring-client

English | Русский

---

English

High-performance network client library for Rust using io_uring (Linux kernel async I/O).

Built on tokio-uring runtime with support for:

• TCP connections
• HTTP/HTTPS (HTTP/1.1)
• WebSocket/WSS (RFC 6455)
• TLS (via rustls)
• SOCKS5 proxy
• Advanced connection configuration (target_ip, local_ip)

Features

• Zero-copy I/O: Leverages io_uring for minimal CPU overhead
• High throughput: 217K RPS for raw TCP, 32.6K RPS for HTTP
• Low latency: 18μs TCP connect, 86μs WebSocket handshake, 131μs HTTP request
• TLS support: Pure Rust TLS via rustls (no OpenSSL dependency)
• Protocol support: HTTP, HTTPS, WebSocket, WSS
• Proxy support: SOCKS5 and HTTP CONNECT proxy with authentication
• Connection control: Configure target_ip (skip DNS), local_ip binding (interface selection)
• Graceful shutdown: Proper close handshakes for WebSocket and TLS

Requirements

• Linux kernel 5.10+ (io_uring support)
• Rust 1.70+
• WSL2 (if running on Windows)

Performance Benchmarks

Tested on Linux with io_uring enabled:

Protocol	Operation	Avg Latency	P99 Latency	Peak RPS
TCP	Connect	18 μs	25 μs	217K
WebSocket	Handshake	86 μs	106 μs	97K
HTTP	GET request	131 μs	246 μs	32.6K
HTTPS	GET request	~300 μs	~500 μs	~15K

Note: Benchmarks use single-threaded tokio-uring runtime. Performance scales with kernel version and hardware.

Architecture

Application Layer
       ↓
HttpClient / WebSocketClient
       ↓
Protocol Detection (http:// vs https:// / ws:// vs wss://)
       ↓
    ┌────────────┬────────────┐
Plain TCP    TLS (rustls)
    └────────────┴────────────┘
            ↓
      ConnectionConfig
            ↓
    ┌──────────┬──────────┐
  Direct    SOCKS5      HTTP Proxy
    └──────────┴──────────┘
            ↓
      io_uring (tokio-uring)
            ↓
         Network

Quick Start

TCP Connection

use tcp_uring_client::connection::config::ConnectionConfig;
use tcp_uring_client::connection::connector::Connector;

tokio_uring::start(async {
    let config = ConnectionConfig::new("example.com:80".to_string());
    let stream = Connector::connect_tcp(&config).await?;
    // Use stream for read/write
    Ok(())
})

HTTP Request

use tcp_uring_client::http::client::HttpClient;

tokio_uring::start(async {
    let response = HttpClient::get("http://httpbin.org/get").await?;
    println!("Status: {} {}", response.status_code, response.status_text);
    println!("Body: {}", String::from_utf8_lossy(&response.body));
    Ok(())
})

WebSocket Connection

use tcp_uring_client::websocket::client::WebSocketClient;

tokio_uring::start(async {
    let mut client = WebSocketClient::connect("wss://echo.websocket.org").await?;
    client.send_text("Hello, WebSocket!").await?;
    let frame = client.receive().await?;
    client.close().await?;
    Ok(())
})

SOCKS5 Proxy

use tcp_uring_client::connection::config::{ConnectionConfig, ProxyConfig};
use tcp_uring_client::connection::connector::Connector;

tokio_uring::start(async {
    let proxy = ProxyConfig::socks5("127.0.0.1".to_string(), 1080);
    let config = ConnectionConfig::new("example.com:80".to_string())
        .with_proxy(proxy);
    let stream = Connector::connect_tcp(&config).await?;
    Ok(())
})

API Reference

Connection Module

ConnectionConfig: Configuration builder for TCP connections

pub struct ConnectionConfig {
    pub url: String,
    pub local_ip: Option<String>,
    pub target_ip: Option<String>,
    pub proxy: Option<ProxyConfig>,
}

ConnectionConfig::new(url: String) -> Self
    .with_local_ip(local_ip: String) -> Self
    .with_target_ip(target_ip: String) -> Self
    .with_proxy(proxy: ProxyConfig) -> Self

ProxyConfig: Proxy configuration

ProxyConfig::socks5(host: String, port: u16) -> Self
ProxyConfig::http(host: String, port: u16) -> Self
    .with_auth(username: String, password: String) -> Self

HTTP Module

impl HttpClient {
    pub async fn get(url: &str) -> Result<HttpResponse, Error>;
    pub async fn post(url: &str, body: Vec<u8>) -> Result<HttpResponse, Error>;
    pub async fn request(url: &str, request: HttpRequest) -> Result<HttpResponse, Error>;
}

WebSocket Module

impl WebSocketClient {
    pub async fn connect(url: &str) -> Result<Self, Error>;
    pub async fn send_text(&mut self, text: &str) -> Result<(), Error>;
    pub async fn send_binary(&mut self, data: &[u8]) -> Result<(), Error>;
    pub async fn receive(&mut self) -> Result<Frame, Error>;
    pub async fn close(&mut self) -> Result<(), Error>;
}

Why io_uring?

io_uring provides:

• Lower syscall overhead: Batch operations in ring buffer
• True async I/O: No thread pool needed for blocking operations
• Better cache utilization: Ring buffers stay in CPU cache
• Scalability: Handles thousands of connections efficiently

Performance gain vs epoll: 2-3x lower latency, 20-30% higher throughput for network workloads.

Dependencies

• tokio-uring (0.5): io_uring runtime
• rustls (0.23): Pure Rust TLS implementation
• webpki-roots (0.26): Mozilla root certificates

License

MIT

---

Russian

Высокопроизводительная сетевая библиотека для Rust с использованием io_uring (асинхронный I/O ядра Linux).

Построена на runtime tokio-uring с поддержкой:

• TCP соединений
• HTTP/HTTPS (HTTP/1.1)
• WebSocket/WSS (RFC 6455)
• TLS (через rustls)
• SOCKS5 прокси
• Расширенная конфигурация соединений (target_ip, local_ip)

Возможности

• Zero-copy I/O: Использует io_uring для минимальной нагрузки на CPU
• Высокая пропускная способность: 217K RPS для TCP, 32.6K RPS для HTTP
• Низкая задержка: 18μs TCP подключение, 86μs WebSocket handshake, 131μs HTTP запрос
• Поддержка TLS: Чистый Rust TLS через rustls (без зависимости от OpenSSL)
• Поддержка протоколов: HTTP, HTTPS, WebSocket, WSS
• Поддержка прокси: SOCKS5 и HTTP CONNECT прокси с аутентификацией

Требования

• Linux kernel 5.10+ (поддержка io_uring)
• Rust 1.70+
• WSL2 (если запускаете из Windows)

Бенчмарки производительности

Протокол	Операция	Средняя задержка	P99 задержка	Пиковый RPS
TCP	Подключение	18 μs	25 μs	217K
WebSocket	Handshake	86 μs	106 μs	97K
HTTP	GET запрос	131 μs	246 μs	32.6K
HTTPS	GET запрос	~300 μs	~500 μs	~15K

Почему io_uring?

io_uring предоставляет:

• Меньше системных вызовов: Пакетная обработка операций в ring buffer
• Настоящий асинхронный I/O: Не требуется пул потоков для блокирующих операций
• Лучшее использование кеша: Ring буферы остаются в кеше CPU
• Масштабируемость: Эффективно обрабатывает тысячи соединений

Прирост производительности vs epoll: задержка в 2-3 раза ниже, пропускная способность на 20-30% выше.