enricobuehler
2bfd1cd2d5
scripts/ci/check-unsafe-hygiene.sh — textual gates for three classes no lint covers: A. unsafe fn markers carrying no contract. unsafe_op_in_unsafe_fn forces real ops into blocks, so an unsafe fn with no `unsafe` in its body is a marker with no contract (db659809found two by hand). Contract-deferring fns (Vec::set_len shape) waive with `// unsafe-fn-no-op-ok: <reason>`; fenced files and `unsafe extern "ABI" fn` (signature-mandated markers) are skipped structurally. B. unwrap/expect/panic! inside extern "C"/"system" bodies — an abort since Rust 1.81, not linted, not fuzzable (8b98d0b3). catch_unwind bodies are exempt; `// panic-in-extern-ok: <reason>` waives a deliberate abort. C. Safe-but-process-global APIs (env::set_var/remove_var, sigaction, setlocale, set_current_dir) — the972af299environ race lived in a file with zero occurrences of the word `unsafe`. Per-file count ratchet with the baseline in the script; any increase or new file fails. Making gate B clean on main surfaced 14 real instances of exactly its class — `.lock().unwrap()` in unguarded extern fns, where a poisoned mutex aborts the embedding process: six punktfunk-core abi.rs entry points (poll_frame, next_au, next_audio, next_audio_pcm, next_cursor_shape, next_clipboard), seven Android JNI entry points, and the Windows client's deeplink wnd_proc. All fixed with poison-recovering locks (the slots are last-value caches, valid whatever a poisoned writer left) and Option::insert for the set-then-unwrap shape; punktfunk-core's 203 lib tests pass. Gate A's findings were six genuine contract-deferring fns — waived with reasons, not fixed, because the markers are correct. Gate-of-the-gate: all three shown to FAIL on deliberately planted instances (marker fn, panicking extern callback, env::set_var in an unlisted file) and to run clean on the tree, before the ci.yml step made them blocking.
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