Struct Builder 

pub struct Builder { /* private fields */ }

Implementation of the builder pattern for PROXY protocol v2 headers. Supports both valid and invalid headers via the write_payload and write_payloads functions.

Examples

use rama_haproxy::protocol::v2::{Addresses, AddressFamily, Builder, Command, IPv4, Protocol, PROTOCOL_PREFIX, Type, Version};
let mut expected = Vec::from(PROTOCOL_PREFIX);
expected.extend([
   0x21, 0x12, 0, 16, 127, 0, 0, 1, 192, 168, 1, 1, 0, 80, 1, 187, 4, 0, 1, 42
]);

let addresses: Addresses = IPv4::new([127, 0, 0, 1], [192, 168, 1, 1], 80, 443).into();
let header = Builder::with_addresses(
    Version::Two | Command::Proxy,
    Protocol::Datagram,
    addresses
)
.write_tlv(Type::NoOp, [42].as_slice())
.unwrap()
.build()
.unwrap();

assert_eq!(header, expected);

Implementations

impl Builder

pub const fn new(version_command: u8, address_family_protocol: u8) -> Self

Creates an instance of a Builder with the given header bytes. No guarantee is made that any address bytes written as a payload will match the header’s address family. The length is determined on build unless set_length is called to set an explicit value.

pub fn with_addresses<T: Into<Addresses>>( version_command: u8, protocol: Protocol, addresses: T, ) -> Self

Creates an instance of a Builder with the given header bytes and Addresses. The address family is determined from the variant of the Addresses given. The length is determined on build unless set_length is called to set an explicit value.

pub fn with_reserve_capacity(self, capacity: usize) -> Self

Reserves the requested additional capacity in the underlying buffer. Helps to prevent resizing the underlying buffer when called before write_payload, write_payloads. When called after write_payload, write_payloads, useful as a hint on how to resize the buffer.

pub fn set_reserve_capacity(&mut self, capacity: usize) -> &mut Self

Reserves the requested additional capacity in the underlying buffer. Helps to prevent resizing the underlying buffer when called before write_payload, write_payloads. When called after write_payload, write_payloads, useful as a hint on how to resize the buffer.

pub fn with_length(self, length: impl Into<Option<u16>>) -> Self

Overrides the length in the header. When set to Some value, the length may be smaller or larger than the actual payload in the buffer.

pub fn set_length(&mut self, length: impl Into<Option<u16>>) -> &mut Self

Overrides the length in the header. When set to Some value, the length may be smaller or larger than the actual payload in the buffer.

pub fn write_payloads<T, I, II>(self, payloads: II) -> Result<Self>

where T: WriteToHeader, I: Iterator<Item = T>, II: IntoIterator<IntoIter = I, Item = T>,

Writes a iterable set of payloads in order to the buffer. No bytes are added by this Builder as a delimiter.

pub fn write_payload<T: WriteToHeader>(self, payload: T) -> Result<Self>

Writes a single payload to the buffer. No surrounding bytes (terminal or otherwise) are added by this Builder.

pub fn write_tlv(self, kind: impl Into<Type>, value: &[u8]) -> Result<Self>

Writes a Type-Length-Value as a payload. No surrounding bytes (terminal or otherwise) are added by this Builder. The length is determined by the length of the slice. An error is returned when the length of the slice exceeds u16::MAX.

pub fn with_crc32c(self, enabled: bool) -> Self

Toggle automatic emission of a valid PP2_TYPE_CRC32C TLV.

When set, Builder::build appends the CRC32C TLV as the last thing in the header (so it covers every other TLV) and patches in the correct value, computed over the entire serialised header with the CRC field treated as zeros (spec section 2.2.5).

Callers should never write a CRC32C TLV themselves — the value depends on the final byte layout, which only the builder sees.

pub fn set_crc32c(&mut self, enabled: bool) -> &mut Self

Toggle automatic emission of a valid PP2_TYPE_CRC32C TLV.

When set, Builder::build appends the CRC32C TLV as the last thing in the header (so it covers every other TLV) and patches in the correct value, computed over the entire serialised header with the CRC field treated as zeros (spec section 2.2.5).

Callers should never write a CRC32C TLV themselves — the value depends on the final byte layout, which only the builder sees.

pub fn build(self) -> Result<Vec<u8>>

Builds the header and returns the underlying buffer. If no length was explicitly set, returns an error when the length of the payload portion exceeds u16::MAX.

If Builder::with_crc32c is enabled, a PP2_TYPE_CRC32C TLV is appended as the last thing in the header and patched with the value computed over the entire serialised header (with the CRC field zeroed during computation, per spec section 2.2.5).

Trait Implementations

impl Debug for Builder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.