Skip to content

ADR 0006: Zero-Copy Header Parsing and Payload Views

Status

Approved

Context

Standard packet analyzers decode protocol headers into high-level representations, copying fields into new heap-allocated structures like std::string src_ip and std::string dst_ip for processing. String formatting and copy operations destroy low-latency objectives.

Decision

We will cast raw frame bytes directly to header structures (EthernetHeader, IPv4Header, TCPHeader) and access payload sequences using std::string_view.

Design Constraints:

  • The original frame payload is never copied.
  • Strings are only formatted on-demand outside of the packet loop (for CLI output/reporting).
  • All internal evaluations (IP comparison, subnet matching) are performed on numeric byte sequences.

Options Considered

  1. Full Object Decoding: Decodes every packet layer into a heavy heap-allocated class hierarchy. Easy to read, but slow.
  2. Buffer-Sharing Offset Pointers: The engine passes raw pointers and offset indices (ip_offset, tcp_offset) to references. Excellent performance, zero allocations.

Consequences

  • Positive: High performance (sub-50ns parsing), zero runtime heap allocations, minimal CPU instruction footprint.
  • Negative: Raw pointer offsets must be validated against buffer boundaries to prevent memory access violations (buffer overflows) on malformed network traffic.