misalcedo / ppp

A Proxy Protocol Parser written in Rust.

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]

ppp's Issues

Short IPv6 parsing

Awesome crate!

HAproxy sends shortened ipv6 sometimes (like ::1), but this crate doesn't parse them. Would it be possible to add this feature?

For example, this test fails:

        let text =
            "PROXY TCP6 ::1 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff 65535 65535\r\nHi!".as_bytes();
        let expected = Header::version_1(
            (
                [0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x1],
                [
                    0xFFFF, 0xFFFF, 0xFFFF, 0xFFFF, 0xFFFF, 0xFFFF, 0xFFFF, 0xFFFF,
                ],
                65535,
                65535,
            )
                .into(),
        );

        assert_eq!(parse_v1_header(text), Ok((&b"Hi!"[..], expected)));

Auto-publish new versions to crates.io

Add a new release that only runs when when the Cargo.toml file changes on master to publish a new version to crates.IO

SSL TLV should be hex 0x20

There is a typo in the definition of PP2_TYPE_SSL, it's 20 in decimal and it should be in hex.

ppp/src/v2/model.rs

Line 132 in 2eebc45

SSL = 20,

See proxy-protocol.txt

#define PP2_TYPE_SSL            0x20
#define PP2_SUBTYPE_SSL_VERSION 0x21
#define PP2_SUBTYPE_SSL_CN      0x22

Use Cow in headers

Cow allows borrowed or owned values so the header would be able to store either a byte or string slice, or a byte vector or string respectively.

That allows us to build headers using the same struct returned when parsing headers, which removes the need for the builder. Though we still need the builder's ability to create TLVs.

Build ppv2 headers to write

The goal is to make writer an enum of either a vec or box dyn write.

Then to create a from impl for write, create a new with builder method, and expose the write header method as having arguments.

Finally flush the writer in build

Add support for zero copy header parsing

Currently, creating a header clones all of the information into a struct that owns the cloned bits.

An alternative would be to have a struct with the same lifetime as the input source that could be turned into an owned version as needed.

This would be beneficial in cases where you only need a subset of fields as owned values or don't need the header past the input's lifetime.

See https://doc.rust-lang.org/std/borrow/trait.ToOwned.html

Lastly, would be useful to separate the header into an enum with different structs for version 1 vs. 2. Version 1 is much simpler as it lacks TLV support.