enricobuehler
a913042367
Ground-up low-latency streaming stack per docs/implementation-plan.md. M1 is
complete and tested; Linux host backends are cfg-gated stubs to be filled in on
real hardware (M0/M2).
lumen-core (built + tested on macOS/aarch64 — 21 tests):
- fec: ErasureCoder over GF(2^8) (reed-solomon-erasure, Moonlight-compatible)
and GF(2^16) Leopard-RS (reed-solomon-simd, the >1 Gbps wall-breaker); proptested
- packet: zero-copy #[repr(C)] framing, multi-block, FEC-aware reassembly
- crypto: AES-128-GCM with per-direction nonce salts + sequence-as-AAD
- session: host submit / client poll hot paths + input; loopback & UDP transports
- abi: opaque handles, versioned LumenConfig, panic guards; cbindgen-generated header
- acceptance: Rust loopback+proptest and a C harness that links the staticlib
Scaffold (compiles green on all platforms): lumen-host (vdisplay/capture/encode/
inject/web/pipeline seams under cfg(linux)), lumen-client-rs, tools/{loss-harness,
latency-probe}, Apple/Android client stubs, Gitea CI, docs.
Hardened against a multi-agent adversarial review (13 verified findings fixed,
regression-tested): reassembler memory-DoS bounds + block-consistency validation,
GCM nonce-reuse direction separation, ABI struct_size guard + range checks, FEC
shard-length guards, shard_payload datagram bound, key zeroization + Debug redaction.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
67 lines
3.0 KiB
Markdown
67 lines
3.0 KiB
Markdown
# lumen
|
|
|
|
*A ground-up low-latency desktop streaming stack, built Linux-first, with a shared Rust
|
|
protocol core and native clients per platform.*
|
|
|
|
`lumen` is a placeholder codename. The bet: ship a **Linux virtual-display streaming
|
|
host** that speaks the existing Moonlight protocol (every Moonlight/Artemis client works
|
|
day one), then break the ~1 Gbps FEC wall with a **GF(2¹⁶) Leopard-RS** transport as a
|
|
negotiated extension. See [`docs/implementation-plan.md`](docs/implementation-plan.md).
|
|
|
|
## Status
|
|
|
|
| Milestone | State |
|
|
|-----------|-------|
|
|
| **M1 — `lumen-core` + C ABI** | ✅ done & tested (FEC, packetization, crypto, session, `lumen_core.h`) |
|
|
| M0 — pipeline spike (wlroots→PipeWire→encode→file) | ⬜ needs Linux GPU |
|
|
| M2 — P1 host → stock Moonlight | ⬜ scaffolded (`lumen-host`) |
|
|
| M3 — measurement harness | 🟡 `tools/loss-harness` runs; `latency-probe` scaffolded |
|
|
| M4 — P2 transport + Rust client | 🟡 GF(2¹⁶) core done; `lumen-client-rs` scaffolded |
|
|
| M5 — Apple client | ⬜ scaffolded (`clients/apple`) |
|
|
|
|
`lumen-core` is complete and verified: it builds and its full test suite (FEC recovery,
|
|
loopback round-trip under loss, property tests, and a **C ABI harness**) passes on
|
|
macOS/aarch64. The Linux host backends (PipeWire, VAAPI/NVENC, KWin, libei) are
|
|
`#[cfg(target_os = "linux")]` seams — defined and compiling, implementations pending.
|
|
|
|
## Layout
|
|
|
|
```
|
|
crates/
|
|
lumen-core/ protocol · FEC · pacing · crypto — the C ABI (lib + cdylib + staticlib)
|
|
lumen-host/ Linux host: vdisplay · capture · encode · inject · web (cfg-gated)
|
|
lumen-client-rs/ reference client (M4): VAAPI decode + wgpu present
|
|
clients/{apple,android}/ native client scaffolds (import lumen_core.h)
|
|
include/lumen_core.h cbindgen-generated C header (checked in)
|
|
tools/{latency-probe,loss-harness}/ measurement (plan §10)
|
|
docs/implementation-plan.md
|
|
```
|
|
|
|
## Build & test
|
|
|
|
```sh
|
|
cargo build --workspace # green on Linux and macOS
|
|
cargo test --workspace # unit + loopback + proptest + C ABI harness
|
|
cargo clippy --workspace --all-targets
|
|
|
|
cargo run -p loss-harness # FEC loss-resilience sweep (no network needed)
|
|
bash crates/lumen-core/tests/c/run.sh # standalone C-ABI link+round-trip proof
|
|
```
|
|
|
|
The C header regenerates from `crates/lumen-core/src/abi.rs` on every build (cbindgen via
|
|
`build.rs`) into `include/lumen_core.h`.
|
|
|
|
## Design invariants
|
|
|
|
- **One core, linked everywhere.** Protocol/FEC/crypto/pacing live in `lumen-core` exactly
|
|
once, exposed over a stable, versioned C ABI (`lumen_abi_version()`, `LumenConfig`
|
|
carries its own `struct_size`).
|
|
- **No async on the hot path.** The per-frame pipeline uses native threads only;
|
|
`tokio`/`quinn` are gated behind the off-by-default `quic` feature (control plane only).
|
|
- **FEC is the wall-breaker.** GF(2⁸) (≤255 shards/block) for Moonlight compat;
|
|
GF(2¹⁶) (≤65535 shards/block, SIMD, O(n log n)) to push past ~1 Gbps.
|
|
|
|
## License
|
|
|
|
MIT OR Apache-2.0.
|