network-protocol 1.0.1

Secure, high-performance protocol core with backpressure control, structured logging, timeout handling, TLS support, and comprehensive benchmarking for robust Rust networked applications and services.
Documentation

Security Guarantees

🔒 Cryptographic Protections

  • Modern Encryption: ChaCha20-Poly1305 AEAD or TLS 1.2+/1.3 (no legacy ciphers)
  • Key Exchange: X25519 ECDH with per-session ephemeral keys
  • Forward Secrecy: Session keys never persist, automatic key rotation
  • Replay Protection: Nonce tracking (10,000 per session) + timestamp validation (±5s window)
  • Authentication: Mutual TLS support, certificate pinning available

🛡️ DoS/Memory Protections

  • Decompression Bombs: Pre-validation prevents LZ4/Zstd expansion attacks (16MB hard limit)
  • Memory Exhaustion: Maximum packet size 16MB, backpressure prevents unbounded buffering
  • Slowloris: Connection timeouts (configurable), automatic dead connection cleanup
  • Resource Limits: Bounded channels, connection limits, compression thresholds
  • Fuzzing: 3 fuzz targets continuously tested, OOM attacks caught pre-release

🔍 Implementation Safety

  • Memory Safe: 100% safe Rust (zero unsafe in protocol core), fuzz-tested
  • No Panics: All unwrap()/expect() confined to test code only
  • Validated Input: All network data validated before processing, fail-fast on invalid packets
  • Audit Trail: Structured logging, comprehensive error context for forensics
  • Supply Chain: cargo-deny + cargo-audit in CI, vetted crypto dependencies (RustCrypto/Rustls)

📋 Standards Compliance

  • TLS: Enforces TLS 1.2+ minimum (no SSLv3/TLS 1.0/1.1), strong cipher suites only
  • Crypto: NIST-approved algorithms (ChaCha20-Poly1305, X25519, SHA-256)
  • Best Practices: Certificate validation, no homebrew crypto, constant-time operations

Threat Model: See THREAT_MODEL.md for comprehensive security analysis and attack scenarios.

Features

Security

  • Secure handshake + post-handshake encryption using Elliptic Curve Diffie-Hellman (ECDH) key exchange
  • TLS transport with client/server implementations and mutual authentication (mTLS)
  • Certificate pinning for enhanced security in TLS connections
  • Self-signed certificate generation capability for development environments
  • Protection against replay attacks using timestamps and nonce verification

Performance & Reliability

  • Advanced backpressure mechanism to prevent server overload from slow clients
  • Bounded channels with dynamic read pausing to maintain stable memory usage
  • Configurable connection timeouts for all network operations with proper error handling
  • Heartbeat mechanism with keep-alive ping/pong messages for connection health monitoring
  • Automatic detection and cleanup of dead connections
  • Client-side timeout handling with reconnection capabilities
  • Optimized Release Builds: LTO + single codegen unit for maximum performance

Testing & Quality

  • 77+ Test Suite: Unit, integration, edge cases, stress tests, doc tests
  • Fuzzing Infrastructure: 3 targets (packet, handshake, compression) with CI smoke tests
  • Benchmarking: Criterion-based micro-benchmarks for packet encode/decode, compression, messages
  • CI Pipeline: Format, clippy, cross-platform builds (Linux/macOS/Windows), security audits

Core Architecture

  • Custom binary packet format with optional compression (LZ4, Zstd)
  • Plugin-friendly dispatcher for message routing with zero-copy serialization
  • Graceful shutdown support for all server implementations with configurable timeouts
  • Modular transport: TCP, Unix socket, TLS, cluster sync
  • Comprehensive configuration system with TOML files and environment variable overrides
  • Structured logging with flexible log level control via configuration

Compatibility

  • Cross-platform support for local transport (Windows, Linux, macOS)
  • Windows-compatible alternative for Unix Domain Sockets
  • Ready for microservices, databases, daemons, and system protocols

Installation

Add the library to your Cargo.toml:

[dependencies]
network-protocol = "1.0.1"

Quick Start

TCP Server with Backpressure and Structured Logging

use network_protocol::utils::logging;
use network_protocol::service::daemon::{self, ServerConfig};
use network_protocol::config::NetworkConfig;
use network_protocol::protocol::dispatcher::Dispatcher;
use network_protocol::error::Result;
use std::sync::Arc;
use std::time::Duration;
use tracing::{info, warn};

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize structured logging
    logging::init_logging(Some("info"), None).expect("Failed to initialize logging");
    
    // Create a dispatcher
    let dispatcher = Arc::new(Dispatcher::default());
    
    // Register message handlers
    dispatcher.register("ECHO", |msg| {
        info!(message_type = "ECHO", "Processing echo request");
        Ok(msg.clone())
    });
    
    // Option 1: Load configuration from file
    // let config = NetworkConfig::from_file("config.toml")?.server;
    
    // Option 2: Load configuration from environment variables
    // let config = NetworkConfig::from_env()?.server;
    
    // Option 3: Configure server with custom settings
    let config = ServerConfig {
        address: "127.0.0.1:9000".to_string(),
        backpressure_limit: 100, // Limit pending messages
        connection_timeout: Duration::from_secs(30),
        heartbeat_interval: Duration::from_secs(15),
        shutdown_timeout: Duration::from_secs(10),
        max_connections: 1000,
    };
    
    // Start server with configuration
    let server = daemon::new_with_config(config, dispatcher);
    
    // Handle Ctrl+C for graceful shutdown
    tokio::spawn(async move {
        tokio::signal::ctrl_c().await.expect("Failed to listen for ctrl+c");
        info!("Initiating graceful shutdown...");
        server.shutdown(Some(Duration::from_secs(10))).await;
    });
    
    // Run server until stopped
    info!("Server starting on 127.0.0.1:9000");
    server.run().await
}

TLS Server

#[tokio::main]
async fn main() -> Result<()> {
    // Generate or load certificates
    let cert_config = TlsConfig {
        cert_path: "server_cert.pem",
        key_path: "server_key.pem",
        ca_path: Some("ca_cert.pem"), // For mTLS
        verify_client: true, // Enable mTLS
    };
    
    // Start TLS server
    network_protocol::service::tls_daemon::start("127.0.0.1:9443", cert_config).await?;
    Ok(())
}

Client with Timeout Handling

use network_protocol::utils::logging;
use network_protocol::service::client::{self, ClientConfig};
use network_protocol::config::NetworkConfig;
use network_protocol::protocol::message::Message;
use network_protocol::error::ProtocolError;
use std::time::Duration;
use tracing::{info, error};
use tokio::time::timeout;

#[tokio::main]
async fn main() -> Result<(), ProtocolError> {
    // Initialize structured logging
    logging::init_logging(Some("info"), None)?;
    
    // Option 1: Load configuration from file
    // let config = NetworkConfig::from_file("config.toml")?.client;
    
    // Option 2: Load from environment variables
    // let config = NetworkConfig::from_env()?.client;
    
    // Option 3: Configure client with custom settings
    let config = ClientConfig {
        address: "127.0.0.1:9000".to_string(),
        connection_timeout: Duration::from_secs(5),
        operation_timeout: Duration::from_secs(3),
        response_timeout: Duration::from_secs(30),
        heartbeat_interval: Duration::from_secs(15),
        auto_reconnect: true,
        max_reconnect_attempts: 3,
        reconnect_delay: Duration::from_secs(1),
    };
    
    // Connect with timeout handling
    info!("Connecting to server...");
    let mut conn = match timeout(Duration::from_secs(5), client::connect_with_config(config)).await {
        Ok(Ok(conn)) => conn,
        Ok(Err(e)) => {
            error!(error = ?e, "Failed to connect to server");
            return Err(e);
        }
        Err(_) => {
            error!("Connection timeout");
            return Err(ProtocolError::Timeout);
        }
    };
    
    info!("Connected successfully");
    
    // Send message with timeout
    match timeout(Duration::from_secs(3), conn.secure_send(Message::Echo("hello".into()))).await {
        Ok(Ok(_)) => info!("Message sent successfully"),
        Ok(Err(e)) => {
            error!(error = ?e, "Failed to send message");
            return Err(e);
        }
        Err(_) => {
            error!("Send timeout");
            return Err(ProtocolError::Timeout);
        }
    }
    
    // Receive reply with timeout
    let reply = match timeout(Duration::from_secs(3), conn.secure_recv()).await {
        Ok(Ok(msg)) => msg,
        Ok(Err(e)) => {
            error!(error = ?e, "Failed to receive reply");
            return Err(e);
        }
        Err(_) => {
            error!("Receive timeout");
            return Err(ProtocolError::Timeout);
        }
    };
    
    info!(reply = ?reply, "Received reply");
    
    // Close connection gracefully
    conn.close().await?
    
    Ok(())
}

TLS Client

use network_protocol::service::client::{self, TlsClientConfig};
use network_protocol::protocol::message::Message;
use network_protocol::error::Result;
use tracing::info;

#[tokio::main]
async fn main() -> Result<()> {
    // Configure TLS client
    let tls_config = TlsClientConfig {
        cert_path: Some("client_cert.pem"), // For mTLS
        key_path: Some("client_key.pem"),  // For mTLS
        ca_path: Some("ca_cert.pem"),      // Server verification
        server_name: "example.com",         // SNI
    };
    
    // Connect with TLS
    let mut conn = client::connect_tls(
        "127.0.0.1:9443", 
        tls_config
    ).await?;
    
    info!("Connected securely to TLS server");
    
    // Communicate securely
    conn.send(Message::Echo("secure message".into())).await?;
    let reply = conn.receive().await?;
    
    info!(response = ?reply, "Received secure response");
    
    // Close connection properly
    conn.close().await?
}

Message Types

Built-in messages include:

  • HandshakeInit / HandshakeAck
  • Ping / Pong
  • Echo(String)
  • Unknown

You can extend this list with your own enums or handlers.

Benchmarks

Run microbenchmarks (Criterion):

cargo bench

Highlights:

  • Packet encode: up to ~1.9 GiB/s, decode up to ~24.5 GiB/s
  • LZ4: compress ~1.0 GiB/s, decompress ~18–19 GiB/s @ 1 MiB
  • Zstd (level 1): compress ~1.0 GiB/s, decompress ~0.4 GiB/s @ 1 MiB
  • Compression threshold: default 512 bytes (configurable) to skip compression on tiny payloads

See detailed results and recommendations in docs/PERFORMANCE.md.

Testing

Full test suite:

cargo test --all --all-features

Fuzz smoke tests (nightly):

rustup install nightly
cargo install cargo-fuzz
cargo +nightly fuzz build
cargo +nightly fuzz run fuzz_target_1 -- -max_total_time=30
cargo +nightly fuzz run fuzz_handshake -- -max_total_time=30
cargo +nightly fuzz run fuzz_compression -- -max_total_time=30

Stress tests:

cargo test --test stress -- --nocapture
cargo test --test concurrency -- --nocapture

Production build profile (already configured): LTO, codegen-units=1, opt-level=3, stripped symbols. Run with cargo build --release.

Custom Message Handlers

Register your own handlers with the dispatcher to process different message types:

use network_protocol::protocol::dispatcher::Dispatcher;
use network_protocol::protocol::message::Message;
use network_protocol::error::Result;
use std::sync::Arc;
use tracing::info;

// Create a dispatcher (typically shared between connections)
let dispatcher = Arc::new(Dispatcher::default());

// Basic handlers for built-in message types
dispatcher.register("PING", |_| {
    info!("Ping received, sending pong");
    Ok(Message::Pong)
});

dispatcher.register("ECHO", |msg| {
    info!(content = ?msg, "Echo request received");
    Ok(msg.clone())
});

// Custom message type handler with complex processing
dispatcher.register("DATA_PROCESS", |msg| {
    if let Message::Custom(data) = msg {
        // Process custom data
        info!(bytes = data.len(), "Processing custom data");
        
        // Return a response based on processing outcome
        if data.len() > 100 {
            Ok(Message::Custom(vec![1, 0, 1])) // Success code
        } else {
            Ok(Message::Custom(vec![0, 0, 1])) // Error code
        }
    } else {
        // Handle unexpected message type
        info!("Received incorrect message type for DATA_PROCESS");
        Ok(Message::Unknown)
    }
});

The dispatcher automatically routes incoming messages based on their message_type(). You can register handlers for both built-in message types and your own custom message types.

Running Tests

cargo test

Runs full unit + integration tests.

Benchmarking

# Run all benchmarks with output
cargo test --test perf -- --nocapture

# Run specific benchmark
cargo test --test perf benchmark_roundtrip_latency -- --nocapture
cargo test --test perf benchmark_throughput -- --nocapture

Performance Metrics

Metric Result Environment
Roundtrip Latency <1ms avg Local transport
Throughput ~5,000 msg/sec Standard payload
TLS Overhead +2-5ms With certificate validation

The library includes comprehensive benchmarking tools that measure:

  • Message roundtrip latency (client → server → client)
  • Maximum throughput under various conditions
  • Backpressure effectiveness during high load
  • Connection recovery after network failures

For detailed benchmarking documentation, see the API Reference.

Documentation

Project Structure

src/
├── config.rs    # Configuration structures and loading
├── core/        # Codec, packet structure  
├── protocol/    # Handshake, heartbeat, message types
├── transport/   # TCP, Unix socket, TLS, Cluster
├── service/     # Daemon + client APIs
├── utils/       # Compression, crypto, timers
benches/         # Criterion benchmarks
fuzz/            # Fuzzing targets (cargo-fuzz)
tests/           # Integration and stress tests

Contributing

Contributions welcome! Please:

  1. Run cargo fmt && cargo clippy --workspace -- -D warnings before committing
  2. Add tests for new features
  3. Update documentation as needed
  4. Follow existing code style and patterns

For security issues, see SECURITY.md.

Documentation | API Reference | Performance | Principles