lvqr_mesh/lib.rs
1//! LVQR peer mesh topology planner.
2//!
3//! `MeshCoordinator` assigns peers to a relay tree, balances children
4//! across parents, reassigns orphans, tracks heartbeat liveness, and
5//! consults each peer's self-reported `capacity` (session 144) when
6//! picking a parent. The `PeerAssignment` returned by `add_peer` and
7//! `reassign_peer` is coordination state that `lvqr-signal` pushes to
8//! the client via `SignalMessage::AssignParent`.
9//!
10//! ## Scope of this Rust crate
11//!
12//! This crate owns the *topology* side of the mesh: which peer should
13//! relay to which other peer. It does not embed a WebRTC stack. The
14//! actual peer-to-peer media forwarding lives in the browser SDK
15//! (`bindings/js/packages/core/src/mesh.ts`'s `MeshPeer`), which opens
16//! `RTCPeerConnection` to its assigned parent and forwards bytes over a
17//! DataChannel using the 8-byte big-endian `object_id` framing the data
18//! plane locked in session 111-B1.
19//!
20//! ## System-level mesh status: shipped (sessions 141-144)
21//!
22//! * Two-peer + three-peer Playwright E2Es exercise the full
23//! ingest-to-leaf path on every CI push (`mesh-e2e.yml`).
24//! * Session 141 closed actual-vs-intended offload reporting: browser
25//! peers emit a `ForwardReport` signal message every second with
26//! their cumulative forwarded-frame counter; the coordinator
27//! aggregates per peer and surfaces the count via
28//! `MeshPeerStats.forwarded_frames` on `GET /api/v1/mesh` alongside
29//! the planner's `intended_children`.
30//! * Session 143 added `--mesh-ice-servers <JSON>` so operators can
31//! push STUN/TURN config to every browser peer through
32//! `AssignParent`.
33//! * Session 144 added per-peer capacity advertisement: browsers may
34//! self-report `capacity: u32` on `Register`, the lvqr-cli signal
35//! bridge clamps the claim to `--max-peers`, and
36//! `MeshCoordinator::find_best_parent` consults `PeerInfo.capacity`
37//! so a peer self-reporting `capacity: 1` forces subsequent peers
38//! to descend even when the global ceiling is higher.
39//!
40//! See `docs/mesh.md` (status: **IMPLEMENTED**) for the operator runbook
41//! and the deployment recipe under `deploy/turn/`.
42
43pub mod coordinator;
44pub mod error;
45pub mod tree;
46
47pub use coordinator::{MeshConfig, MeshCoordinator};
48pub use error::MeshError;
49pub use tree::{PeerAssignment, PeerInfo, PeerRole};