enricobuehler
7b2cdf5a7a
Four defects from the punktfunk-core quality sweep, all in the data plane. transport/udp: the hole-punch adopted the source address of ANY datagram whose first 8 bytes matched PUNCH_MAGIC — a fixed public constant with no key, nonce or session id — and the authenticated QUIC peer was passed only as the no-punch fallback, so it was never used to validate. Hole-punch is the default bring-up path (it is skipped only for a fixed --data-port), and the data socket is an OS ephemeral, so spraying the ephemeral range during the 2500 ms punch wait let anyone steal the video plane: the legitimate client is then filtered out by the connect() and gets nothing, while QUIC stays healthy so no reconnect fires. With a spoofed source the same 8 bytes aim a full-rate stream at a third party. Take the authenticated peer IP and require the punch to match it — only the PORT is in question (that is what a NAT remaps and what the punch exists to discover); the client dials the same host IP as its QUIC connection, so a NAT presents one source IP for both planes. Also budget each read from the REMAINING window, so off-peer datagrams cannot stretch the wait past punch_timeout. transport/udp: the punch keepalive treated every send error as fatal and broke out of its loop permanently and silently. It holds a clone of the connected, non-blocking data socket — exactly the socket whose transient conditions this module defines and documents in is_transient_io. One ENOBUFS from a full wlan tx queue or an ENETUNREACH during an AP roam killed the only thing holding the NAT mapping open; the path recovers, video keeps flowing, and the stream dies later when the idle timer expires the mapping during a static scene. Route it through is_transient_io like every other send site in the file. packet: adaptive FEC moved fec_percent live (host bands it 1..=50 while Welcome advertises 10) but the receiver's per-block acceptance ceiling was computed once from the negotiated percentage and never re-derived. Once FEC ramped, every packet of a maximal block failed `total > max_total_shards`, the block never accumulated a shard, the frame aged out, and the resulting loss drove FEC higher still — large frames wedged at 100% loss exactly when FEC was meant to rescue the link. Fixed on both sides, because hosts and clients update independently: the sender clamps per-block parity to the ceiling the peer negotiated, and the receiver sizes that ceiling from the whole clamp range rather than a stale snapshot of it. No wire bytes and no C ABI signature change; WIRE_VERSION and ABI_VERSION are unchanged. Regression tests cover all three (the punch tests were confirmed to fail without the fix). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
punktfunk-core
The shared protocol core — the one place where punktfunk's transport, forward error correction, and crypto live. It's linked into the host and every native client, so there's exactly one implementation of the wire format everywhere.
Written in Rust with no async on the per-frame path (native threads only). It exposes both a normal Rust API and a stable, versioned C ABI, so the Swift and Kotlin clients — and any C embedder — link the same code as the Rust ones.
What's in here
- Transport & session (
session.rs,transport/,packet.rs) — thepunktfunk/1data plane over raw UDP: packetization, reassembly (with attacker-bounded limits), pacing, and socket tuning. - FEC (
fec/) — the wall-breaker. Two codes:- GF(2⁸) classic Reed–Solomon with the Cauchy generator matrix — byte-identical to the
nanorslibrary Moonlight uses, so our parity is decodable by a stock Moonlight client. - GF(2¹⁶) Leopard-RS (SIMD, O(n log n)) — up to 65535 shards/block, which removes the ~1 Gbps
FEC ceiling.
punktfunk/1negotiates this one.
- GF(2⁸) classic Reed–Solomon with the Cauchy generator matrix — byte-identical to the
- Crypto (
crypto.rs) — AES-128-GCM session encryption with per-direction nonce salts and sequence-as-AAD; SPAKE2 PIN pairing lives behind thequicfeature. - QUIC control plane (
quic.rs,client.rs, featurequic) — the Hello/Welcome/Start handshake, cert pinning/TOFU, reverse audio, and the embeddableNativeClientconnector. This is the only placetokio/quinnare allowed; the feature is off by default so the core stays runtime-free. - C ABI (
abi.rs) — the versioned surface (punktfunk_abi_version(),PunktfunkConfigcarrying its ownstruct_size) that generatesinclude/punktfunk_core.hvia cbindgen at build time.
Build outputs
The crate builds three ways at once (crate-type = ["lib", "cdylib", "staticlib"]):
| Output | Used by |
|---|---|
lib (rlib) |
the host, probe, and tools link it as a normal Rust crate |
cdylib (.so/.dylib) |
the Swift / Kotlin clients via the C ABI |
staticlib (.a) |
the C test harness and static embedding |
Test
cargo test -p punktfunk-core # unit + proptest + loopback
cargo run -p loss-harness # FEC loss-resilience sweep (no network needed)
bash crates/punktfunk-core/tests/c/run.sh # standalone C-ABI link + round-trip proof
Design invariants (do not regress)
- One core, linked everywhere — protocol/FEC/crypto live only here, behind the stable C ABI.
- No async on the hot path — the per-frame pipeline is native threads only;
quic(tokio/quinn) is control-plane only, feature-gated, off by default. - Security hardening stays intact — the reassembler bounds attacker-controlled fields before
allocating; AES-GCM keeps per-direction nonce salts + seq-as-AAD; the ABI checks
struct_size. Regression tests exist — keep them green.
Related
punktfunk-host— the streaming host built on this core- Clients — the apps that link this core over the C ABI (or directly, in Rust)
- punktfunk-planning:
implementation-plan.md(internal planning repo) — why GF(2¹⁶) FEC, the latency budget, and the architecture thesis