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:

ppp = "2.0"

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

To parse or generate the text version use:

use ppp::v1;
use std::net::SocketAddr;

let client_address: SocketAddr = ...;
let server_address: SocketAddr = ...;

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

assert_eq!(header, v1::Header::try_from(header.as_str()).unwrap().to_string());

To parse or generate the binary version use:

use ppp::v2;
use std::net::SocketAddr;

let client_address: SocketAddr = ...;
let server_address: SocketAddr = ...;

let header = v2::Builder::with_addresses(
    v2::Version::Two | v2::Command::Proxy,
    v2::Protocol::Stream,
    (client_address, server_address),
)
.write_tlv(v2::Type::NoOp, b"Hello, World!")
.unwrap()
.build()
.unwrap();

assert_eq!(
    header,
    v2::Header::try_from(header.as_slice()).unwrap().as_bytes()
);

To parse either version use:

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:

cargo run --examples one_byte

Version 1:

cargo run --examples one_byte v1

Server

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

cargo run --examples server

HTTP Client

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

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:

cargo bench -- --profile-time=60

Benchmark

To run the benchmarks use:

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

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

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]