packet patterns 🌶️ 🌶️ 🌶️

[daniel-noland]

Match on the shape of a packet!

[!NOTE] I think this is the last round of significant structure changes before I can get down to cutting PRs for the ACL stuff 🥳

---

Adds headers::pat, a protocol-aware pattern matching API for Headers. The matcher chain uses Within<T> bounds (from #1445) to enforce valid layer ordering at compile time and runtime gap checks to catch silently skipped layers (e.g. an unaccounted-for VLAN between Ethernet and IPv4).

• Both immutable (pat()) and mutable (pat_mut()) variants are provided, with mutable access via split borrows and split_first_mut no unsafe code is used (directly).
• Embedded ICMP error payloads are reachable through .embedded() with a nested sub-tuple, supporting the NAT rewrite path required by RFC 5508. The abstraction is zero-cost: cargo-show-asm confirms the generated assembly is identical to hand-written code.
• IPv6 extension headers are silently skipped by default from IP positions (the common case), but become strict once any extension is explicitly matched in the chain.
• VLANs are always strict.
• Optional methods (opt_*) distinguish "genuinely absent" from "wrong variant present": a wrong variant is a miss, not absence.
• Utility combinators .when(), .inspect(), and .otherwise() are available at any chain position

[daniel-noland]

notes for agent

[Copilot]

Pull request overview

Adds protocol-aware “packet pattern” matching over Headers, using type-level layer adjacency (Within<T>) to enforce valid layer transitions at compile time while performing strict runtime gap checks for VLANs (and optionally IPv6 extensions).

Changes:

• Moved Within<T> and all layer-ordering/conformance impls into a new headers::within module.
• Added headers::pat providing immutable/mutable matchers (pat() / pat_mut()) plus embedded ICMP payload matching.
• Adjusted visibility of EmbeddedHeaders fields to support matcher implementation.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
net/src/headers/within.rs	Centralizes Within<T> trait + ordering/conformance graph (incl. IPv6 extensions + embedded headers).
net/src/headers/pat.rs	Introduces the pattern-matching API, including mutable + embedded matchers and tests.
net/src/headers/mod.rs	Wires in within and exposes the new pat module.
net/src/headers/embedded.rs	Widens EmbeddedHeaders field visibility for matcher access.
net/src/headers/builder.rs	Removes local Within definition/impls and re-exports the moved trait.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

[Copilot]

confidence: 8
tags: [docs]

ExtGapCheck is documented as a sealed implementation detail that users “never need to reference”, but it is declared pub inside the public headers::pat module, making it part of the crate’s public API surface. To keep the public API minimal (and align docs with reality), consider reducing its visibility (e.g., pub(crate)/pub(super)) and relying on the existing #![allow(private_bounds)], or keep it pub but add #[doc(hidden)] to avoid advertising it as public API.

Suggested change

	/// this module and users never need to reference this trait directly.
	/// this module and users never need to reference this trait directly.
	#[doc(hidden)]

[Copilot]

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

[mvachhar]

Wow, there is a lot of tedious stuff in here. It looks reasonable, though I am relying on the fact that the tests pass rather than a detailed analysis of every case in the implementation. I'm unhappy about the tuple expansion stuff, but without variadic templates, there isn't much alternative. In the C++ world, this type of thing did pay off for Boost which had very ergonomic APIs. Eventually C++ added variadic templates and alot of the ugliness went away. I hope the same happens in Rust.

[mvachhar]

I thought I was done with this crap. Rust needs variadic generics!