# BACKLOG - netforge
# NOTE: single authoritative netforge ledger. The stale duplicate at
# libs/performance/io/BACKLOG.md (a second, divergent netforge review that marked
# already-fixed items open) was reconciled into this file and deleted, per the
# one-ledger-per-crate rule.
## Safety / correctness
src/backend_xdp.rs:61 | bug | high | Umem declared before the socket queues in XdpEngine, so it drops FIRST, leaving the queues (built from Socket::new(&umem,...)) to tear down against a freed UMEM mmap - a drop-order use-after-free. | FIXED: moved `umem` to be the LAST struct field (queues drop before it), with a doc note that field order is load-bearing. Struct-literal order is unaffected. Compile-verified via `cargo check --features xdp-backend` (xsk-rs/libbpf present). | status=done
src/backend_sendmmsg.rs:222 | bug | high | rx_batch used set_len on a Vec<[u8;N]> with uninitialized bytes (UB). | FIXED: pkt_bufs is now Vec<MaybeUninit<[u8; PKT_CAP]>> (set_len sound); read loop views only the kernel-written msg_len bytes via slice::from_raw_parts. | status=done
src/backend_sendmmsg.rs:273 | bug | medium | RX parser sliced the TCP header at `&pkt_buf[ihl..]` without checking ihl >= 20, so a malformed IHL<5 packet parsed IP-header bytes as TCP fields. | FIXED: `if ihl < 20 || n < ihl + 20 { continue; }` (a valid IPv4 header is >= 20 bytes). | status=done
src/backend_sendmmsg.rs:301 | silent-fallback | medium | RxPacket built with `RawPacket::from_bytes(..).unwrap_or_default()` silently emitted a bodyless packet when the frame exceeded MAX_PACKET_SIZE. | FIXED (Law-10): `let Some(raw_packet) = RawPacket::from_bytes(..) else { continue; }` - an unparseable/oversized frame is skipped, never emitted as an empty "received" packet. | status=done
src/backend_sendmmsg.rs:88 | bug | high | SendmmsgEngine held a bound placeholder UdpSocket "to keep the raw fds alive", but that socket had its OWN unrelated fd and did nothing for tx_fd/rx_fd; its bind on a failure path also returned early via `?` and leaked the two raw fds (Drop never ran, Self not yet constructed). | FIXED: removed the placeholder bind + the `_tx_sock` field (and the now-unused `use std::sync::Mutex`). tx_fd/rx_fd are owned RawFds closed in Drop. Subsumes the io-ledger duplicates backend_sendmmsg.rs:37 and :89 (fd leak on bind failure). | status=done
src/backend_xdp.rs:326 | bug | critical | stamp_and_submit owns the descs Vec but tx_q.produce_and_wakeup may accept fewer than requested; the unsubmitted tail (descs[produced..]) is dropped at scope exit - neither submitted nor returned to tx_pool - so the TX free pool leaks descriptors and starves over time. | FIXED: stamp_and_submit now returns (produced, unsubmitted_tail) where unsubmitted = descs.split_off(produced.min(len)) - the frames the kernel refused (TX ring full), which were popped from tx_pool and written but never handed to the kernel, so they will NEVER reach the COMP ring and drain_completion can never reclaim them. Both tx_batch call sites (the pool-exhausted partial branch + the normal branch) now `pool.extend(unsubmitted)` to recycle them, so a partial produce no longer permanently shrinks the pool. The produced prefix stays owned by the kernel and returns via the COMP ring (drain_completion) as before. Correct by inspection of the produce/COMP-ring lifecycle; NOT run-verified here (xdp-backend needs libbpf-dev + kernel 5.10+ + CAP_BPF and the packet engines lack a raw-socket/loopback tx/rx harness - see backend_pnet.rs:1 test-gap row). Compile-checked GREEN under --features xdp-backend on this host (libbpf present, cargo check EXIT=0, no errors/warnings on backend_xdp); only the live AF_XDP TX run-through remains harness-blocked (CAP_BPF + NIC/loopback). | status=done
DONE 2026-07-14 src/backend_pnet.rs:131 | bug | high | PnetEngine populated RxPacket.packet with only the TCP header+payload (L4), inconsistent with the IP+TCP (L3) frame other backends return. Also used RawPacket::from_bytes(..).unwrap_or_default() (Law-10 silent empty on parse fail). | FIXED: rx_batch now reconstructs a 20-byte IPv4 header in front of the TCP segment: version/IHL=4/5, total length = 20 + TCP bytes, TTL=64 (default, not exposed by pnet Layer4), protocol=TCP, src IP from the packet source address, dst IP from `config.source_ip`. The `RxPacket.packet` is now a valid L3 IP+TCP frame matching the sendmmsg/xdp layout. Invalid TCP data offsets and oversized frames are dropped via `continue` + `record_drop` instead of silently emitting empty/default packets. `cargo check -p netforge` and `cargo test -p netforge` green. | status=done
src/backend_pnet.rs:160 | bug | medium | Reading stats() calls snapshot_pps(), which MUTATES the rolling-rate baseline (last_total/last_at), so a second stats() reader sees a reset window and a wrong pps. | FIXED (root cause in src/stats_window.rs, covers ALL THREE backends pnet/xdp/sendmmsg since they share PpsTracker): snapshot_pps now only advances the baseline when the elapsed window >= MIN_SAMPLE_SECS (1e-3); within that interval it returns the cached last_pps WITHOUT touching last_total/last_at. Added a `last_pps: u64` field to Window caching the rate at the last advance. Consequences: (1) a rapid second stats() read is idempotent (returns the same rate, not a spurious 0); (2) the baseline is not reset by the rapid read, so the next genuinely-spaced sample still measures real throughput from the correct reference point. The new 1e-3 floor subsumes the old MIN_WINDOW_SECS=1e-6 anti-spike guard (ONE threshold, one purpose = minimum meaningful sample interval). Proving test stats_window::rapid_reread_is_idempotent_and_does_not_corrupt_baseline (first spaced read >0; immediate re-read == first, discriminating the old 0-return bug; a subsequent spaced sample still >0, proving the baseline survived). No separate ticker added (stats() remains the tick, per the design constraint) - the fix decouples READING the rate from ADVANCING the window via the sample-interval gate. | status=done
## Perf
src/backend_sendmmsg.rs:214 | perf | medium | rx_batch allocates up to ~16MB of MaybeUninit slot buffers (256 * 64KiB) on the heap every call. | SHARPENED (fix approach constrained by the trait): the 16 MiB is `pkt_bufs: Vec<MaybeUninit<[u8;65536]>>` (iovecs/msgs are only KBs, ignore them). CANNOT be a plain reusable `&mut self` struct field: PacketEngine::rx_batch takes `&self` and SendmmsgEngine is `unsafe impl Sync` (called across threads), so reuse needs interior mutability - a Mutex would serialize/contend the hot RX path, so the right choice is a `thread_local! { static RX_PKT_BUFS: RefCell<Vec<MaybeUninit<[u8;65536]>>> }` sized once to RX_BATCH_CAP and reused per calling thread (16 MiB per RX thread held persistently - acceptable for a fixed pool, zero per-call alloc). Requires wrapping the recvmmsg body in the `.with(|cell| ...)` closure (iovecs/msgs stay local, referencing the borrowed pkt_bufs). Focused unsafe-hot-path change; verify with a full netforge build (its isolated target cache was pruned). | FIXED: the 16 MiB `pkt_bufs` slot buffer is no longer allocated per call. rx_batch now owns a function-local `thread_local! { static RX_PKT_BUFS: RefCell<Vec<MaybeUninit<[u8;65536]>>> }` (const-init), grown once to RX_BATCH_CAP=256 and retained; it borrows it and delegates the syscall+parse to a new inherent method `rx_batch_into(&self, buf, pkt_bufs: &mut [MaybeUninit<[u8;65536]>])` so the thread-local lifetime is owned by the wrapper and the parse loop stays a plain borrowed-slice method (zero reindent, identical logic). iovecs/msgs remain per-call (KiB) since they hold raw pointers into the buffer. Thread-local (not a &mut self field) is forced by PacketEngine::rx_batch taking &self + SendmmsgEngine being Sync; per-thread reuse avoids the Mutex contention a shared field would need. Cost: 16 MiB held per RX thread (bounded for a fixed pool). NOTE placement subtlety: rx_batch_into had to move to a SECOND inherent `impl SendmmsgEngine` block after the trait impl (a helper fn inside `impl PacketEngine for` is E0407). Full netforge build clean (0 errors, 0 warnings) on the pruned isolated cache. | status=done
src/backend_xdp.rs:165 | perf | low | drain_completion allocates a new Vec<FrameDesc> every call in the hot TX loop despite docs claiming reuse. | FIXED (Law-7 + doc/code mismatch: the comment literally said "Reuse a small scratch buffer to avoid per-call allocation" while `vec![FrameDesc::default(); MAX_TX_BATCH]` allocated every call): now a `thread_local! COMP_SCRATCH: RefCell<Vec<FrameDesc>>` grown once to MAX_TX_BATCH and reused via with_borrow_mut; consume fills `&mut scratch[..MAX_TX_BATCH]`, reclaimed descs `pool.push(*desc)` (FrameDesc is Copy). Matches the crate's existing thread_local scratch precedent (backend_sendmmsg RX_PKT_BUFS). Compile-checked green under --features xdp-backend. | status=done
src/backend_xdp.rs:242 | perf | low | rx_batch allocates a new Vec<FrameDesc> every call in the hot RX path. | FIXED (Law-7): the per-tick `vec![FrameDesc::default(); buf.len()]` is now a `thread_local! RX_DESC_SCRATCH: RefCell<Vec<FrameDesc>>` grown to buf.len() and reused; the RX body (poll_and_consume -> parse -> fill_q.produce round-trip) moved inside a with_borrow_mut closure returning Result<usize,EngineError> so the `?` early-return still propagates. Same thread_local precedent as drain_completion/sendmmsg. Compile-checked green under --features xdp-backend. | status=done
## Capability / config
DONE 2026-07-14 | src/engine.rs:20 | capability | medium | rate_pps config option is ignored by all backends - scanning speed is not restricted. | FIXED: all three backends now create a `ratelimit::TokenBucket` from `config.rate_pps` and enforce it in `tx_batch`: pnet and xdp per-packet, sendmmsg per-packet before batching. `EngineConfig::rate_pps` 0 disables limiting; values are clamped to u32::MAX. Added unit tests `tx_batch_rate_limits_to_rate_pps` and `tx_batch_rate_pps_zero_is_unlimited` in `backend_pnet.rs`. Gate: `cargo +1.92.0 test -p netforge` passes (37 passed, CARGO_EXIT=0); `cargo check --features sendmmsg-backend` and `--features xdp-backend` green. | status=done
DONE 2026-07-14 | src/backend_xdp.rs:108 | capability | medium | EngineConfig tx_ring_size/rx_ring_size are ignored by all backends (fixed sizes used). | FIXED: `XdpEngine::new` now maps `config.tx_ring_size` to the socket TX queue and UMEM completion queue, and `config.rx_ring_size` to the socket RX queue and UMEM fill queue. Sizes default to 4096 when 0; non-power-of-two values fail closed with the new `EngineError::InvalidConfig`. `pnet`/`sendmmsg` have no kernel-exposed ring buffers, so the config remains unused there (documented in the engine config doc comments). | status=done
## Stats
src/stats_window.rs:91 | bug | medium | snapshot_pps guarded only `elapsed <= 0.0`, so two snapshots microseconds apart divided a tiny packet delta by a tiny interval and reported an absurd multi-billion-pps spike. | FIXED: originally added a MIN_WINDOW_SECS = 1e-6 floor. SUPERSEDED by the backend_pnet.rs:160 fix: the constant is now MIN_SAMPLE_SECS = 1e-3 and, instead of returning 0 inside the window, returns the cached last_pps WITHOUT advancing the baseline (ONE threshold serving both anti-spike and rapid-reread-idempotency). | status=done
## Crypto / determinism
src/seq.rs:28 | bug | high | StatelessCookie::new used fastrand (non-crypto PRNG), making stateless cookies predictable/spoofable. | FIXED: key drawn from the OS CSPRNG via getrandom::fill (getrandom=0.3), fails closed if entropy unavailable. Test fresh_cookie_keys_are_random_not_constant. | status=done
src/seq.rs:90 | bug | low | SeqEncoder::encode uses std DefaultHasher (algorithm unspecified/unstable across releases, fixed internal keys), while the module doc claims SipHash-2-4. | FIXED: added `siphasher = "1"` and rewrote encode to `SipHasher24::new_with_keys(key, key)` with the secret as the PRF KEY (a proper keyed MAC), hashing only the (dst_ip,dst_port,src_port,phase) tuple. This (a) makes the doc's SipHash-2-4 claim TRUE (DefaultHasher was SipHash-1-3), (b) uses a specified, cross-release-STABLE implementation (DefaultHasher is documented unstable), and (c) is a real keyed PRF instead of the old zero-keyed prefix-MAC. The crypto-dep add is justified: this module's entire purpose is cryptographic anti-spoofing, so the wrong/unstable primitive undermined its stated guarantee; siphasher is a minimal, widely-used no_std crate. 64-bit secret keys both 128-bit halves (64-bit security = the secret size; widening StatelessCookie to 128-bit is a separate API change). All 11 seq tests + the encode_roundtrips proptest stay green (they assert properties - determinism, differs-by-key/target/port/phase, verify round-trip - not pinned values, so the algorithm swap is transparent to them). netforge 27/0. | status=done
## Checksum
src/checksum.rs:54 | bug | medium | tcp_checksum indexed src_ip/dst_ip without length validation. | FIXED: signature takes [u8; 4] arrays (out-of-bounds impossible by construction); caller converts its 4-byte slices via try_into().expect. | status=done
src/checksum.rs:48 | bug | low | tcp_segment.len() cast `as u16` silently truncates >65535. | FIXED: u16::try_from(len).unwrap_or(u16::MAX) + debug_assert; a segment > 65535 cannot exist on the wire. Doc # Panics added. | status=done
src/checksum.rs:93 | bug | medium | batch_ip_checksum assumed a 20-byte IP header, wrong for packets with IP options. | FIXED: reads IHL, checksums exactly ihl*4 bytes, skips ihl<5 / header>captured. Tests batch_ip_checksum_covers_ihl_options_header + _skips_invalid_ihl + tcp_checksum_verifies_to_ffff_when_embedded. | status=done
DONE 2026-07-14 | src/checksum.rs:4 | stub | low | Doc claims AVX2 SIMD checksum acceleration but the implementation is a scalar loop. | OPEN: implement the AVX2 path or correct the doc to state scalar. (Also a pre-existing `unused variable: ip_sum` warning lives in this module - fold into whichever change touches it.) | FIXED: corrected the module documentation to state the implementation is a portable scalar loop and that AVX2 acceleration is future work, removing the false "16x speedup" claim. No `ip_sum` unused variable was present in the current source; it appears to have been removed by an earlier pass. `cargo +1.92.0 test -p netforge --lib` green (CARGO_EXIT=0). | status=done
## Tests
DONE 2026-07-14 | src/backend_pnet.rs:1 | test-gap | medium | The packet engines lack unit/integration tests for the tx_batch and rx_batch hot paths (they need a raw-socket/loopback harness). | FIXED: introduced `PnetSender` and `PnetReceiver` traits in `src/backend_pnet.rs` and made `PnetEngine<S,R>` generic so tests inject mocks. Added mock sender/receiver tests covering tx_batch (valid SYN, short-packet drop, send-error drop) and rx_batch (L3 reconstruction, malformed data-offset skip, data-offset-past-end skip, buffer-full stop, empty receiver). `cargo +1.92.0 test -p netforge` passes (35 passed, CARGO_EXIT=0). | status=done
src/backend_xdp.rs:477 | netforge | silent-fallback | low | REPOPULATE 2026-07-16: RawPacket::from_bytes(ip) returns None when packet length exceeds MAX_PACKET_SIZE, but unwrap_or_default() silently substitutes a default (empty/bodyless) RawPacket, causing a corrupted packet to be processed downstream | FIXED (Law-10): parse_rx_packet now binds `let packet = RawPacket::from_bytes(ip)?;` so an oversized/unrepresentable frame returns None (dropped) instead of emitting an RxPacket with a bodyless default packet + fully-populated fields. Proving test backend_xdp::inner::tests::parse_discards_oversized_frame_instead_of_emitting_empty_packet builds an otherwise-valid TCP/IPv4 frame whose IP portion is MAX_PACKET_SIZE+1 bytes and asserts parse_rx_packet returns None. Gate: cargo +1.92.0 test -p netforge --features sendmmsg-backend,xdp-backend green (46 passed, EXIT=0). | status=done
src/backend_pnet.rs:236 | netforge | silent-fallback | medium | REPOPULATE 2026-07-16: TransportReceiver::next_segment returning Err is discarded by the Err(_) => break pattern, returning Ok(received) and silently ignoring the socket read error | FIXED (Law-10): the rx_batch drain now maps `Err(e) => return Err(EngineError::Io(e))` (Ok(None) still breaks as the legitimate "no more packets" timeout). A socket read error surfaces instead of being reported as a short Ok batch. Proving test backend_pnet::tests::rx_batch_propagates_socket_read_error_instead_of_reporting_short_batch injects a FailAfterOneReceiver (one good segment, then an io::Error) and asserts rx_batch returns EngineError::Io whose message preserves the underlying error. Gate green (46 passed, EXIT=0). | status=done
src/backend_sendmmsg.rs:328 | netforge | silent-fallback | medium | REPOPULATE 2026-07-16: recvmmsg returning -1 (error) is treated as 0 packets received by the n_recv <= 0 check, silently discarding the socket read error | FIXED (Law-10): the `n_recv <= 0 => Ok(0)` blanket swallow is replaced by a single-owner classifier `classify_recvmmsg(n_recv, errno)`: n_recv>=0 -> that count; n_recv<0 with EAGAIN/EINTR -> Ok(0) (legitimate non-blocking "no data this round"); any other errno -> Err(EngineError::Io). rx_batch_into reads errno immediately after the syscall and `?`-propagates. Proving tests backend_sendmmsg::inner::tests::{genuine_recvmmsg_error_surfaces_instead_of_reporting_zero_packets (EBADF -> EngineError::Io preserving the errno), eagain_is_the_legitimate_non_blocking_empty_case (EAGAIN & EINTR -> Ok(0)), positive_return_is_the_received_packet_count}. Gate green (46 passed, EXIT=0). | status=done
src/backend_pnet.rs:202 | netforge | performance | low | REPOPULATE 2026-07-16: rx_batch allocates a Vec for l3_packet on every received packet, causing heap churn in the hot RX path | FIXED (Law-7): the per-packet `Vec::with_capacity(..)` L3 staging buffer (which `RawPacket::from_bytes` then copied AGAIN into its inline `[u8; MAX_PACKET_SIZE]`) is replaced by `reconstruct_l3_packet(&ip_header, tcp_segment)`, which writes both segments directly into an empty RawPacket's inline buffer: zero heap, single copy, and returns None past MAX_PACKET_SIZE. Proving tests backend_pnet::tests::{reconstruct_l3_packet_writes_ip_header_then_tcp_segment (byte-correct layout), reconstruct_l3_packet_does_not_heap_allocate (per-thread counting global allocator asserts 0 allocations across the call), reconstruct_l3_packet_rejects_oversized_segment_at_the_boundary}. Gate: cargo +1.92.0 test -p netforge --features sendmmsg-backend,xdp-backend EXIT=0. | status=done
src/backend_xdp.rs:297 | netforge | performance | low | REPOPULATE 2026-07-16: tx_batch drains and collects FrameDesc from pool into a fresh Vec on every batch, causing needless heap allocation in the hot TX loop | FIXED (Law-7): both `tx_batch` sites did `pool.drain(..N).collect()` (fresh Vec) AND `stamp_and_submit` did `descs.split_off(..)` (second Vec) per batch. Now both route through one `submit_chunk` owning a thread-local `TX_FRAME_SCRATCH: Vec<FrameDesc>`; `marshal_and_submit_with` clears+extends that reused buffer (in-place, no realloc after warmup) and recycles only the refused tail (`stamp_and_submit` now borrows `&mut [FrameDesc]` and returns the accepted count, no split_off). Submit is injected so the marshalling logic is unit-testable without XDP hardware. Proving tests backend_xdp::inner::tests::{marshal_and_submit_recycles_refused_frames_into_the_pool (produced frames stay kernel-owned, refused tail recycled, pool math), marshal_and_submit_reuses_the_scratch_buffer_without_reallocating (buffer ptr+capacity stable across batches)}. Gate: EXIT=0. | status=done
DONE 2026-08-06 | Cargo.toml | standard-compliance | low | Added package.metadata.santh.status = "beta", SPEC.md, CHANGELOG.md, tests/ layout (unit/adversarial/property/contract), fixed stamp_syn undersized template range panic, and clamped batch_ip_checksum packet length reads. | FIXED: default features cargo test passes 79 tests cleanly across 6 test suites. | status=done