enricobuehler
bdcbb2d3a7
The embedder-facing frame queue was a 16-deep sync_channel whose try_send dropped the NEWEST access unit on overflow — backwards for a live stream (keeps stale, discards fresh), a ~266 ms floor that could not self-drain (producer and consumer both run at frame rate, so any depth a burst injects is conserved forever — the latency ratchet), and a silent reference-chain break the loss counters never saw. The clock-based flush meant to catch it was gated on the skew handshake and never even drained that queue. Replace it with a purpose-built FrameChannel (VecDeque + Condvar) exposing depth() and clear(). Pre-decode AUs are reference-chained under the host's infinite GOP, so they are never dropped mid-stream; instead, when the embedder falls persistently behind, the pump JUMPS TO LIVE — flush_backlog() + clear the queued AUs + request a keyframe — so decode re-anchors cleanly at an IDR. Two cooldown-gated detectors, both suspended during a speed test: - clock-based (existing): > FLUSH_LATENCY behind the skew-corrected clock for FLUSH_AFTER_FRAMES straight; also catches kernel/reassembler backlog. - clock-free (new): the hand-off queue sat >= QUEUE_HIGH without draining to QUEUE_LOW for STANDING_FRAMES straight. Works on same-clock / no-handshake sessions where the clock path is disarmed — the direct "the embedder can't keep up" signal. A transient Wi-Fi clump drains in a few frames and never trips it. Bounded (90-frame hard cap, drop-oldest memory backstop) and diagnosable (each jump logs queue_depth / flushed_datagrams / dropped_frames). next_frame's external Timeout/Closed contract is unchanged, so every native client inherits the fix. Adds 5 FrameChannel unit tests. 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)
design/implementation-plan.md— why GF(2¹⁶) FEC, the latency budget, and the architecture thesis