proxy-protocol-codec 0.1.2

PROXY Protocol codec implementation in Rust. See HAProxy for the protocol specification.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

# proxy-protocol-codec

[![License](https://img.shields.io/badge/License-Apache%202.0-yellowgreen.svg)](https://opensource.org/licenses/Apache-2.0)
[![Crates.io Version](https://img.shields.io/crates/v/proxy-protocol-codec.svg)](https://crates.io/crates/proxy-protocol-codec)
[![Docs.rs Version](https://docs.rs/proxy-protocol-codec/badge.svg)](https://docs.rs/proxy-protocol-codec)

PROXY Protocol codec implementation in Rust. See [HAProxy](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) for the protocol specification.

## Usage

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

```toml
proxy-protocol-codec = "0.1"
```

### Encoding

```rust
// PROXY Protocol v1 (text format), TCP4
let address_pair = proxy_protocol_codec::v1::AddressPair::Inet {
    src_ip: "127.0.0.1".parse().unwrap(),
    dst_ip: "127.0.0.2".parse().unwrap(),
    src_port: 8080,
    dst_port: 80,
};
let header = proxy_protocol_codec::v1::Header::new(address_pair);

assert_eq!(header.encode(), "PROXY TCP4 127.0.0.1 127.0.0.2 8080 80\r\n");

// PROXY Protocol v1 (text format), TCP6
let address_pair = proxy_protocol_codec::v1::AddressPair::Inet6 {
    src_ip: "::1".parse().unwrap(),
    dst_ip: "::2".parse().unwrap(),
    src_port: 8080,
    dst_port: 80,
};
let header = proxy_protocol_codec::v1::Header::new(address_pair);

assert_eq!(header.encode(), "PROXY TCP6 ::1 ::2 8080 80\r\n");

// PROXY Protocol v1 (text format), UNKNOWN
let address_pair = proxy_protocol_codec::v1::AddressPair::Unspecified;
let header = proxy_protocol_codec::v1::Header::new(address_pair);

assert_eq!(header.encode(), "PROXY UNKNOWN\r\n");
```

```rust
// PROXY Protocol v1 (binary format)
let header = proxy_protocol_codec::v2::Header::new_proxy(
    proxy_protocol_codec::v2::Protocol::Stream,
    proxy_protocol_codec::v2::AddressPair::Inet {
        src_ip: "127.0.0.1".parse().unwrap(),
        dst_ip: "127.0.0.2".parse().unwrap(),
        src_port: 8080,
        dst_port: 80,
    },
);

let encoded = header
    .encode()
    .write_ext_authority(b"example.com")? // Optional, write extensions.
    .finish()?;
```

### Decoding

```rust
// PROXY Protocol v1 (text format)
let encoded = ...;

proxy_protocol_codec::v1::Header::decode(encoded))?
```

```rust
// PROXY Protocol v2 (binary format)
let tcp_stream = ...;

let mut buf = Vec::with_capacity(proxy_protocol_codec::v2::HEADER_SIZE);

unsafe {
    // Safe op filling with 0 is OK
    buf.set_len(proxy_protocol_codec::v2::HEADER_SIZE);
}

let peeked = tcp_stream.peek(&mut buf[..])?;

if peeked != 16 {
    // Not enough data to decode the header, the sender should not fragment the header.
    return Err(std::io::Error::new(
        std::io::ErrorKind::UnexpectedEof,
        "Not enough data to decode PROXY Protocol v2 header",
    ));
}

match proxy_protocol_codec::v2::Header::decode(&buf[..])? {
    proxy_protocol_codec::v2::Decoded::Partial(remaining) => {
        let total_length = proxy_protocol_codec::v2::HEADER_SIZE + remaining.get();

        unsafe {
            // Safe op filling with 0 is OK
            buf.set_len(total_length);
        }

        // Partial header, need more data.
        tcp_stream.read_exact(
            &mut buf[proxy_protocol_codec::v2::HEADER_SIZE..proxy_protocol_codec::v2::HEADER_SIZE + remaining.get()]
        )?;

        // Decode the full header with the remaining bytes.
        let proxy_protocol_codec::v2::Decoded::Some(header) = proxy_protocol_codec::v2::Header::decode(&buf[..])? else {
            panic!("must be Some here");
        };

        header
    }
    proxy_protocol_codec::v2::Decoded::Some(header) => {
        // Successfully decoded the header (without address pair or extensions).

        header
    }
    proxy_protocol_codec::v2::Decoded::None => {
        // Partial header, need more data.
        
        return ...;
    }
}
```