Sliding-Window RLC (RFC 8681) FEC scheme + --fec-scheme switch

[josephnef]

Summary

Companion to PR #86. RaptorQ is a block code; each IP packet has to wait for K source symbols to accumulate before the encoder emits anything, giving an unavoidable ~95 ms per-packet latency floor on this link even at K=8/flush=20 ms. RFC 8681 RLC is a sliding-window code: every source symbol is shipped systematically (zero encoder buffer), repair symbols are linear combinations over the last window source symbols, and the decoder can emit each source the instant it arrives — better for interactive traffic.

Per the user's direction the implementation wraps Inria's reference swif-codec C library (irtf-nwcrg/swif-codec, co-authored by Vincent Roca, the RFC 8681 author) via cffi rather than reimplementing the codec in pure Python.

Wire format

A new RLC envelope MAGIC 0xF534 lives alongside RaptorQ's frozen 0xF52E. The receive dispatcher peeks the first two bytes of the stream payload and routes per-frame — a mixed-scheme deployment is silently rejected (the foreign decoder counts the symbol as malformed) instead of corrupting IP traffic.

MAGIC(2)  VER(1)  TYPE(1)  SYMBOL_SIZE(2)  ESI(4)  WIN(1)  KEY(2)  DT(1)  PAYLOAD(symbol_size)

Source symbols ride the same length-prefix concat-packing scheme as RaptorQ.

Files

Path	Purpose
vendor/swif-codec/	Pinned snapshot of upstream commit de8cd8e (CeCILL-B) + four small patches in PATCHES.md (C99 callback-signature fix, drop #define DEBUG and a handful of unconditional printf/full_symbol_dump calls).
_swif_build.py	cffi extension builder. Drives gcc directly — modern setuptools' distutils path-handling broke the standard ffi.compile() path.
stream_fec.py (modified)	Reshaped into a thin dispatcher: FecConfig grows scheme/window/density_threshold; make_encoder/make_decoder route to the right module. FecConfig(k=…) / FecEncoder(cfg) / FecDecoder(cfg) callers still work via backward-compat aliases — scheme defaults to raptorq for them; tun_p2p.py's --fec-scheme defaults to rlc.
stream_fec_raptorq.py	Moved-out RaptorQ code, renamed RaptorQEncoder / RaptorQDecoder. Otherwise unchanged.
stream_fec_rlc.py	New RlcEncoder / RlcDecoder over the cffi binding. Encoder emits 1 source envelope + ceil(overhead) repair envelopes per sealed source symbol; decoder feeds source symbols straight through (systematic) and rebuilds the encoder's coding window on each repair to re-derive the same TinyMT32 coefficients.
test_stream_fec_rlc.py	13 RLC tests: round-trip, loss tolerance at 0/10/20 %, overhead bumping for 30 % loss, concatenation packing, oversized rejection, dispatcher MAGIC routing, garbage envelope drop, partial-symbol flush, distinct-MAGIC, config validation.
tun_p2p.py (modified)	New --fec-scheme {rlc,raptorq}, --fec-window, --fec-density-threshold. make_encoder/make_decoder factories. TUN-write boundary drops malformed FEC-recovered packets as mal-counted instead of taking the bridge down.

Verification

Offline — cd tools/precoder && uv sync && uv run pytest:

• 100 tests pass (31 pipeline + 37 stream + 19 raptorq + 13 rlc).

Hardware (two-netns single-host bench, RTL8812AU 0x8812 ↔ TP-Link Archer T2U Plus / RTL8821AU 2357:0120, ch 6), 10-min soak (600 pings at 1 Hz, no --repeat):

Scheme	Config	Loss	RTT min/avg/max	Airtime/pkt	blk-lost
RLC	W=16, R/K=1, 20 ms	6.0 %	13 / 42 / 79 ms	~4 ms (2 envelopes)	10 / 586
RaptorQ	K=8, R/K=1, 20 ms	0.17 %	59 / 95 / 146 ms	~34 ms (17 envelopes)	1 / 606

The 6 % RLC loss is end-to-end after recovery: ~1.7 % of RLC blocks are unrecoverable (window expires before enough repairs land), and each unrecoverable block can carry multiple concatenation-packed ICMP packets. Raising --fec-overhead closes the gap at the cost of airtime.

Bandwidth-vs-recovery trade-off (this is the bigger story than RTT)

Per-IP-packet envelope count from the same soak: RLC ships 2 envelopes per packet, RaptorQ ships 17 — an 8.5× airtime gap at this traffic shape. The reason is structural: RaptorQ's block code emits K source + R repair symbols per block regardless of how full the block is, so a 1 Hz ping triggers a flush of 1 real packet plus K-1 zero-padded sources + K repairs. RLC's sliding-window code emits 1 source + R repair per source symbol, so sparse traffic stays sparse on the wire.

This makes --fec-scheme a bandwidth knob as much as a latency one:

• RLC wins on interactive / sparse traffic — lower per-packet airtime and lower per-packet latency, at the cost of higher residual loss.
• RaptorQ wins on bulk / saturated traffic — its asymptotic ~50 % loss tolerance at large K beats RLC's ~30 % at small W, and the K-symbol amortisation cost only stings when blocks aren't naturally full.

Test plan

• uv run pytest → 100 passed
• python tun_p2p.py --help | grep '^\s*--fec' parses scheme + window + density-threshold + the existing five flags
• 10-min RLC soak: 564/600 (6 %), RTT avg 42 ms, ~2 envelopes/pkt
• 10-min RaptorQ regression: 599/600 (0.17 %), RTT avg 95 ms, ~17 envelopes/pkt — matches PR RaptorQ (RFC 6330) FEC layer for the stream link #86 baseline
• Mixed-scheme negative: test_dispatcher_routes_by_magic proves RLC envelopes go nowhere through a RaptorQ decoder and vice-versa
• Reviewer to re-soak on their bench with their own pair of 8812/8821 adapters

Builds on master (#86 merged). cffi extension is built lazily on first import; pyproject.toml adds cffi>=1.16.

Open caveats (documented in script)

• swif-codec upstream's C99 / verbose-codec quirks are patched in the vendored copy; reapply on next upstream pull.
• The fixed encoder repair cadence (no rateless overhead bumping) is shared with the RaptorQ path; a future PR could add reverse-channel hints.
• Windows MSVC build of the cffi extension is untested — Linux/macOS only on CI initially.

🤖 Generated with Claude Code