rust-networking-protocols-guide

name	rust-networking-protocols-guide
description	Use when building Rust networking protocol implementations (QUIC, HTTP/3, gRPC, custom TCP/UDP protocols, WebSocket, DNS, TLS-terminating proxies). Covers protocol state machine modeling, zero-copy parsing, TLS integration, congestion control, connection pooling, and QUIC multiplexing. Vertical deepening of rust-architecture-guide for network protocol engineering.
metadata	{"version":"1.0.0","philosophy":"Protocol First, Mechanical Sympathy, Defense in Depth, Jeet Kune Do","domain":"network protocol engineering","relationship":"vertical-deepening-of:[rust-architecture-guide, rust-systems-cloud-infra-guide]","default_edition":"2024","supported_editions":["2021","2024"],"aligned_with":["QUIC RFC 9000","HTTP/3 RFC 9114","rustls architecture","tokio codec","nom/winnow parsing"]}

Rust Networking Protocols Guide V1.0.0

Vertical deepening of rust-architecture-guide and rust-systems-cloud-infra-guide for network protocol engineering. Covers the full stack from wire format parsing to application-level protocol state machines.

Core Philosophy

Principle	Description
Protocol First	The protocol specification is the source of truth. Code is the executable version of the RFC.
Mechanical Sympathy	Wire format parsing aligns with CPU branch predictor. Zero-copy at every layer boundary.
Defense in Depth	Every byte from the network is hostile. Validate at ingress. Fuzz at integration.
Jeet Kune Do	Parse with one pass. State machines fold all edge cases into a closed set of transitions.

---

Action 1: Protocol State Machine Modeling

Every protocol is a finite state machine. Model it as such.

• Typed States: enum State { Handshake, Established, Closing, Closed } — compiler-enforced transitions
• tokio-util Codec: Encoder + Decoder traits. Frame-level parsing with backpressure.
• Layered Protocol Stacks: L2 (Ethernet) → L3 (IP) → L4 (TCP/UDP) → L5 (TLS) → L7 (HTTP/gRPC)
• Red Line: Protocol states must be exhaustive. Missing transitions = panics or hangs.

→ references/01-state-machines.md

---

Action 2: Zero-Copy Wire Parsing

Parse network bytes without allocating intermediate buffers.

• nom / winnow: Combinator-based parsing on &[u8]. Zero-copy by default.
• Streaming Parsers: winnow::Partial for incomplete input — resume parsing when more data arrives
• Binary Protocols: Fixed-width headers + length-prefixed payloads. Skip fields via seek.
• Red Line: Never allocate a Vec<u8> copy of parsed fields. References to input buffer.

→ references/02-zero-copy-parsing.md

---

Action 3: QUIC & HTTP/3 Implementation

QUIC is TCP+TLS+HTTP/2 reimagined on UDP with 0-RTT and connection migration.

• Quinn / quiche / s2n-quic: Choose based on platform and feature requirements
• Stream Multiplexing: Unlimited independent streams per connection, no head-of-line blocking
• 0-RTT Data: Security trade-offs — replay-safe idempotent requests only
• Connection Migration: Survive IP address changes (mobile/Wi-Fi handoff) via connection IDs
• Red Line: 0-RTT replay protection must be handled at the application layer.

→ references/03-quic-http3.md

---

Action 4: TLS Integration

TLS is not optional for public internet protocols. All internet-facing production protocols must encrypt by default. Internal trusted LAN services, Unix socket control planes, and WireGuard/IPsec mesh endpoints may omit TLS with documented threat model rationale.

• rustls: Pure-Rust TLS. ServerConfig/ClientConfig with Arc<CryptoProvider>.
• Certificate Management: rcgen for self-signed, rustls-acme for Let's Encrypt automation
• ALPN Negotiation: Application-Layer Protocol Negotiation for HTTP/2 vs HTTP/1.1 routing
• mTLS: Mutual TLS for service-to-service authentication. Client certificate verification.
• Red Line: Never disable certificate verification in production. Use dangerous_configuration only in tests.

→ references/04-tls-integration.md

---

Action 5: Congestion Control & Flow Control

Protocol performance is bounded by congestion control algorithms.

• BBR / CUBIC: Implemented in kernel or userspace. BBR for high-BDP paths, CUBIC for compatibility.
• Pacing: Smooth out bursts to avoid packet loss. Tokens-based rate limiter.
• ECN: Explicit Congestion Notification — mark instead of drop. Respond with CWR.
• Flow Control Windows: QUIC stream-level and connection-level flow control credits
• Red Line: Unbounded send buffers → bufferbloat. Must enforce send window limits.

→ references/05-congestion-control.md

---

Action 6: Connection Pooling & Multiplexing

Managing thousands of concurrent connections requires pooling.

• Connection Pool: deadpool / bb8 pattern. Max idle, max lifetime, health check on checkout.
• HTTP/2 HPACK: Header compression dictionary per connection. Dynamic table size limits.
• Multiplexing Strategy: Stream count limits, stream prioritization (weighted fair queuing)
• Red Line: Connection pools must detect dead connections (TCP RST, idle timeout) and evict.

→ references/06-connection-pooling.md

---

Action 7: DNS & Service Discovery

Every connection starts with DNS. Get it right.

• hickory-resolver (formerly trust-dns): Async DNS with caching, DNSSEC, DoH/DoT
• SRV Records: Service discovery with priority/weight for load distribution
• Happy Eyeballs: Race IPv6 and IPv4 connections, use whichever succeeds first
• Red Line: DNS resolution must have timeout (default 5s). Infinite DNS wait = infinite connection wait.

→ references/07-dns-discovery.md

---

Action 8: Fuzzing & Protocol Security

Network protocols are attack surfaces. Fuzz them aggressively.

• cargo-fuzz / libfuzzer: Structure-aware fuzzing with arbitrary::Arbitrary for wire format structs
• proptest: Property-based testing for protocol invariants (round-trip, idempotency)
• AFL++ / honggfuzz: Coverage-guided fuzzing for complex protocol parsers
• Red Line: P0 wire-format protocol parsers must have a fuzz target. Fixed-structure parsers and internal formats may defer fuzzing to release gates. CI smoke fuzz (60s) acceptable for PRs; long fuzz (hours) reserved for pre-release.

→ references/08-fuzzing-security.md

---

Prohibitions Quick List

Category	Prohibited	Mandatory
Wire Parsing	Vec<u8> copies of parsed fields	Zero-copy &[u8] references
TLS	Disabled certificate verification	rustls with CA verification
0-RTT	Non-idempotent data in 0-RTT	Application-level replay protection
Send Buffer	Unbounded send window	Flow control with credit limits
Protocol State	Missing state transitions	Exhaustive enum + match
DNS	Infinite resolution wait	Timeout (< 5s)
Connection Pool	Blind connection reuse	Health check + dead connection eviction
Parser Security	Parsing without fuzzing	cargo-fuzz target per parser
ALPN	No application protocol negotiation	Explicit ALPN in TLS config

---

Document Relationship Map

flowchart TD
    subgraph Foundation["rust-architecture-guide + cloud-infra-guide"]
        StateMachine[07-state-machine.md]
        IOModel[01-io-model.md]
        FFI[15-ffi-interop.md]
    end

    subgraph Net["rust-networking-protocols-guide"]
        States[01-state-machines.md]
        Parse[02-zero-copy-parsing.md]
        QUIC[03-quic-http3.md]
        TLS[04-tls-integration.md]
        CC[05-congestion-control.md]
        Pooling[06-connection-pooling.md]
        DNS[07-dns-discovery.md]
        Fuzz[08-fuzzing-security.md]
    end

    StateMachine -->|protocol states| States
    IOModel -->|epoll/io_uring| QUIC
    FFI -->|FFI safety| Parse
    States --> QUIC
    States --> Pooling
    Parse --> QUIC
    TLS --> QUIC
    CC --> QUIC
    DNS --> Pooling
    Parse --> Fuzz

    style States fill:#d9534f,stroke:#c9302c,color:#fff
    style Parse fill:#5cb85c,stroke:#4cae4c,color:#fff
    style QUIC fill:#f0ad4e,stroke:#ec971f,color:#000

---

Reference Files

File	Topic	Key Directive
01-state-machines.md	Protocol State Machines	Typed states, tokio-util Codec, layered stacks
02-zero-copy-parsing.md	Zero-Copy Wire Parsing	nom/winnow, streaming parsers, binary protocols
03-quic-http3.md	QUIC & HTTP/3	Multiplexing, 0-RTT, connection migration
04-tls-integration.md	TLS Integration	rustls, mTLS, ALPN, certificate management
05-congestion-control.md	Congestion & Flow Control	BBR/CUBIC, pacing, ECN, flow control windows
06-connection-pooling.md	Connection Pooling	deadpool/bb8, HPACK, multiplexing strategy
07-dns-discovery.md	DNS & Service Discovery	hickory-resolver, SRV, Happy Eyeballs
08-fuzzing-security.md	Fuzzing & Protocol Security	cargo-fuzz, proptest, AFL++

---

Changelog

V1.0.0

• Initial framework: protocol state machines, zero-copy parsing with nom/winnow
• QUIC/HTTP/3 implementation patterns and 0-RTT security considerations
• TLS integration with rustls, mTLS, and certificate automation
• Congestion control, connection pooling, DNS discovery, fuzzing for security
• Aligned with rust-architecture-guide V9.1.0 and rust-systems-cloud-infra-guide V6.1.0