hydra_sync/
lib.rs

1//! # hydra-sync: A Lightweight Zero-Copy E2E SPMC Relay Network Library
2//!
3//! `hydra-sync` is a high-performance, end-to-end encrypted relay library for single producer,
4//! multiple consumer (SPMC) network architectures. It provides a simple yet powerful abstraction
5//! for building distributed systems where one producer broadcasts encrypted data to many consumers
6//! with minimal latency and memory overhead.
7//!
8//! ### Overview
9//!
10//! The library is organized around two main components:
11//!
12//! - **Server** ([`server`]): Manages relay state, maintains active sessions, and routes encrypted frames
13//!   from producers to their respective consumers. Uses `DashMap` for thread-safe session storage.
14//!
15//! - **Client** ([`client`]): Connects to the relay server as either a producer or consumer. Producers
16//!   broadcast encrypted frames, while consumers receive and decrypt them from the internal memory pool.
17//!
18//! ### Protocol
19//!
20//! The protocol consists of two phases:
21//!
22//! 1. **Handshake**: Client and server establish a transport key via X25519 Diffie-Hellman key & nonce exchange.
23//!    This transport key encrypts join and control frames.
24//!
25//! 2. **Data Transfer**: Producers encrypt broadcast frames using AES-GCM with a session-specific key.
26//!    Consumers decrypt received frames using the same session key. Each frame includes an AEAD tag
27//!    for integrity verification. (NO SERVER INTERVENTION IN DATA TRANSFER, SERVER ONLY RELAYS ENCRYPTED FRAMES)
28//!
29//!
30//! #### Quick Example
31//!
32//! ```no_run
33//!use hydra_sync::client::HydraClient;
34//!use hydra_sync::server::HydraServer;
35//!use std::net::SocketAddr;
36//!use anyhow::Result;
37//!
38//!#[tokio::main]
39//!async fn main() -> anyhow::Result<()> {
40//!    let (server, server_addr) = HydraServer::bind_default().await?; // bind to os-assigned port
41//!    let session_id = [0xFFu8; 64];
42//!    let session_key = [0xAAu8; 32];
43//!
44//!    tokio::spawn(async move { server.run(500).await }); // run in background
45//!
46//!    // Producer; sends data to all consumers in the session
47//!    let mut producer =
48//!        HydraClient::connect_producer(server_addr, &session_id, session_key).await?;
49//!    producer.broadcast(b"you are an idiot").await?;
50//!
51//!    // Consumer; receives and decrypts frames from the producer
52//!    let mut consumer =
53//!        HydraClient::connect_consumer(server_addr, &session_id, session_key).await?;
54//!
55//!    loop {
56//!        let data = consumer.recv().await?;
57//!        println!("received {} bytes: {:?}", data.len(), data);
58//!
59//!        // `data` borrows from `consumer`'s internal memory pool and is
60//!        // only valid until the next `recv()` or `broadcast()` call.
61//!        // Copy it out (e.g. `data.to_vec()`) if you need to keep it longer.
62//!        break;
63//!     }
64//!     producer.close().await?; // clean shutdown
65//!
66//!     Ok(())
67//!}
68//! ```
69//!
70//! ### Memory Overhead
71//!
72//! Each client maintains a 18 MB internal memory pool (`BytesMut`) for:
73//! - Buffering encrypted frames during read/write operations
74//! - In-place encryption and decryption without allocating new buffers
75//! - Reusing memory across multiple `recv()`/`broadcast()` calls
76//!
77//! This zero-copy design minimizes garbage collection pressure and reduces latency for
78//! high-throughput scenarios.
79//!
80pub mod client;
81pub mod crypto;
82pub(crate) mod log;
83pub(crate) mod protocol;
84pub mod server;
85pub(crate) mod session;
86
87/// Buffer size for `BufReader` and `BufWriter` in TCP operations (6 MB)
88pub const BUFFER_SIZE: usize = 1024 * 1024 * 6;
hydra_sync/lib.rs

hydra_sync/
lib.rs
