ppp

A Proxy Protocol Parser written in Rust. Supports both text and binary versions of the HAProxy header. See HAProxy for the protocol specification.

Usage

Add the following to your Cargo.toml as a dependency:

toml ppp = "2.0"

Then, you can use either the text or binary versions of the protocol.

To parse or generate the text version use: ```rust use ppp::v1; use std::net::SocketAddr;

let clientaddress: SocketAddr = ...; let serveraddress: SocketAddr = ...;

// Create a v1 header let header = v1::Addresses::from((clientaddress, serveraddress)).to_string();

asserteq!(header, v1::Header::tryfrom(header.asstr()).unwrap().tostring()); ```

To parse or generate the binary version use: ```rust use ppp::v2; use std::net::SocketAddr;

let clientaddress: SocketAddr = ...; let serveraddress: SocketAddr = ...;

let header = v2::Builder::withaddresses( v2::Version::Two | v2::Command::Proxy, v2::Protocol::Stream, (clientaddress, serveraddress), ) .writetlv(v2::Type::NoOp, b"Hello, World!") .unwrap() .build() .unwrap();

asserteq!( header, v2::Header::tryfrom(header.asslice()).unwrap().asbytes() ); ```

To parse either version use:

```rust use ppp::{HeaderResult, PartialResult, v1};

let input = "PROXY UNKNOWN\r\n"; let header = HeaderResult::parse(input.as_bytes());

assert_eq!(header, Ok(v1::Header::new(input, v1::Addresses::Unknown)).into()); ```

Examples

The repository contains examples for how to use both versions of the proxy protocol with streaming support. To run the examples, you will need to use 3 terminal windows.

Proxy

The proxy Server that writes the proxy protocol header will be in its own terminal. The example takes an optional argument of which version of the header to write as v1 or v2, with a default of v2.

Version 2: bash cargo run --examples one_byte

Version 1: bash cargo run --examples one_byte v1

Server

A minimal HTTP server that reads the proxy protocol headers and responds to HTTP requests.

bash cargo run --examples server

HTTP Client

We use cURL as the HTTP client for the examples, but any HTTP client will do.

bash curl -vvv http://localhost:8888/

Profiling

Profiling a benchmark run is currently only supported on a *nix environment. The profiler outputs a flamegraph in the target directory. To run a profiling session use:

bash cargo bench -- --profile-time=60

Benchmark

To run the benchmarks use:

bash cargo bench

Results

The following are a snapshot of a benchmarking run on a desktop with a hexa-core i7 processor with hyper-threading.

Binary

bash PPP Binary/v2::Header::try_from/IPv4 with TLVs time: [51.357 ns 52.009 ns 52.722 ns] PPP Binary/v2::Header::as_bytes/IPv4 with TLVs time: [515.38 ps 516.26 ps 517.48 ps] PPP Binary/v2::Header::try_from/IPv6 without TLVs time: [48.939 ns 49.032 ns 49.147 ns] PPP Binary/v2::Header::as_bytes/IPv6 without TLVs time: [514.61 ps 515.33 ps 516.42 ps] PPP Binary/v2::Builder::build/IPv6 with TLVs time: [1.3795 us 1.3983 us 1.4194 us] PPP Binary/v2::Builder::build/IPv6 with TLVs with length time: [136.72 ns 139.03 ns 141.54 ns]

Text

bash PPP Text/v1::Header::try_from/UNKNOWN time: [54.173 ns 54.247 ns 54.338 ns] PPP Text/v1::Header::try_from/TCP4 time: [217.13 ns 217.62 ns 218.33 ns] PPP Text/v1::Header::try_from/TCP6 time: [537.42 ns 537.92 ns 538.60 ns] PPP Text/v1::Header::try_from/TCP6 Compact time: [395.83 ns 397.08 ns 398.96 ns] PPP Text/v1::Header::try_from/Worst Case time: [209.62 ns 209.75 ns 209.89 ns] PPP Text/v1::Header::to_string/TCP4 time: [70.355 ns 70.432 ns 70.528 ns] PPP Text/v1::Addresses::to_string/TCP4 time: [413.55 ns 415.27 ns 418.09 ns] PPP Text/v1::Header::to_string/TCP6 time: [81.200 ns 81.421 ns 81.716 ns] PPP Text/v1::Addresses::to_string/TCP6 time: [851.04 ns 852.34 ns 853.91 ns] PPP Text/v1::Header::to_string/UNKNOWN time: [72.256 ns 73.089 ns 73.979 ns] PPP Text/v1::Addresses::to_string/UNKNOWN time: [66.237 ns 66.305 ns 66.391 ns]