netforge 0.1.5

High-performance raw packet I/O engine with AF_XDP, sendmmsg, and pnet backends
Documentation
# SPEC - netforge

## Overview

`netforge` is a high-performance raw packet I/O engine designed for internet-scale network scanning. It provides a unified `PacketEngine` trait over three execution backends:

1. **AF_XDP (`xdp-backend`)**: Linux 5.10+ zero-copy userspace ring using `xsk-rs` / `libbpf`.
2. **sendmmsg (`sendmmsg-backend`)**: Linux batched raw socket syscalls using `sendmmsg()` and `recvmmsg()`.
3. **pnet (`pnet-backend`)**: Portable single-packet raw sockets using `pnet::transport`.

The engine automatically selects the fastest available backend based on system capabilities (`auto_select`).

---

## Architecture & Data Flow

```
                     +---------------------------------------+
                     |             PacketEngine              |
                     +---------------------------------------+
                                        |
           +----------------------------+----------------------------+
           |                            |                            |
           v                            v                            v
  +------------------+         +------------------+         +------------------+
  |    XdpEngine     |         |  SendmmsgEngine  |         |    PnetEngine    |
  | (AF_XDP Zero-Copy) |       | (Batched Syscall)|         | (Portable Raw)   |
  +------------------+         +------------------+         +------------------+
           |                            |                            |
           v                            v                            v
    UMEM Ring Buffers            Raw Sockets (v4)             pnet Layer4 Channel
```

### Packet Representation

Packets are represented by `RawPacket`, a fixed-size zero-allocation stack buffer of `MAX_PACKET_SIZE` (1514 bytes).
- **Template Stamping**: Probes are pre-built as templates (`build_syn_template`) and stamped in-place per target (`stamp_syn`) with target IP, port, sequence number, and pre-calculated checksums.
- **Buffer Safety**: Slices derived from `RawPacket` go through `clamped_len()`, preventing out-of-bounds reads or buffer overruns.

### Stateless Sequence Encoding (`seq`)

To achieve zero per-connection state during SYN scanning:
- Sequence numbers are computed using a keyed SipHash-2-4 digest of `(dst_ip, dst_port, src_port, phase)` combined with a 64-bit secret key drawn from `getrandom` (OS CSPRNG).
- `verify_synack` checks whether incoming SYN-ACK `ack_num - 1` matches the expected SipHash-2-4 sequence number.
- `verify_data_ack` verifies sequence progress for multi-phase stateless banner grabbing.

### Rate Limiting & Performance Accounting (`stats_window`)

- **Token Bucket**: Optional in-tree rate limiting via `santh-ratelimit` enforced in `tx_batch` across all backends.
- **PpsTracker**: Lock-free, two-sample rolling window tracking lifetime packets and drops. `snapshot_pps()` enforces a minimum sample interval (`MIN_SAMPLE_SECS = 1ms`), returning cached rates for rapid reads to ensure idempotency across multiple consumers.

---

## Guarantees & Invariants

1. **No Silent Fallback**: Malformed or unparseable frames on receive are discarded (`None`) rather than emitted as empty or corrupted `RxPacket` structs.
2. **Error Propagation**: Real socket I/O errors (e.g. `EBADF`, `EIO`) surface as `EngineError::Io`. Non-blocking `EAGAIN` / `EINTR` return 0 packets without corrupting state.
3. **Drop-Order Safety**: In `XdpEngine`, `umem` is declared last so queues tearing down during drop execute before UMEM mmap deallocation.
4. **Memory Allocation Bounds**:
   - `sendmmsg` uses thread-local `RX_PKT_BUFS` scratch buffers.
   - `xdp` uses thread-local `COMP_SCRATCH`, `RX_DESC_SCRATCH`, and `TX_FRAME_SCRATCH` buffers.

---

## API Contract

### Engine Selection

```rust
pub fn auto_select(config: EngineConfig) -> Result<Box<dyn PacketEngine>, EngineError>;
```

Tries `XdpEngine` -> `SendmmsgEngine` -> `PnetEngine`. Returns `EngineError::PermissionDenied` when host capabilities or permissions are insufficient, falling through to the next backend.

### PacketEngine Trait

```rust
pub trait PacketEngine: Send + Sync {
    fn tx_batch(&self, packets: &[RawPacket]) -> Result<usize, EngineError>;
    fn rx_batch(&self) -> Result<Vec<RxPacket>, EngineError>;
    fn rx_batch_into(&self, buf: &mut [RxPacket]) -> Result<usize, EngineError>;
    fn stats(&self) -> EngineStats;
    fn name(&self) -> &'static str;
}
```

---

## Roadmap

- **SIMD Checksums**: Implement explicit AVX2 SIMD vectorization for `checksum::ones_complement_sum` when targeting x86_64 architectures with AVX2 feature flags.
- **IPv6 Support**: Extend `RawPacket` templates and stateless sequence encoding to IPv6 raw socket scanning.