pea2pea

A clean, modular, and lightweight peer-to-peer networking library for Rust.

pea2pea abstracts away the complex, low-level boilerplate of P2P networking - TCP stream handling, connection pooling, framing, backpressure, etc. - allowing you to focus strictly on your network's logic and protocol implementation.

📖 Table of Contents

• ⚡ Why pea2pea?
• 🚀 Quick Start
• 🧩 Architecture
• 🔒 Security
• 🏁 Benchmarking
• 📚 Examples
• 📦 Installation
• 🚧 Project Status
• 🤝 Contributing

---

⚡ Why pea2pea?

• Battle-Tested in Production: This library has been vendored and deployed in high-throughput, real-world decentralized networks, successfully managing complex topologies and heavy traffic.
• Simplicity First: No complex configuration objects or rigid frameworks. You can audit the library yourself in a single afternoon.
• Minimal Dependency Tree: pea2pea relies strictly on tokio and standard crates, resulting in lightning-fast compile times and tiny binaries.
• Uncompromising Performance: Designed as a zero-weight abstraction layer, the library imposes negligible overhead, allowing your application to saturate the underlying network hardware or loopback interface limits.
• Tiny Footprint: The core node structure occupies just ~16kB of RAM; per-connection memory usage starts at ~14kB and scales directly with your configured buffer sizes.
• Meticulously Tested: A comprehensive collection of tests and examples ensures correctness; there is no unsafe code involved.
• Complete Control: You dictate the application logic, and control every byte sent and received. Use slightly altered nodes to fuzz-test and stress-test your production nodes.

---

🚀 Quick Start

Spin up a TCP node capable of receiving messages in 36 lines of code:

use std::{io, net::SocketAddr};

use pea2pea::{Config, ConnectionSide, Node, Pea2Pea, protocols::Reading};

// Define your node
#[derive(Clone)]
struct MyNode {
    p2p: Node,
    // add your state here
}

// Implement the Pea2Pea trait
impl Pea2Pea for MyNode {
    fn node(&self) -> &Node {
        &self.p2p
    }
}

// Specify how to read network messages
impl Reading for MyNode {
    type Message = bytes::BytesMut;
    type Codec = tokio_util::codec::LengthDelimitedCodec;

    fn codec(&self, _addr: SocketAddr, _side: ConnectionSide) -> Self::Codec {
        Default::default()
    }

    async fn process_message(&self, source: SocketAddr, _message: Self::Message) {
        tracing::info!(parent: self.node().span(), "received a message from {source}");
    }
}

#[tokio::main]
async fn main() -> io::Result<()> {
    // Log events
    tracing_subscriber::fmt::init();

    // Create the node's configuration
    let config = Config {
        listener_addr: Some("127.0.0.1:0".parse().unwrap()),
        ..Default::default()
    };

    // Instantiate the node
    let node = MyNode {
        p2p: Node::new(config),
    };

    // Start reading incoming messages according to the Reading protocol
    node.enable_reading().await;

    // Start accepting connections
    node.p2p.toggle_listener().await?;

    // Keep the node running
    std::future::pending::<()>().await;

    Ok(())
}

---

🧩 Architecture

pea2pea operates on a modular "hooks" system. You control the connection lifecycle by implementing specific traits, while the library handles the low-level async plumbing.

(For a visual representation, see the Connection Lifecycle Graph)

Simply implement the traits you need:

• Handshake: Secure your connections (tls, noise, etc.), configure the stream, or exchange metadata.
• Reading & Writing: Define framing (codecs), message processing, and backpressure handling.
• OnConnect / OnDisconnect: Trigger logic when a connection is fully established or severed (cleanup, recovery).

For full details, refer to the protocols documentation.

---

🔒 Security

pea2pea is built to survive the hostile internet. Its architecture naturally mitigates common denial-of-service vectors without requiring complex configuration:

• Slowloris / Connection Exhaustion: The configurable timeouts ensure that "creeper" connections that fail to handshake or send data are aggressively pruned, freeing up slots for legitimate peers.
• SYN Floods / Rapid Churn: The library's internal state machine handles high-frequency connect/disconnect events (churn) without leaking file descriptors or memory.
• Malicious Payloads / Fuzzing: The strict separation of the Reading protocol means that malformed packets or garbage data are rejected at the codec level, instantly dropping the offender before application logic is touched.
• Resource Limits: Hard caps on connection counts prevent bad actors from monopolizing your node's resources.

Challenge: We invite you to try and break a pea2pea-powered node. Point your favorite stress-testing tool (like hping3 or a custom fuzzer) at it; the node will hold its ground.

---

🏁 Benchmarking

pea2pea is designed to be as fast as the machine it runs on. To verify the throughput on your specific hardware, run the included benchmark suite:

cargo test --release --test benches -- --nocapture --ignored

Be sure to also check out the stress tests included in the examples.

---

📚 Examples

Check out the examples directory, which is organized by complexity and use case:

• 🎮 Fun & Visual (Tutorials): Gamified scenarios like the Telephone Game or Hot Potato that demonstrate core concepts like topology, message passing, and basic state synchronization.
• 🛠️ Practical & Patterns: Standard infrastructure patterns, including TLS, Noise Handshakes, Rate Limiting, and RPC.
• 🧠 Advanced & Stress Tests: High-load scenarios like Connection Churn or Dense Mesh that demonstrate the library's performance and libp2p interop.

---

📦 Installation

Add this to your Cargo.toml:

[dependencies]
pea2pea = "x.x.x" # replace with the latest version
tokio = { version = "1", features = ["rt"] } # pick any other features you need

---

🚧 Project Status

Current State: Stable & Feature-Complete.

Despite the 0.x versioning, pea2pea is considered production-ready. The core architecture is finished and proven.

• API Stability: The public API is stable. We do not anticipate breaking changes unless there's a very good reason to do so.
• Scope: The library is effectively in "maintenance mode" regarding features. Future development is strictly limited to hardening internals to ensure maximum reliability. We are not adding new features to the core.

---

🤝 Contributing

Please see CONTRIBUTING.md for details on our strict scope policy.