Expand description
PROXY protocol decoder and encoder
This crate provides a decoder and encoder for the PROXY protocol, which is used to preserve original client connection information when proxying TCP connections for protocols that do not support this higher up in the stack.
The PROXY protocol is supported by many load balancers and proxies, including HAProxy, Amazon ELB, Amazon ALB, and others.
This crate implements the entire specification, except parsing the AF_UNIX
address
type (the header is validated / parsed, but the address is not decoded or exposed in
the API).
§Usage
§Decoding
To decode a PROXY protocol header from an existing buffer, use ProxyHeader::parse
:
use proxy_header::{ProxyHeader, ParseConfig};
let buf = b"PROXY TCP6 2001:db8:1::1 2001:db8:2::1 52953 25\r\nHELO example.com\r\n";
let (header, len) = ProxyHeader::parse(buf, ParseConfig::default())?;
match header.proxied_address() {
Some(addr) => {
println!("Proxied connection from {} to {}", addr.source, addr.destination);
}
None => {
println!("Local connection (e.g. healthcheck)");
}
}
println!("Client sent: {:?}", &buf[len..]);
In addition to the address information, the PROXY protocol version 2 header can contain
additional information in the form of TLV (type-length-value) fields. These can be accessed
through the ProxyHeader::tlvs
iterator or through convenience accessors such as ProxyHeader::authority
.
See Tlv
for more information on the different types of TLV fields.
use proxy_header::Tlv;
for tlv in header.tlvs() {
match tlv? { // TLV can be malformed
Tlv::UniqueId(v) => {
println!("Unique connection ID: {:?}", v);
}
Tlv::Authority(v) => {
println!("Authority string (SNI): {:?}", v);
}
_ => {}
}
}
See also io
module for a stream wrapper that can automatically parse PROXY protocol.
§Encoding
To encode a PROXY protocol header, use ProxyHeader::encode_v1
for version 1 headers and
ProxyHeader::encode_v2
for version 2 headers.
use proxy_header::{ProxyHeader, ProxiedAddress, Protocol};
let addrs = ProxiedAddress::stream(
"[2001:db8::1:1]:51234".parse().unwrap(),
"[2001:db8::2:1]:443".parse().unwrap()
);
let header = ProxyHeader::with_address(addrs);
let mut buf = [0u8; 1024];
let len = header.encode_to_slice_v2(&mut buf).unwrap();
Modules§
- IO wrapper for proxied streams.
Structs§
- Configuration for parsing PROXY protocol headers
- Address information from a PROXY protocol header
- A PROXY protocol header
- SSL information from a PROXY protocol header
- Iterator over PROXY protocol TLV (type-length-value) fields
Enums§
- Protocol type
- Typed TLV (type-length-value) field