v0.2.4: mss-clamp directive + reconfigure CLI + ExecReload

[lunarthegrey]

Summary

Closes the SPEC §11.4 MSS-clamping gap and lands the long-deferred reconfigure CLI / systemctl reload path in one bundled PR.

• mss-clamp directive (fast-path). Inline mutation of the TCP MSS option in matched SYN/SYN-ACK packets before redirect. Fixes the iptables-bypass gap on real edge deployments where allow-prefix overlaps a -j TCPMSS FORWARD rule. Four grammars (global / per-iface / per-prefix / per-prefix+iface), SYN+SYN-ACK both directions, lower-if-higher policy, IPv4 + IPv6 parity, RFC 1624 incremental checksum. See docs/runbooks/mss-clamp.md.
• packetframe reconfigure subcommand. SIGHUP plumbing was already wired (loader.rs:reconfigure_from_signal, reconcile.rs) — what was missing was the CLI side. Now uses PIDFile + /proc/<pid>/comm validation, sends SIGHUP, and polls a last-reconfigure.timestamp ack marker for up to 5s. Exit code distinguishes parse errors from per-module reconcile failures. See docs/runbooks/reconfigure.md.
• ExecReload= + PIDFile= in the systemd unit (crates/cli/debian/packetframe.service). The README's aspirational systemctl reload packetframe finally works.
• block-prefix reconcile path (small adjacent fix). v0.2.1 shipped BLOCK_V4/V6 maps but no reconcile, so adding/removing block-prefix lines required restart. ~50-LOC mirror of the existing allow-prefix reconcile.
• build.rs improvement. Forward BPF rustc JSON diagnostics on failure so future BPF compile errors are visible — without this, cargo::warning=[bpf stderr] only carried "Compiling X" progress lines and the final summary, hiding actual rustc diagnostics. Found while debugging this PR's BPF stack/verifier issues.

Why bundle

• The runbook for mss-clamp explains how to test changes via reconfigure (flip MSS values without re-attaching XDP); they're naturally documented together.
• mss-clamp creates a real test surface for reconfigure (flip values, watch counters).
• ExecReload only makes sense after the CLI subcommand exists.
• block-prefix reconcile was a known gap noticed during the reconfigure exploration; bundling beats a follow-up PR.

What's in the PR

Area	Files	Notes
BPF maps	maps.rs	New MssClampValue, MSS_CLAMP_V4/V6/BY_IFACE. FpCfg layout V1 → V2 (the formerly-_reserved slot is now mss_clamp_global: u16; struct size unchanged). StatIdx 33/34 = mss_clamp_applied/skipped (append-only per CLAUDE.md).
BPF program	main.rs	New mss_clamp_inline (and helpers) called from forward_success between devmap check and TTL decrement. All #[inline(always)] because BPF subprograms can't take packet-pointer args (see "BPF lessons" below). Verifier-bounded TCP-options walk capped at 8 iterations with sequential if branches (state-space-friendly). RFC 1624 incremental TCP checksum update.
Config parser	config.rs	New ModuleDirective::MssClamp + MssClampPrefix enum. Parser disambiguates the four grammars by token shape (CIDR contains /, via is the iface keyword). Bounds check 88 ≤ mss ≤ 65495.
Userspace fast-path	linux_impl.rs, reconcile.rs	populate_mss_clamp (load), reconcile_mss_clamp (SIGHUP delta), reconcile_block_v4/v6. The mss reconcile uses re-insert-on-key semantics so a value change for an existing prefix is picked up.
CLI	main.rs, loader.rs	Reconfigure handler replaces the stub. New loader::reconfigure() + ReconfigureError. PIDFile lifecycle in run_linux. Marker file written by reconfigure_from_signal.
Systemd	packetframe.service	ExecReload=/bin/kill -HUP $MAINPID, PIDFile=....
Build harness	build.rs	Forward BPF rustc JSON diagnostics on failure (parse compiler-message records, emit rendered field as cargo warnings).
Docs	README.md, conf/example.conf, 2 new runbooks	Status table expanded to enumerate sketched future modules (ddos / sampler / randomizer / dispatcher) with SPEC §-pointers + priority buckets. mss-clamp + reconfigure marked Production (v0.2.4+).
SPEC.md (untracked)	local file	§3.2 priority taxonomy note, §4.6 counter rows 32-34, §4.10 closeout, new §4.12 MSS clamping, §5.0 dispatcher prerequisite, §8.4 reconfigure UX + hot-reloadable matrix, §11.4 closeout.

BPF lessons learned (worth recording for future XDP work)

The BPF side took five iterations after the initial design:

1. #[inline(never)] to escape stack budget — failed. BPF kernel verifier rejects bpf2bpf calls with packet-pointer arguments: R1 pointer arithmetic with <<= operator prohibited. LLVM emits a 32→64 bit lift via shift-left for the pkt_ptr arg to satisfy the BPF calling convention; the verifier prohibits arithmetic shifts on packet pointers.
2. Pass ip_offset: usize (scalar) instead — failed. LLVM's SROA decomposes &XdpContext into (data, data_end) packet pointers across the call boundary. Same verifier rejection on the data_end arg.
3. Revert to #[inline(always)], trim stack via block scopes — partially worked. Keeps everything in the parent's frame; reading src/dst inside LPM-lookup blocks lets the compiler reuse stack slots between src and dst keys.
4. 0..40 TCP-options walk — verifier hit 1M-instruction processing limit (BPF program is too large). Combinatorial state explosion across the inner match-based kind dispatch.
5. Cap at 0..8 iterations + flatten match to sequential if — final fix. Real SYN packets put MSS in option positions 1-4 (Linux's tcp_options_write emits MSS very early); 8 is comfortable headroom. SYNs that bury MSS deeper get counted as mss_clamp_skipped (pathological in practice).

Takeaway captured in crates/modules/fast-path/bpf/src/main.rs doc-comments and SPEC §4.12: for BPF code that touches packet pointers, #[inline(always)] is essentially mandatory; stack-budget pressure has to be solved by tightening locals, not by extracting subprograms.

Tests

14 new parser tests in config.rs covering all four grammars (IPv4 + IPv6), boundary values (88, 65495), out-of-range rejection, missing-arg errors, and multi-line accumulation.

test result: ok. 94 passed; 0 failed; ...   # packetframe-common
test result: ok. 40 passed; 0 failed; ...   # other workspace tests

cargo fmt --check clean. cargo clippy --workspace --all-targets --all-features -- -D warnings clean.

CI

Check	Result
fmt + clippy + test	✅
cross-build amd64 / arm64 (gnu + musl)	✅ all 4
qemu kernel v5.15 (BPF verifier + attach)	✅
qemu kernel v6.6 (BPF verifier + attach)	✅
CodeQL / Analyze (actions, rust)	✅

The qemu jobs run the real BPF program through the kernel verifier on attach, so this confirms the byte-level mutation logic is verifier-clean on both 5.15 and 6.6.

Test plan (post-merge, on the deployed router)

• Apply v0.2.4 to the router. apt install ./packetframe_0.2.4_amd64.deb.
• Add mss-clamp 23.191.201.0/24 via eth2 1360 (replacing the equivalent iptables -j TCPMSS rule). sudo packetframe reconfigure.
• Verify packetframe status shows mss_clamp_applied climbing on customer SYN traffic. tcpdump -i eth2 -n 'tcp[tcpflags] & tcp-syn != 0' -c 5 -vv confirms the wire MSS is 1360.
• Retire the iptables -j TCPMSS rule once mss-clamp is confirmed firing.
• block-prefix add/remove via reconfigure → confirm BLOCK_V4 deltas applied without restart.
• Bad config edit → packetframe reconfigure exits non-zero with parse-error detail; daemon stays up with old config.

Out of scope (explicitly)

• Separate mss-clamp module (requires the dispatcher first; SPEC §5.0).
• Hot-reload of attach iface set, route-source, circuit-breaker thresholds, local-prefix.
• packetframe reconfigure --check (dry-run validation).
• Type=notify migration of the systemd unit.
• AppArmor/SELinux profiles, apt-repo hosting, rpm packaging (carry-over from packaging: ship .deb packages with systemd service #39).

Tag flow after merge

git checkout main && git pull
# Bump workspace Cargo.toml + VERSION + README install snippets to 0.2.4
# in a small follow-up PR (see release-v0.2.3 pattern), then:
git tag -a v0.2.4 -m "v0.2.4"
git push origin v0.2.4

🤖 Generated with Claude Code