enricobuehler
8b0172d793
Prepares the move to the NVIDIA-GPU Ubuntu VM where M0/M2 run (macOS can't drive the Wayland/GPU stack). The repo carries the context, since Claude Code sessions are machine-local and don't transfer. - CLAUDE.md: project state + design invariants + don't-regress security notes. Auto-loads every session, so a fresh session on the VM continues from here. - scripts/bootstrap-ubuntu.sh: verifies the (already-installed) NVIDIA/NVENC stack, installs rustup + PipeWire/portal/wlroots/Sway + DRM/EGL/GBM/VA dev deps; GATES the FFmpeg -dev headers so apt can't clobber a custom NVENC build; checks nvidia-drm.modeset. - scripts/headless/: headless-Sway + xdg-desktop-portal-wlr config templates, the NVIDIA-wlroots env workarounds, run-headless-sway.sh, and a wf-recorder->hevc_nvenc capture smoke test (proves capture->NVENC with no Rust). - docs/linux-setup.md: M0 walkthrough + verified gotchas (modeset, headless backend, vGPU NVENC licensing, dmabuf->NVENC CPU-copy fallback, FFmpeg-dev gate, crate versions). Ubuntu 24.04 package names/versions verified against the live archive; scripts pass shellcheck and `bash -n`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
78 lines
3.9 KiB
Markdown
78 lines
3.9 KiB
Markdown
# CLAUDE.md — lumen
|
|
|
|
Low-latency desktop streaming stack, Linux-first, with a shared Rust protocol core
|
|
(`lumen-core`) exposed over a C ABI and native clients per platform. Full design:
|
|
[`docs/implementation-plan.md`](docs/implementation-plan.md). Status table: `README.md`.
|
|
|
|
## Where the work stands
|
|
|
|
- **M1 (`lumen-core` + C ABI) is complete, tested, and hardened.** It builds and its full
|
|
suite passes (FEC recovery, loopback-under-loss, proptests, a C ABI harness). It was put
|
|
through an adversarial review and 13 verified findings were fixed + regression-tested
|
|
(commit `a913042`).
|
|
- **The host backends are `#[cfg(target_os = "linux")]` stubs.** They compile everywhere
|
|
but `bail!` until implemented. This is the next work (**M0**, then **M2**) and needs a
|
|
real Linux GPU + Wayland stack — which is why this repo is being moved to the NVIDIA
|
|
Ubuntu VM.
|
|
|
|
## Build / test / run
|
|
|
|
```sh
|
|
cargo build --workspace # green on Linux and macOS
|
|
cargo test --workspace # unit + loopback + proptest + C ABI harness
|
|
cargo clippy --workspace --all-targets -- -D warnings
|
|
cargo fmt --all --check
|
|
|
|
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
|
|
```
|
|
|
|
`include/lumen_core.h` is generated from `crates/lumen-core/src/abi.rs` by cbindgen
|
|
(`build.rs`) on every build and is **checked in**; CI fails if it drifts, so commit the
|
|
regenerated header when the ABI changes.
|
|
|
|
## Layout
|
|
|
|
```
|
|
crates/lumen-core/ protocol · FEC · pacing · crypto — the C ABI (lib + cdylib + staticlib)
|
|
crates/lumen-host/ Linux host: vdisplay · capture · encode · inject · web · pipeline (cfg-gated)
|
|
crates/lumen-client-rs/ reference client (M4)
|
|
tools/{loss-harness,latency-probe}/ measurement (plan §10)
|
|
clients/{apple,android}/ native client scaffolds (import lumen_core.h)
|
|
include/lumen_core.h generated C header
|
|
```
|
|
|
|
## Design invariants — do not regress
|
|
|
|
- **One core, linked everywhere.** Protocol/FEC/crypto/pacing live only in `lumen-core`,
|
|
behind a stable, versioned C ABI (`lumen_abi_version`, `LumenConfig.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, Moonlight-compatible) and
|
|
GF(2¹⁶) Leopard-RS (≤65535 shards/block, SIMD) — the latter removes the ~1 Gbps ceiling.
|
|
- **Security hardening from the M1 review must stay intact:** the reassembler bounds every
|
|
attacker-controlled header field against negotiated limits *before allocating*
|
|
(`ReassemblerLimits` in `packet.rs`); AES-GCM uses per-direction nonce salts + seq-as-AAD
|
|
(`crypto.rs`); the ABI enforces `struct_size` and range-checks inputs. There are
|
|
regression tests for these — keep them green.
|
|
|
|
## Next: M0 (the pipeline spike) on this VM
|
|
|
|
**Start here on the NVIDIA Ubuntu VM:** [`docs/linux-setup.md`](docs/linux-setup.md), then
|
|
run `bash scripts/bootstrap-ubuntu.sh` (verifies NVIDIA/NVENC, installs the Rust/PipeWire/
|
|
wlroots/FFmpeg-dev deps) and bring up headless Sway with `scripts/headless/`.
|
|
|
|
Per plan §8/§12: drive a headless Sway/wlroots output → capture via PipeWire (ScreenCast
|
|
portal, `ashpd` 0.13 + `pipewire` 0.10) → encode with NVENC (`ffmpeg-next` 7.x,
|
|
`hevc_nvenc`) → write a playable H.265 file. Then wire that pipeline into a `lumen-core`
|
|
host `Session` (M2). The module seams exist in
|
|
`crates/lumen-host/src/{vdisplay,capture,encode,inject,pipeline}.rs`. **Budget for the
|
|
CPU-copy fallback first** — dmabuf→NVENC zero-copy import is unreliable across NVIDIA
|
|
driver versions (plan §9 risk); the setup doc covers it.
|
|
|
|
## Conventions
|
|
|
|
- Rust 2021, `rustfmt` + `clippy -D warnings` clean before commit.
|
|
- Match the surrounding code's comment density and naming.
|
|
- Commit messages end with the Co-Authored-By trailer (see `git log`).
|