v0.1: fast-path BPF program + toolchain + verifier-pass test (PR #3)

[lunarthegrey]

Summary

Stands up the BPF half of the v0.1 fast-path: the §4.4 XDP program, §4.5 maps, §4.6 counter enum, the nightly+bpfel-unknown-none+bpf-linker toolchain pipeline, and a verifier-pass integration test that round-trips the program through the kernel's BPF verifier in CI. Userspace still stubs run; the aya loader, attach/detach, pin registry, and netns integration test land in PR #4.

What landed

BPF crate — crates/modules/fast-path/bpf/

New non-workspace crate on nightly Rust targeting bpfel-unknown-none. Separate from the main workspace so the rest of the tree stays on stable.

• rust-toolchain.toml pins nightly-2026-04-14; .cargo/config.toml sets linker = bpf-linker and build-std = ["core"] (the target has no prebuilt rust-std).
• aya-ebpf =0.1.1, network-types =0.1.0 pinned per SPEC §7.1.
• Root Cargo.toml workspace.excludes the BPF subdir; build.rs invokes a nested cargo against it.

§4.4 program

Parse Ethernet → IPv4/IPv6 (with IHL + fragment + TTL + complex-header checks) → LPM src-or-dst match (§4.2) → bpf_fib_lookup → TTL decrement + RFC 1624 incremental csum fixup → MAC rewrite → defensive devmap pre-check (§4.4 step 9d) → bpf_redirect_map. Every verdict path bumps its corresponding counter from §4.6.

• Dry-run via cfg map bypasses rewrites and short-circuits to XDP_PASS after matched-counter bumps.
• 802.1Q/802.1ad tagged frames XDP_PASS — VLAN choreography (§4.7) is PR v0.1: VLAN choreography, packet fixtures, kernel 6.0+ probe fix (PR #5) #5.
• IPv4 checksum fixup decrements the csum by 0x0100 in one's-complement arithmetic (the word at bytes 8-9 is TTL:proto; TTL-1 is equivalent to the checksum's M-word shifting +0x0100).

§4.5 maps + §4.6 counters

All §4.5 maps except vlan_resolve:

• allow_v4, allow_v6: LpmTrie with 1024-entry max, matches src-or-dst per §4.2.
• cfg: 1-entry Array<FpCfg>. FpCfg has a reserved version: u32 byte so future additions don't break userspace reads of older layouts.
• stats: PerCpuArray<u64> with 19 entries matching the StatIdx enum discriminants. Indices are append-only once shipped — operator dashboards key on them.
• log: 256 KiB RingBuf (power-of-two, multiple of 4 KiB and 16 KiB page sizes).
• redirect_devmap: DevMapHash with 64 entries — hash-keyed per §4.5 note so size doesn't scale with ifindex density.

vlan_resolve is deferred to PR #5 (VLAN).

Verifier-pass test

crates/modules/fast-path/tests/verifier.rs loads the BPF ELF through aya::Ebpf, extracts the fast_path XDP program, and calls Xdp::load() — which round-trips the program through the kernel verifier. Pass = verifier accepts. Requires CAP_BPF + CAP_NET_ADMIN; a dedicated CI step runs it under sudo -E cargo test ... --ignored.

aya is Linux-only (SYS_bpf, netlink bindings etc.), so the dev-dep + test module are cfg(target_os = "linux")-gated. macOS cargo test still runs cleanly.

Toolchain hygiene

• Swapped dtolnay/rust-toolchain → direct rustup (first-party).
• Swapped Swatinem/rust-cache → actions/cache@v5 (first-party).
• Swapped softprops/action-gh-release → gh release create (first-party).
• Bumped every action to latest majors (checkout@v6, cache@v5, upload-artifact@v7, download-artifact@v8) to clear Node.js 20 deprecation warnings.
• Bumped every Rust dep to actual latest-stable on crates.io: rust stable 1.85 → 1.95, thiserror 1.0 → 2.0, aya-build 0.1.2 → 0.1.3, network-types 0.0.6 → 0.1.0, bpf-linker 0.9.13 → 0.10.3.
• Added .github/dependabot.yml covering workspace cargo, BPF cargo, and github-actions ecosystems — SPEC §7.1 requires "Dependabot or equivalent" for version drift.

CI-only BPF builds

build.rs attempts a nested cargo build --release in bpf/. On success it stages the ELF and emits cargo:rustc-cfg=packetframe_bpf_built; on any failure (no rustup, no nightly, no bpf-linker, real compile error) it writes an empty stub ELF and prints a cargo warning. PACKETFRAME_SKIP_BPF_BUILD=1 is an explicit bypass used by the four cross-build CI jobs (BPF bytecode is architecture-independent, the check job already builds it once).

Result: macOS dev laptops cargo test cleanly with a stub ELF; CI builds real BPF and verifier-tests it.

Deferred to PR #4

• Packet-level bpf_prog_test_run fixtures for parse/fragment/TTL/allowlist-miss/complex-header verdicts. aya 0.13.1 doesn't wrap BPF_PROG_TEST_RUN for XDP; implementing via raw syscalls is feasible but non-trivial. PR v0.1: fast-path runs end-to-end on configured interfaces (PR #4) #4 introduces the netns integration test (which exercises FIB-return cases needing real routes) and is the natural home for these fixtures.
• aya userspace loader: Module::load/attach/detach, pin registry, packetframe run wiring.
• §2.3 per-interface trial-attach probe in the feasibility subcommand (graduates from Deferred once we have a real program to trial-attach with).

Reviewer notes

• bpf_fib_lookup struct access uses the bindgen anonymous unions (.__bindgen_anon_1.tot_len, .__bindgen_anon_3.ipv4_src, etc.) because that's what the aya-ebpf bindings expose. Not pretty; stable vs layout drift matters more than prettiness for hot-path code.
• IPv4 csum fixup is the simplified "TTL down by 1 → csum up by 0x0100 in one's complement" form with explicit carry fold. Matches what the reference implementations (ip_decrease_ttl in the kernel) do.
• I couldn't verifier-check locally (no rustup per the approved plan's CI-only BPF build choice). First CI run hit clippy::unnecessary_cast on an i64 cast that was a no-op on 64-bit Linux; handled with a targeted #[allow] per the pattern established in PR v0.0.1 feasibility slice: workspace, config parser, §2.1 capability probes #1.

Test plan

• CI green (five jobs: check, four cross-builds, plus the Dependabot config check).
• Verifier-pass test green under sudo.
• cargo test --workspace on macOS still clean (stub BPF path).
• No Node.js 20 deprecation warnings in the action logs.
• Feasibility probe reports all §2.1 caps as PASS on a Linux host with BPF enabled, post-merge.
• Bump the BPF crate's aya-ebpf version via Dependabot and confirm a PR is opened (sanity-check the Dependabot config).

🤖 Generated with Claude Code

[lunarthegrey]

@claude review