# Instructions for AI Agents
## What is This Codebase?
A Tokio-native Rust implementation of the Proxy Protocol (v1 and v2).
## Build System
All the standard Cargo commands apply but with one important detail: make sure to add `--all-features` so that
all feature-gated code (vendor TLV parsing, axum integration) is included.
* `cargo build --all-features` to build
* `cargo nextest run --all-features` to run tests
* `cargo clippy --all-features` to lint
* `cargo fmt` to reformat
* `cargo bench` to run criterion benchmarks
* `cargo publish` to publish the crate
Always run `cargo check --all-features` before making changes to verify the codebase compiles cleanly.
If compilation fails, investigate and fix compilation errors before proceeding with any modifications.
## Key Files
* `src/parse/` — v1 and v2 header parsing, TLV parsing, CRC32c validation
* `src/builder.rs` — `HeaderBuilder` for constructing headers
* `src/listener.rs` — `ProxyProtocolListener` wrapping `TcpListener`
* `src/stream.rs` — `ProxiedStream` with leftover-byte handling
* `src/types.rs` — core types: `ProxyInfo`, `Tlvs`, `SslInfo`, enums
* `src/config.rs` — `ProxyProtocolConfig`, `VersionPreference`
* `src/policy.rs` — connection policies (`AcceptAll`, `TrustedProxies`, `MixedMode`)
* `src/axum.rs` — axum `Listener` integration, `ProxyConnectInfo` (feature-gated)
* `src/vendor/` — AWS, Azure, GCP vendor TLV parsing (feature-gated)
## Test Suite Layout
* `tests/unit/parse_v1.rs` — v1 parsing: TCP4, TCP6, UNKNOWN, edge cases, errors
* `tests/unit/parse_v2.rs` — v2 parsing: IPv4/IPv6/Unix stream/dgram, LOCAL, errors
* `tests/unit/parse_tlv.rs` — TLV parsing: ALPN, authority, SSL, NOOP, vendor TLVs
* `tests/unit/parse_crc.rs` — CRC32c roundtrips, corruption detection
* `tests/unit/builder.rs` — builder roundtrips for all variants
* `tests/unit/integration.rs` — full listener/stream integration with real TCP
* `tests/unit/policy.rs` — policy unit tests
* `tests/proptests/proptest_parse.rs` — property-based tests
Use `cargo nextest run --profile default --all-features '--' --exact [test module name]` to run
all tests in a specific module.
### Property-based Tests
Property-based tests are written using [proptest](https://docs.rs/proptest/latest/proptest/) and
use a naming convention: they begin with `prop_`.
To run the property-based tests specifically, use `cargo nextest run --all-features 'prop_'`.
## Source of Domain Knowledge
The [HAProxy Proxy Protocol specification](https://www.haproxy.org/download/2.9/doc/proxy-protocol.txt).
## Writing Style
Keep comments short and to the point. Avoid filler words like "This function does X" when the
function name already says it. Don't add doc comments to obvious methods. Match the existing
comment density — the codebase is deliberately light on comments.
## Change Log
If asked to perform change log updates, consult and modify `CHANGELOG.md` and stick to its
existing writing style.
## Git Commits
* Do not commit changes automatically without an explicit permission to do so
* Never add yourself as a git commit coauthor
* Never mention yourself in commit messages in any way (no "Generated by", no AI tool links, etc)