v0.1: fast-path runs end-to-end on configured interfaces (PR #4)

[lunarthegrey]

Summary

Brings fast-path from verifier-pass (PR #3) to end-to-end deployable in dry-run on any configured interface. packetframe run --config <file> now loads the BPF ELF via aya, populates allow_v4/allow_v6/cfg/redirect_devmap from config, XDP-attaches to every attach <iface> <mode> with the SPEC §2.3 trial-attach fallback, persists the pin registry, and blocks on SIGTERM/SIGINT.

CI proves this works end-to-end on a real interface: the attach integration test creates a veth pair under sudo, loads the compiled BPF ELF through aya, XDP-attaches with DRV_MODE → SKB_MODE fallback, and detaches cleanly. Together with PR #3's verifier-pass test, the load/attach/detach round-trip is covered by CI.

What landed

crates/modules/fast-path/src/linux_impl.rs (new, Linux-only)

Real aya-driven loader: aya::Ebpf::load, populate_cfg (writes the v1 FpCfg layout), populate_allowlists (LPM inserts from allow-prefix{,6}), attach (resolves ifindex via libc::if_nametoindex, XDP-attaches with per-interface trial-attach, populates redirect_devmap before returning any link), detach, plus trial_attach_native for the feasibility probe and snapshot_{links,stats} for status reporting.

crates/modules/fast-path/src/registry.rs (new)

JSON pin registry at <state-dir>/attachments.json, atomic write-then-rename. Attachment ↔ AttachmentRecord conversions so the packetframe-common::module::Attachment type doesn't need Serde.

crates/modules/fast-path/src/lib.rs

FastPathModule now has real trait impls that delegate to linux_impl on Linux, return ModuleError::other(...) on non-Linux. links() / stats() accessors for status.

crates/cli/src/loader.rs (new)

Drives the module lifecycle from packetframe run. Config parse → §2.1 capability probe → §2.3 trial-attach probe for each configured iface → refuse-to-attach-on-required-cap-fail → load/attach → persist registry → block on signal. SIGTERM/SIGINT exit is explicitly no-detach per §8.5 (Ebpf drop implicitly tears down until PR #6 adds pinning).

crates/cli/src/feasibility.rs

Per-interface xdp.attach.<iface> capabilities replace the Deferred placeholder. Tests native first, falls back to generic; reports Pass for generic-only with the native error in detail.

crates/modules/fast-path/tests/attach.rs (new)

veth-backed integration test: creates pf-veth0/1, loads ELF, attaches with native→generic fallback, detaches, cleans up via a Drop guard. Runs under sudo in CI.

CI

• check job's sudo step runs all ignored fast-path integration tests (--tests -- --ignored), so the verifier + veth tests both run under sudo.
• signal-hook added as a Linux-only dep on cli for the signal loop.
• aya promoted from dev-dep to Linux-only regular dep on fast-path.

Spec audit — see comment

• ✓ §2.3 per-interface trial-attach probe graduates from Deferred
• ✓ §4.3 attach surface (config-driven)
• ✓ §4.4 unchanged from PR v0.1: fast-path BPF program + toolchain + verifier-pass test (PR #3) #3 (verifier still happy)
• ✓ §4.5 maps populated correctly; incremental LPM inserts (§4.5 atomicity-safe path)
• ✓ §4.5 redirect_devmap populated pre-attach with every ifindex in scope (§4.4 step 9d defensive pre-check works)
• ✓ §7.3 exit codes, signal intent
• Deferred to PR v0.1: VLAN choreography, packet fixtures, kernel 6.0+ probe fix (PR #5) #5/6 per v0.1 slicing plan: pinning, SIGHUP reconcile, live status readback, metrics, circuit breaker, VLAN (§4.7), packet-level fixtures

Test plan

• CI green on all five jobs (including sudo verifier + veth attach)
• cargo test --workspace on macOS still clean (stub BPF path)
• Post-merge: smoke-run packetframe run --config conf/example.conf on a Linux dev VM with veth interfaces; confirm attach, counters accumulate, SIGINT exits cleanly
• Post-merge: run on the reference EFG in dry-run mode, verify matched_v4 matches expected traffic volume over 24h (SPEC §9 Phase 2)

🤖 Generated with Claude Code

[lunarthegrey]

Critical regression audit — PR #3 and PR #4 tests were false-positives

While the user tested PR #4 on a Linux VM, the local build failed to produce a valid BPF ELF. Investigation found a chain of issues that had been silently hiding since PR #3:

1. bpf/Cargo.toml had no [workspace] table. Nested cargo walked up, found the root workspace that excluded it, errored "current package believes it's in a workspace when it's not". Fix: add empty [workspace] to make the subcrate its own workspace root.
2. build.rs captured the nested cargo's output and swallowed it. Users saw only the opaque BPF build failed (exit 101) line with no way to diagnose. Fix: re-emit stderr as cargo:warning lines.
3. Nested cargo inherited CARGO/RUSTUP_TOOLCHAIN from the outer stable build and never switched to the nightly pinned in bpf/rust-toolchain.toml. build-std only activates under nightly, so cargo tried to link a precompiled core that doesn't exist for bpfel-unknown-none → error[E0463]: can't find crate for 'core'. Fix: env_remove the outer cargo/rustup vars before spawning.
4. Hardcoded artifact path was wrong. Switched to parsing --message-format=json for the compiler-artifact message — lets cargo tell us where the file landed.
5. include_bytes! returns a 1-byte-aligned slice; the object crate's ELF parser does aligned u32/u64 reads on the header and rejected it with "Invalid ELF header size or alignment". Fix: aligned_bpf_copy() helper that heap-copies the bytes into a 16-byte-aligned Vec<u8>.
6. Integration tests silently treated missing BPF as "skip" + report ok. Added PACKETFRAME_BPF_REQUIRED=1 to CI's check job env; build.rs now panics on stub-fallback when that's set, so CI can never again be green with a broken BPF build.

Net effect: the tests merged with PR #3 (verifier pass) and PR #4 (veth attach) now actually exercise the kernel verifier and aya's attach path — they used to stub the ELF and early-return ok with 0.00s execution. With this commit series they take 0.19s and 0.25s respectively, doing real kernel work.

The §4.4 BPF program has genuinely passed the kernel verifier for the first time in this CI run. The sport/dport fix from PR #3's spec audit has been exercised.