diff --git a/Cargo.lock b/Cargo.lock index 27c00d7..70a0f01 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -479,6 +479,19 @@ version = "2.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" +[[package]] +name = "muninn-contracts" +version = "0.1.0" +dependencies = [ + "anyhow", + "cultcache-rs", + "cultmesh-rs", + "cultnet-rs", + "rmp-serde", + "serde", + "serde_json", +] + [[package]] name = "muninn-daemon" version = "0.1.0" @@ -488,6 +501,7 @@ dependencies = [ "cultmesh-rs", "cultnet-rs", "libc", + "muninn-contracts", "muninn-move-tracker", "muninn-psmoveapi-tracker", "odin-core", @@ -791,6 +805,21 @@ version = "0.4.12" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" +[[package]] +name = "sleipnir-daemon" +version = "0.1.0" +dependencies = [ + "anyhow", + "cultcache-rs", + "cultmesh-rs", + "cultnet-rs", + "muninn-contracts", + "odin-core", + "rmp-serde", + "serde_json", + "vigem-client", +] + [[package]] name = "socket2" version = "0.5.10" @@ -878,6 +907,15 @@ version = "0.9.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" +[[package]] +name = "vigem-client" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b857e6f99efe1e1eb1e4dfb035de8ae7ec8ec56bd1928edcbd7c6e4427634d52" +dependencies = [ + "winapi", +] + [[package]] name = "wasi" version = "0.11.1+wasi-snapshot-preview1" diff --git a/Cargo.toml b/Cargo.toml index a6c8188..b9d770a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,8 +1,10 @@ [workspace] members = [ + "crates/muninn-contracts", "crates/muninn-daemon", "crates/muninn-move-tracker", "crates/muninn-psmoveapi-tracker", + "crates/sleipnir-daemon", ] resolver = "3" @@ -10,3 +12,11 @@ resolver = "3" edition = "2024" license = "MIT" publish = false + +# One pin per shared upstream. Muninn and Sleipnir resolve the same CultLib and +# odin-core by construction; a bump is one edit here. +[workspace.dependencies] +cultcache-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c2a9a6e526390808ef195759056fda0b9a55d8a3", package = "cultcache-rs" } +cultmesh-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c2a9a6e526390808ef195759056fda0b9a55d8a3", package = "cultmesh-rs" } +cultnet-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c2a9a6e526390808ef195759056fda0b9a55d8a3", package = "cultnet-rs" } +odin-core = { git = "https://github.com/GameCult/Odin.git", rev = "3e96c6c85ca8b89b1bc7b01c1b7744f43111be99" } diff --git a/README.md b/README.md index f1bad58..c894b34 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,14 @@ # Muninn +> **Deprecation notice (Meta, 2026-11-06).** Muninn's *streaming* role (screen and audio +> capture, the media sender, and the OBS media receiver at +> [github.com/GameCult/Ratatoskr](https://github.com/GameCult/Ratatoskr), not the forge chat +> client of the same name) is superseded in the streaming space. Do not build new work on it. +> Nothing is deleted yet; what depends on it and what looks removable is in +> [docs/streaming-deprecation.md](docs/streaming-deprecation.md). The non-streaming roles +> (sensors, PS Move, input for Sleipnir) are not covered by this notice. + + **Local capture broker for the GameCult swarm.** Muninn resolves what data streams a host can offer, advertises them, and serves @@ -11,6 +20,11 @@ Muninn running does not mean Muninn is broadcasting. Each feed it can reach is for input. A stream asks for screen and audio. Muninn does not decide what any of them are for. +**Naming note.** Muninn's docs say "Ratatoskr" for the OBS media receiver, which lives at +[github.com/GameCult/Ratatoskr](https://github.com/GameCult/Ratatoskr) (forge mirror: +[GameCult/Ratatoskr-receiver](https://eureka.gamecult.org/forge/GameCult/Ratatoskr-receiver)). +The forge repo `GameCult/Ratatoskr` is an unrelated project, Void's Cinny-based chat client. + Extracted from [Odin](https://github.com/GameCult/Odin) with its full history. Muninn had lived as three crates inside the repository of the service that discovers it, with its document schemas owned by `odin-core` — an inversion of diff --git a/crates/muninn-contracts/Cargo.toml b/crates/muninn-contracts/Cargo.toml new file mode 100644 index 0000000..8b674b5 --- /dev/null +++ b/crates/muninn-contracts/Cargo.toml @@ -0,0 +1,21 @@ +[package] +name = "muninn-contracts" +version = "0.1.0" +edition.workspace = true +license.workspace = true +publish.workspace = true + +[lib] +name = "muninn_contracts" +path = "src/lib.rs" + +[dependencies] +anyhow = "1" +cultcache-rs = { workspace = true } +cultmesh-rs = { workspace = true } +cultnet-rs = { workspace = true } +serde = { version = "1", features = ["derive"] } +serde_json = "1" + +[dev-dependencies] +rmp-serde = "1.3" diff --git a/crates/muninn-contracts/src/lib.rs b/crates/muninn-contracts/src/lib.rs new file mode 100644 index 0000000..e111ae5 --- /dev/null +++ b/crates/muninn-contracts/src/lib.rs @@ -0,0 +1,526 @@ +//! Muninn's typed state records: the wire and store contract that `muninn` and +//! `sleipnir` share. Library only: no sockets, threads, devices or Odin. + +mod records; + +pub use records::*; + +cultmesh_rs::cultmesh_documents!(MuninnRecords { + MuninnTelemetrySurfaceRecord => MUNINN_TELEMETRY_SURFACE_SCHEMA, + MuninnCaptureStreamRecord => MUNINN_CAPTURE_STREAM_SCHEMA, + MuninnCaptureStreamCommandRecord => MUNINN_CAPTURE_STREAM_COMMAND_SCHEMA, + MuninnObsStreamCatalogRecord => MUNINN_OBS_STREAM_CATALOG_SCHEMA, + MuninnMoveMarkerCandidateRecord => MUNINN_MOVE_MARKER_CANDIDATE_SCHEMA, + MuninnMoveControllerStateRecord => MUNINN_MOVE_CONTROLLER_STATE_SCHEMA, + MuninnHidControllerStateRecord => MUNINN_HID_CONTROLLER_STATE_SCHEMA, + MuninnMoveIdentityRecord => MUNINN_MOVE_IDENTITY_SCHEMA, + MuninnMoveLightCommandRecord => MUNINN_MOVE_LIGHT_COMMAND_SCHEMA, + MuninnMoveHueProgramRecord => MUNINN_MOVE_HUE_PROGRAM_SCHEMA, + MuninnMoveTrackerHealthRecord => MUNINN_MOVE_TRACKER_HEALTH_SCHEMA, + MuninnMoveEvidenceTransportHealthRecord => MUNINN_MOVE_EVIDENCE_TRANSPORT_HEALTH_SCHEMA, + MuninnQuestAccessRecord => MUNINN_QUEST_ACCESS_SCHEMA, + MuninnCommandBoundaryCompatRecord => MUNINN_COMMAND_BOUNDARY_SCHEMA, + MuninnTransportProfileCompatRecord => MUNINN_TRANSPORT_PROFILE_SCHEMA, +}); + +#[cfg(test)] +mod tests { + use super::*; + use cultcache_rs::{CultCache, DatabaseEntry}; + use cultmesh_rs::CultMeshDocumentSet; + use cultnet_rs::CultNetDocumentRegistry; + + /// Every Muninn record: its type name, its schema id, the schema constant + /// the document set binds it under, and its Rust name. + fn contract() -> Vec<(&'static str, &'static str, &'static str, &'static str)> { + macro_rules! row { + ($record:ty, $constant:expr) => { + ( + <$record as DatabaseEntry>::TYPE, + <$record as DatabaseEntry>::SCHEMA_NAME, + $constant, + stringify!($record), + ) + }; + } + vec![ + row!(MuninnTelemetrySurfaceRecord, MUNINN_TELEMETRY_SURFACE_SCHEMA), + row!(MuninnCaptureStreamRecord, MUNINN_CAPTURE_STREAM_SCHEMA), + row!(MuninnCaptureStreamCommandRecord, MUNINN_CAPTURE_STREAM_COMMAND_SCHEMA), + row!(MuninnObsStreamCatalogRecord, MUNINN_OBS_STREAM_CATALOG_SCHEMA), + row!(MuninnMoveMarkerCandidateRecord, MUNINN_MOVE_MARKER_CANDIDATE_SCHEMA), + row!(MuninnMoveControllerStateRecord, MUNINN_MOVE_CONTROLLER_STATE_SCHEMA), + row!(MuninnHidControllerStateRecord, MUNINN_HID_CONTROLLER_STATE_SCHEMA), + row!(MuninnMoveIdentityRecord, MUNINN_MOVE_IDENTITY_SCHEMA), + row!(MuninnMoveLightCommandRecord, MUNINN_MOVE_LIGHT_COMMAND_SCHEMA), + row!(MuninnMoveHueProgramRecord, MUNINN_MOVE_HUE_PROGRAM_SCHEMA), + row!(MuninnMoveTrackerHealthRecord, MUNINN_MOVE_TRACKER_HEALTH_SCHEMA), + row!( + MuninnMoveEvidenceTransportHealthRecord, + MUNINN_MOVE_EVIDENCE_TRANSPORT_HEALTH_SCHEMA + ), + row!(MuninnQuestAccessRecord, MUNINN_QUEST_ACCESS_SCHEMA), + row!(MuninnCommandBoundaryCompatRecord, MUNINN_COMMAND_BOUNDARY_SCHEMA), + row!(MuninnTransportProfileCompatRecord, MUNINN_TRANSPORT_PROFILE_SCHEMA), + ] + } + + #[test] + fn record_names_are_the_published_schema_ids() { + let expected = [ + ("muninn.telemetry_surface", "muninn.telemetry_surface.v1"), + ("muninn.capture_stream", "muninn.capture_stream.v1"), + ("muninn.capture_stream_command", "muninn.capture_stream_command.v1"), + ("muninn.obs_stream_catalog", "muninn.obs_stream_catalog.v1"), + ("muninn.move_marker_candidate", "muninn.move_marker_candidate.v1"), + ("muninn.move_controller_state", "muninn.move_controller_state.v1"), + ("muninn.hid_controller_state", "muninn.hid_controller_state.v1"), + ("muninn.move_identity", "muninn.move_identity.v1"), + ("muninn.move_light_command", "muninn.move_light_command.v1"), + ("muninn.move_hue_program", "muninn.move_hue_program.v1"), + ("muninn.move_tracker_health", "muninn.move_tracker_health.v1"), + ( + "muninn.move_evidence_transport_health", + "muninn.move_evidence_transport_health.v1", + ), + ("muninn.quest_access", "muninn.quest_access.v1"), + ("muninn.command_boundary", "muninn.command_boundary.v1"), + ("muninn.transport_profile", "muninn.transport_profile.v1"), + ]; + let actual: Vec<_> = contract() + .into_iter() + .map(|(record_type, schema, constant, _)| { + assert_eq!(schema, constant, "schema constant and derive disagree"); + (record_type, schema) + }) + .collect(); + assert_eq!(actual, expected); + } + + #[test] + fn document_set_binds_every_record_under_its_schema() { + let mut cache = CultCache::new(); + MuninnRecords.register_cache(&mut cache).unwrap(); + let mut registry = CultNetDocumentRegistry::new(); + MuninnRecords.register_documents(&mut registry).unwrap(); + + let rows = contract(); + let mut registered = cache.registered_entry_types(); + registered.sort(); + let mut expected: Vec = rows.iter().map(|row| row.0.to_string()).collect(); + expected.sort(); + assert_eq!(registered, expected); + for (record_type, schema, _, record) in rows { + let binding = registry + .binding_by_schema_id(schema) + .unwrap_or_else(|| panic!("{record} is not bound under {schema}")); + assert_eq!(binding.document_type, record_type, "{record}"); + } + } + + /// One wire pin per record. `bytes` is the record's positional MessagePack + /// array, encoded from a sample whose every field holds a distinct, + /// non-default value (Options: one `None`, one `Some`). `first_default` is + /// the key of the first defaulted tail field; records without one carry + /// `None`. + struct Pin { + record: &'static str, + bytes: Vec, + first_default: Option, + golden: &'static str, + /// Decode a payload as this record and encode it again. + reencode: fn(&[u8]) -> Result, String>, + } + + fn pin( + record: &'static str, + sample: T, + first_default: Option, + golden: &'static str, + ) -> Pin + where + T: serde::Serialize + serde::de::DeserializeOwned, + { + Pin { + record, + bytes: rmp_serde::to_vec(&sample).unwrap(), + first_default, + golden, + reencode: |bytes| { + let decoded: T = rmp_serde::from_slice(bytes).map_err(|error| error.to_string())?; + rmp_serde::to_vec(&decoded).map_err(|error| error.to_string()) + }, + } + } + + fn text(value: &str) -> String { + value.to_string() + } + + fn texts(values: &[&str]) -> Vec { + values.iter().map(|value| value.to_string()).collect() + } + + fn pins() -> Vec { + vec![ + pin( + "MuninnTelemetrySurfaceRecord", + MuninnTelemetrySurfaceRecord { + surface_id: text("surface"), + host_id: text("host"), + state: text("live"), + available_sources: texts(&["src"]), + stream_affordances: texts(&["aff"]), + active_streams: texts(&["act"]), + activation_authority: text("auth"), + detail: text("detail"), + updated_at: text("t"), + primary_stream_id: text("psid"), + primary_stream_label: text("plabel"), + command_rudp_target: text("cmd"), + media_target_host: text("mth"), + media_port: 4001, + media_packet_bytes: 1200, + rudp_video_bitrate_kbps: 8000, + rudp_latency_budget_ms: 40, + video_source_ids: texts(&["vid"]), + video_source_labels: texts(&["vlab"]), + audio_source_ids: texts(&["aid"]), + audio_source_labels: texts(&["alab"]), + }, + Some(9), + "dc0015a773757266616365a4686f7374a46c69766591a373726391a361666691a3616374a461757468a664657461696ca174a470736964a6706c6162656ca3636d64a36d7468cd0fa1cd04b0cd1f402891a376696491a4766c616291a361696491a4616c6162", + ), + pin( + "MuninnCaptureStreamRecord", + MuninnCaptureStreamRecord { + stream_id: text("stream"), + host_id: text("host"), + state: text("live"), + video_source: text("vsrc"), + audio_source: text("asrc"), + transport: text("rudp"), + targets: texts(&["tgt"]), + command_witness: text("wit"), + supervisor_pid: None, + mux_pid: Some(77), + restart_count: 3, + detail: text("detail"), + updated_at: text("t"), + }, + None, + "9da673747265616da4686f7374a46c697665a476737263a461737263a47275647091a3746774a3776974c04d03a664657461696ca174", + ), + pin( + "MuninnCaptureStreamCommandRecord", + MuninnCaptureStreamCommandRecord { + command_id: text("cmd"), + host_id: text("host"), + stream_id: text("stream"), + state: text("live"), + action: text("start"), + target_host: text("tgt"), + port: 4001, + obs_target_host: Some(text("obs")), + obs_port: 4002, + media_transport: text("rudp"), + media_packet_bytes: 1200, + requested_by: text("who"), + detail: text("detail"), + updated_at: text("t"), + rudp_video_bitrate_kbps: 8000, + rudp_latency_budget_ms: 40, + video_source_id: text("vid"), + audio_source_id: text("aid"), + }, + Some(14), + "dc0012a3636d64a4686f7374a673747265616da46c697665a57374617274a3746774cd0fa1a36f6273cd0fa2a472756470cd04b0a377686fa664657461696ca174cd1f4028a3766964a3616964", + ), + pin( + "MuninnObsStreamCatalogRecord", + MuninnObsStreamCatalogRecord { + catalog_id: text("catalog"), + host_id: text("host"), + stream_ids: texts(&["sid"]), + labels: texts(&["lab"]), + urls: texts(&["url"]), + states: texts(&["st"]), + updated_at: text("t"), + command_rudp_target: text("cmd"), + media_target_host: text("mth"), + media_port: 4001, + media_packet_bytes: 1200, + rudp_video_bitrate_kbps: 8000, + rudp_latency_budget_ms: 40, + video_source_ids: texts(&["vid"]), + video_source_labels: texts(&["vlab"]), + audio_source_ids: texts(&["aid"]), + audio_source_labels: texts(&["alab"]), + }, + Some(7), + "dc0011a7636174616c6f67a4686f737491a373696491a36c616291a375726c91a27374a174a3636d64a36d7468cd0fa1cd04b0cd1f402891a376696491a4766c616291a361696491a4616c6162", + ), + pin( + "MuninnMoveMarkerCandidateRecord", + MuninnMoveMarkerCandidateRecord { + stream_id: text("stream"), + host_id: text("host"), + camera_id: text("cam"), + frame_sequence: 11, + source_id_hash: 12, + tile_x: 13, + tile_y: 14, + center_x_px: 1.5, + center_y_px: 2.5, + radius_px: 3.5, + area_px: 15, + mean_luma: 4.5, + peak_luma: 16, + score: 0.5, + observed_at: text("t"), + move_id: text("move"), + }, + Some(15), + "dc0010a673747265616da4686f7374a363616d0b0c0d0eca3fc00000ca40200000ca406000000fca4090000010ca3f000000a174a46d6f7665", + ), + pin( + "MuninnMoveControllerStateRecord", + MuninnMoveControllerStateRecord { + stream_id: text("stream"), + host_id: text("host"), + move_id: text("move"), + sequence: 21, + source_timestamp_ns: -22, + accelerometer_xyz: vec![1.0, 2.0, 3.0], + gyroscope_xyz: vec![4.0, 5.0, 6.0], + magnetometer_xyz: vec![7.0, 8.0, 9.0], + trigger_value: 0.25, + buttons: texts(&["cross"]), + battery01: 0.75, + observed_at: text("t"), + source_path: text("/dev/js0"), + }, + Some(12), + "9da673747265616da4686f7374a46d6f766515ea93ca3f800000ca40000000ca4040000093ca40800000ca40a00000ca40c0000093ca40e00000ca41000000ca41100000ca3e80000091a563726f7373ca3f400000a174a82f6465762f6a7330", + ), + pin( + "MuninnHidControllerStateRecord", + MuninnHidControllerStateRecord { + stream_id: text("muninn.raven.hid"), + host_id: text("raven"), + device_id: text("xbox-0"), + device_kind: text("xinput"), + sequence: 7, + source_timestamp_ns: -3, + axes: vec![0.5, -1.0], + buttons: texts(&["a", "b"]), + battery01: 1.0, + observed_at: text("unix:100"), + source_path: text("xinput://0"), + }, + None, + "9bb06d756e696e6e2e726176656e2e686964a5726176656ea678626f782d30a678696e70757407fd92ca3f000000cabf80000092a161a162ca3f800000a8756e69783a313030aa78696e7075743a2f2f30", + ), + pin( + "MuninnMoveIdentityRecord", + MuninnMoveIdentityRecord { + identity_id: text("identity"), + host_id: text("host"), + move_id: text("move"), + source_path: text("path"), + bluetooth_host_address: text("bt"), + state: text("live"), + detail: text("detail"), + observed_at: text("t"), + }, + None, + "98a86964656e74697479a4686f7374a46d6f7665a470617468a26274a46c697665a664657461696ca174", + ), + pin( + "MuninnMoveLightCommandRecord", + MuninnMoveLightCommandRecord { + command_id: text("cmd"), + host_id: text("host"), + move_id: text("move"), + hidraw_path: text("hidraw"), + colors: texts(&["red"]), + durations_ms: vec![100, 200], + repeat_count: 5, + authority: text("auth"), + state: text("live"), + detail: text("detail"), + updated_at: text("t"), + }, + None, + "9ba3636d64a4686f7374a46d6f7665a668696472617791a37265649264ccc805a461757468a46c697665a664657461696ca174", + ), + pin( + "MuninnMoveHueProgramRecord", + MuninnMoveHueProgramRecord { + program_id: text("prog"), + host_id: text("raven"), + mode: text("cycle"), + cycle_ms: 20, + epoch_ns: -1, + hold_at_ns: 0, + requested_by: text("mimir"), + updated_at: text("unix:1"), + order_mode: text("ring"), + transition_percent: 50, + transition_percent_explicit: true, + }, + Some(8), + "9ba470726f67a5726176656ea56379636c6514ff00a56d696d6972a6756e69783a31a472696e6732c3", + ), + pin( + "MuninnMoveTrackerHealthRecord", + MuninnMoveTrackerHealthRecord { + health_id: text("health"), + host_id: text("host"), + camera_id: text("cam"), + camera_index: -2, + state: text("live"), + camera_name: text("name"), + camera_api: text("api"), + width: 640, + height: 480, + exposure: 0.5, + calibrated_controller_count: 2, + update_count: 30, + observation_count: 31, + latest_observation_count: 32, + last_observation_at: text("last"), + detail: text("detail"), + updated_at: text("t"), + image_mean_rgb: vec![1, 2, 3], + image_peak_rgb: vec![4, 5, 6], + color_evidence_move_ids: texts(&["move"]), + color_evidence_pixel_counts: vec![40], + rejected_stale_count: 41, + rejected_radius_count: 42, + rejected_bounds_count: 43, + rejected_continuity_count: 44, + }, + Some(17), + "dc0019a66865616c7468a4686f7374a363616dfea46c697665a46e616d65a3617069cd0280cd01e0ca3f000000021e1f20a46c617374a664657461696ca174930102039304050691a46d6f76659128292a2b2c", + ), + pin( + "MuninnMoveEvidenceTransportHealthRecord", + MuninnMoveEvidenceTransportHealthRecord { + health_id: text("health"), + host_id: text("host"), + stream_id: text("stream"), + produced_frames: 50, + local_ring_admissions: 51, + remote_handoffs: 52, + remote_sends: 53, + updated_at: text("t"), + }, + None, + "98a66865616c7468a4686f7374a673747265616d32333435a174", + ), + pin( + "MuninnQuestAccessRecord", + MuninnQuestAccessRecord { + access_id: text("access"), + host_id: text("host"), + serial: text("serial"), + connection_state: text("conn"), + product: text("product"), + model: text("model"), + device: text("device"), + transport_id: text("tid"), + input_stream_id: text("input"), + pose_stream_id: text("pose"), + video_input_stream_id: text("video"), + video_input_transport: text("vtransport"), + state: text("live"), + detail: text("detail"), + observed_at: text("t"), + }, + None, + "9fa6616363657373a4686f7374a673657269616ca4636f6e6ea770726f64756374a56d6f64656ca6646576696365a3746964a5696e707574a4706f7365a5766964656faa767472616e73706f7274a46c697665a664657461696ca174", + ), + pin( + "MuninnCommandBoundaryCompatRecord", + MuninnCommandBoundaryCompatRecord { + value: serde_json::json!({ "daemon_id": "muninn" }), + }, + None, + "9181a96461656d6f6e5f6964a66d756e696e6e", + ), + pin( + "MuninnTransportProfileCompatRecord", + MuninnTransportProfileCompatRecord { + value: serde_json::json!({ "state": "live" }), + }, + None, + "9181a57374617465a46c697665", + ), + ] + } + + /// Every record's bytes are exactly the pinned positional array: a swapped + /// key, a changed type or a moved field changes them. + #[test] + fn every_record_encodes_to_its_pinned_positional_bytes() { + let mut wrong = Vec::new(); + for pin in pins() { + let actual = hex(&pin.bytes); + if actual != pin.golden { + wrong.push(format!("{}: {actual}", pin.record)); + } + let reencoded = (pin.reencode)(&pin.bytes) + .unwrap_or_else(|error| panic!("{} does not decode its own bytes: {error}", pin.record)); + assert_eq!(reencoded, pin.bytes, "{} round trip", pin.record); + } + assert!( + wrong.is_empty(), + "unpinned or moved wire layouts:\n{}", + wrong.join("\n") + ); + } + + /// A payload written before a defaulted key existed still decodes, once + /// per defaulted key, and every key from there on reads as its zero value. + #[test] + fn every_defaulted_tail_key_decodes_from_a_payload_that_ends_before_it() { + use serde_json::Value; + let is_zero = |value: &Value| match value { + Value::Null => true, + Value::Bool(flag) => !flag, + Value::Number(number) => number.as_f64() == Some(0.0), + Value::String(text) => text.is_empty(), + Value::Array(items) => items.is_empty(), + Value::Object(_) => false, + }; + for pin in pins() { + let Some(first_default) = pin.first_default else { + continue; + }; + let full: Vec = rmp_serde::from_slice(&pin.bytes).unwrap(); + for end in first_default..full.len() { + let truncated = rmp_serde::to_vec(&full[..end]).unwrap(); + let decoded = (pin.reencode)(&truncated).unwrap_or_else(|error| { + panic!( + "{} does not decode a payload ending before key {end}: {error}", + pin.record + ) + }); + let decoded: Vec = rmp_serde::from_slice(&decoded).unwrap(); + assert_eq!(decoded.len(), full.len(), "{} ending before key {end}", pin.record); + assert_eq!(&decoded[..end], &full[..end], "{} ending before key {end}", pin.record); + assert!( + decoded[end..].iter().all(is_zero), + "{} ending before key {end} defaulted to {:?}", + pin.record, + &decoded[end..] + ); + } + } + } + + fn hex(bytes: &[u8]) -> String { + bytes.iter().map(|byte| format!("{byte:02x}")).collect() + } +} diff --git a/crates/muninn-contracts/src/records.rs b/crates/muninn-contracts/src/records.rs new file mode 100644 index 0000000..7742843 --- /dev/null +++ b/crates/muninn-contracts/src/records.rs @@ -0,0 +1,508 @@ +use cultcache_rs::DatabaseEntry; +use serde_json::Value; + +pub const MUNINN_TELEMETRY_SURFACE_SCHEMA: &str = "muninn.telemetry_surface.v1"; +pub const MUNINN_CAPTURE_STREAM_SCHEMA: &str = "muninn.capture_stream.v1"; +pub const MUNINN_CAPTURE_STREAM_COMMAND_SCHEMA: &str = "muninn.capture_stream_command.v1"; +pub const MUNINN_OBS_STREAM_CATALOG_SCHEMA: &str = "muninn.obs_stream_catalog.v1"; +pub const MUNINN_MOVE_MARKER_CANDIDATE_SCHEMA: &str = "muninn.move_marker_candidate.v1"; +pub const MUNINN_MOVE_CONTROLLER_STATE_SCHEMA: &str = "muninn.move_controller_state.v1"; +pub const MUNINN_HID_CONTROLLER_STATE_SCHEMA: &str = "muninn.hid_controller_state.v1"; +pub const MUNINN_MOVE_IDENTITY_SCHEMA: &str = "muninn.move_identity.v1"; +pub const MUNINN_MOVE_LIGHT_COMMAND_SCHEMA: &str = "muninn.move_light_command.v1"; +pub const MUNINN_MOVE_HUE_PROGRAM_SCHEMA: &str = "muninn.move_hue_program.v1"; +pub const MUNINN_MOVE_TRACKER_HEALTH_SCHEMA: &str = "muninn.move_tracker_health.v1"; +pub const MUNINN_MOVE_EVIDENCE_TRANSPORT_HEALTH_SCHEMA: &str = + "muninn.move_evidence_transport_health.v1"; +pub const MUNINN_QUEST_ACCESS_SCHEMA: &str = "muninn.quest_access.v1"; +pub const MUNINN_COMMAND_BOUNDARY_SCHEMA: &str = "muninn.command_boundary.v1"; +pub const MUNINN_TRANSPORT_PROFILE_SCHEMA: &str = "muninn.transport_profile.v1"; + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache(type = "muninn.capture_stream", schema = "muninn.capture_stream.v1")] +pub struct MuninnCaptureStreamRecord { + #[cultcache(key = 0)] + pub stream_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub state: String, + #[cultcache(key = 3)] + pub video_source: String, + #[cultcache(key = 4)] + pub audio_source: String, + #[cultcache(key = 5)] + pub transport: String, + #[cultcache(key = 6)] + pub targets: Vec, + #[cultcache(key = 7)] + pub command_witness: String, + #[cultcache(key = 8)] + pub supervisor_pid: Option, + #[cultcache(key = 9)] + pub mux_pid: Option, + #[cultcache(key = 10)] + pub restart_count: u32, + #[cultcache(key = 11)] + pub detail: String, + #[cultcache(key = 12)] + pub updated_at: String, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache( + type = "muninn.capture_stream_command", + schema = "muninn.capture_stream_command.v1" +)] +pub struct MuninnCaptureStreamCommandRecord { + #[cultcache(key = 0)] + pub command_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub stream_id: String, + #[cultcache(key = 3)] + pub state: String, + #[cultcache(key = 4)] + pub action: String, + #[cultcache(key = 5)] + pub target_host: String, + #[cultcache(key = 6)] + pub port: u16, + #[cultcache(key = 7)] + pub obs_target_host: Option, + #[cultcache(key = 8)] + pub obs_port: u16, + #[cultcache(key = 9)] + pub media_transport: String, + #[cultcache(key = 10)] + pub media_packet_bytes: u32, + #[cultcache(key = 11)] + pub requested_by: String, + #[cultcache(key = 12)] + pub detail: String, + #[cultcache(key = 13)] + pub updated_at: String, + #[cultcache(key = 14, default)] + pub rudp_video_bitrate_kbps: u32, + #[cultcache(key = 15, default)] + pub rudp_latency_budget_ms: u32, + #[cultcache(key = 16, default)] + pub video_source_id: String, + #[cultcache(key = 17, default)] + pub audio_source_id: String, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache( + type = "muninn.telemetry_surface", + schema = "muninn.telemetry_surface.v1" +)] +pub struct MuninnTelemetrySurfaceRecord { + #[cultcache(key = 0)] + pub surface_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub state: String, + #[cultcache(key = 3)] + pub available_sources: Vec, + #[cultcache(key = 4)] + pub stream_affordances: Vec, + #[cultcache(key = 5)] + pub active_streams: Vec, + #[cultcache(key = 6)] + pub activation_authority: String, + #[cultcache(key = 7)] + pub detail: String, + #[cultcache(key = 8)] + pub updated_at: String, + #[cultcache(key = 9, default)] + pub primary_stream_id: String, + #[cultcache(key = 10, default)] + pub primary_stream_label: String, + #[cultcache(key = 11, default)] + pub command_rudp_target: String, + #[cultcache(key = 12, default)] + pub media_target_host: String, + #[cultcache(key = 13, default)] + pub media_port: u16, + #[cultcache(key = 14, default)] + pub media_packet_bytes: u32, + #[cultcache(key = 15, default)] + pub rudp_video_bitrate_kbps: u32, + #[cultcache(key = 16, default)] + pub rudp_latency_budget_ms: u32, + #[cultcache(key = 17, default)] + pub video_source_ids: Vec, + #[cultcache(key = 18, default)] + pub video_source_labels: Vec, + #[cultcache(key = 19, default)] + pub audio_source_ids: Vec, + #[cultcache(key = 20, default)] + pub audio_source_labels: Vec, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache( + type = "muninn.obs_stream_catalog", + schema = "muninn.obs_stream_catalog.v1" +)] +pub struct MuninnObsStreamCatalogRecord { + #[cultcache(key = 0)] + pub catalog_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub stream_ids: Vec, + #[cultcache(key = 3)] + pub labels: Vec, + #[cultcache(key = 4)] + pub urls: Vec, + #[cultcache(key = 5)] + pub states: Vec, + #[cultcache(key = 6)] + pub updated_at: String, + #[cultcache(key = 7, default)] + pub command_rudp_target: String, + #[cultcache(key = 8, default)] + pub media_target_host: String, + #[cultcache(key = 9, default)] + pub media_port: u16, + #[cultcache(key = 10, default)] + pub media_packet_bytes: u32, + #[cultcache(key = 11, default)] + pub rudp_video_bitrate_kbps: u32, + #[cultcache(key = 12, default)] + pub rudp_latency_budget_ms: u32, + #[cultcache(key = 13, default)] + pub video_source_ids: Vec, + #[cultcache(key = 14, default)] + pub video_source_labels: Vec, + #[cultcache(key = 15, default)] + pub audio_source_ids: Vec, + #[cultcache(key = 16, default)] + pub audio_source_labels: Vec, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "muninn.move_marker_candidate", + schema = "muninn.move_marker_candidate.v1" +)] +pub struct MuninnMoveMarkerCandidateRecord { + #[cultcache(key = 0)] + pub stream_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub camera_id: String, + #[cultcache(key = 3)] + pub frame_sequence: u64, + #[cultcache(key = 4)] + pub source_id_hash: u64, + #[cultcache(key = 5)] + pub tile_x: u32, + #[cultcache(key = 6)] + pub tile_y: u32, + #[cultcache(key = 7)] + pub center_x_px: f32, + #[cultcache(key = 8)] + pub center_y_px: f32, + #[cultcache(key = 9)] + pub radius_px: f32, + #[cultcache(key = 10)] + pub area_px: u32, + #[cultcache(key = 11)] + pub mean_luma: f32, + #[cultcache(key = 12)] + pub peak_luma: u32, + #[cultcache(key = 13)] + pub score: f32, + #[cultcache(key = 14)] + pub observed_at: String, + #[cultcache(key = 15, default)] + pub move_id: String, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "muninn.move_controller_state", + schema = "muninn.move_controller_state.v1" +)] +pub struct MuninnMoveControllerStateRecord { + #[cultcache(key = 0)] + pub stream_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub move_id: String, + #[cultcache(key = 3)] + pub sequence: u64, + #[cultcache(key = 4)] + pub source_timestamp_ns: i64, + #[cultcache(key = 5)] + pub accelerometer_xyz: Vec, + #[cultcache(key = 6)] + pub gyroscope_xyz: Vec, + #[cultcache(key = 7)] + pub magnetometer_xyz: Vec, + #[cultcache(key = 8)] + pub trigger_value: f32, + #[cultcache(key = 9)] + pub buttons: Vec, + #[cultcache(key = 10)] + pub battery01: f32, + #[cultcache(key = 11)] + pub observed_at: String, + #[cultcache(key = 12, default)] + pub source_path: String, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "muninn.hid_controller_state", + schema = "muninn.hid_controller_state.v1" +)] +pub struct MuninnHidControllerStateRecord { + #[cultcache(key = 0)] + pub stream_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub device_id: String, + #[cultcache(key = 3)] + pub device_kind: String, + #[cultcache(key = 4)] + pub sequence: u64, + #[cultcache(key = 5)] + pub source_timestamp_ns: i64, + #[cultcache(key = 6)] + pub axes: Vec, + #[cultcache(key = 7)] + pub buttons: Vec, + #[cultcache(key = 8)] + pub battery01: f32, + #[cultcache(key = 9)] + pub observed_at: String, + #[cultcache(key = 10)] + pub source_path: String, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache(type = "muninn.move_identity", schema = "muninn.move_identity.v1")] +pub struct MuninnMoveIdentityRecord { + #[cultcache(key = 0)] + pub identity_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub move_id: String, + #[cultcache(key = 3)] + pub source_path: String, + #[cultcache(key = 4)] + pub bluetooth_host_address: String, + #[cultcache(key = 5)] + pub state: String, + #[cultcache(key = 6)] + pub detail: String, + #[cultcache(key = 7)] + pub observed_at: String, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache( + type = "muninn.move_light_command", + schema = "muninn.move_light_command.v1" +)] +pub struct MuninnMoveLightCommandRecord { + #[cultcache(key = 0)] + pub command_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub move_id: String, + #[cultcache(key = 3)] + pub hidraw_path: String, + #[cultcache(key = 4)] + pub colors: Vec, + #[cultcache(key = 5)] + pub durations_ms: Vec, + #[cultcache(key = 6)] + pub repeat_count: u32, + #[cultcache(key = 7)] + pub authority: String, + #[cultcache(key = 8)] + pub state: String, + #[cultcache(key = 9)] + pub detail: String, + #[cultcache(key = 10)] + pub updated_at: String, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache( + type = "muninn.move_hue_program", + schema = "muninn.move_hue_program.v1" +)] +pub struct MuninnMoveHueProgramRecord { + #[cultcache(key = 0)] + pub program_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub mode: String, + #[cultcache(key = 3)] + pub cycle_ms: u64, + #[cultcache(key = 4)] + pub epoch_ns: i64, + #[cultcache(key = 5)] + pub hold_at_ns: i64, + #[cultcache(key = 6)] + pub requested_by: String, + #[cultcache(key = 7)] + pub updated_at: String, + #[cultcache(key = 8, default)] + pub order_mode: String, + #[cultcache(key = 9, default)] + pub transition_percent: u8, + #[cultcache(key = 10, default)] + pub transition_percent_explicit: bool, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "muninn.move_tracker_health", + schema = "muninn.move_tracker_health.v1" +)] +pub struct MuninnMoveTrackerHealthRecord { + #[cultcache(key = 0)] + pub health_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub camera_id: String, + #[cultcache(key = 3)] + pub camera_index: i32, + #[cultcache(key = 4)] + pub state: String, + #[cultcache(key = 5)] + pub camera_name: String, + #[cultcache(key = 6)] + pub camera_api: String, + #[cultcache(key = 7)] + pub width: u32, + #[cultcache(key = 8)] + pub height: u32, + #[cultcache(key = 9)] + pub exposure: f32, + #[cultcache(key = 10)] + pub calibrated_controller_count: u32, + #[cultcache(key = 11)] + pub update_count: u64, + #[cultcache(key = 12)] + pub observation_count: u64, + #[cultcache(key = 13)] + pub latest_observation_count: u32, + #[cultcache(key = 14)] + pub last_observation_at: String, + #[cultcache(key = 15)] + pub detail: String, + #[cultcache(key = 16)] + pub updated_at: String, + #[cultcache(key = 17, default)] + pub image_mean_rgb: Vec, + #[cultcache(key = 18, default)] + pub image_peak_rgb: Vec, + #[cultcache(key = 19, default)] + pub color_evidence_move_ids: Vec, + #[cultcache(key = 20, default)] + pub color_evidence_pixel_counts: Vec, + #[cultcache(key = 21, default)] + pub rejected_stale_count: u64, + #[cultcache(key = 22, default)] + pub rejected_radius_count: u64, + #[cultcache(key = 23, default)] + pub rejected_bounds_count: u64, + #[cultcache(key = 24, default)] + pub rejected_continuity_count: u64, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache( + type = "muninn.move_evidence_transport_health", + schema = "muninn.move_evidence_transport_health.v1" +)] +pub struct MuninnMoveEvidenceTransportHealthRecord { + #[cultcache(key = 0)] + pub health_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub stream_id: String, + #[cultcache(key = 3)] + pub produced_frames: u64, + #[cultcache(key = 4)] + pub local_ring_admissions: u64, + #[cultcache(key = 5)] + pub remote_handoffs: u64, + #[cultcache(key = 6)] + pub remote_sends: u64, + #[cultcache(key = 7)] + pub updated_at: String, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache(type = "muninn.quest_access", schema = "muninn.quest_access.v1")] +pub struct MuninnQuestAccessRecord { + #[cultcache(key = 0)] + pub access_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub serial: String, + #[cultcache(key = 3)] + pub connection_state: String, + #[cultcache(key = 4)] + pub product: String, + #[cultcache(key = 5)] + pub model: String, + #[cultcache(key = 6)] + pub device: String, + #[cultcache(key = 7)] + pub transport_id: String, + #[cultcache(key = 8)] + pub input_stream_id: String, + #[cultcache(key = 9)] + pub pose_stream_id: String, + #[cultcache(key = 10)] + pub video_input_stream_id: String, + #[cultcache(key = 11)] + pub video_input_transport: String, + #[cultcache(key = 12)] + pub state: String, + #[cultcache(key = 13)] + pub detail: String, + #[cultcache(key = 14)] + pub observed_at: String, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "muninn.command_boundary", + schema = "muninn.command_boundary.v1" +)] +pub struct MuninnCommandBoundaryCompatRecord { + #[cultcache(key = 0)] + pub value: Value, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "muninn.transport_profile", + schema = "muninn.transport_profile.v1" +)] +pub struct MuninnTransportProfileCompatRecord { + #[cultcache(key = 0)] + pub value: Value, +} diff --git a/crates/muninn-daemon/Cargo.toml b/crates/muninn-daemon/Cargo.toml index ac34344..c77d6c5 100644 --- a/crates/muninn-daemon/Cargo.toml +++ b/crates/muninn-daemon/Cargo.toml @@ -15,13 +15,14 @@ path = "src/main.rs" [dependencies] anyhow = "1" -cultcache-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c2a9a6e526390808ef195759056fda0b9a55d8a3", package = "cultcache-rs" } -cultmesh-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c2a9a6e526390808ef195759056fda0b9a55d8a3", package = "cultmesh-rs" } -cultnet-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c2a9a6e526390808ef195759056fda0b9a55d8a3", package = "cultnet-rs" } +cultcache-rs = { workspace = true } +cultmesh-rs = { workspace = true } +cultnet-rs = { workspace = true } libc = "0.2" +muninn-contracts = { path = "../muninn-contracts" } muninn-move-tracker = { path = "../muninn-move-tracker" } muninn-psmoveapi-tracker = { path = "../muninn-psmoveapi-tracker", optional = true } -odin-core = { git = "https://github.com/GameCult/Odin.git", rev = "3e96c6c85ca8b89b1bc7b01c1b7744f43111be99" } +odin-core = { workspace = true } rmp-serde = "1.3" serde = { version = "1", features = ["derive"] } serde_bytes = "0.11" diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index cba71f0..0a031d6 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -1,10 +1,11 @@ mod idunn_presence; mod media_packetizer; +mod media_send; -use crate::media_packetizer::{ - AudioPcmStreamSendConfig, AudioPcmStreamSendState, GameCultMediaWireRecord, - MuninnMediaSendPayload, VideoAnnexBStreamSendConfig, VideoAnnexBStreamSendState, - decode_media_wire_record, +use crate::media_packetizer::{AudioPcmStreamSendConfig, VideoAnnexBStreamSendConfig}; +use crate::media_send::{ + MediaSendCore, MediaSendPolicy, clamp_latency_budget_ms, media_intake_channel, + spawn_audio_group_reader, spawn_video_group_reader, }; use anyhow::{Context, Result, anyhow}; use cultmesh_rs::{ @@ -12,32 +13,30 @@ use cultmesh_rs::{ CultMeshSharedMemoryFrameRing, CultMeshStreamBodyTransport, CultMeshStreamCatalog, CultMeshStreamClock, CultMeshStreamDescriptor, CultMeshStreamKind, }; -use cultnet_rs::GameCultMediaReceiverFeedbackRecord; use cultnet_rs::{ - CultNetMessage, CultNetRawDocumentRecord, CultNetRawPayloadEncoding, CultNetRudpServerEvent, - CultNetRudpServerHub, CultNetRudpServerHubOptions, CultNetRudpServerSessionContext, - CultNetRudpSocketTransportConnection, CultNetRudpSocketTransportOptions, CultNetTransportFrame, - CultNetWireContract, GAMECULT_MEDIA_STREAM_ADVERTISEMENT_SCHEMA, + CultNetRudpServerHub, CultNetRudpServerHubOptions, CultNetRudpSocketTransportConnection, + CultNetRudpSocketTransportOptions, + GAMECULT_MEDIA_STREAM_ADVERTISEMENT_SCHEMA, GAMECULT_MEDIA_STREAM_REQUEST_SCHEMA, GAMECULT_RUNTIME_PRESENCE_HEALTH_SCHEMA, GameCultMediaStreamAdvertisementRecord, GameCultMediaStreamRequestRecord, - GameCultRuntimePresenceHealthRecord, decode_cultnet_message_from_slice, - encode_cultnet_message_to_vec, media_stream_request_key, validate_media_stream_request, + GameCultRuntimePresenceHealthRecord, + media_stream_request_key, validate_media_stream_request, }; -#[cfg(feature = "psmoveapi-tracker")] -use odin_core::MuninnMoveTrackerHealthRecord; -use odin_core::{ - EveProviderAdvertisementRecord, EveSurfaceStateRecord, IdunnDaemonHealthRecord, +use muninn_contracts::{ MUNINN_MOVE_HUE_PROGRAM_SCHEMA, MUNINN_OBS_STREAM_CATALOG_SCHEMA, MuninnCaptureStreamCommandRecord, MuninnCaptureStreamRecord, MuninnCommandBoundaryCompatRecord, MuninnHidControllerStateRecord, MuninnMoveControllerStateRecord, MuninnMoveEvidenceTransportHealthRecord, MuninnMoveHueProgramRecord, MuninnMoveIdentityRecord, MuninnMoveLightCommandRecord, MuninnMoveMarkerCandidateRecord, MuninnObsStreamCatalogRecord, - MuninnQuestAccessRecord, MuninnTelemetrySurfaceRecord, MuninnTransportProfileCompatRecord, - OdinDocuments, + MuninnQuestAccessRecord, MuninnRecords, MuninnTelemetrySurfaceRecord, + MuninnTransportProfileCompatRecord, }; +#[cfg(feature = "psmoveapi-tracker")] +use muninn_contracts::MuninnMoveTrackerHealthRecord; +use odin_core::{EveProviderAdvertisementRecord, OdinDocuments}; use serde::{Deserialize, Serialize}; use serde_json::json; -use std::collections::{HashMap, HashSet, VecDeque}; +use std::collections::{HashMap, HashSet}; use std::env; use std::fs; #[cfg(feature = "psmoveapi-tracker")] @@ -52,8 +51,9 @@ use std::process::{Child, Command, Stdio}; use std::sync::{ Arc, Mutex, atomic::{AtomicU64, Ordering}, - mpsc, }; +#[cfg(any(windows, feature = "psmoveapi-tracker"))] +use std::sync::mpsc; use std::thread; use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; @@ -69,10 +69,8 @@ use std::os::windows::ffi::OsStrExt; use windows_sys::Win32::UI::Input::XboxController::{XINPUT_GAMEPAD, XINPUT_STATE, XInputGetState}; const CULTNET_RUDP_PROTOCOL_ID: &str = "cultnet.transport.rudp.v0"; -const IDUNN_HEALTH_RUDP_CONNECTION_ID: u32 = 0x1d0d_0001; const MUNINN_MEDIA_RUDP_CONNECTION_ID: u32 = 0x6d75_0001; const MUNINN_HID_CONTROLLER_RUDP_CONNECTION_ID: u32 = 0x6d75_0005; -const MUNINN_COMMAND_RUDP_CONNECTION_ID: u32 = 0x61e0_0001; const MUNINN_RUDP_MEDIA_PROFILE_ID: &str = "muninn.rudp.low_latency_h264_lan.v1"; const MUNINN_RUDP_MEDIA_VIDEO_BITRATE_KBPS: u32 = 12_000; const MUNINN_RUDP_MEDIA_VBV_FRAME_BUDGETS: u32 = 1; @@ -90,25 +88,14 @@ const MUNINN_RUDP_MEDIA_MAX_FRAGMENT_BYTES: usize = MUNINN_RUDP_IPV4_UDP_PAYLOAD /// nearly every audio fragment was resent before its ack arrived and the /// producer's send loop drowned in retransmits, starving video (measured /// 2026-09-10: 7 frames in 9 s with audio on, 266 without). Audio expires at -/// the assembly deadline anyway; 30 ms costs nothing it can feel. +/// the latency budget anyway; 30 ms costs nothing it can feel. const MUNINN_RUDP_MEDIA_RESEND_DELAY_MS: u64 = 30; -const MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS: u64 = 2_000; +/// What a request that names no latency budget gets, and what the +/// advertisement offers as `default_latency_budget_ms`. It is the request, +/// not this constant, that owns the deadline once one is named. +const MUNINN_RUDP_MEDIA_DEFAULT_LATENCY_BUDGET_MS: u64 = 250; const MUNINN_RUDP_MEDIA_RECEIVER_GAP_WAIT_MS: u64 = 16; -const MUNINN_RUDP_MEDIA_REPAIR_CACHE_CHUNKS: usize = 16_384; -const MUNINN_RUDP_MEDIA_REPAIR_BURST_CHUNKS: usize = 2_048; -const MUNINN_RUDP_MEDIA_REPAIR_INITIAL_CHUNKS_PER_SECOND: usize = 4_096; -const MUNINN_RUDP_MEDIA_REPAIR_MIN_CHUNKS_PER_SECOND: usize = 8; -const MUNINN_RUDP_MEDIA_REPAIR_MAX_CHUNKS_PER_SECOND: usize = 16_384; -const MUNINN_RUDP_MEDIA_REPAIR_ADD_CHUNKS_PER_SECOND: usize = 2_048; -const MUNINN_RUDP_MEDIA_REPAIR_RECOVERY_INTERVAL_MS: u64 = 2_000; -const MUNINN_RUDP_MEDIA_REPAIR_MAX_FEEDBACK_PER_POLL: usize = 32; -const MUNINN_RUDP_MEDIA_REPAIR_MAX_CHUNKS_PER_POLL: usize = 256; const MUNINN_RUDP_MEDIA_SOCKET_BUFFER_BYTES: usize = 16 * 1024 * 1024; -/// A receiver that has said nothing for this long (Ratatoskr pings every -/// second or so) is dropped so its payloads stop being sent into the void. -const MUNINN_RUDP_MEDIA_RECEIVER_TIMEOUT_MS: u64 = 6_000; -const MUNINN_RUDP_MEDIA_SEND_PACE_EVERY_PAYLOADS: usize = 4; -const MUNINN_RUDP_MEDIA_SEND_PACE_SLEEP_US: u64 = 250; const MUNINN_RUDP_ACTIVE_CATALOG_REPUBLISH_MS: u64 = 2_000; const MUNINN_ODIN_PROVIDER_LEASE_REFRESH_SECONDS: u64 = 30; const PS_MOVE_LED_REPORT_LEN: usize = 49; @@ -224,12 +211,10 @@ struct Options { quest_input_stream_id: Option, quest_pose_stream_id: Option, quest_video_input_stream_id: Option, - idunn_rudp_health: Option, odin_cultmesh_uri: Option, hid_controller_rudp_target: Option, hid_controller_rudp_bind: Option, hid_controller_rudp_advertise: Option, - command_rudp_bind: Option, command_rudp_advertise: Option, hid_controller_receipt_retention_seconds: u64, } @@ -275,12 +260,7 @@ struct MuninnRudpMediaProfile { max_fragment_bytes: usize, video_b_frames: u8, video_rc_lookahead: u8, - sender_queue_deadline_ms: u64, sender_resend_delay_ms: u64, - sender_reliable_expire_after_ms: u64, - sender_pace_every_payloads: usize, - sender_pace_sleep_us: u64, - receiver_assembly_deadline_ms: u64, receiver_gap_wait_ms: u64, } @@ -290,13 +270,6 @@ struct MoveStateSource { hidraw_path: String, } -#[derive(Clone, Debug, PartialEq, Eq)] -struct IdunnRudpHealthOptions { - endpoint: SocketAddr, - daemon_id: String, - health_contract: String, -} - #[derive(Clone, Debug, PartialEq, Eq)] struct MuxPlan { command_line: String, @@ -421,7 +394,6 @@ fn serve(options: Options) -> Result<()> { let move_runtime_enabled = serve_should_manage_move_runtime(&options); let mut active_move_states = active_move_state_sources(serve_move_state_sources(&options, move_runtime_enabled)); - start_daemon_health_worker(&options); start_idunn_presence_worker(&options); let mut active_move_marker_cameras = active_move_marker_camera_sources(&options, Arc::clone(&move_hue_program)); @@ -458,7 +430,6 @@ fn serve(options: Options) -> Result<()> { ); } start_move_hue_program_sync_worker(&options, Arc::clone(&move_hue_program)); - start_provider_command_ingress(&options, Arc::clone(&move_hue_program))?; start_odin_provider_lease_worker(&options); let mut answered_requests: HashMap = HashMap::new(); @@ -628,29 +599,10 @@ fn start_idunn_presence_worker(options: &Options) { }); } -fn start_daemon_health_worker(options: &Options) { - if options.idunn_rudp_health.is_none() { - return; - } - let options = options.clone(); - thread::spawn(move || { - loop { - if let Err(error) = run_daemon_health_publisher(&options) { - eprintln!("Muninn Idunn health publish failed: {error:#}"); - } - thread::sleep(Duration::from_secs(5)); - } - }); -} - fn move_hue_program_key(host_id: &str) -> String { format!("muninn:{host_id}:move-hue-program") } -fn move_hue_surface_key(host_id: &str) -> String { - format!("surface:muninn.telemetry.{host_id}.move-hue") -} - fn load_or_initialize_move_hue_program( options: &Options, ) -> Result>> { @@ -760,135 +712,6 @@ fn start_move_hue_program_sync_worker( }); } -fn start_provider_command_ingress( - options: &Options, - runtime_program: Arc>, -) -> Result<()> { - let Some(bind) = options.command_rudp_bind else { - return Ok(()); - }; - let socket = UdpSocket::bind(bind) - .with_context(|| format!("binding Muninn provider command route at {bind}"))?; - socket.set_read_timeout(Some(Duration::from_millis(5)))?; - let options = options.clone(); - thread::spawn(move || { - if let Err(error) = run_provider_command_ingress(socket, options, runtime_program) { - eprintln!("Muninn provider command ingress stopped: {error:#}"); - } - }); - Ok(()) -} - -fn run_provider_command_ingress( - socket: UdpSocket, - options: Options, - runtime_program: Arc>, -) -> Result<()> { - let mut transport = - CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { - media_delivery: None, - runtime_id: format!("muninn-{}-command-ingress", options.host_id), - socket, - mode: cultnet_rs::CultNetRudpSocketMode::Server, - remote_addr: None, - connection_id: MUNINN_COMMAND_RUDP_CONNECTION_ID, - initial_sequence: 1, - resend_delay_ms: 15, - transport_id: Some("muninn-provider-command-rudp".to_string()), - max_payload_bytes: None, - max_fragment_bytes: Some(1200), - max_pending_reliable_packets: Some(64), - media_reliable_expire_after_ms: None, - reconnect_policy: None, - })?; - loop { - if let Some(frame) = transport.receive_once()? - && frame.channel_id == "schema" - { - let message = decode_cultnet_message_from_slice( - &frame.payload, - CultNetWireContract::CultNetSchemaV0, - )?; - if let CultNetMessage::DocumentPutRaw { document, .. } = message { - apply_provider_command_document(&options, &runtime_program, document)?; - } - } - transport.poll_resends()?; - } -} - -fn apply_provider_command_document( - options: &Options, - runtime_program: &Arc>, - document: CultNetRawDocumentRecord, -) -> Result<()> { - if document.schema_id != "gamecult.eve.command.v1" { - return Ok(()); - } - let value: serde_json::Value = match document.payload_encoding { - CultNetRawPayloadEncoding::Messagepack => rmp_serde::from_slice(&document.payload)?, - }; - let command_type = value - .get("command") - .or_else(|| value.get("type")) - .and_then(serde_json::Value::as_str) - .unwrap_or_default(); - if command_type != "muninn.set-move-hue-program" { - return Ok(()); - } - let payload = value - .get("payload") - .filter(|payload| payload.is_object()) - .unwrap_or(&value); - let provider_id = value - .get("providerId") - .and_then(serde_json::Value::as_str) - .unwrap_or_default(); - if provider_id != muninn_provider_id(options) { - return Err(anyhow!( - "Move hue command targets provider {provider_id}, not {}", - muninn_provider_id(options) - )); - } - let mut program = runtime_program - .lock() - .map_err(|_| anyhow!("Move hue runtime program lock is poisoned"))? - .clone(); - if let Some(mode) = payload.get("mode").and_then(serde_json::Value::as_str) { - program.mode = mode.to_string(); - if mode == "hold" { - program.hold_at_ns = timestamp_ns()?; - } - } - if let Some(order) = payload.get("orderMode").and_then(serde_json::Value::as_str) { - program.order_mode = order.to_string(); - } - if let Some(cycle_ms) = payload.get("cycleMs").and_then(serde_json::Value::as_u64) { - program.cycle_ms = cycle_ms; - } - if let Some(value) = payload - .get("transitionPercent") - .and_then(serde_json::Value::as_u64) - { - program.transition_percent = u8::try_from(value) - .map_err(|_| anyhow!("Move hue transitionPercent must be at most 100"))?; - program.transition_percent_explicit = true; - } - program.requested_by = value - .get("publishedBy") - .and_then(serde_json::Value::as_str) - .unwrap_or("eve-command") - .to_string(); - program.updated_at = timestamp()?; - validate_move_hue_program(&program)?; - let key = move_hue_program_key(&options.host_id); - open_node(options, "muninn-provider-command")?.put(&key, &program)?; - *runtime_program - .lock() - .map_err(|_| anyhow!("Move hue runtime program lock is poisoned"))? = program; - Ok(()) -} - const MUNINN_VIDEO_CODECS: [&str; 1] = ["h264"]; const MUNINN_AUDIO_CODECS: [&str; 1] = ["pcm-f32le-interleaved"]; @@ -1488,9 +1311,9 @@ fn command_rudp_video_bitrate_kbps(command: &MuninnCaptureStreamCommandRecord) - fn command_rudp_latency_budget_ms(command: &MuninnCaptureStreamCommandRecord) -> u32 { if command.rudp_latency_budget_ms == 0 { - MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS as u32 + MUNINN_RUDP_MEDIA_DEFAULT_LATENCY_BUDGET_MS as u32 } else { - command.rudp_latency_budget_ms + clamp_latency_budget_ms(command.rudp_latency_budget_ms) } } @@ -1827,7 +1650,14 @@ fn reconcile_move_identity_records( ) -> Result<()> { publish_move_identity_records(node, options, sources)?; publish_bluetooth_move_identity_records(node, options, active)?; + prune_stale_move_identity_records(node, options, sources) +} +fn prune_stale_move_identity_records( + node: &mut cultmesh_rs::CultMeshNode, + options: &Options, + sources: &[MoveStateSource], +) -> Result<()> { let current_ids = current_move_identity_records_from_sources(options, sources)? .into_iter() .map(|identity| identity.identity_id) @@ -2408,7 +2238,8 @@ fn run_rudp_mux_once( let mut audio_sender = None; let result = (|| -> Result { let media_profile = muninn_rudp_media_profile_for_options(options); - let mut hub = open_media_rudp_hub(options, &media_profile)?; + let policy = MediaSendPolicy::from_request(options.rudp_latency_budget_ms); + let hub = open_media_rudp_hub(options, &media_profile, &policy)?; publish_stream( node, options, @@ -2424,10 +2255,10 @@ fn run_rudp_mux_once( )?; let mut last_stream_publish_at = Instant::now(); - let (payload_tx, payload_rx) = mpsc::channel::>(); + let (intake_tx, intake_rx) = media_intake_channel(); video_sender = if let Some(stdout) = video_ffmpeg_stdout { - Some(video_rudp_payload_reader( - payload_tx.clone(), + Some(spawn_video_group_reader( + intake_tx.clone(), stdout, VideoAnnexBStreamSendConfig { stream_id: options.stream_id.clone(), @@ -2438,19 +2269,20 @@ fn run_rudp_mux_once( frame_duration_ticks: video_frame_duration_ticks(options)?, timebase_num: 1, timebase_den: 90_000, - deadline_delay_ticks: rudp_media_deadline_delay_ticks(&media_profile), + deadline_delay_ticks: policy.video_deadline_delay_ticks(), max_payload_bytes: options.media_packet_bytes.max(256), max_pending_bytes: options.media_packet_bytes.max(256) * 4096, source_runtime_id: options.host_id.clone(), source_role: "muninn.rudp.video".to_string(), }, + policy.clone(), )) } else { None }; audio_sender = if let Some(stdout) = audio_ffmpeg_stdout { - Some(audio_rudp_payload_reader( - payload_tx.clone(), + Some(spawn_audio_group_reader( + intake_tx.clone(), stdout, AudioPcmStreamSendConfig { stream_id: options.stream_id.clone(), @@ -2461,7 +2293,7 @@ fn run_rudp_mux_once( packet_duration_ticks: 480, timebase_num: 1, timebase_den: options.audio_sample_rate, - deadline_delay_ticks: rudp_audio_deadline_delay_ticks(options, &media_profile), + deadline_delay_ticks: policy.audio_deadline_delay_ticks(options.audio_sample_rate), channels: options.audio_channels, bytes_per_sample: 4, max_pending_bytes: 480usize @@ -2471,193 +2303,39 @@ fn run_rudp_mux_once( source_runtime_id: options.host_id.clone(), source_role: "muninn.rudp.audio".to_string(), }, + policy.clone(), )) } else { None }; - drop(payload_tx); + drop(intake_tx); - let mut payloads_sent = 0_u64; - let mut payloads_queue_expired = 0_u64; - let mut payloads_send_expired = 0_u64; - let mut receiver_feedback = MuninnRudpReceiverFeedbackStats::default(); - let mut handled_keyframe_requests = 0_u64; - let mut repair_cache = - RecentVideoChunkRepairCache::new(MUNINN_RUDP_MEDIA_REPAIR_CACHE_CHUNKS); - let mut repair_budget = MuninnRudpRepairBudget::new( - MUNINN_RUDP_MEDIA_REPAIR_INITIAL_CHUNKS_PER_SECOND, - MUNINN_RUDP_MEDIA_REPAIR_BURST_CHUNKS, - ); - let mut video_send_pacer = MuninnRudpMediaSendPacer::new( - media_profile.sender_pace_every_payloads, - Duration::from_micros(media_profile.sender_pace_sleep_us), - ); - let mut audio_send_pacer = MuninnRudpMediaSendPacer::new(0, Duration::ZERO); - let mut pending_payloads = PendingMuninnMediaSendQueues::default(); - let mut payload_channel_disconnected = false; + let mut core = MediaSendCore::new(hub, &policy); loop { - if pending_payloads.is_empty() && !payload_channel_disconnected { - payload_channel_disconnected = receive_pending_media_payloads( - &payload_rx, - &mut pending_payloads, - Duration::from_millis(5), - )?; - } else if !payload_channel_disconnected { - payload_channel_disconnected = - drain_available_media_payloads(&payload_rx, &mut pending_payloads)?; - } - - if let Some(queued) = pending_payloads.pop_next() { - if media_payload_queue_age_exceeded( - queued.queued_at, - Instant::now(), - Duration::from_millis(media_profile.sender_queue_deadline_ms), - ) { - payloads_queue_expired += 1; - let payloads_dropped = payloads_queue_expired + payloads_send_expired; - // A stale payload is already unsendable. Do not make - // queue recovery slower by polling feedback, sending - // repairs, and polling retransmits once for every stale - // item. Normal live-send and idle paths service those - // controls as soon as the expired backlog is drained. - if payloads_dropped == 1 || payloads_dropped % 300 == 0 { - let expired = reliable_packets_expired(&hub); - eprintln!( - "{}", - rudp_media_progress_detail( - payloads_sent, - payloads_dropped, - payloads_queue_expired, - payloads_send_expired, - expired, - hub.sessions().len(), - &receiver_feedback - ) - ); - } - continue; - } - - let payload_len = queued.payload.payload.len(); - let send_pacer = match queued.kind { - QueuedMuninnMediaKind::Video => &mut video_send_pacer, - QueuedMuninnMediaKind::Audio => &mut audio_send_pacer, - }; - let sent = send_rudp_media_payload_with_backpressure( - &mut hub, - None, - queued.payload.clone(), - queued.queued_at, - Duration::from_millis(media_profile.sender_queue_deadline_ms), - send_pacer, - )?; - if !sent { - payloads_send_expired += 1; - continue; - } - let payloads_dropped = payloads_queue_expired + payloads_send_expired; - if queued.kind == QueuedMuninnMediaKind::Video { - repair_cache.remember(&queued.payload)?; - } - poll_rudp_media_receiver_feedback( - &mut hub, - &mut receiver_feedback, - &repair_cache, - &mut repair_budget, - &media_profile, - &mut video_send_pacer, - payloads_dropped, - )?; - record_receiver_keyframe_pressure( - &receiver_feedback, - &mut handled_keyframe_requests, - ); - poll_rudp_resends_with_backpressure(&mut hub)?; - republish_running_stream_if_due( - node, - options, - plan, - supervisor_pid, - video_ffmpeg - .as_ref() - .map(Child::id) - .or_else(|| audio_ffmpeg.as_ref().map(Child::id)) - .unwrap_or(supervisor_pid), - restart_count, - &mut last_stream_publish_at, - )?; - payloads_sent += 1; - if payloads_sent == 1 || payloads_sent % 900 == 0 { - let expired = reliable_packets_expired(&hub); - eprintln!( - "{}; pending_audio={} pending_video={}; latest {:?} payload was {payload_len} bytes.", - rudp_media_progress_detail( - payloads_sent, - payloads_dropped, - payloads_queue_expired, - payloads_send_expired, - expired, - hub.sessions().len(), - &receiver_feedback - ), - pending_payloads.audio_len(), - pending_payloads.video_len(), - queued.kind - ); - } - continue; - } - - if payload_channel_disconnected { - let expired = reliable_packets_expired(&hub); - let payloads_dropped = payloads_queue_expired + payloads_send_expired; + core.intake(&intake_rx, Duration::from_millis(5))?; + if core.send_next(Instant::now())? { + core.service_control(Instant::now())?; + } else if core.finished() { break Ok(RudpMuxRestart { - detail: format!( - "encoder stdout ended; {}", - rudp_media_progress_detail( - payloads_sent, - payloads_dropped, - payloads_queue_expired, - payloads_send_expired, - expired, - hub.sessions().len(), - &receiver_feedback - ) - ), + detail: format!("encoder stdout ended; {}", core.progress_detail()), delay: default_rudp_mux_restart_delay(restart_count), }); + } else { + core.service_control(Instant::now())?; } - - { - let payloads_dropped = payloads_queue_expired + payloads_send_expired; - poll_rudp_media_receiver_feedback( - &mut hub, - &mut receiver_feedback, - &repair_cache, - &mut repair_budget, - &media_profile, - &mut video_send_pacer, - payloads_dropped, - )?; - record_receiver_keyframe_pressure( - &receiver_feedback, - &mut handled_keyframe_requests, - ); - poll_rudp_resends_with_backpressure(&mut hub)?; - republish_running_stream_if_due( - node, - options, - plan, - supervisor_pid, - video_ffmpeg - .as_ref() - .map(Child::id) - .or_else(|| audio_ffmpeg.as_ref().map(Child::id)) - .unwrap_or(supervisor_pid), - restart_count, - &mut last_stream_publish_at, - )?; - } + republish_running_stream_if_due( + node, + options, + plan, + supervisor_pid, + video_ffmpeg + .as_ref() + .map(Child::id) + .or_else(|| audio_ffmpeg.as_ref().map(Child::id)) + .unwrap_or(supervisor_pid), + restart_count, + &mut last_stream_publish_at, + )?; } })(); @@ -2685,506 +2363,17 @@ fn run_rudp_mux_once( result } -struct QueuedMuninnMediaSendPayload { - payload: MuninnMediaSendPayload, - queued_at: Instant, - kind: QueuedMuninnMediaKind, -} - -#[derive(Clone, Copy, Debug, PartialEq, Eq)] -enum QueuedMuninnMediaKind { - Video, - Audio, -} - -#[derive(Default)] -struct PendingMuninnMediaSendQueues { - audio: VecDeque, - video: VecDeque, -} - -impl PendingMuninnMediaSendQueues { - fn push(&mut self, payload: QueuedMuninnMediaSendPayload) { - match payload.kind { - QueuedMuninnMediaKind::Audio => self.audio.push_back(payload), - QueuedMuninnMediaKind::Video => self.video.push_back(payload), - } - } - - fn pop_next(&mut self) -> Option { - self.audio.pop_front().or_else(|| self.video.pop_front()) - } - - fn is_empty(&self) -> bool { - self.audio.is_empty() && self.video.is_empty() - } - - fn audio_len(&self) -> usize { - self.audio.len() - } - - fn video_len(&self) -> usize { - self.video.len() - } -} - -#[derive(Clone, Debug, Default, PartialEq, Eq)] -struct MuninnRudpReceiverFeedbackStats { - feedback_records: u64, - requested_keyframes: u64, - late_frames: u64, - missing_video_chunks: u64, - repaired_video_chunks: u64, - deferred_repair_chunks: u64, - repair_chunks_per_second: usize, - highest_decodable_frame_id: Option, -} - -#[derive(Debug)] -struct MuninnRudpRepairBudget { - chunks_per_second: usize, - min_chunks_per_second: usize, - max_chunks_per_second: usize, - add_chunks_per_second: usize, - recovery_interval: Duration, - max_available_chunks: usize, - available_chunks: usize, - last_refill_at: Instant, - last_rate_adjust_at: Instant, - last_queue_dropped: u64, -} - -impl MuninnRudpRepairBudget { - fn new(chunks_per_second: usize, max_available_chunks: usize) -> Self { - let now = Instant::now(); - let max_available_chunks = max_available_chunks.max(1); - Self { - chunks_per_second: chunks_per_second.max(1), - min_chunks_per_second: MUNINN_RUDP_MEDIA_REPAIR_MIN_CHUNKS_PER_SECOND, - max_chunks_per_second: MUNINN_RUDP_MEDIA_REPAIR_MAX_CHUNKS_PER_SECOND, - add_chunks_per_second: MUNINN_RUDP_MEDIA_REPAIR_ADD_CHUNKS_PER_SECOND, - recovery_interval: Duration::from_millis(MUNINN_RUDP_MEDIA_REPAIR_RECOVERY_INTERVAL_MS), - max_available_chunks, - available_chunks: max_available_chunks, - last_refill_at: now, - last_rate_adjust_at: now, - last_queue_dropped: 0, - } - } - - fn chunks_per_second(&self) -> usize { - self.chunks_per_second - } - - fn take(&mut self, requested_chunks: usize, now: Instant, queue_dropped: u64) -> usize { - self.adjust_rate(now, queue_dropped, requested_chunks); - self.refill(now); - let allowed = requested_chunks.min(self.available_chunks); - self.available_chunks -= allowed; - allowed - } - - fn adjust_rate(&mut self, now: Instant, queue_dropped: u64, requested_chunks: usize) { - if queue_dropped > self.last_queue_dropped { - self.chunks_per_second = (self.chunks_per_second / 2).max(self.min_chunks_per_second); - self.available_chunks = self.available_chunks.min(self.chunks_per_second); - self.last_queue_dropped = queue_dropped; - self.last_rate_adjust_at = now; - return; - } - self.last_queue_dropped = queue_dropped; - if requested_chunks == 0 - || now.saturating_duration_since(self.last_rate_adjust_at) < self.recovery_interval - { - return; - } - if self.chunks_per_second < self.max_chunks_per_second { - self.chunks_per_second = self - .chunks_per_second - .saturating_add(self.add_chunks_per_second) - .min(self.max_chunks_per_second); - self.last_rate_adjust_at = now; - } - } - - fn refill(&mut self, now: Instant) { - let elapsed_ms = now - .saturating_duration_since(self.last_refill_at) - .as_millis() as usize; - if elapsed_ms == 0 { - return; - } - let refill_chunks = elapsed_ms.saturating_mul(self.chunks_per_second) / 1_000; - if refill_chunks == 0 { - return; - } - self.available_chunks = self - .available_chunks - .saturating_add(refill_chunks) - .min(self.max_available_chunks); - self.last_refill_at = now; - } -} - -#[derive(Debug)] -struct RecentVideoChunkRepairCache { - max_entries: usize, - order: VecDeque, - entries: HashMap, -} - -impl RecentVideoChunkRepairCache { - fn new(max_entries: usize) -> Self { - Self { - max_entries, - order: VecDeque::new(), - entries: HashMap::new(), - } - } - - fn remember(&mut self, payload: &MuninnMediaSendPayload) -> Result<()> { - let Some(key) = video_repair_cache_key_from_payload(payload)? else { - return Ok(()); - }; - if self.entries.contains_key(&key) { - self.entries.insert(key, payload.clone()); - return Ok(()); - } - self.order.push_back(key.clone()); - self.entries.insert(key, payload.clone()); - while self.entries.len() > self.max_entries { - let Some(expired) = self.order.pop_front() else { - break; - }; - self.entries.remove(&expired); - } - Ok(()) - } - - fn repair_payloads_for_feedback( - &self, - feedback: &GameCultMediaReceiverFeedbackRecord, - ) -> Vec { - feedback - .missing_video_chunk_keys - .iter() - .filter_map(|chunk_key| { - self.entries - .get(&video_repair_cache_key( - &feedback.stream_id, - &feedback.session_id, - chunk_key, - )) - .cloned() - }) - .collect() - } -} - -fn video_repair_cache_key(stream_id: &str, session_id: &str, chunk_key: &str) -> String { - format!("{stream_id}:{session_id}:video:{chunk_key}") -} - -fn video_repair_cache_key_from_payload(payload: &MuninnMediaSendPayload) -> Result> { - if payload.channel_id != crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL { - return Ok(None); - } - let GameCultMediaWireRecord::Video(video) = decode_media_wire_record(&payload.payload)? else { - return Ok(None); - }; - Ok(Some(video_repair_cache_key( - &video.stream_id, - &video.session_id, - &crate::media_packetizer::video_chunk_feedback_key(video.frame_id, video.chunk_index), - ))) -} - -fn queue_muninn_media_payload( - tx: &mpsc::Sender>, - payload: MuninnMediaSendPayload, - kind: QueuedMuninnMediaKind, -) -> Result<()> { - tx.send(Ok(QueuedMuninnMediaSendPayload { - payload, - queued_at: Instant::now(), - kind, - })) - .context("queueing typed Muninn media payload") -} - -fn receive_pending_media_payloads( - rx: &mpsc::Receiver>, - pending: &mut PendingMuninnMediaSendQueues, - timeout: Duration, -) -> Result { - match rx.recv_timeout(timeout) { - Ok(Ok(payload)) => { - pending.push(payload); - drain_available_media_payloads(rx, pending) - } - Ok(Err(error)) => Err(error), - Err(mpsc::RecvTimeoutError::Timeout) => Ok(false), - Err(mpsc::RecvTimeoutError::Disconnected) => Ok(true), - } -} - -fn drain_available_media_payloads( - rx: &mpsc::Receiver>, - pending: &mut PendingMuninnMediaSendQueues, -) -> Result { - loop { - match rx.try_recv() { - Ok(Ok(payload)) => pending.push(payload), - Ok(Err(error)) => return Err(error), - Err(mpsc::TryRecvError::Empty) => return Ok(false), - Err(mpsc::TryRecvError::Disconnected) => return Ok(true), - } - } -} - -fn media_payload_queue_age_exceeded(queued_at: Instant, now: Instant, max_age: Duration) -> bool { - now.saturating_duration_since(queued_at) > max_age -} - -fn poll_rudp_resends_with_backpressure(hub: &mut CultNetRudpServerHub) -> Result<()> { - match hub.poll_resends() { - Ok(()) => Ok(()), - Err(error) if is_would_block_error(&error) => Ok(()), - Err(error) => Err(error).context("polling Muninn RUDP media resends"), - } -} - -/// To one receiver, or with `None` to every receiver attached right now. A -/// payload with nobody to send it to is not a failure; the progress line -/// says how many receivers there are. -fn send_rudp_media_payload_with_backpressure( - hub: &mut CultNetRudpServerHub, - receiver: Option<&CultNetRudpServerSessionContext>, - payload: MuninnMediaSendPayload, - queued_at: Instant, - max_age: Duration, - send_pacer: &mut MuninnRudpMediaSendPacer, -) -> Result { - let receivers = match receiver { - Some(receiver) => vec![receiver.clone()], - None => hub.sessions(), - }; - for receiver in &receivers { - loop { - match hub.send(receiver, payload.channel_id, payload.payload.clone()) { - Ok(()) => break, - Err(error) if is_would_block_error(&error) => { - if media_payload_queue_age_exceeded(queued_at, Instant::now(), max_age) { - return Ok(false); - } - poll_rudp_resends_with_backpressure(hub)?; - thread::sleep(Duration::from_millis(1)); - } - Err(error) => { - return Err(error) - .context("sending typed Muninn media payload over RUDP media"); - } - } - } - } - send_pacer.observe_sent_payload(); - Ok(true) -} - -#[derive(Debug)] -struct MuninnRudpMediaSendPacer { - payloads_since_pause: usize, - every_payloads: usize, - sleep_for: Duration, -} - -impl MuninnRudpMediaSendPacer { - fn new(every_payloads: usize, sleep_for: Duration) -> Self { - Self { - payloads_since_pause: 0, - every_payloads: every_payloads.max(1), - sleep_for, - } - } - - fn observe_sent_payload(&mut self) { - if self.sleep_for.is_zero() { - return; - } - self.payloads_since_pause = self.payloads_since_pause.saturating_add(1); - if self.payloads_since_pause < self.every_payloads { - return; - } - self.payloads_since_pause = 0; - thread::sleep(self.sleep_for); - } -} - -fn is_would_block_error(error: &anyhow::Error) -> bool { - error.chain().any(|cause| { - cause - .downcast_ref::() - .is_some_and(|io| io.kind() == ErrorKind::WouldBlock) - || cause.to_string().contains("os error 10035") - }) -} - fn default_rudp_mux_restart_delay(restart_count: u32) -> Duration { Duration::from_secs((2 + restart_count).min(30) as u64) } -fn record_receiver_keyframe_pressure( - receiver_feedback: &MuninnRudpReceiverFeedbackStats, - handled_keyframe_requests: &mut u64, -) { - if receiver_feedback.requested_keyframes <= *handled_keyframe_requests { - return; - } - *handled_keyframe_requests = receiver_feedback.requested_keyframes; - eprintln!( - "Muninn RUDP receiver requested a fresh keyframe; continuing current low-latency encoder session until explicit encoder control exists." - ); -} - -fn rudp_media_progress_detail( - sent: u64, - queue_dropped: u64, - queue_expired: u64, - send_expired: u64, - reliable_expired: u64, - receivers: usize, - receiver_feedback: &MuninnRudpReceiverFeedbackStats, -) -> String { - format!( - "Muninn RUDP media progress: receivers={receivers} sent={sent} queue_dropped={queue_dropped} queue_expired={queue_expired} send_expired={send_expired} reliable_expired={reliable_expired} receiver_feedback={} receiver_keyframes={} receiver_late_frames={} receiver_missing_chunks={} receiver_repaired_chunks={} receiver_deferred_repairs={} repair_rate={} receiver_highest_decodable={}", - receiver_feedback.feedback_records, - receiver_feedback.requested_keyframes, - receiver_feedback.late_frames, - receiver_feedback.missing_video_chunks, - receiver_feedback.repaired_video_chunks, - receiver_feedback.deferred_repair_chunks, - receiver_feedback.repair_chunks_per_second, - receiver_feedback - .highest_decodable_frame_id - .map(|frame_id| frame_id.to_string()) - .unwrap_or_else(|| "none".to_string()) - ) -} - -fn poll_rudp_media_receiver_feedback( - hub: &mut CultNetRudpServerHub, - stats: &mut MuninnRudpReceiverFeedbackStats, - repair_cache: &RecentVideoChunkRepairCache, - repair_budget: &mut MuninnRudpRepairBudget, - media_profile: &MuninnRudpMediaProfile, - send_pacer: &mut MuninnRudpMediaSendPacer, - queue_dropped: u64, -) -> Result<()> { - for gone in hub.remove_timed_out_sessions(MUNINN_RUDP_MEDIA_RECEIVER_TIMEOUT_MS) { - eprintln!( - "Muninn media receiver {} at {} went silent and was dropped.", - String::from_utf8_lossy(&gone.connect_payload), - gone.remote_addr - ); - } - let mut feedback_processed = 0_usize; - loop { - match hub.receive_event_once() { - Ok(Some(CultNetRudpServerEvent::Connected { session })) => { - eprintln!( - "Muninn media receiver {} attached from {}.", - String::from_utf8_lossy(&session.connect_payload), - session.remote_addr - ); - } - Ok(Some(CultNetRudpServerEvent::Disconnected { session, reason })) => { - eprintln!( - "Muninn media receiver {} at {} disconnected: {}.", - String::from_utf8_lossy(&session.connect_payload), - session.remote_addr, - String::from_utf8_lossy(&reason) - ); - } - Ok(Some(CultNetRudpServerEvent::Frame { session, frame })) => { - if feedback_processed >= MUNINN_RUDP_MEDIA_REPAIR_MAX_FEEDBACK_PER_POLL { - return Ok(()); - } - feedback_processed += 1; - let repair_payloads = - record_rudp_media_receiver_feedback(&frame, stats, repair_cache)?; - let requested_repairs = repair_payloads.len(); - let poll_limited_repairs = - requested_repairs.min(MUNINN_RUDP_MEDIA_REPAIR_MAX_CHUNKS_PER_POLL); - let allowed_repairs = - repair_budget.take(poll_limited_repairs, Instant::now(), queue_dropped); - stats.repair_chunks_per_second = repair_budget.chunks_per_second(); - stats.deferred_repair_chunks = stats - .deferred_repair_chunks - .saturating_add(requested_repairs.saturating_sub(allowed_repairs) as u64); - // Repairs go back to the receiver that asked, not to everyone. - for payload in repair_payloads.into_iter().take(allowed_repairs) { - if send_rudp_media_payload_with_backpressure( - hub, - Some(&session), - payload, - Instant::now(), - Duration::from_millis(media_profile.sender_queue_deadline_ms), - send_pacer, - )? { - stats.repaired_video_chunks = stats.repaired_video_chunks.saturating_add(1); - } - } - } - Ok(Some(CultNetRudpServerEvent::Pong { .. })) => {} - Ok(None) => return Ok(()), - Err(error) if is_would_block_error(&error) => return Ok(()), - Err(error) => return Err(error).context("polling Muninn RUDP media feedback"), - } - } -} - -fn record_rudp_media_receiver_feedback( - frame: &CultNetTransportFrame, - stats: &mut MuninnRudpReceiverFeedbackStats, - repair_cache: &RecentVideoChunkRepairCache, -) -> Result> { - if frame.channel_id != crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL { - return Ok(Vec::new()); - } - - let GameCultMediaWireRecord::Feedback(feedback) = decode_media_wire_record(&frame.payload)? - else { - return Ok(Vec::new()); - }; - - let repair_payloads = repair_cache.repair_payloads_for_feedback(&feedback); - stats.feedback_records = stats.feedback_records.saturating_add(1); - if feedback.requested_keyframe { - stats.requested_keyframes = stats.requested_keyframes.saturating_add(1); - } - stats.late_frames = stats - .late_frames - .saturating_add(feedback.late_frame_ids.len() as u64); - stats.missing_video_chunks = stats - .missing_video_chunks - .saturating_add(feedback.missing_video_chunk_keys.len() as u64); - if let Some(frame_id) = feedback.highest_decodable_frame_id { - stats.highest_decodable_frame_id = Some( - stats - .highest_decodable_frame_id - .map(|current| current.max(frame_id)) - .unwrap_or(frame_id), - ); - } - Ok(repair_payloads) -} - /// Muninn listens for receivers here. It used to dial a receiver that had /// to open a port for it; that put a firewall rule on every viewer's /// machine. The producer is the host that serves, so the producer listens. fn open_media_rudp_hub( options: &Options, media_profile: &MuninnRudpMediaProfile, + policy: &MediaSendPolicy, ) -> Result { let socket = UdpSocket::bind(options.media_rudp_bind).with_context(|| { format!( @@ -3197,7 +2386,11 @@ fn open_media_rudp_hub( socket .set_nonblocking(true) .context("setting Muninn media RUDP listener nonblocking")?; - let hub = CultNetRudpServerHub::new(muninn_media_rudp_hub_options(socket, media_profile))?; + let hub = CultNetRudpServerHub::new(muninn_media_rudp_hub_options( + socket, + media_profile, + policy, + ))?; eprintln!( "Muninn media RUDP listening at {} for receivers dialling connection {:#x}.", hub.local_addr()?, @@ -3219,110 +2412,21 @@ fn configure_media_rudp_socket_buffers(socket: &UdpSocket) -> Result<()> { /// One session per receiver carries both legs: video lossy under parity on /// the media channel, audio reliable on its own channel and given up on -/// past the receiver's assembly deadline. +/// past the request's latency budget. fn muninn_media_rudp_hub_options( socket: UdpSocket, media_profile: &MuninnRudpMediaProfile, + policy: &MediaSendPolicy, ) -> CultNetRudpServerHubOptions { let mut options = CultNetRudpServerHubOptions::new("muninn-media", socket, MUNINN_MEDIA_RUDP_CONNECTION_ID); options.resend_delay_ms = media_profile.sender_resend_delay_ms; options.max_fragment_bytes = Some(media_profile.max_fragment_bytes as u32); options.media_delivery = Some(cultnet_rs::CultNetTransportDelivery::Unreliable); - options.media_reliable_expire_after_ms = Some(media_profile.receiver_assembly_deadline_ms); + options.media_reliable_expire_after_ms = Some(policy.latency_budget_ms()); options } -fn reliable_packets_expired(hub: &CultNetRudpServerHub) -> u64 { - hub.stats().reliable_packets_expired -} - -fn video_rudp_payload_reader( - tx: mpsc::Sender>, - mut reader: R, - config: VideoAnnexBStreamSendConfig, -) -> thread::JoinHandle<()> -where - R: Read + Send + 'static, -{ - thread::spawn(move || { - if let Err(error) = read_video_rudp_payloads(&tx, &mut reader, config) { - let _ = tx.send(Err(error)); - } - }) -} - -fn audio_rudp_payload_reader( - tx: mpsc::Sender>, - mut reader: R, - config: AudioPcmStreamSendConfig, -) -> thread::JoinHandle<()> -where - R: Read + Send + 'static, -{ - thread::spawn(move || { - if let Err(error) = read_audio_rudp_payloads(&tx, &mut reader, config) { - let _ = tx.send(Err(error)); - } - }) -} - -fn read_video_rudp_payloads( - tx: &mpsc::Sender>, - reader: &mut R, - config: VideoAnnexBStreamSendConfig, -) -> Result<()> -where - R: Read, -{ - let mut sender = VideoAnnexBStreamSendState::new(config)?; - let mut buffer = vec![0_u8; 64 * 1024]; - loop { - let read = reader - .read(&mut buffer) - .context("reading encoded Annex B video from ffmpeg stdout")?; - if read == 0 { - for payload in sender.finish(×tamp()?)? { - queue_muninn_media_payload(tx, payload, QueuedMuninnMediaKind::Video) - .context("queueing final typed video media payload")?; - } - return Ok(()); - } - for payload in sender.push(×tamp()?, &buffer[..read])? { - queue_muninn_media_payload(tx, payload, QueuedMuninnMediaKind::Video) - .context("queueing typed video media payload")?; - } - } -} - -fn read_audio_rudp_payloads( - tx: &mpsc::Sender>, - reader: &mut R, - config: AudioPcmStreamSendConfig, -) -> Result<()> -where - R: Read, -{ - let mut sender = AudioPcmStreamSendState::new(config)?; - let mut buffer = vec![0_u8; 16 * 1024]; - loop { - let read = reader - .read(&mut buffer) - .context("reading PCM audio from ffmpeg stdout")?; - if read == 0 { - for payload in sender.finish(×tamp()?)? { - queue_muninn_media_payload(tx, payload, QueuedMuninnMediaKind::Audio) - .context("queueing final typed audio media payload")?; - } - return Ok(()); - } - for payload in sender.push(×tamp()?, &buffer[..read])? { - queue_muninn_media_payload(tx, payload, QueuedMuninnMediaKind::Audio) - .context("queueing typed audio media payload")?; - } - } -} - fn video_frame_duration_ticks(options: &Options) -> Result { if options.framerate == 0 { return Err(anyhow!("framerate must be greater than zero")); @@ -3330,32 +2434,6 @@ fn video_frame_duration_ticks(options: &Options) -> Result { Ok((90_000_u32 / options.framerate).max(1)) } -fn rudp_media_deadline_delay_ticks(media_profile: &MuninnRudpMediaProfile) -> i64 { - i64::try_from( - media_profile - .receiver_assembly_deadline_ms - .saturating_mul(90), - ) - .unwrap_or(i64::MAX) -} - -fn rudp_audio_deadline_delay_ticks( - options: &Options, - media_profile: &MuninnRudpMediaProfile, -) -> i64 { - if options.audio_sample_rate == 0 { - return i64::from(1_024); - } - i64::try_from( - media_profile - .receiver_assembly_deadline_ms - .saturating_mul(u64::from(options.audio_sample_rate)) - / 1_000, - ) - .unwrap_or(i64::MAX) - .max(i64::from(1_024)) -} - fn publish_surface( node: &mut cultmesh_rs::CultMeshNode, options: &Options, @@ -3415,155 +2493,6 @@ fn publish_surface( }; node.put("latest", &record)?; node.put(&record.surface_id, &record)?; - publish_move_hue_eve_surface(node, options)?; - Ok(()) -} - -fn publish_move_hue_eve_surface( - node: &mut cultmesh_rs::CultMeshNode, - options: &Options, -) -> Result<()> { - let program_key = move_hue_program_key(&options.host_id); - let program = node - .get::(&program_key)? - .unwrap_or_else(|| bootstrap_move_hue_program(options)); - let provider_id = muninn_provider_id(options); - let surface_key = move_hue_surface_key(&options.host_id); - let action = |id: &str, - label: &str, - mode: Option<&str>, - order_mode: Option<&str>, - cycle_ms: Option, - transition_percent: Option| { - json!({ - "id": format!("{provider_id}.move-hue.{id}"), - "kind": "card", - "props": { - "title": label, - "commandId": "muninn.set-move-hue-program", - "action": { - "type": "muninn.set-move-hue-program", - "providerId": provider_id, - "programId": program_key, - "schema": MUNINN_MOVE_HUE_PROGRAM_SCHEMA, - "mode": mode, - "orderMode": order_mode, - "cycleMs": cycle_ms, - "transitionPercent": transition_percent - } - }, - "children": [] - }) - }; - let surface = EveSurfaceStateRecord { - provider_id: provider_id.clone(), - title: format!("Muninn {} Move Hue Program", options.host_id), - version: SystemTime::now() - .duration_since(UNIX_EPOCH) - .unwrap_or_default() - .as_millis() as i64, - updated_at: timestamp()?, - surface: json!({ - "schema": "gamecult.eve.surface.v1", - "id": format!("{provider_id}.move-hue.surface"), - "title": "Move Hue Program", - "root": { - "id": format!("{provider_id}.move-hue.root"), - "kind": "dashboard", - "props": { - "title": "Move Hue Program", - "summary": format!("{} / {} / {} ms / {}% transition", program.mode, program.order_mode, program.cycle_ms, effective_transition_percent(&program)) - }, - "children": [ - { - "id": format!("{provider_id}.move-hue.state"), - "kind": "pane", - "props": { "title": "State" }, - "children": [ - { "id": format!("{provider_id}.move-hue.state.mode"), "kind": "text", "props": { "text": format!("mode: {}", program.mode) } }, - { "id": format!("{provider_id}.move-hue.state.order"), "kind": "text", "props": { "text": format!("order: {}", program.order_mode) } }, - { "id": format!("{provider_id}.move-hue.state.rate"), "kind": "text", "props": { "text": format!("cycle: {} ms", program.cycle_ms) } }, - { "id": format!("{provider_id}.move-hue.state.transition"), "kind": "text", "props": { "text": format!("transition: {}%", effective_transition_percent(&program)) } } - ] - }, - { - "id": format!("{provider_id}.move-hue.mode"), - "kind": "pane", - "props": { "title": "Mode" }, - "children": [ - action("mode-animated", "Animate", Some("animated"), None, None, None), - action("mode-hold", "Hold Current Colors", Some("hold"), None, None, None), - action("mode-static", "Static Palette", Some("static"), None, None, None) - ] - }, - { - "id": format!("{provider_id}.move-hue.order"), - "kind": "pane", - "props": { "title": "Update Order" }, - "children": [ - action("order-descending", "Descending", None, Some("descending"), None, None), - action("order-ascending", "Ascending", None, Some("ascending"), None, None), - action("order-bounce", "Bounce", None, Some("bounce"), None, None), - action("order-rotating", "Rotating Lead", None, Some("rotating-lead"), None, None), - action("order-golden", "Golden Permutation", None, Some("golden-permutation"), None, None) - ] - }, - { - "id": format!("{provider_id}.move-hue.rate"), - "kind": "pane", - "props": { "title": "Cycle Rate" }, - "children": [ - action("rate-500", "2 Hz", None, None, Some(500), None), - action("rate-1000", "1 Hz", None, None, Some(1000), None), - action("rate-2000", "0.5 Hz", None, None, Some(2000), None) - ] - }, - { - "id": format!("{provider_id}.move-hue.transition"), - "kind": "pane", - "props": { "title": "Transition Duration" }, - "children": [ - action("transition-0", "Off", None, None, None, Some(0)), - action("transition-10", "10%", None, None, None, Some(10)), - action("transition-25", "25%", None, None, None, Some(25)), - action("transition-50", "50%", None, None, None, Some(50)), - action("transition-75", "75%", None, None, None, Some(75)), - action("transition-100", "100%", None, None, None, Some(100)) - ] - } - ] - } - }), - }; - node.put(&surface_key, &surface)?; - if let Some(target) = resolve_odin_cultmesh_uri(options) { - let _ = node.publish_document_to_rudp_catalog( - &program_key, - &program, - CultMeshRudpDocumentPublishOptions { - target, - runtime_id: muninn_daemon_id(options), - source_role: Some("muninn.move-hue-program-state".to_string()), - tags: vec!["muninn".to_string(), "move-hue-program".to_string()], - flush_timeout: Duration::from_millis(300), - resend_delay_ms: 15, - ..CultMeshRudpDocumentPublishOptions::default() - }, - ); - let _ = node.publish_document_to_rudp_catalog( - &surface_key, - &surface, - CultMeshRudpDocumentPublishOptions { - target, - runtime_id: muninn_daemon_id(options), - source_role: Some("muninn.move-hue-eve-surface".to_string()), - tags: vec!["muninn".to_string(), "eve-surface".to_string()], - flush_timeout: Duration::from_millis(300), - resend_delay_ms: 15, - ..CultMeshRudpDocumentPublishOptions::default() - }, - ); - } Ok(()) } @@ -3606,43 +2535,18 @@ fn publish_runtime_boundary_records( .as_ref() .map(|command| json!([command])) .unwrap_or_else(|| json!([])); - let current_transport = if options.idunn_rudp_health.is_some() { - "daemon-published-rudp-health + daemon-owned-cultcache-telemetry-store" - } else { - "daemon-owned-cultcache-telemetry-store + missing-rudp-health-publication" - }; - let transport_state = if options.idunn_rudp_health.is_some() { - "rudp-health-and-provider-store-live" - } else { - "cultcache-provider-store-only" - }; + let current_transport = "daemon-owned-cultcache-telemetry-store"; + let transport_state = "cultcache-provider-store-only"; let hid_controller_endpoint = options.hid_controller_rudp_bind.map(|bind| { options .hid_controller_rudp_advertise .clone() .unwrap_or_else(|| bind.to_string()) }); - let mut provider_routes = vec![json!({ + let provider_routes = vec![json!({ "transport": "cultcache-store", "address": options.store_path.display().to_string() })]; - if let Some(bind) = options.command_rudp_bind { - let address = options - .command_rudp_advertise - .clone() - .unwrap_or_else(|| bind.to_string()); - provider_routes.push(json!({ - "id": "muninn.provider.command", - "role": "muninn provider command ingress", - "uri": format!("cultmesh://{address}/muninn/{}/commands", options.host_id), - "transport": CULTNET_RUDP_PROTOCOL_ID, - "address": address, - "connectionId": MUNINN_COMMAND_RUDP_CONNECTION_ID, - "channel": "schema", - "schema": "gamecult.eve.command.v1", - "tags": ["muninn", "command", "provider-owned"] - })); - } let hid_controller_devices_snake = live_move_sources .iter() .map(|source| { @@ -3754,18 +2658,6 @@ fn publish_runtime_boundary_records( "state_store": store_path, "log_root": log_root, "lifecycle_authority": "idunn-supervisor-command", - "health_publication": options.idunn_rudp_health.as_ref().map(|idunn| json!({ - "contract": idunn.health_contract, - "transport": CULTNET_RUDP_PROTOCOL_ID, - "publication_source": "daemon-published", - "endpoint": idunn.endpoint.to_string(), - "state_owner": "Muninn serve process" - })).unwrap_or_else(|| json!({ - "contract": serde_json::Value::Null, - "transport": "unconfigured", - "publication_source": "missing-daemon-publication", - "state_owner": "Muninn local store" - })), "commands": [ { "command": "muninn.capture_stream_command", @@ -3813,7 +2705,7 @@ fn publish_runtime_boundary_records( "target_transport": CULTNET_RUDP_PROTOCOL_ID, "current_transport": current_transport, "state": transport_state, - "health_contract": options.idunn_rudp_health.as_ref().map(|idunn| idunn.health_contract.clone()), + "health_contract": serde_json::Value::Null, "provider_advertisement_schema": "gamecult.eve.provider_advertisement.v1", "command_boundary_schema": "muninn.command_boundary.v1", "telemetry_surface_schema": "muninn.telemetry_surface.v1", @@ -3838,10 +2730,8 @@ fn publish_runtime_boundary_records( "video_gop_frames": muninn_rudp_video_gop_frames(options), "video_rate_control": "cbr", "video_rc_lookahead": media_profile.video_rc_lookahead, - "sender_queue_deadline_ms": media_profile.sender_queue_deadline_ms, "sender_resend_delay_ms": media_profile.sender_resend_delay_ms, - "sender_reliable_expire_after_ms": media_profile.sender_reliable_expire_after_ms, - "receiver_assembly_deadline_ms": media_profile.receiver_assembly_deadline_ms, + "latency_budget_ms": options.rudp_latency_budget_ms, "receiver_gap_wait_ms": media_profile.receiver_gap_wait_ms, "late_media_policy": "drop expired queued media; do not repair frames outside the latency budget", "recovery": "fixed quarter-second IDR budget with receiver feedback pressure telemetry" @@ -3877,12 +2767,6 @@ fn publish_runtime_boundary_records( "endpoints": provider_endpoints, "inputStreams": provider_input_streams, "routes": provider_routes, - "surfaces": [{ - "surfaceId": format!("{provider_id}.move-hue.surface"), - "surfaceKind": "gamecult.eve.surface_state.v1", - "recordRef": move_hue_surface_key(&options.host_id), - "title": "Move Hue Program" - }], "commandSurface": { "commandBoundaryId": command_boundary_key, "transportProfileId": transport_profile_key @@ -3953,9 +2837,6 @@ fn muninn_provider_id(options: &Options) -> String { } fn muninn_daemon_id(options: &Options) -> String { - if let Some(idunn) = options.idunn_rudp_health.as_ref() { - return idunn.daemon_id.clone(); - } match options.host_id.as_str() { "raven" => "muninn".to_string(), "starfire" => "starfire-muninn".to_string(), @@ -9360,31 +8241,9 @@ fn quest_access_status(options: Options) -> Result<()> { } fn health_check(options: &Options) -> Result<()> { - let observed_at = idunn_timestamp()?; - let result = evaluate_health(options); - let (state, detail) = match &result { - Ok(detail) => ("active", detail.clone()), - Err(error) => ("failed", error.to_string()), - }; - if let Some(idunn) = options.idunn_rudp_health.as_ref() { - let publish_result = publish_idunn_rudp_health(idunn, state, &detail, &observed_at); - if let Err(publish_error) = publish_result { - return match result { - Ok(_) => Err(publish_error).context("publishing Muninn health to Idunn RUDP"), - Err(health_error) => Err(anyhow!( - "{health_error}; also failed to publish Muninn health to Idunn RUDP: {publish_error}" - )), - }; - } - } - - match result { - Ok(detail) => { - println!("{detail}"); - Ok(()) - } - Err(error) => Err(error), - } + let detail = evaluate_health(options)?; + println!("{detail}"); + Ok(()) } fn evaluate_health(options: &Options) -> Result { @@ -9436,22 +8295,6 @@ fn evaluate_health_from_node( )) } -fn publish_idunn_rudp_health( - options: &IdunnRudpHealthOptions, - state: &str, - detail: &str, - observed_at: &str, -) -> Result<()> { - let mut transport = connect_idunn_rudp_health(options)?; - transport - .send( - "schema", - idunn_health_payload(options, state, detail, observed_at)?, - ) - .with_context(|| format!("sending Idunn health to {}", options.endpoint))?; - Ok(()) -} - fn smootherstep(value: f64) -> f64 { let t = value.clamp(0.0, 1.0); t * t * t * (t * (t * 6.0 - 15.0) + 10.0) @@ -9462,104 +8305,6 @@ fn wrapped_hue_lerp(source: f64, target: f64, amount: f64) -> f64 { (source + delta * amount).rem_euclid(1.0) } -fn run_daemon_health_publisher(options: &Options) -> Result<()> { - let idunn = options - .idunn_rudp_health - .as_ref() - .context("Muninn daemon health publisher requires Idunn RUDP options")?; - let mut transport = connect_idunn_rudp_health(idunn)?; - let cadence = Duration::from_secs(options.interval_seconds.unwrap_or(15).max(1)); - let mut next_publish_at = Instant::now(); - loop { - if Instant::now() >= next_publish_at { - let observed_at = idunn_timestamp()?; - let (state, detail) = match evaluate_health(options) { - Ok(detail) => ("active", detail), - Err(error) => ("failed", error.to_string()), - }; - transport - .send( - "schema", - idunn_health_payload(idunn, state, &detail, &observed_at)?, - ) - .with_context(|| format!("sending Idunn health to {}", idunn.endpoint))?; - next_publish_at = Instant::now() + cadence; - } - let _ = transport.receive_once()?; - transport.poll_resends()?; - } -} - -fn idunn_health_payload( - options: &IdunnRudpHealthOptions, - state: &str, - detail: &str, - observed_at: &str, -) -> Result> { - let health = IdunnDaemonHealthRecord { - daemon_id: options.daemon_id.clone(), - state: state.to_string(), - detail: detail.to_string(), - observed_at: observed_at.to_string(), - health_contract: options.health_contract.clone(), - publication_source: "daemon-published".to_string(), - transport: CULTNET_RUDP_PROTOCOL_ID.to_string(), - }; - let message = CultNetMessage::DocumentPutRaw { - message_id: format!( - "muninn-health:{}:{}", - options.daemon_id, - observed_at.replace(':', "-") - ), - document: CultNetRawDocumentRecord { - schema_id: "idunn.daemon_health".to_string(), - record_key: options.daemon_id.clone(), - stored_at: observed_at.to_string(), - payload_encoding: CultNetRawPayloadEncoding::Messagepack, - payload: rmp_serde::to_vec(&health).context("encoding Idunn daemon health")?, - source_runtime_id: Some("muninn-daemon".to_string()), - source_agent_id: None, - source_role: Some("daemon-health-publisher".to_string()), - tags: Some(vec![CULTNET_RUDP_PROTOCOL_ID.to_string()]), - }, - }; - encode_cultnet_message_to_vec(&message, CultNetWireContract::CultNetSchemaV0) - .context("encoding Idunn health CultNet message") -} - -fn connect_idunn_rudp_health( - options: &IdunnRudpHealthOptions, -) -> Result { - let bind_address = if options.endpoint.is_ipv4() { - "0.0.0.0:0" - } else { - "[::]:0" - }; - let socket = UdpSocket::bind(bind_address) - .with_context(|| format!("binding Muninn RUDP sender at {bind_address}"))?; - socket.set_read_timeout(Some(Duration::from_secs(1)))?; - let mut transport = - CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions::client( - "muninn-daemon", - socket, - options.endpoint, - IDUNN_HEALTH_RUDP_CONNECTION_ID, - ))?; - transport.connect(Vec::new())?; - let deadline = Instant::now() + Duration::from_secs(2); - while !transport.connected() { - let _ = transport.receive_once()?; - transport.poll_resends()?; - if Instant::now() >= deadline { - return Err(anyhow!( - "timed out connecting Muninn RUDP sender to {}", - options.endpoint - )); - } - } - Ok(transport) -} - fn verify_move_sources_fresh(options: &Options, node: &cultmesh_rs::CultMeshNode) -> Result<()> { let move_state_sources = serve_move_state_sources(options, serve_should_manage_move_runtime(options)); @@ -10254,24 +8999,12 @@ fn muninn_rudp_media_profile() -> MuninnRudpMediaProfile { } fn muninn_rudp_media_profile_for_options(options: &Options) -> MuninnRudpMediaProfile { - muninn_rudp_media_profile_for_bitrate_and_latency( - options.rudp_video_bitrate_kbps, - options.rudp_latency_budget_ms, - ) + muninn_rudp_media_profile_for_bitrate(options.rudp_video_bitrate_kbps) } +/// Encoder and wire shape. It carries no deadline: the request's latency +/// budget reaches the sender only through `MediaSendPolicy`. fn muninn_rudp_media_profile_for_bitrate(video_bitrate_kbps: u32) -> MuninnRudpMediaProfile { - muninn_rudp_media_profile_for_bitrate_and_latency( - video_bitrate_kbps, - MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS as u32, - ) -} - -fn muninn_rudp_media_profile_for_bitrate_and_latency( - video_bitrate_kbps: u32, - latency_budget_ms: u32, -) -> MuninnRudpMediaProfile { - let latency_budget_ms = u64::from(latency_budget_ms.max(1)); MuninnRudpMediaProfile { profile_id: MUNINN_RUDP_MEDIA_PROFILE_ID, video_codec: "h264", @@ -10283,12 +9016,7 @@ fn muninn_rudp_media_profile_for_bitrate_and_latency( max_fragment_bytes: MUNINN_RUDP_MEDIA_MAX_FRAGMENT_BYTES, video_b_frames: 0, video_rc_lookahead: 0, - sender_queue_deadline_ms: latency_budget_ms, sender_resend_delay_ms: MUNINN_RUDP_MEDIA_RESEND_DELAY_MS, - sender_reliable_expire_after_ms: latency_budget_ms, - sender_pace_every_payloads: MUNINN_RUDP_MEDIA_SEND_PACE_EVERY_PAYLOADS, - sender_pace_sleep_us: MUNINN_RUDP_MEDIA_SEND_PACE_SLEEP_US, - receiver_assembly_deadline_ms: latency_budget_ms, receiver_gap_wait_ms: MUNINN_RUDP_MEDIA_RECEIVER_GAP_WAIT_MS, } } @@ -10489,15 +9217,21 @@ fn ensure_state_dirs(options: &Options) -> Result<()> { Ok(()) } -/// Odin's document set plus the producer-agnostic media stream contract. -/// Muninn advertises through the latter and takes requests through it; the -/// former is what the rest of its state still speaks. +/// Odin's document set, Muninn's own records, and the producer-agnostic media +/// stream contract. Today Odin's document set (odin-core) is registered first +/// and carries identical `muninn.*` type names and schema ids, so +/// `MuninnRecords` registers the same strings again and binds nothing new; +/// cultcache errors at startup if the two ever diverge. Odin's copies are to be +/// deleted, at which point `muninn-contracts` becomes the sole owner of every +/// `muninn.*` binding. The registration stays so that deletion changes nothing +/// here. #[derive(Clone, Copy, Debug, Default)] struct MuninnDocuments; impl cultmesh_rs::CultMeshDocumentSet for MuninnDocuments { fn register_cache(&self, cache: &mut cultcache_rs::CultCache) -> Result<()> { OdinDocuments.register_cache(cache)?; + MuninnRecords.register_cache(cache)?; cache.register_entry_type::()?; cache.register_entry_type::()?; cache.register_entry_type::()?; @@ -10506,6 +9240,7 @@ impl cultmesh_rs::CultMeshDocumentSet for MuninnDocuments { fn register_documents(&self, registry: &mut cultnet_rs::CultNetDocumentRegistry) -> Result<()> { OdinDocuments.register_documents(registry)?; + MuninnRecords.register_documents(registry)?; registry.register( cultnet_rs::CultNetDocumentBinding::for_entry_with_schema_id::< GameCultMediaStreamAdvertisementRecord, @@ -10564,7 +9299,7 @@ impl Options { media_transport: MediaTransport::Rudp, media_packet_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES, rudp_video_bitrate_kbps: MUNINN_RUDP_MEDIA_VIDEO_BITRATE_KBPS, - rudp_latency_budget_ms: MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS as u32, + rudp_latency_budget_ms: MUNINN_RUDP_MEDIA_DEFAULT_LATENCY_BUDGET_MS as u32, width: 1920, height: 1080, framerate: 30, @@ -10616,20 +9351,15 @@ impl Options { quest_input_stream_id: None, quest_pose_stream_id: None, quest_video_input_stream_id: None, - idunn_rudp_health: None, odin_cultmesh_uri: Some("cultmesh://odin/rendezvous/provider-catalog".to_string()), hid_controller_rudp_target: None, hid_controller_rudp_bind: None, hid_controller_rudp_advertise: None, - command_rudp_bind: None, command_rudp_advertise: None, hid_controller_receipt_retention_seconds: 3_600, }; let mut args = args.peekable(); - let mut idunn_rudp_health_endpoint = None; - let mut idunn_daemon_id = None; - let mut idunn_health_contract = None; while let Some(arg) = args.next() { match arg.as_str() { "serve" => options.mode = Mode::Serve, @@ -10707,7 +9437,7 @@ impl Options { "--rudp-latency-budget-ms must be greater than zero" )); } - options.rudp_latency_budget_ms = latency_budget; + options.rudp_latency_budget_ms = clamp_latency_budget_ms(latency_budget); } "--width" => options.width = take_value(&mut args, "--width")?.parse()?, "--height" => options.height = take_value(&mut args, "--height")?.parse()?, @@ -10866,19 +9596,6 @@ impl Options { options.quest_video_input_stream_id = Some(take_value(&mut args, "--quest-video-input-stream")?) } - "--idunn-rudp-health" => { - idunn_rudp_health_endpoint = Some( - take_value(&mut args, "--idunn-rudp-health")? - .parse() - .context("--idunn-rudp-health must be a socket address")?, - ) - } - "--idunn-daemon" => { - idunn_daemon_id = Some(take_value(&mut args, "--idunn-daemon")?) - } - "--idunn-health-contract" => { - idunn_health_contract = Some(take_value(&mut args, "--idunn-health-contract")?) - } "--odin-cultmesh-rudp" => { let _ = take_value(&mut args, "--odin-cultmesh-rudp")?; return Err(anyhow!( @@ -10907,11 +9624,10 @@ impl Options { Some(take_value(&mut args, "--hid-controller-rudp-advertise")?) } "--command-rudp-bind" => { - options.command_rudp_bind = Some( - take_value(&mut args, "--command-rudp-bind")? - .parse() - .context("--command-rudp-bind must be a socket address")?, - ) + let _ = take_value(&mut args, "--command-rudp-bind")?; + return Err(anyhow!( + "--command-rudp-bind has been removed; the Eve command ingress was quarantined (tag parked/muninn-eve-surface)" + )); } "--command-rudp-advertise" => { options.command_rudp_advertise = @@ -11066,32 +9782,11 @@ impl Options { options.quest_video_input_stream_id.as_ref(), ), ("--move-host", options.move_host_address.as_ref()), - ("--idunn-daemon", idunn_daemon_id.as_ref()), - ("--idunn-health-contract", idunn_health_contract.as_ref()), ] { if value.is_some_and(|value| value.trim().is_empty()) { return Err(anyhow!("{name} must be non-empty")); } } - options.idunn_rudp_health = match ( - idunn_rudp_health_endpoint, - idunn_daemon_id, - idunn_health_contract, - ) { - (None, None, None) => None, - (Some(endpoint), Some(daemon_id), Some(health_contract)) => { - Some(IdunnRudpHealthOptions { - endpoint, - daemon_id, - health_contract, - }) - } - _ => { - return Err(anyhow!( - "--idunn-rudp-health, --idunn-daemon, and --idunn-health-contract must be provided together" - )); - } - }; Ok(options) } } @@ -11109,14 +9804,6 @@ fn timestamp() -> Result { Ok(format!("unix-{seconds}")) } -fn idunn_timestamp() -> Result { - let seconds = SystemTime::now() - .duration_since(UNIX_EPOCH) - .context("system clock is before Unix epoch")? - .as_secs(); - Ok(format!("unix:{seconds}")) -} - fn timestamp_ns() -> Result { let nanos = SystemTime::now() .duration_since(UNIX_EPOCH) @@ -11185,7 +9872,7 @@ fn parse_move_marker_camera_source(value: &str) -> Result &'static str { - "Usage: muninn [serve|activate|request-stream|capture-stream-status|obs-catalog-status|request-move-light|move-light-status|move-identity-status|move-source-status|move-state-status|claim-move-host|quest-access-status] [--store ] [--activate-store ] [--stream-action ] [--target-host ] [--media-transport ] [--media-rudp-bind ] [--media-rudp-advertise ] [--media-packet-bytes ] [--rudp-video-bitrate-kbps ] [--rudp-latency-budget-ms ] [--video-source ] [--audio-source ] [--audio-source-id ] [--no-video] [--no-audio] [--loopback-script ] [--ffmpeg ] [--odin-cultmesh-uri ] [--move-state =] [--move-marker-camera =] [--move-psmoveapi-tracker] [--move-tracker-exposure-milli <0..1000>] [--move-marker-width ] [--move-marker-height ] [--move-marker-fps ] [--move-host ] [--move-evidence-stream ] [--move-evidence-verse ] [--move-evidence-ring-slots ] [--move-evidence-slot-bytes ] [--move-evidence-snapshot ] [--quest-adb] [--quest-serial ] [--quest-input-stream ] [--quest-pose-stream ] [--quest-video-input-stream ] [--idunn-rudp-health ] [--idunn-daemon ] [--idunn-health-contract ] [--dry-run] [--health]\n\nMuninn is Odin's portable telemetry Verse assembler. serve publishes cheap typed telemetry affordances, optional Quest USB access surfaces, and the explicitly configured Move runtime; when serve receives --move-state, --move-marker-camera, --move-host, or --move-evidence-stream it may publish source-local Move controller state, source-local optical marker candidates, typed Move identity records, a CultMesh Move evidence stream, optionally write a latest one-copy Move proof evidence snapshot for Mimir field capture/replay, and keep USB-attached PS Moves claimed to that explicit Bluetooth host; --move-psmoveapi-tracker delegates camera exposure and optical extraction to the reference PSMoveAPI backend while Muninn retains stable-ID light actuation; serve consumes typed capture stream commands from its provider-owned activation store and owns the local ffmpeg/loopback activation child lifecycle, listens for media receivers on --media-rudp-bind and advertises that endpoint (--media-rudp-advertise when the bind address is not reachable as-is), and publishes its discovery advertisement through --odin-cultmesh-uri; activate starts an explicitly requested local CultNet RUDP stream as a daemon child that serves every receiver dialling --media-rudp-bind; request-stream discovers the provider through Odin and sends its typed command to that provider; obs-catalog-status pulls Odin-owned muninn.obs_stream_catalog discovery into the local compatibility store for OBS; capture-stream-status reads typed capture stream command receipts; use --no-video or --no-audio to request one leg over the CultNet RUDP media lane; request-move-light publishes a typed Move light command for Muninn serve to execute; move-light-status reads typed command receipts; move-identity-status reads typed Move identity records; move-source-status prints live Move source discovery; move-state-status reads typed controller-state records; claim-move-host assigns USB-attached PS Moves to a Bluetooth host; quest-access-status reads typed Quest access state. In --health mode, the Idunn RUDP flags publish the same typed daemon health document to Idunn for explicit diagnostics." + "Usage: muninn [serve|activate|request-stream|capture-stream-status|obs-catalog-status|request-move-light|move-light-status|move-identity-status|move-source-status|move-state-status|claim-move-host|quest-access-status] [--store ] [--activate-store ] [--stream-action ] [--target-host ] [--media-transport ] [--media-rudp-bind ] [--media-rudp-advertise ] [--media-packet-bytes ] [--rudp-video-bitrate-kbps ] [--rudp-latency-budget-ms ] [--video-source ] [--audio-source ] [--audio-source-id ] [--no-video] [--no-audio] [--loopback-script ] [--ffmpeg ] [--odin-cultmesh-uri ] [--move-state =] [--move-marker-camera =] [--move-psmoveapi-tracker] [--move-tracker-exposure-milli <0..1000>] [--move-marker-width ] [--move-marker-height ] [--move-marker-fps ] [--move-host ] [--move-evidence-stream ] [--move-evidence-verse ] [--move-evidence-ring-slots ] [--move-evidence-slot-bytes ] [--move-evidence-snapshot ] [--quest-adb] [--quest-serial ] [--quest-input-stream ] [--quest-pose-stream ] [--quest-video-input-stream ] [--dry-run] [--health]\n\nMuninn is Odin's portable telemetry Verse assembler. serve publishes cheap typed telemetry affordances, optional Quest USB access surfaces, and the explicitly configured Move runtime; when serve receives --move-state, --move-marker-camera, --move-host, or --move-evidence-stream it may publish source-local Move controller state, source-local optical marker candidates, typed Move identity records, a CultMesh Move evidence stream, optionally write a latest one-copy Move proof evidence snapshot for Mimir field capture/replay, and keep USB-attached PS Moves claimed to that explicit Bluetooth host; --move-psmoveapi-tracker delegates camera exposure and optical extraction to the reference PSMoveAPI backend while Muninn retains stable-ID light actuation; serve consumes typed capture stream commands from its provider-owned activation store and owns the local ffmpeg/loopback activation child lifecycle, listens for media receivers on --media-rudp-bind and advertises that endpoint (--media-rudp-advertise when the bind address is not reachable as-is), and publishes its discovery advertisement through --odin-cultmesh-uri; activate starts an explicitly requested local CultNet RUDP stream as a daemon child that serves every receiver dialling --media-rudp-bind; request-stream discovers the provider through Odin and sends its typed command to that provider; obs-catalog-status pulls Odin-owned muninn.obs_stream_catalog discovery into the local compatibility store for OBS; capture-stream-status reads typed capture stream command receipts; use --no-video or --no-audio to request one leg over the CultNet RUDP media lane; request-move-light publishes a typed Move light command for Muninn serve to execute; move-light-status reads typed command receipts; move-identity-status reads typed Move identity records; move-source-status prints live Move source discovery; move-state-status reads typed controller-state records; claim-move-host assigns USB-attached PS Moves to a Bluetooth host; quest-access-status reads typed Quest access state." } fn parse_move_state_source(value: &str) -> Result { @@ -11208,6 +9895,7 @@ fn parse_move_state_source(value: &str) -> Result { #[cfg(test)] mod tests { use super::*; + use crate::media_send::{MediaKind, QueuedMediaGroup}; fn media_stream_request() -> GameCultMediaStreamRequestRecord { GameCultMediaStreamRequestRecord { @@ -11653,39 +10341,20 @@ mod tests { } #[test] - fn health_idunn_rudp_options_are_explicit_bundle() { - let options = Options::parse( - [ - "--health", - "--idunn-rudp-health", - "127.0.0.1:17870", - "--idunn-daemon", - "starfire-muninn", - "--idunn-health-contract", - "muninn.cultnet-rudp-local-telemetry-and-quest-access", - ] - .into_iter() - .map(String::from), - ) - .unwrap(); - - let idunn = options.idunn_rudp_health.unwrap(); - assert_eq!(options.mode, Mode::Health); - assert_eq!(idunn.endpoint, "127.0.0.1:17870".parse().unwrap()); - assert_eq!(idunn.daemon_id, "starfire-muninn"); - assert_eq!( - idunn.health_contract, - "muninn.cultnet-rudp-local-telemetry-and-quest-access" - ); - - let error = Options::parse( - ["--health", "--idunn-rudp-health", "127.0.0.1:17870"] - .into_iter() - .map(String::from), - ) - .unwrap_err() - .to_string(); - assert!(error.contains("must be provided together")); + fn retired_idunn_rudp_health_flags_are_unknown_arguments() { + for flag in [ + "--idunn-rudp-health", + "--idunn-daemon", + "--idunn-health-contract", + ] { + let error = Options::parse(["--health", flag, "127.0.0.1:17870"].into_iter().map(String::from)) + .unwrap_err() + .to_string(); + assert!( + error.contains(&format!("unknown Muninn argument: {flag}")), + "{flag} must be rejected, got: {error}" + ); + } } #[test] @@ -11773,67 +10442,6 @@ mod tests { assert!(error.contains("request-stream requires --odin-cultmesh-uri")); } - #[test] - fn idunn_rudp_health_publisher_sends_raw_daemon_health_document() { - let receiver = UdpSocket::bind("127.0.0.1:0").unwrap(); - receiver - .set_read_timeout(Some(Duration::from_secs(1))) - .unwrap(); - let receiver_addr = receiver.local_addr().unwrap(); - let handle = thread::spawn(move || { - let mut transport = CultNetRudpSocketTransportConnection::new( - CultNetRudpSocketTransportOptions::server( - "idunn-test", - receiver, - IDUNN_HEALTH_RUDP_CONNECTION_ID, - ), - ) - .unwrap(); - let deadline = Instant::now() + Duration::from_secs(2); - loop { - if let Some(frame) = transport.receive_once().unwrap() { - return cultnet_rs::decode_cultnet_message_from_slice( - &frame.payload, - CultNetWireContract::CultNetSchemaV0, - ) - .unwrap(); - } - transport.poll_resends().unwrap(); - if Instant::now() >= deadline { - panic!("timed out waiting for Muninn RUDP health frame"); - } - } - }); - let options = IdunnRudpHealthOptions { - endpoint: receiver_addr, - daemon_id: "starfire-muninn".to_string(), - health_contract: "muninn.cultnet-rudp-local-telemetry-and-quest-access".to_string(), - }; - - publish_idunn_rudp_health(&options, "active", "Muninn healthy", "unix:100").unwrap(); - - let message = handle.join().unwrap(); - let CultNetMessage::DocumentPutRaw { document, .. } = message else { - panic!("expected raw document put"); - }; - assert_eq!(document.schema_id, "idunn.daemon_health"); - assert_eq!(document.record_key, "starfire-muninn"); - assert_eq!( - document.payload_encoding, - CultNetRawPayloadEncoding::Messagepack - ); - let health: IdunnDaemonHealthRecord = rmp_serde::from_slice(&document.payload).unwrap(); - assert_eq!(health.daemon_id, "starfire-muninn"); - assert_eq!(health.state, "active"); - assert_eq!( - health.health_contract, - "muninn.cultnet-rudp-local-telemetry-and-quest-access" - ); - assert_eq!(health.publication_source, "daemon-published"); - assert_eq!(health.transport, CULTNET_RUDP_PROTOCOL_ID); - assert_eq!(health.observed_at, "unix:100"); - } - #[test] fn repeated_capture_stream_start_is_equivalent_when_media_shape_matches() { let options = Options::parse( @@ -12344,33 +10952,40 @@ mod tests { assert_eq!(muninn_rudp_video_gop_frames(&sixty_fps), 15); } + fn send_single_access_unit( + config: crate::media_packetizer::VideoAnnexBStreamSendConfig, + access_unit: &[u8], + ) -> Vec { + let mut sender = crate::media_packetizer::VideoAnnexBStreamSendState::new(config).unwrap(); + let mut groups = sender.push("2026-06-18T00:00:00Z", access_unit).unwrap(); + groups.extend(sender.finish("2026-06-18T00:00:00Z").unwrap()); + groups.into_iter().flatten().collect() + } + #[test] fn default_rudp_media_packet_size_keeps_late_typed_video_wire_under_udp_mtu() { let mut access_unit = Vec::new(); access_unit.extend_from_slice(&[0, 0, 0, 1, 0x65]); access_unit.resize(MUNINN_RUDP_MEDIA_PACKET_BYTES, 0x80); - let payloads = crate::media_packetizer::video_annex_b_stream_send_payloads( - crate::media_packetizer::VideoAnnexBStreamWireOptions { - packetize: crate::media_packetizer::VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "h264", - first_frame_id: 1_000_000, - first_pts_ticks: 3_000_000_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_800, - max_payload_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES, - }, - stored_at: "2026-06-18T00:00:00Z", - source_runtime_id: "muninn-test", - source_role: "media-test", + let payloads = send_single_access_unit( + crate::media_packetizer::VideoAnnexBStreamSendConfig { + stream_id: "muninn.raven.av.rudp".to_string(), + session_id: "session-1".to_string(), + codec: "h264".to_string(), + first_frame_id: 1_000_000, + first_pts_ticks: 3_000_000_000, + frame_duration_ticks: 3_000, + timebase_num: 1, + timebase_den: 90_000, + deadline_delay_ticks: 1_800, + max_payload_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES, + max_pending_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES * 2, + source_runtime_id: "muninn-test".to_string(), + source_role: "media-test".to_string(), }, &access_unit, - ) - .unwrap(); + ); assert_eq!(payloads.len(), 1); assert!( @@ -12392,27 +11007,24 @@ mod tests { access_unit.extend_from_slice(&[0, 0, 0, 1, 0x65]); access_unit.resize(MUNINN_RUDP_MEDIA_PACKET_BYTES * 64, 0x80); - let payloads = crate::media_packetizer::video_annex_b_stream_send_payloads( - crate::media_packetizer::VideoAnnexBStreamWireOptions { - packetize: crate::media_packetizer::VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "raven:2026-06-19T14-56-23Z:video", - codec: "h264", - first_frame_id: 1_000_000, - first_pts_ticks: 3_000_000_000, - frame_duration_ticks: 1_500, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_500, - max_payload_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES, - }, - stored_at: "2026-06-19T14:56:23Z", - source_runtime_id: "raven", - source_role: "muninn.rudp.video", + let payloads = send_single_access_unit( + crate::media_packetizer::VideoAnnexBStreamSendConfig { + stream_id: "muninn.raven.av.rudp".to_string(), + session_id: "raven:2026-06-19T14-56-23Z:video".to_string(), + codec: "h264".to_string(), + first_frame_id: 1_000_000, + first_pts_ticks: 3_000_000_000, + frame_duration_ticks: 1_500, + timebase_num: 1, + timebase_den: 90_000, + deadline_delay_ticks: 1_500, + max_payload_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES, + max_pending_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES * 65, + source_runtime_id: "raven".to_string(), + source_role: "muninn.rudp.video".to_string(), }, &access_unit, - ) - .unwrap(); + ); assert!(payloads.len() > 1); let largest = payloads @@ -12430,7 +11042,8 @@ mod tests { fn rudp_media_hub_serves_lossy_video_and_reliable_audio_on_one_session() { let socket = UdpSocket::bind("127.0.0.1:0").unwrap(); let profile = muninn_rudp_media_profile(); - let options = muninn_media_rudp_hub_options(socket, &profile); + let policy = MediaSendPolicy::from_request(137); + let options = muninn_media_rudp_hub_options(socket, &profile, &policy); assert_eq!(options.runtime_id, "muninn-media"); assert_eq!(options.connection_id, MUNINN_MEDIA_RUDP_CONNECTION_ID); assert_eq!(options.resend_delay_ms, MUNINN_RUDP_MEDIA_RESEND_DELAY_MS); @@ -12457,7 +11070,7 @@ mod tests { ); assert_eq!( channel("audio").reliable_expire_after_ms, - Some(profile.receiver_assembly_deadline_ms), + Some(policy.latency_budget_ms()), "audio older than the receiver's deadline is not worth a retransmit" ); } @@ -12492,59 +11105,8 @@ mod tests { assert_eq!(args.last().map(String::as_str), Some("pipe:1")); } - #[test] - fn media_payload_queue_deadline_is_strictly_bounded() { - let queued_at = Instant::now(); - let deadline = Duration::from_millis(muninn_rudp_media_profile().sender_queue_deadline_ms); - - assert!(!media_payload_queue_age_exceeded( - queued_at, - queued_at + deadline, - deadline - )); - assert!(media_payload_queue_age_exceeded( - queued_at, - queued_at + deadline + Duration::from_millis(1), - deadline - )); - } - - #[test] - fn rudp_media_sender_prioritizes_pending_audio_over_video() { - let queued_at = Instant::now(); - let mut pending = PendingMuninnMediaSendQueues::default(); - pending.push(QueuedMuninnMediaSendPayload { - payload: MuninnMediaSendPayload { - channel_id: crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL, - payload: vec![0x76], - }, - queued_at, - kind: QueuedMuninnMediaKind::Video, - }); - pending.push(QueuedMuninnMediaSendPayload { - payload: MuninnMediaSendPayload { - channel_id: crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL, - payload: vec![0x61], - }, - queued_at, - kind: QueuedMuninnMediaKind::Audio, - }); - - let first = pending.pop_next().expect("audio payload should be queued"); - let second = pending - .pop_next() - .expect("video payload should remain queued"); - - assert_eq!(first.kind, QueuedMuninnMediaKind::Audio); - assert_eq!(first.payload.payload, vec![0x61]); - assert_eq!(second.kind, QueuedMuninnMediaKind::Video); - assert_eq!(second.payload.payload, vec![0x76]); - assert!(pending.is_empty()); - } - - #[test] - fn rudp_latency_budget_owns_sender_and_record_deadlines() { - let options = Options::parse( + fn options_with_latency_budget(budget_ms: &str) -> Options { + Options::parse( [ "activate", "--media-transport", @@ -12556,210 +11118,121 @@ mod tests { "--audio-sample-rate", "48000", "--rudp-latency-budget-ms", - "2000", + budget_ms, ] .into_iter() .map(String::from), ) - .unwrap(); - let profile = muninn_rudp_media_profile_for_options(&options); + .unwrap() + } - assert_eq!(profile.sender_queue_deadline_ms, 2000); - assert_eq!(profile.sender_reliable_expire_after_ms, 2000); + #[test] + fn the_requests_latency_budget_owns_queue_hub_expiry_and_record_deadlines() { + // Two budgets, both different from the default and from each other, so + // a clamp, an offset or a fallback to the default is visible at one of + // them. + for (budget_ms, video_ticks, audio_ticks) in [(137_u32, 12_330_i64, 6_576_i64), (613, 55_170, 29_424)] + { + let options = options_with_latency_budget(&budget_ms.to_string()); + let policy = MediaSendPolicy::from_request(options.rudp_latency_budget_ms); + let produced_at = Instant::now(); + let group = QueuedMediaGroup::new(MediaKind::Video, produced_at, &policy, Vec::new()); + + assert_eq!( + group.deadline - produced_at, + Duration::from_millis(u64::from(budget_ms)) + ); + assert_eq!(policy.video_deadline_delay_ticks(), video_ticks); + assert_eq!( + policy.audio_deadline_delay_ticks(options.audio_sample_rate), + audio_ticks + ); + let hub_options = muninn_media_rudp_hub_options( + UdpSocket::bind("127.0.0.1:0").unwrap(), + &muninn_rudp_media_profile_for_options(&options), + &policy, + ); + assert_eq!( + hub_options.media_reliable_expire_after_ms, + Some(u64::from(budget_ms)) + ); + } assert_eq!( - profile.sender_pace_every_payloads, - MUNINN_RUDP_MEDIA_SEND_PACE_EVERY_PAYLOADS - ); - assert_eq!( - profile.sender_pace_sleep_us, - MUNINN_RUDP_MEDIA_SEND_PACE_SLEEP_US - ); - assert_eq!(profile.receiver_assembly_deadline_ms, 2000); - assert_eq!(rudp_media_deadline_delay_ticks(&profile), 180_000); - assert_eq!(rudp_audio_deadline_delay_ticks(&options, &profile), 96_000); - assert_eq!( - rudp_endpoint_for_options(&options), + rudp_endpoint_for_options(&options_with_latency_budget("137")), "cultmesh://odin/media/muninn-raven-av#muninn.raven.av.rudp" ); } #[test] - fn rudp_media_progress_detail_reports_queue_and_transport_pressure() { - let receiver_feedback = MuninnRudpReceiverFeedbackStats { - feedback_records: 2, - requested_keyframes: 1, - late_frames: 3, - missing_video_chunks: 4, - repaired_video_chunks: 0, - deferred_repair_chunks: 5, - repair_chunks_per_second: 64, - highest_decodable_frame_id: Some(88), - }; - - assert_eq!( - rudp_media_progress_detail(120, 3, 2, 1, 9, 2, &receiver_feedback), - "Muninn RUDP media progress: receivers=2 sent=120 queue_dropped=3 queue_expired=2 send_expired=1 reliable_expired=9 receiver_feedback=2 receiver_keyframes=1 receiver_late_frames=3 receiver_missing_chunks=4 receiver_repaired_chunks=0 receiver_deferred_repairs=5 repair_rate=64 receiver_highest_decodable=88" - ); - } - - #[test] - fn rudp_repair_budget_backs_off_on_media_drops_and_recovers_when_stable() { - let start = Instant::now(); - let mut budget = MuninnRudpRepairBudget { - chunks_per_second: 64, - min_chunks_per_second: 8, - max_chunks_per_second: 128, - add_chunks_per_second: 8, - recovery_interval: Duration::from_secs(2), - max_available_chunks: 4, - available_chunks: 4, - last_refill_at: start, - last_rate_adjust_at: start, - last_queue_dropped: 0, - }; - - assert_eq!(budget.take(4, start, 0), 4); - assert_eq!(budget.chunks_per_second(), 64); - assert_eq!(budget.take(3, start + Duration::from_millis(10), 1), 0); - assert_eq!(budget.chunks_per_second(), 32); - assert_eq!(budget.take(3, start + Duration::from_secs(1), 1), 3); - assert_eq!(budget.chunks_per_second(), 32); - assert_eq!(budget.take(3, start + Duration::from_secs(3), 1), 3); - assert_eq!(budget.chunks_per_second(), 40); - } - - #[test] - fn default_rudp_repair_budget_has_lan_stream_headroom() { - let mut budget = MuninnRudpRepairBudget::new( - MUNINN_RUDP_MEDIA_REPAIR_INITIAL_CHUNKS_PER_SECOND, - MUNINN_RUDP_MEDIA_REPAIR_BURST_CHUNKS, - ); - let start = budget.last_refill_at; - - assert_eq!(budget.chunks_per_second(), 4_096); - assert_eq!(budget.take(2_048, start, 0), 2_048); - assert_eq!(budget.take(8_192, start + Duration::from_secs(1), 0), 2_048); - assert_eq!(budget.take(8_192, start + Duration::from_secs(3), 0), 2_048); - assert_eq!(budget.chunks_per_second(), 6_144); - assert_eq!(budget.take(512, start + Duration::from_secs(4), 1), 512); - assert_eq!(budget.chunks_per_second(), 3_072); - } - - #[test] - fn receiver_feedback_keyframe_requests_are_recorded_without_encoder_restart() { - let mut handled = 0; - let mut receiver_feedback = MuninnRudpReceiverFeedbackStats::default(); - - record_receiver_keyframe_pressure(&receiver_feedback, &mut handled); - assert_eq!(handled, 0); - - receiver_feedback.requested_keyframes = 1; - record_receiver_keyframe_pressure(&receiver_feedback, &mut handled); - assert_eq!(handled, 1); - record_receiver_keyframe_pressure(&receiver_feedback, &mut handled); - assert_eq!(handled, 1); - - receiver_feedback.requested_keyframes = 2; - record_receiver_keyframe_pressure(&receiver_feedback, &mut handled); - assert_eq!(handled, 2); - } - - #[test] - fn rudp_media_receiver_feedback_updates_sender_pressure_stats() { - let feedback = cultnet_rs::build_receiver_feedback(cultnet_rs::ReceiverFeedbackOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "raven:session:video", - receiver_id: "starfire.obs", - highest_decodable_frame_id: Some(41), - missing_frame_ids: Vec::new(), - missing_video_chunk_keys: vec!["42:1".to_string(), "42:3".to_string()], - late_frame_ids: vec![42, 43], - requested_keyframe: true, - jitter_us: 500, - decode_queue_us: 2_000, - observed_at: "unix:1000", - }) - .unwrap(); - let payload = crate::media_packetizer::encode_media_wire_record( - &crate::media_packetizer::GameCultMediaWireRecord::Feedback(feedback), - crate::media_packetizer::MediaWireProvenance { - stored_at: "unix:1000", - runtime_id: "starfire", - role: "mimir.obs", - producer: "mimir", - }, + fn a_request_naming_no_latency_budget_gets_250_ms_and_the_advertisement_says_so() { + assert_eq!(MUNINN_RUDP_MEDIA_DEFAULT_LATENCY_BUDGET_MS, 250); + let options = Options::parse([].into_iter()).unwrap(); + assert_eq!(options.rudp_latency_budget_ms, 250); + let advertised = Options::parse( + ["serve", "--media-rudp-advertise", "127.0.0.1:5220"] + .into_iter() + .map(String::from), ) .unwrap(); - let frame = CultNetTransportFrame { - channel_id: crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL.to_string(), - payload, - }; - let mut stats = MuninnRudpReceiverFeedbackStats::default(); - let repair_cache = RecentVideoChunkRepairCache::new(16); + let advertisement = media_stream_advertisement(&advertised, false).unwrap(); + assert_eq!(advertisement.default_latency_budget_ms, 250); - let repairs = - record_rudp_media_receiver_feedback(&frame, &mut stats, &repair_cache).unwrap(); - - assert_eq!(stats.feedback_records, 1); - assert_eq!(stats.requested_keyframes, 1); - assert_eq!(stats.late_frames, 2); - assert_eq!(stats.missing_video_chunks, 2); - assert_eq!(stats.repaired_video_chunks, 0); - assert_eq!(stats.highest_decodable_frame_id, Some(41)); - assert!(repairs.is_empty()); + let mut request = media_stream_request(); + request.latency_budget_ms = 0; + let command = command_from_media_stream_request(&options, &request).unwrap(); + assert_eq!(command_rudp_latency_budget_ms(&command), 250); + request.latency_budget_ms = 40; + let command = command_from_media_stream_request(&options, &request).unwrap(); + assert_eq!(command_rudp_latency_budget_ms(&command), 40); } #[test] - fn repair_cache_returns_recent_missing_video_chunks_from_feedback() { - let video = cultnet_rs::GameCultMediaVideoAccessUnitRecord { - stream_id: "muninn.raven.av.rudp".to_string(), - session_id: "raven:session:video".to_string(), - frame_id: 42, - codec: "h264".to_string(), - pts_ticks: 126_000, - duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - keyframe: false, - dependency_frame_id: Some(41), - deadline_ticks: 127_800, - chunk_index: 3, - chunk_count: 5, - payload: vec![1, 2, 3, 4], - }; - let payload = MuninnMediaSendPayload { - channel_id: crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL, - payload: crate::media_packetizer::encode_media_wire_record( - &crate::media_packetizer::GameCultMediaWireRecord::Video(video), - crate::media_packetizer::MediaWireProvenance { - stored_at: "unix:1000", - runtime_id: "muninn-test", - role: "repair-cache-test", - producer: "mimir", - }, - ) - .unwrap(), - }; - let feedback = cultnet_rs::build_receiver_feedback(cultnet_rs::ReceiverFeedbackOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "raven:session:video", - receiver_id: "starfire.obs", - highest_decodable_frame_id: Some(41), - missing_frame_ids: Vec::new(), - missing_video_chunk_keys: vec!["42:3".to_string(), "42:4".to_string()], - late_frame_ids: vec![42], - requested_keyframe: true, - jitter_us: 500, - decode_queue_us: 2_000, - observed_at: "unix:1000", - }) + fn a_latency_budget_above_the_maximum_is_2000_ms_wherever_it_is_read() { + // The request: the command reads back the clamped budget, and + // it is the same stream as a request that asked for 2000. + let options = Options::parse(["serve"].into_iter().map(String::from)).unwrap(); + let mut request = media_stream_request(); + request.latency_budget_ms = 5_000; + let command = command_from_media_stream_request(&options, &request).unwrap(); + assert_eq!(command_rudp_latency_budget_ms(&command), 2_000); + request.latency_budget_ms = 2_000; + let at_maximum = command_from_media_stream_request(&options, &request).unwrap(); + assert!(capture_stream_commands_start_equivalent(&command, &at_maximum)); + + // The command line an activation is spawned with parses to the same + // clamped value, and so does a raw 5000 typed by an operator. + let store_path = + std::env::temp_dir().join(format!("muninn-clamp-{}.cc", timestamp_ns().unwrap())); + let options = Options::parse( + [ + "serve", + "--store", + store_path.to_str().unwrap(), + "--media-rudp-advertise", + "127.0.0.1:5220", + "--rudp-latency-budget-ms", + "5000", + ] + .into_iter() + .map(String::from), + ) .unwrap(); + assert_eq!(options.rudp_latency_budget_ms, 2_000); - let mut cache = RecentVideoChunkRepairCache::new(16); - cache.remember(&payload).unwrap(); - let repairs = cache.repair_payloads_for_feedback(&feedback); + // Advertised. + let advertisement = media_stream_advertisement(&options, false).unwrap(); + assert_eq!(advertisement.default_latency_budget_ms, 2_000); - assert_eq!(repairs, vec![payload]); + // Reported. + let mut node = open_node(&options, "muninn-clamp-test").unwrap(); + publish_runtime_boundary_records(&mut node, &options, "idle", &[], &[]).unwrap(); + let transport = node + .get_required::("transport-profile:muninn") + .unwrap(); + assert_eq!( + transport.value["media_profile"]["latency_budget_ms"].as_u64(), + Some(2_000) + ); } #[test] @@ -12775,42 +11248,6 @@ mod tests { ); } - #[test] - fn muninn_eve_surface_exposes_live_move_hue_program_controls() { - let store_path = std::env::temp_dir().join(format!( - "muninn-move-hue-eve-{}.cc", - timestamp_ns().unwrap() - )); - let options = Options::parse( - [ - "serve", - "--store", - store_path.to_str().unwrap(), - "--host", - "nightwing", - "--odin-cultmesh-uri", - "none", - ] - .into_iter() - .map(String::from), - ) - .unwrap(); - let _ = load_or_initialize_move_hue_program(&options).unwrap(); - let mut node = open_node(&options, "muninn-move-hue-eve-test").unwrap(); - publish_surface(&mut node, &options, "idle", &[]).unwrap(); - let surface = node - .get_required::(&move_hue_surface_key("nightwing")) - .unwrap(); - let encoded = surface.surface.to_string(); - assert!(encoded.contains("Hold Current Colors")); - assert!(encoded.contains("golden-permutation")); - assert!(encoded.contains("Transition Duration")); - assert!(encoded.contains("transitionPercent")); - assert!(encoded.contains(MUNINN_MOVE_HUE_PROGRAM_SCHEMA)); - drop(node); - let _ = fs::remove_file(store_path); - } - #[test] fn move_hue_program_command_updates_typed_live_state() { let store_path = std::env::temp_dir().join(format!( @@ -12850,115 +11287,6 @@ mod tests { let _ = fs::remove_file(store_path); } - #[test] - fn provider_command_rudp_ingress_applies_move_hue_command() { - let store_path = std::env::temp_dir().join(format!( - "muninn-provider-command-{}.cc", - timestamp_ns().unwrap() - )); - let options = Options::parse( - [ - "serve", - "--store", - store_path.to_str().unwrap(), - "--host", - "nightwing", - "--odin-cultmesh-uri", - "none", - ] - .into_iter() - .map(String::from), - ) - .unwrap(); - let runtime_program = load_or_initialize_move_hue_program(&options).unwrap(); - let server_socket = UdpSocket::bind("127.0.0.1:0").unwrap(); - server_socket - .set_read_timeout(Some(Duration::from_millis(5))) - .unwrap(); - let server_address = server_socket.local_addr().unwrap(); - let server_options = options.clone(); - let server_program = Arc::clone(&runtime_program); - thread::spawn(move || { - run_provider_command_ingress(server_socket, server_options, server_program).unwrap() - }); - - let client_socket = UdpSocket::bind("127.0.0.1:0").unwrap(); - client_socket - .set_read_timeout(Some(Duration::from_millis(5))) - .unwrap(); - let mut client = - CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { - media_delivery: None, - runtime_id: "muninn-provider-command-test-client".to_string(), - socket: client_socket, - mode: cultnet_rs::CultNetRudpSocketMode::Client, - remote_addr: Some(server_address), - connection_id: MUNINN_COMMAND_RUDP_CONNECTION_ID, - initial_sequence: 1, - resend_delay_ms: 15, - transport_id: Some("muninn-provider-command-test".to_string()), - max_payload_bytes: None, - max_fragment_bytes: Some(1200), - max_pending_reliable_packets: Some(64), - media_reliable_expire_after_ms: None, - reconnect_policy: None, - }) - .unwrap(); - client.connect(Vec::new()).unwrap(); - let deadline = Instant::now() + Duration::from_secs(2); - while !client.connected() && Instant::now() < deadline { - let _ = client.receive_once().unwrap(); - client.poll_resends().unwrap(); - thread::sleep(Duration::from_millis(1)); - } - assert!(client.connected(), "provider command RUDP handshake"); - let command = json!({ - "type": "surface-command", - "schema": "gamecult.eve.command.v1", - "providerId": "muninn.telemetry.nightwing", - "command": "muninn.set-move-hue-program", - "payload": { - "type": "muninn.set-move-hue-program", - "mode": "hold", - "orderMode": "bounce", - "cycleMs": 1500, - "transitionPercent": 25 - }, - "publishedBy": "provider-command-test" - }); - let message = CultNetMessage::DocumentPutRaw { - message_id: "provider-command-test".to_string(), - document: CultNetRawDocumentRecord { - schema_id: "gamecult.eve.command.v1".to_string(), - record_key: "provider-command-test".to_string(), - stored_at: timestamp().unwrap(), - payload_encoding: CultNetRawPayloadEncoding::Messagepack, - payload: rmp_serde::to_vec_named(&command).unwrap(), - source_runtime_id: Some("provider-command-test".to_string()), - source_agent_id: None, - source_role: Some("test".to_string()), - tags: None, - }, - }; - client - .send( - "schema", - encode_cultnet_message_to_vec(&message, CultNetWireContract::CultNetSchemaV0) - .unwrap(), - ) - .unwrap(); - let apply_deadline = Instant::now() + Duration::from_secs(2); - while runtime_program.lock().unwrap().mode != "hold" && Instant::now() < apply_deadline { - client.poll_resends().unwrap(); - thread::sleep(Duration::from_millis(2)); - } - assert_eq!(runtime_program.lock().unwrap().mode, "hold"); - assert_eq!(runtime_program.lock().unwrap().order_mode, "bounce"); - assert_eq!(runtime_program.lock().unwrap().cycle_ms, 1500); - assert_eq!(runtime_program.lock().unwrap().transition_percent, 25); - let _ = fs::remove_file(store_path); - } - #[test] fn move_light_command_writes_ps_move_led_report() { let command = pending_move_light_command(); @@ -13883,6 +12211,64 @@ Device 00:07:04:A8:00:D0 (public) let _ = fs::remove_file(store_path); } + #[test] + fn help_names_no_retired_health_flag() { + assert!(!help_text().contains("--idunn")); + assert!(!help_text().contains("daemon health")); + } + + #[test] + fn runtime_boundary_names_each_host_daemon_and_its_transport() { + for (host, daemon_id) in [ + ("raven", "muninn"), + ("starfire", "starfire-muninn"), + ("nightwing", "nightwing-muninn"), + ] { + let store_path = std::env::temp_dir().join(format!( + "muninn-boundary-{host}-{}.cc", + timestamp_ns().unwrap() + )); + let options = Options::parse( + ["serve", "--host", host, "--store", store_path.to_str().unwrap()] + .into_iter() + .map(String::from), + ) + .unwrap(); + let mut node = open_node(&options, "muninn-boundary-host-test").unwrap(); + + publish_runtime_boundary_records(&mut node, &options, "idle", &[], &[]).unwrap(); + + let boundary = node + .get_required::(&format!( + "command-boundary:{daemon_id}" + )) + .unwrap(); + let transport = node + .get_required::(&format!( + "transport-profile:{daemon_id}" + )) + .unwrap(); + for record in [&boundary.value, &transport.value] { + assert_eq!( + record.get("daemon_id").and_then(|value| value.as_str()), + Some(daemon_id), + "{host}" + ); + } + assert_eq!( + transport.value.get("current_transport").and_then(|value| value.as_str()), + Some("daemon-owned-cultcache-telemetry-store"), + "{host}" + ); + assert_eq!( + transport.value.get("state").and_then(|value| value.as_str()), + Some("cultcache-provider-store-only"), + "{host}" + ); + let _ = fs::remove_file(store_path); + } + } + #[test] fn runtime_boundary_records_use_explicit_activation_store_path() { let store_path = @@ -13898,12 +12284,6 @@ Device 00:07:04:A8:00:D0 (public) "C:/Meta/Odin/state/muninn.activate.cc", "--target-host", "cultmesh://odin/media/muninn-raven-av", - "--idunn-rudp-health", - "198.51.100.10:17870", - "--idunn-daemon", - "muninn", - "--idunn-health-contract", - "muninn.cultnet-rudp-remote-telemetry-health", ] .into_iter() .map(String::from), @@ -13936,6 +12316,13 @@ Device 00:07:04:A8:00:D0 (public) assert!(invocation.contains("request-stream")); assert!(invocation.contains("--target-host cultmesh://odin/media/muninn-raven-av")); + assert_eq!( + boundary.value.get("daemon_id").and_then(|value| value.as_str()), + Some("muninn") + ); + assert!(boundary.value.get("health_publication").is_none()); + assert!(transport.value.get("health_contract").is_some_and(|value| value.is_null())); + let command_lowerings = transport .value .get("command_lowerings") @@ -14026,10 +12413,20 @@ Device 00:07:04:A8:00:D0 (public) ); assert_eq!( media_profile - .get("sender_reliable_expire_after_ms") + .get("latency_budget_ms") .and_then(|value| value.as_u64()), - Some(MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS) + Some(MUNINN_RUDP_MEDIA_DEFAULT_LATENCY_BUDGET_MS) ); + for retired in [ + "sender_queue_deadline_ms", + "sender_reliable_expire_after_ms", + "receiver_assembly_deadline_ms", + ] { + assert!( + media_profile.get(retired).is_none(), + "{retired} was a second name for the request budget" + ); + } assert_eq!( media_profile .get("sender_resend_delay_ms") @@ -14076,8 +12473,6 @@ Device 00:07:04:A8:00:D0 (public) "0.0.0.0:17888", "--hid-controller-rudp-advertise", "198.51.100.66:17888", - "--command-rudp-bind", - "0.0.0.0:17889", "--command-rudp-advertise", "198.51.100.66:17889", ] @@ -14096,21 +12491,6 @@ Device 00:07:04:A8:00:D0 (public) let provider = node .get_required::("muninn.telemetry.starfire") .unwrap(); - let command_route = provider - .value - .get("routes") - .and_then(|value| value.as_array()) - .and_then(|routes| { - routes.iter().find(|route| { - route.get("role").and_then(|value| value.as_str()) - == Some("muninn provider command ingress") - }) - }) - .expect("provider-owned command route"); - assert_eq!( - command_route.get("uri").and_then(|value| value.as_str()), - Some("cultmesh://198.51.100.66:17889/muninn/starfire/commands") - ); let streams = provider .value .get("inputStreams") @@ -14321,7 +12701,8 @@ Device 00:07:04:A8:00:D0 (public) hidraw_path: "windows-psmove://current".to_string(), }]; - reconcile_move_identity_records(&mut node, &options, ¤t, &[]).unwrap(); + publish_move_identity_records(&mut node, &options, ¤t).unwrap(); + prune_stale_move_identity_records(&mut node, &options, ¤t).unwrap(); assert!( node.get::("starfire:move-0006f523e2d1:move-identity") diff --git a/crates/muninn-daemon/src/media_packetizer.rs b/crates/muninn-daemon/src/media_packetizer.rs index 25449b9..3462d05 100644 --- a/crates/muninn-daemon/src/media_packetizer.rs +++ b/crates/muninn-daemon/src/media_packetizer.rs @@ -1,12 +1,8 @@ use anyhow::{Context, Result, anyhow}; use cultnet_rs::{ - CultNetMessage, CultNetWireContract, GAMECULT_MEDIA_AUDIO_PACKET_SCHEMA, - GameCultMediaAudioPacketRecord, - GameCultMediaReceiverFeedbackRecord, GameCultMediaVideoAccessUnitRecord, - GameCultMediaVideoParityShardRecord, decode_cultnet_message_from_slice, - encode_cultnet_message_to_vec, + GameCultMediaAudioPacketRecord, GameCultMediaVideoAccessUnitRecord, + GameCultMediaVideoParityShardRecord, }; -use serde::{Serialize, de::DeserializeOwned}; use std::collections::BTreeMap; /// Re-exported so this module stays the one place Muninn's media code imports @@ -159,26 +155,6 @@ pub struct VideoFramePacketizeOptions<'a> { pub max_payload_bytes: usize, } -pub struct VideoAnnexBStreamPacketizeOptions<'a> { - pub stream_id: &'a str, - pub session_id: &'a str, - pub codec: &'a str, - pub first_frame_id: u64, - pub first_pts_ticks: i64, - pub frame_duration_ticks: u32, - pub timebase_num: u32, - pub timebase_den: u32, - pub deadline_delay_ticks: i64, - pub max_payload_bytes: usize, -} - -pub struct VideoAnnexBStreamWireOptions<'a> { - pub packetize: VideoAnnexBStreamPacketizeOptions<'a>, - pub stored_at: &'a str, - pub source_runtime_id: &'a str, - pub source_role: &'a str, -} - pub struct VideoAnnexBStreamSendConfig { pub stream_id: String, pub session_id: String, @@ -214,7 +190,6 @@ pub struct AudioPacketWireOptions<'a> { pub source_role: &'a str, } - pub struct AudioPcmStreamSendConfig { pub stream_id: String, pub session_id: String, @@ -232,23 +207,26 @@ pub struct AudioPcmStreamSendConfig { pub source_role: String, } - - - - - - #[derive(Clone, Debug, PartialEq, Eq)] pub struct MuninnMediaSendPayload { pub channel_id: &'static str, pub payload: Vec, } +/// Everything one video access unit puts on the wire: its chunks and, until +/// the FEC cut replaces it, their parity. A group is sent whole or not at +/// all, because parity for a frame that never completes is wasted bandwidth. +pub type MuninnMediaPayloadGroup = Vec; + pub struct VideoAnnexBStreamSendState { config: VideoAnnexBStreamSendConfig, pending: Vec, next_frame_id: u64, next_pts_ticks: i64, + dropped_access_units: u64, + /// Set by an overflow drop: the slices that follow belong to the dropped + /// access unit and are discarded up to the next access-unit boundary. + discarding_tail: bool, } impl VideoAnnexBStreamSendState { @@ -291,26 +269,43 @@ impl VideoAnnexBStreamSendState { next_pts_ticks: config.first_pts_ticks, config, pending: Vec::new(), + dropped_access_units: 0, + discarding_tail: false, }) } - pub fn push(&mut self, stored_at: &str, bytes: &[u8]) -> Result> { + /// One group per completed access unit. Whatever is still pending after + /// that is a single unfinished access unit; when it outgrows + /// `max_pending_bytes` it is dropped and counted, never an error that + /// would restart the stream. The dropped unit consumes its frame id, so a + /// receiver sees the gap, and its remaining slices are discarded up to the + /// next access-unit boundary instead of being emitted as a frame of their + /// own. + pub fn push(&mut self, stored_at: &str, bytes: &[u8]) -> Result> { if !bytes.is_empty() { self.pending.extend_from_slice(bytes); } + let groups = self.emit_available(stored_at, false)?; if self.pending.len() > self.config.max_pending_bytes { - return Err(anyhow!( - "Annex B stream sender pending buffer exceeded {} bytes without a complete frame", - self.config.max_pending_bytes - )); + self.pending.clear(); + if !self.discarding_tail { + self.dropped_access_units += 1; + self.advance_frame_clock()?; + self.discarding_tail = true; + } } - self.emit_available(stored_at, false) + Ok(groups) } - pub fn finish(&mut self, stored_at: &str) -> Result> { + pub fn finish(&mut self, stored_at: &str) -> Result> { self.emit_available(stored_at, true) } + /// Access units dropped for outgrowing `max_pending_bytes`, cumulative. + pub fn dropped_access_units(&self) -> u64 { + self.dropped_access_units + } + pub fn pending_bytes(&self) -> usize { self.pending.len() } @@ -323,10 +318,23 @@ impl VideoAnnexBStreamSendState { &mut self, stored_at: &str, flush_last: bool, - ) -> Result> { + ) -> Result> { if stored_at.is_empty() { return Err(anyhow!("stored_at must be non-empty")); } + // After a drop the tail of the dropped access unit arrives with no + // start code in front of it; skip to the next one. + if let Some((start, _)) = find_annex_b_start_code(&self.pending, 0) + && start > 0 + { + self.pending.drain(..start); + } + if self.pending.is_empty() { + return Ok(Vec::new()); + } + if self.discarding_tail && !self.discard_leftover_slices(flush_last)? { + return Ok(Vec::new()); + } if self.pending.is_empty() { return Ok(Vec::new()); } @@ -350,7 +358,7 @@ impl VideoAnnexBStreamSendState { return Ok(Vec::new()); } - let mut send_payloads = Vec::new(); + let mut groups = Vec::with_capacity(emit_count); let mut emitted_bytes = 0_usize; for access_unit in access_units.iter().take(emit_count) { emitted_bytes = emitted_bytes @@ -376,7 +384,7 @@ impl VideoAnnexBStreamSendState { access_unit, )?; let wire_records = video_wire_records_with_parity(&records)?; - send_payloads.extend(wire_payloads_to_media_send(encode_media_wire_records( + groups.push(wire_payloads_to_media_send(encode_media_wire_records( &wire_records, stored_at, &self.config.source_runtime_id, @@ -386,7 +394,49 @@ impl VideoAnnexBStreamSendState { } self.pending.drain(..emitted_bytes); - Ok(send_payloads) + Ok(groups) + } + + /// While the tail of a dropped access unit is being discarded: if the + /// pending bytes open with a continuation slice, drops that leftover access + /// unit (up to the next boundary) and stops discarding; if they open on a + /// boundary, stops discarding and leaves them alone. `false` means it + /// cannot tell yet (the leftover is not complete) and the caller must wait + /// for more bytes. + fn discard_leftover_slices(&mut self, flush_last: bool) -> Result { + let codec = self.config.codec.as_str(); + let nal_units = match normalized_video_codec(codec) { + Some("h265") => annex_b_nal_units(&self.pending, "H.265", h265_nal_type), + _ => annex_b_nal_units(&self.pending, "H.264", h264_nal_type), + }; + let Ok(nal_units) = nal_units else { + return Ok(false); + }; + let first = &nal_units[0]; + let continuation = match normalized_video_codec(codec) { + Some("h265") => { + is_h265_vcl_nal(first.nal_type) + && !h265_first_slice_segment_in_pic(first.payload).unwrap_or(false) + } + _ => { + is_h264_vcl_nal(first.nal_type) + && h264_first_mb_in_slice(first.payload).unwrap_or(1) != 0 + } + }; + if !continuation { + self.discarding_tail = false; + return Ok(true); + } + let access_units = video_annex_b_access_units(codec, &self.pending)?; + if access_units.len() >= 2 { + self.pending.drain(..access_units[0].bytes.len()); + } else if flush_last { + self.pending.clear(); + } else { + return Ok(false); + } + self.discarding_tail = false; + Ok(true) } fn advance_frame_clock(&mut self) -> Result<()> { @@ -402,8 +452,6 @@ impl VideoAnnexBStreamSendState { } } - - pub struct AudioPcmStreamSendState { config: AudioPcmStreamSendConfig, pending: Vec, @@ -552,9 +600,6 @@ impl AudioPcmStreamSendState { } } - - - pub fn packetize_video_access_unit( options: VideoFramePacketizeOptions<'_>, access_unit: &VideoAccessUnit, @@ -724,86 +769,19 @@ pub fn build_video_parity_shards( } fn video_wire_records_with_parity( - records: &[GameCultMediaVideoAccessUnitRecord], + frame_records: &[GameCultMediaVideoAccessUnitRecord], ) -> Result> { - let mut wire_records = Vec::new(); - let mut offset = 0_usize; - while offset < records.len() { - let first = &records[offset]; - let mut end = offset + 1; - while end < records.len() - && records[end].stream_id == first.stream_id - && records[end].session_id == first.session_id - && records[end].frame_id == first.frame_id - { - end += 1; - } - let frame_records = &records[offset..end]; - wire_records.extend( - frame_records - .iter() - .cloned() - .map(GameCultMediaWireRecord::Video), - ); - for parity in build_video_parity_shards(frame_records)? { - wire_records.push(GameCultMediaWireRecord::VideoParity(parity)); - } - offset = end; + let mut wire_records: Vec = frame_records + .iter() + .cloned() + .map(GameCultMediaWireRecord::Video) + .collect(); + for parity in build_video_parity_shards(frame_records)? { + wire_records.push(GameCultMediaWireRecord::VideoParity(parity)); } Ok(wire_records) } -pub fn packetize_video_annex_b_stream( - options: VideoAnnexBStreamPacketizeOptions<'_>, - input: &[u8], -) -> Result> { - if options.frame_duration_ticks == 0 { - return Err(anyhow!("frame_duration_ticks must be greater than zero")); - } - if options.deadline_delay_ticks < 0 { - return Err(anyhow!("deadline_delay_ticks must be non-negative")); - } - - let access_units = video_annex_b_access_units(options.codec, input)?; - let mut records = Vec::new(); - for (index, access_unit) in access_units.iter().enumerate() { - let frame_offset = u64::try_from(index).context("video frame index overflow")?; - let frame_id = options - .first_frame_id - .checked_add(frame_offset) - .ok_or_else(|| anyhow!("video frame_id overflow"))?; - let pts_offset = i64::try_from(index) - .ok() - .and_then(|index| index.checked_mul(i64::from(options.frame_duration_ticks))) - .ok_or_else(|| anyhow!("video pts_ticks overflow"))?; - let pts_ticks = options - .first_pts_ticks - .checked_add(pts_offset) - .ok_or_else(|| anyhow!("video pts_ticks overflow"))?; - let deadline_ticks = pts_ticks - .checked_add(options.deadline_delay_ticks) - .ok_or_else(|| anyhow!("video deadline_ticks overflow"))?; - - records.extend(packetize_video_access_unit( - VideoFramePacketizeOptions { - stream_id: options.stream_id, - session_id: options.session_id, - codec: options.codec, - frame_id, - pts_ticks, - duration_ticks: options.frame_duration_ticks, - timebase_num: options.timebase_num, - timebase_den: options.timebase_den, - deadline_ticks, - max_payload_bytes: options.max_payload_bytes, - }, - access_unit, - )?); - } - - Ok(records) -} - pub fn packetize_audio_packet( options: AudioPacketizeOptions<'_>, payload: &[u8], @@ -844,145 +822,6 @@ pub fn packetize_audio_packet( }) } -#[derive(Default)] -pub struct AudioPacketBuffer { - stream_id: Option, - session_id: Option, - codec: Option, - timebase_num: Option, - timebase_den: Option, - next_packet_id: Option, - emitted_any: bool, - packets: BTreeMap, -} - -impl AudioPacketBuffer { - pub fn insert(&mut self, packet: GameCultMediaAudioPacketRecord) -> Result<()> { - self.require_matching_audio_stream(&packet)?; - if packet.payload.is_empty() { - return Err(anyhow!("audio packet buffer payload must be non-empty")); - } - if self.packets.contains_key(&packet.packet_id) { - return Err(anyhow!( - "audio packet buffer has duplicate packet_id {}", - packet.packet_id - )); - } - match self.next_packet_id { - None => self.next_packet_id = Some(packet.packet_id), - Some(next_packet_id) if packet.packet_id < next_packet_id && !self.emitted_any => { - self.next_packet_id = Some(packet.packet_id); - } - Some(next_packet_id) if packet.packet_id < next_packet_id => { - return Err(anyhow!( - "audio packet buffer received stale packet_id {} before next expected {}", - packet.packet_id, - next_packet_id - )); - } - _ => {} - } - self.packets.insert(packet.packet_id, packet); - Ok(()) - } - - pub fn pop_ready_packets(&mut self) -> Vec { - let Some(mut next_packet_id) = self.next_packet_id else { - return Vec::new(); - }; - let mut ready = Vec::new(); - while let Some(packet) = self.packets.remove(&next_packet_id) { - ready.push(packet); - next_packet_id = next_packet_id.saturating_add(1); - } - if !ready.is_empty() { - self.emitted_any = true; - } - self.next_packet_id = Some(next_packet_id); - ready - } - - pub fn expire_late_packets(&mut self, now_ticks: i64) -> Vec { - let expired_ids = self - .packets - .iter() - .filter_map(|(packet_id, packet)| { - if packet.deadline_ticks <= now_ticks { - Some(*packet_id) - } else { - None - } - }) - .collect::>(); - for packet_id in &expired_ids { - self.packets.remove(packet_id); - } - if let Some(next_packet_id) = self.next_packet_id { - if expired_ids.contains(&next_packet_id) { - self.next_packet_id = self.packets.keys().next().copied(); - } - } - expired_ids - } - - pub fn pending_packet_count(&self) -> usize { - self.packets.len() - } - - fn require_matching_audio_stream( - &mut self, - packet: &GameCultMediaAudioPacketRecord, - ) -> Result<()> { - if packet.stream_id.is_empty() { - return Err(anyhow!("audio packet buffer stream_id must be non-empty")); - } - if packet.session_id.is_empty() { - return Err(anyhow!("audio packet buffer session_id must be non-empty")); - } - if packet.codec.is_empty() { - return Err(anyhow!("audio packet buffer codec must be non-empty")); - } - if packet.timebase_num == 0 || packet.timebase_den == 0 { - return Err(anyhow!("audio packet buffer timebase must be non-zero")); - } - - match ( - self.stream_id.as_deref(), - self.session_id.as_deref(), - self.codec.as_deref(), - self.timebase_num, - self.timebase_den, - ) { - (None, None, None, None, None) => { - self.stream_id = Some(packet.stream_id.clone()); - self.session_id = Some(packet.session_id.clone()); - self.codec = Some(packet.codec.clone()); - self.timebase_num = Some(packet.timebase_num); - self.timebase_den = Some(packet.timebase_den); - Ok(()) - } - ( - Some(stream_id), - Some(session_id), - Some(codec), - Some(timebase_num), - Some(timebase_den), - ) if stream_id == packet.stream_id - && session_id == packet.session_id - && codec == packet.codec - && timebase_num == packet.timebase_num - && timebase_den == packet.timebase_den => - { - Ok(()) - } - _ => Err(anyhow!( - "audio packet buffer received mixed stream metadata" - )), - } - } -} - - /// Muninn's producer name on the wire. The envelope in CultLib takes this as a /// parameter so it never has to know any producer; this is where Muninn says /// who it is, once. @@ -1014,27 +853,6 @@ pub fn encode_media_wire_records( .collect() } -pub fn encode_video_annex_b_stream_wire_records( - options: VideoAnnexBStreamWireOptions<'_>, - input: &[u8], -) -> Result>> { - let records = packetize_video_annex_b_stream(options.packetize, input)?; - let wire_records = video_wire_records_with_parity(&records)?; - encode_media_wire_records( - &wire_records, - options.stored_at, - options.source_runtime_id, - options.source_role, - ) -} - -pub fn video_annex_b_stream_send_payloads( - options: VideoAnnexBStreamWireOptions<'_>, - input: &[u8], -) -> Result> { - encode_video_annex_b_stream_wire_records(options, input).map(wire_payloads_to_media_send) -} - pub fn encode_audio_packet_wire_record( options: AudioPacketWireOptions<'_>, payload: &[u8], @@ -1076,27 +894,6 @@ fn wire_payload_to_media_send(payload: Vec) -> MuninnMediaSendPayload { } } - -fn encode_record_payload(record: &T) -> Result> { - rmp_serde::to_vec(record).map_err(Into::into) -} - - - - -fn decode_record_payload(payload: &[u8]) -> Result { - rmp_serde::from_slice(payload).map_err(Into::into) -} - - - - - - - - - - fn normalized_video_codec(codec: &str) -> Option<&'static str> { match codec.trim().to_ascii_lowercase().as_str() { "h264" | "h.264" | "avc" | "avc1" | "video/avc" => Some("h264"), @@ -1106,8 +903,6 @@ fn normalized_video_codec(codec: &str) -> Option<&'static str> { } } - - fn annex_b_nal_units<'a>( input: &'a [u8], codec_name: &str, @@ -1292,7 +1087,11 @@ impl<'a> BitReader<'a> { #[cfg(test)] mod tests { use super::*; - use cultnet_rs::{ReceiverFeedbackOptions, VideoChunkKey, build_receiver_feedback}; + use cultnet_rs::{ + CultNetMessage, CultNetWireContract, GAMECULT_MEDIA_AUDIO_PACKET_SCHEMA, + ReceiverFeedbackOptions, VideoChunkKey, build_receiver_feedback, + decode_cultnet_message_from_slice, encode_cultnet_message_to_vec, + }; fn start_code() -> [u8; 4] { [0, 0, 0, 1] @@ -1530,101 +1329,6 @@ mod tests { Ok(()) } - #[test] - fn packetizes_annex_b_stream_into_timed_video_records() -> Result<()> { - let mut stream = Vec::new(); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x65, 0x80]); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x41, 0x80]); - - let records = packetize_video_annex_b_stream( - VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "avc", - first_frame_id: 9, - first_pts_ticks: 27_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_800, - max_payload_bytes: 16, - }, - &stream, - )?; - - assert_eq!(records.len(), 2); - assert_eq!(records[0].frame_id, 9); - assert_eq!(records[0].pts_ticks, 27_000); - assert_eq!(records[0].deadline_ticks, 28_800); - assert!(records[0].keyframe); - assert_eq!(records[1].frame_id, 10); - assert_eq!(records[1].pts_ticks, 30_000); - assert_eq!(records[1].deadline_ticks, 31_800); - assert_eq!(records[1].dependency_frame_id, Some(9)); - assert_eq!(records[1].codec, "avc"); - Ok(()) - } - - #[test] - fn packetizes_non_reference_h264_p_frames_without_dependency() -> Result<()> { - let mut stream = Vec::new(); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x65, 0x80]); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x01, 0x80]); - - let records = packetize_video_annex_b_stream( - VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "h264", - first_frame_id: 9, - first_pts_ticks: 27_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_800, - max_payload_bytes: 16, - }, - &stream, - )?; - - assert_eq!(records.len(), 2); - assert!(records[0].keyframe); - assert_eq!(records[0].dependency_frame_id, None); - assert!(!records[1].keyframe); - assert_eq!(records[1].dependency_frame_id, None); - Ok(()) - } - - #[test] - fn rejects_negative_annex_b_stream_deadline_delay() { - let error = packetize_video_annex_b_stream( - VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "h264", - first_frame_id: 9, - first_pts_ticks: 27_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: -1, - max_payload_bytes: 4, - }, - &[0, 0, 0, 1, 0x65, 0x80], - ) - .unwrap_err(); - - assert!( - error - .to_string() - .contains("deadline_delay_ticks must be non-negative") - ); - } - #[test] fn rejects_zero_duration_video_access_units() { let access_unit = VideoAccessUnit { @@ -1799,123 +1503,6 @@ mod tests { ); } - fn audio_packet(packet_id: u64, deadline_ticks: i64) -> GameCultMediaAudioPacketRecord { - packetize_audio_packet( - AudioPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "opus", - packet_id, - pts_ticks: (packet_id as i64) * 960, - duration_ticks: 960, - timebase_num: 1, - timebase_den: 48_000, - deadline_ticks, - }, - &[0xf8, 0xff, packet_id as u8], - ) - .unwrap() - } - - #[test] - fn audio_packet_buffer_emits_contiguous_packets_in_order() -> Result<()> { - let mut buffer = AudioPacketBuffer::default(); - - buffer.insert(audio_packet(7, 10_000))?; - buffer.insert(audio_packet(9, 12_000))?; - let ready = buffer.pop_ready_packets(); - - assert_eq!( - ready - .iter() - .map(|packet| packet.packet_id) - .collect::>(), - vec![7] - ); - assert_eq!(buffer.pending_packet_count(), 1); - - buffer.insert(audio_packet(8, 11_000))?; - let ready = buffer.pop_ready_packets(); - - assert_eq!( - ready - .iter() - .map(|packet| packet.packet_id) - .collect::>(), - vec![8, 9] - ); - assert_eq!(buffer.pending_packet_count(), 0); - Ok(()) - } - - #[test] - fn audio_packet_buffer_tracks_lowest_packet_before_first_emit() -> Result<()> { - let mut buffer = AudioPacketBuffer::default(); - - buffer.insert(audio_packet(9, 12_000))?; - buffer.insert(audio_packet(7, 10_000))?; - buffer.insert(audio_packet(8, 11_000))?; - - let ready = buffer.pop_ready_packets(); - - assert_eq!( - ready - .iter() - .map(|packet| packet.packet_id) - .collect::>(), - vec![7, 8, 9] - ); - assert_eq!(buffer.pending_packet_count(), 0); - Ok(()) - } - - #[test] - fn audio_packet_buffer_rejects_stale_packets_after_emit() -> Result<()> { - let mut buffer = AudioPacketBuffer::default(); - - buffer.insert(audio_packet(7, 10_000))?; - assert_eq!(buffer.pop_ready_packets().len(), 1); - let error = buffer.insert(audio_packet(6, 9_000)).unwrap_err(); - - assert!(error.to_string().contains("stale packet_id")); - Ok(()) - } - - #[test] - fn audio_packet_buffer_expires_late_packets() -> Result<()> { - let mut buffer = AudioPacketBuffer::default(); - - buffer.insert(audio_packet(7, 10_000))?; - buffer.insert(audio_packet(8, 12_000))?; - - let expired = buffer.expire_late_packets(10_000); - - assert_eq!(expired, vec![7]); - assert_eq!(buffer.pending_packet_count(), 1); - assert_eq!( - buffer - .pop_ready_packets() - .into_iter() - .map(|packet| packet.packet_id) - .collect::>(), - vec![8] - ); - Ok(()) - } - - #[test] - fn audio_packet_buffer_rejects_mixed_stream_metadata() -> Result<()> { - let mut buffer = AudioPacketBuffer::default(); - let mut mixed = audio_packet(8, 12_000); - mixed.session_id = "session-2".to_string(); - - buffer.insert(audio_packet(7, 10_000))?; - let error = buffer.insert(mixed).unwrap_err(); - - assert!(error.to_string().contains("mixed stream metadata")); - Ok(()) - } - #[test] fn media_wire_round_trips_video_document() -> Result<()> { let access_unit = VideoAccessUnit { @@ -1989,129 +1576,6 @@ mod tests { Ok(()) } - #[test] - fn media_wire_batches_annex_b_video_records() -> Result<()> { - let mut stream = Vec::new(); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x65, 0x80]); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x41, 0x80]); - let records = packetize_video_annex_b_stream( - VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "h264", - first_frame_id: 9, - first_pts_ticks: 27_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_800, - max_payload_bytes: 16, - }, - &stream, - )?; - let wire_records = records - .iter() - .cloned() - .map(GameCultMediaWireRecord::Video) - .collect::>(); - - let wire = encode_media_wire_records( - &wire_records, - "2026-06-18T00:00:00Z", - "muninn-test", - "media-test", - )?; - - assert_eq!(wire.len(), 2); - assert_eq!(decode_media_wire_record(&wire[0])?, wire_records[0]); - assert_eq!(decode_media_wire_record(&wire[1])?, wire_records[1]); - Ok(()) - } - - #[test] - fn media_wire_encodes_annex_b_stream_for_sender() -> Result<()> { - let mut stream = Vec::new(); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x65, 0x80]); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x41, 0x80]); - - let wire = encode_video_annex_b_stream_wire_records( - VideoAnnexBStreamWireOptions { - packetize: VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "h264", - first_frame_id: 9, - first_pts_ticks: 27_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_800, - max_payload_bytes: 16, - }, - stored_at: "2026-06-18T00:00:00Z", - source_runtime_id: "muninn-test", - source_role: "media-test", - }, - &stream, - )?; - - assert_eq!(wire.len(), 2); - let first = decode_media_wire_record(&wire[0])?; - let second = decode_media_wire_record(&wire[1])?; - let GameCultMediaWireRecord::Video(first) = first else { - panic!("expected video media record"); - }; - let GameCultMediaWireRecord::Video(second) = second else { - panic!("expected video media record"); - }; - assert_eq!(first.frame_id, 9); - assert_eq!(first.deadline_ticks, 28_800); - assert_eq!(second.frame_id, 10); - assert_eq!(second.deadline_ticks, 31_800); - Ok(()) - } - - #[test] - fn media_send_payloads_pin_video_to_media_channel() -> Result<()> { - let mut stream = Vec::new(); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x65, 0x80]); - - let payloads = video_annex_b_stream_send_payloads( - VideoAnnexBStreamWireOptions { - packetize: VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "h264", - first_frame_id: 9, - first_pts_ticks: 27_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_800, - max_payload_bytes: 16, - }, - stored_at: "2026-06-18T00:00:00Z", - source_runtime_id: "muninn-test", - source_role: "media-test", - }, - &stream, - )?; - - assert_eq!(payloads.len(), 1); - assert_eq!(payloads[0].channel_id, MUNINN_MEDIA_RUDP_CHANNEL); - let GameCultMediaWireRecord::Video(record) = decode_media_wire_record(&payloads[0].payload)? - else { - panic!("expected video media record"); - }; - assert_eq!(record.frame_id, 9); - Ok(()) - } - fn stream_send_config() -> VideoAnnexBStreamSendConfig { VideoAnnexBStreamSendConfig { stream_id: "muninn.raven.av.rudp".to_string(), @@ -2130,6 +1594,109 @@ mod tests { } } + /// Push two access units through the sender and return every video data + /// record (parity excluded) it put on the wire, in order. + fn sent_video_records( + config: VideoAnnexBStreamSendConfig, + second_slice_header: u8, + ) -> Result> { + let mut stream = Vec::new(); + stream.extend_from_slice(&start_code()); + stream.extend_from_slice(&[0x65, 0x80]); + stream.extend_from_slice(&start_code()); + stream.extend_from_slice(&[second_slice_header, 0x80]); + let mut sender = VideoAnnexBStreamSendState::new(config)?; + let mut payloads = flat(sender.push("2026-06-18T00:00:00Z", &stream)?); + payloads.extend(flat(sender.finish("2026-06-18T00:00:00Z")?)); + let mut records = Vec::new(); + for payload in &payloads { + if let GameCultMediaWireRecord::Video(record) = + decode_media_wire_record(&payload.payload)? + { + records.push(record); + } + } + Ok(records) + } + + #[test] + fn annex_b_stream_send_state_times_records_from_the_configured_clock() -> Result<()> { + let mut config = stream_send_config(); + config.codec = "avc".to_string(); + + let records = sent_video_records(config, 0x41)?; + + assert_eq!(records.len(), 2); + assert_eq!(records[0].frame_id, 9); + assert_eq!(records[0].pts_ticks, 27_000); + assert_eq!(records[0].deadline_ticks, 28_800); + assert!(records[0].keyframe); + assert_eq!(records[1].frame_id, 10); + assert_eq!(records[1].pts_ticks, 30_000); + assert_eq!(records[1].deadline_ticks, 31_800); + assert_eq!(records[1].dependency_frame_id, Some(9)); + assert_eq!(records[1].codec, "avc"); + Ok(()) + } + + #[test] + fn annex_b_stream_send_state_leaves_non_reference_p_frames_without_dependency() -> Result<()> { + let records = sent_video_records(stream_send_config(), 0x01)?; + + assert_eq!(records.len(), 2); + assert!(records[0].keyframe); + assert_eq!(records[0].dependency_frame_id, None); + assert!(!records[1].keyframe); + assert_eq!(records[1].dependency_frame_id, None); + Ok(()) + } + + #[test] + fn annex_b_stream_send_state_rejects_negative_deadline_delay() { + let mut config = stream_send_config(); + config.deadline_delay_ticks = -1; + + let error = match VideoAnnexBStreamSendState::new(config) { + Ok(_) => panic!("a negative deadline delay must not create a sender"), + Err(error) => error, + }; + + assert!( + error + .to_string() + .contains("deadline_delay_ticks must be non-negative") + ); + } + + #[test] + fn media_wire_batches_sender_records_and_reencodes_them_identically() -> Result<()> { + let mut stream = Vec::new(); + stream.extend_from_slice(&start_code()); + stream.extend_from_slice(&[0x65, 0x80]); + stream.extend_from_slice(&start_code()); + stream.extend_from_slice(&[0x41, 0x80]); + let mut sender = VideoAnnexBStreamSendState::new(stream_send_config())?; + let mut payloads = flat(sender.push("2026-06-18T00:00:00Z", &stream)?); + payloads.extend(flat(sender.finish("2026-06-18T00:00:00Z")?)); + assert!(payloads.len() >= 2); + let wire_records = payloads + .iter() + .map(|payload| decode_media_wire_record(&payload.payload)) + .collect::>>()?; + + let wire = encode_media_wire_records( + &wire_records, + "2026-06-18T00:00:00Z", + "muninn-test", + "media-test", + )?; + + assert_eq!(wire.len(), payloads.len()); + for (encoded, original) in wire.iter().zip(&payloads) { + assert_eq!(encoded, &original.payload); + } + Ok(()) + } #[test] fn annex_b_stream_send_state_emits_only_completed_frames() -> Result<()> { @@ -2150,9 +1717,10 @@ mod tests { let second_push = sender.push("2026-06-18T00:00:00Z", &second_frame)?; assert_eq!(second_push.len(), 1); - assert_eq!(second_push[0].channel_id, MUNINN_MEDIA_RUDP_CHANNEL); + assert_eq!(second_push[0].len(), 1); + assert_eq!(second_push[0][0].channel_id, MUNINN_MEDIA_RUDP_CHANNEL); let GameCultMediaWireRecord::Video(first) = - decode_media_wire_record(&second_push[0].payload)? + decode_media_wire_record(&second_push[0][0].payload)? else { panic!("expected video media record"); }; @@ -2165,7 +1733,8 @@ mod tests { let tail = sender.finish("2026-06-18T00:00:00Z")?; assert_eq!(tail.len(), 1); - let GameCultMediaWireRecord::Video(second) = decode_media_wire_record(&tail[0].payload)? + assert_eq!(tail[0].len(), 1); + let GameCultMediaWireRecord::Video(second) = decode_media_wire_record(&tail[0][0].payload)? else { panic!("expected video media record"); }; @@ -2194,27 +1763,207 @@ mod tests { ); } + /// `(frame_id, whole access unit bytes)` for each group, chunks rejoined. + fn frames_of(groups: &[MuninnMediaPayloadGroup]) -> Result)>> { + groups + .iter() + .map(|group| { + let mut frame_id = None; + let mut bytes = Vec::new(); + for payload in group { + if let GameCultMediaWireRecord::Video(record) = + decode_media_wire_record(&payload.payload)? + { + frame_id = Some(record.frame_id); + bytes.extend_from_slice(&record.payload); + } + } + Ok((frame_id.expect("a group carries video chunks"), bytes)) + }) + .collect() + } + #[test] - fn annex_b_stream_send_state_rejects_unbounded_pending_bytes() -> Result<()> { + fn an_overflow_drop_consumes_its_frame_id_and_discards_the_leftover_slices() -> Result<()> { let mut config = stream_send_config(); - config.max_pending_bytes = 4; + config.max_pending_bytes = 16; + config.max_payload_bytes = 64; let mut sender = VideoAnnexBStreamSendState::new(config)?; + let stored_at = "2026-06-18T00:00:00Z"; + let nal = |header: [u8; 2], filler: &[u8]| { + [&start_code()[..], &header[..], filler].concat() + }; - let error = sender - .push("2026-06-18T00:00:00Z", &[0x47, 0x40, 0x00, 0x10, 0x00]) - .unwrap_err(); + // Frame 9 whole, then the head of a frame that outgrows the ceiling. + let mut first = nal([0x65, 0x80], &[0xA1]); + first.extend(nal([0x41, 0x80], &[0xB2; 30])); + let groups = frames_of(&sender.push(stored_at, &first)?)?; + assert_eq!(groups, vec![(9, nal([0x65, 0x80], &[0xA1]))]); + assert_eq!(sender.dropped_access_units(), 1); + assert_eq!(sender.next_frame_id(), 11, "the dropped frame 10 is spent"); - assert!( - error - .to_string() - .contains("pending buffer exceeded 4 bytes") + // Its second slice (first_mb_in_slice != 0) arrives alone: nothing can + // be decided yet, and nothing is emitted. + assert!(sender.push(stored_at, &nal([0x41, 0x40], &[0xC3]))?.is_empty()); + assert_eq!(sender.dropped_access_units(), 1); + + // Then two whole frames follow: the leftover slice goes with frame 10. + let mut next = nal([0x41, 0x80], &[0xD4]); + next.extend(nal([0x41, 0x80], &[0xE5])); + let mut groups = frames_of(&sender.push(stored_at, &next)?)?; + groups.extend(frames_of(&sender.finish(stored_at)?)?); + assert_eq!( + groups, + vec![ + (11, nal([0x41, 0x80], &[0xD4])), + (12, nal([0x41, 0x80], &[0xE5])), + ] ); + assert_eq!(sender.dropped_access_units(), 1); Ok(()) } + #[test] + fn a_leftover_spanning_two_pushes_is_discarded_whole() -> Result<()> { + let mut config = stream_send_config(); + config.max_pending_bytes = 16; + config.max_payload_bytes = 64; + let mut sender = VideoAnnexBStreamSendState::new(config)?; + let stored_at = "2026-06-18T00:00:00Z"; + let nal = |header: [u8; 2], filler: &[u8]| { + [&start_code()[..], &header[..], filler].concat() + }; + let mut first = nal([0x65, 0x80], &[0xA1]); + first.extend(nal([0x41, 0x80], &[0xB2; 30])); + assert_eq!(sender.push(stored_at, &first)?.len(), 1); + assert_eq!(sender.dropped_access_units(), 1); + // The dropped frame's second and third slices (first_mb_in_slice 1 + // and 3) arrive in separate pushes. Neither is a frame, and neither + // may come out as one. + assert!(sender.push(stored_at, &nal([0x41, 0x40], &[0xC3]))?.is_empty()); + assert!(sender.push(stored_at, &nal([0x41, 0x20], &[0xC4]))?.is_empty()); + assert_eq!(sender.next_frame_id(), 11); + let mut next = nal([0x41, 0x80], &[0xD4]); + next.extend(nal([0x41, 0x80], &[0xE5])); + let mut groups = frames_of(&sender.push(stored_at, &next)?)?; + groups.extend(frames_of(&sender.finish(stored_at)?)?); + assert_eq!( + groups, + vec![ + (11, nal([0x41, 0x80], &[0xD4])), + (12, nal([0x41, 0x80], &[0xE5])), + ], + "both leftover slices went with the dropped frame" + ); + assert_eq!(sender.dropped_access_units(), 1); + Ok(()) + } + + #[test] + fn a_stream_that_resumes_on_a_frame_boundary_after_an_overflow_loses_nothing_more() -> Result<()> { + let mut config = stream_send_config(); + config.max_pending_bytes = 16; + let mut sender = VideoAnnexBStreamSendState::new(config)?; + let stored_at = "2026-06-18T00:00:00Z"; + let nal = |header: [u8; 2], filler: &[u8]| { + [&start_code()[..], &header[..], filler].concat() + }; + + assert!(sender.push(stored_at, &nal([0x65, 0x80], &[0xB2; 30]))?.is_empty()); + assert_eq!(sender.next_frame_id(), 10); + + // The next bytes open on a new frame, not on a leftover slice. + let mut next = nal([0x41, 0x80], &[0xD4]); + next.extend(nal([0x41, 0x80], &[0xE5])); + let groups = frames_of(&sender.push(stored_at, &next)?)?; + assert_eq!(groups.len(), 1); + assert_eq!(groups[0].0, 10); + Ok(()) + } + + fn flat(groups: Vec) -> Vec { + groups.into_iter().flatten().collect() + } + + #[test] + fn annex_b_stream_send_state_drops_and_counts_an_oversize_access_unit_instead_of_erroring() + -> Result<()> { + let mut config = stream_send_config(); + config.max_pending_bytes = 8; + let mut sender = VideoAnnexBStreamSendState::new(config)?; + + // One access unit that never completes and is larger than the ceiling. + let mut oversize = start_code().to_vec(); + oversize.extend_from_slice(&[0x65, 0x80, 1, 2, 3, 4, 5, 6, 7, 8]); + let groups = sender.push("2026-06-18T00:00:00Z", &oversize)?; + + assert!(groups.is_empty()); + assert_eq!(sender.dropped_access_units(), 1); + assert_eq!(sender.pending_bytes(), 0); + + // The tail of the dropped unit has no start code and is skipped; the + // stream then carries on with the next access units. + let mut next = vec![9, 9, 9]; + next.extend_from_slice(&start_code()); + next.extend_from_slice(&[0x65, 0x80]); + next.extend_from_slice(&start_code()); + next.extend_from_slice(&[0x41, 0x80]); + let groups = sender.push("2026-06-18T00:00:00Z", &next)?; + + assert_eq!(groups.len(), 1); + assert_eq!(sender.dropped_access_units(), 1); + let GameCultMediaWireRecord::Video(record) = + decode_media_wire_record(&groups[0][0].payload)? + else { + panic!("expected video media record"); + }; + assert!(record.keyframe); + Ok(()) + } + + #[test] + fn annex_b_stream_send_state_returns_one_group_per_access_unit_with_all_its_chunks_and_parity() + -> Result<()> { + // Three chunks of 16 bytes plus a short fourth: one access unit. + let mut stream = start_code().to_vec(); + stream.extend_from_slice(&[0x65, 0x80]); + stream.resize(52, 0xAB); + stream.extend_from_slice(&start_code()); + stream.extend_from_slice(&[0x41, 0x80]); + let mut sender = VideoAnnexBStreamSendState::new(stream_send_config())?; + + let mut groups = sender.push("2026-06-18T00:00:00Z", &stream)?; + groups.extend(sender.finish("2026-06-18T00:00:00Z")?); + + assert_eq!(groups.len(), 2); + let mut frame_ids_per_group = Vec::new(); + for group in &groups { + let mut ids = std::collections::BTreeSet::new(); + let mut data = 0; + let mut parity = 0; + for payload in group { + match decode_media_wire_record(&payload.payload)? { + GameCultMediaWireRecord::Video(record) => { + ids.insert(record.frame_id); + data += 1; + } + GameCultMediaWireRecord::VideoParity(record) => { + ids.insert(record.frame_id); + parity += 1; + } + other => panic!("unexpected record {other:?}"), + } + } + assert_eq!(ids.len(), 1, "a group carries exactly one frame"); + frame_ids_per_group.push((ids.into_iter().next().unwrap(), data, parity)); + } + assert_eq!(frame_ids_per_group[0], (9, 4, 4)); + assert_eq!(frame_ids_per_group[1], (10, 1, 0)); + Ok(()) + } #[test] fn media_wire_encodes_audio_packet_for_sender() -> Result<()> { @@ -2464,43 +2213,6 @@ mod tests { Ok(()) } - #[test] - fn feedback_payload_decodes_legacy_record_without_chunk_keys() -> Result<()> { - #[derive(serde::Serialize)] - struct LegacyFeedbackRecord { - stream_id: String, - session_id: String, - receiver_id: String, - highest_decodable_frame_id: Option, - missing_frame_ids: Vec, - late_frame_ids: Vec, - requested_keyframe: bool, - jitter_us: i64, - decode_queue_us: i64, - observed_at: String, - } - - let payload = encode_record_payload(&LegacyFeedbackRecord { - stream_id: "muninn.raven.av.rudp".to_string(), - session_id: "session-1".to_string(), - receiver_id: "starfire.obs".to_string(), - highest_decodable_frame_id: Some(41), - missing_frame_ids: vec![42], - late_frame_ids: vec![40], - requested_keyframe: true, - jitter_us: 750, - decode_queue_us: 2_000, - observed_at: "2026-06-18T00:00:00Z".to_string(), - })?; - - let decoded: GameCultMediaReceiverFeedbackRecord = decode_record_payload(&payload)?; - - assert_eq!(decoded.missing_video_chunk_keys, Vec::::new()); - assert_eq!(decoded.missing_frame_ids, vec![42]); - assert!(decoded.requested_keyframe); - Ok(()) - } - #[test] fn media_wire_rejects_mismatched_record_key() -> Result<()> { let record = packetize_audio_packet( diff --git a/crates/muninn-daemon/src/media_send.rs b/crates/muninn-daemon/src/media_send.rs new file mode 100644 index 0000000..08ff860 --- /dev/null +++ b/crates/muninn-daemon/src/media_send.rs @@ -0,0 +1,1085 @@ +//! The media send path: the one place that decides when a frame is too old. +//! +//! **Owner.** `MediaSendCore` owns the bounded group queues, the hub, the +//! receiver-feedback intake, the repair cache and its budget, and the progress +//! counters. `run_rudp_mux_once` spawns the encoders and publishes; it feeds +//! this module bytes and never decides a deadline. +//! +//! **One deadline owner.** `MediaSendPolicy::latency_budget` comes from the +//! request's `latency_budget_ms` and is the only source of a deadline. A group +//! is stamped `produced_at + latency_budget` when it leaves the packetizer; a +//! repair inherits the deadline of the frame it repairs; the hub's reliable +//! expiry and the record deadline ticks derive from the same budget. +//! +//! **Priority.** The send loop moves one payload per step and chooses the +//! payload afresh each time: audio first, then repairs, then video. Audio that +//! arrives while a video group is half sent, or while the socket is full, +//! goes out before the video group's next payload; nothing holds audio behind +//! video for longer than one payload. The group deadline is checked before +//! every payload; a group that outlives it mid-send is abandoned and counted +//! `groups_cut_short`. +//! +//! **Bounds.** Between the encoder and the socket every queue has a count +//! bound (`MEDIA_GROUP_CHANNEL_BOUND`, the per-kind group caps) and a time +//! bound (the group deadline). Crossing either drops whole groups, oldest +//! first, and counts them. The video cap is 512 groups of at most one access +//! unit each, and an access unit is at most `max_pending_bytes` (848 * 4096 +//! bytes at the default packet size), so the count cap alone implies a worst +//! case of about 1.7 GiB; in practice the deadline empties the queue long +//! before that. + +use crate::media_packetizer::{ + AudioPcmStreamSendConfig, AudioPcmStreamSendState, GameCultMediaWireRecord, + MUNINN_MEDIA_RUDP_CHANNEL, MuninnMediaPayloadGroup, MuninnMediaSendPayload, + VideoAnnexBStreamSendConfig, VideoAnnexBStreamSendState, decode_media_wire_record, + video_chunk_feedback_key, +}; +use anyhow::{Context, Result}; +use cultnet_rs::{ + CultNetRudpServerEvent, CultNetRudpServerHub, CultNetRudpServerSessionContext, + CultNetTransportFrame, GameCultMediaReceiverFeedbackRecord, +}; +use std::collections::{HashMap, VecDeque}; +use std::io::{ErrorKind, Read}; +use std::sync::mpsc; +use std::thread; +use std::time::{Duration, Instant}; + +pub const MEDIA_SEND_AUDIO_GROUP_CAP: usize = 256; +pub const MEDIA_SEND_VIDEO_GROUP_CAP: usize = 512; +/// The longest latency budget a request may claim (the old default). Above +/// this the queues stop being bounded in time. +pub const MEDIA_SEND_MAX_LATENCY_BUDGET_MS: u32 = 2_000; + +/// The one clamp on a requested latency budget. Everything that reads a budget +/// from a request or a command line passes it through here; nothing else +/// clamps. +pub fn clamp_latency_budget_ms(requested_ms: u32) -> u32 { + requested_ms.clamp(1, MEDIA_SEND_MAX_LATENCY_BUDGET_MS) +} +/// Groups the reader threads may have handed over and the send loop not yet +/// taken. Small on purpose: the caps above are where a backlog lives. +pub const MEDIA_GROUP_CHANNEL_BOUND: usize = 8; + +const REPAIR_CACHE_CHUNKS: usize = 16_384; +pub const REPAIR_BURST_CHUNKS: usize = 2_048; +pub const REPAIR_INITIAL_CHUNKS_PER_SECOND: usize = 4_096; +const REPAIR_MIN_CHUNKS_PER_SECOND: usize = 8; +const REPAIR_MAX_CHUNKS_PER_SECOND: usize = 16_384; +const REPAIR_ADD_CHUNKS_PER_SECOND: usize = 2_048; +const REPAIR_RECOVERY_INTERVAL_MS: u64 = 2_000; +const REPAIR_MAX_FEEDBACK_PER_POLL: usize = 32; +const REPAIR_MAX_CHUNKS_PER_POLL: usize = 256; +/// A receiver that has said nothing for this long (Ratatoskr pings every +/// second or so) is dropped so its payloads stop being sent into the void. +const RECEIVER_TIMEOUT_MS: u64 = 6_000; +pub const SEND_PACE_EVERY_PAYLOADS: usize = 4; +pub const SEND_PACE_SLEEP_US: u64 = 250; + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum MediaKind { + Video, + Audio, +} + +/// What the request decided about sending. Nothing else mints a deadline. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct MediaSendPolicy { + pub latency_budget: Duration, + pub video_pace_every_payloads: usize, + pub video_pace_sleep: Duration, +} + +impl MediaSendPolicy { + pub fn from_request(latency_budget_ms: u32) -> Self { + Self { + latency_budget: Duration::from_millis(u64::from(clamp_latency_budget_ms( + latency_budget_ms, + ))), + video_pace_every_payloads: SEND_PACE_EVERY_PAYLOADS, + video_pace_sleep: Duration::from_micros(SEND_PACE_SLEEP_US), + } + } + + pub fn latency_budget_ms(&self) -> u64 { + self.latency_budget.as_millis() as u64 + } + + /// The video record deadline, in the 90 kHz video timebase. + pub fn video_deadline_delay_ticks(&self) -> i64 { + i64::try_from(self.latency_budget_ms().saturating_mul(90)).unwrap_or(i64::MAX) + } + + /// The audio record deadline, in samples at `sample_rate`. + pub fn audio_deadline_delay_ticks(&self, sample_rate: u32) -> i64 { + if sample_rate == 0 { + return 1_024; + } + i64::try_from( + self.latency_budget_ms() + .saturating_mul(u64::from(sample_rate)) + / 1_000, + ) + .unwrap_or(i64::MAX) + .max(1_024) + } +} + +/// One access unit with its parity, or one audio packet. It is sent whole or +/// not at all, and it dies at `deadline`. +pub struct QueuedMediaGroup { + pub kind: MediaKind, + pub deadline: Instant, + pub payloads: MuninnMediaPayloadGroup, +} + +impl QueuedMediaGroup { + pub fn new( + kind: MediaKind, + produced_at: Instant, + policy: &MediaSendPolicy, + payloads: MuninnMediaPayloadGroup, + ) -> Self { + Self { + kind, + deadline: produced_at + policy.latency_budget, + payloads, + } + } + + /// Sendable at the deadline itself, expired one instant after. + pub fn expired(&self, now: Instant) -> bool { + now > self.deadline + } +} + +/// What a reader thread hands the send loop. +pub enum MediaIntake { + Group(QueuedMediaGroup), + /// Video access units the packetizer dropped for outgrowing its ceiling. + VideoDropped(u64), +} + +pub type MediaIntakeSender = mpsc::SyncSender>; +pub type MediaIntakeReceiver = mpsc::Receiver>; + +pub fn media_intake_channel() -> (MediaIntakeSender, MediaIntakeReceiver) { + mpsc::sync_channel(MEDIA_GROUP_CHANNEL_BOUND) +} + +#[derive(Default)] +struct PendingMediaGroups { + audio: VecDeque, + video: VecDeque, +} + +impl PendingMediaGroups { + /// `true` when the queue was at its cap and its oldest group was dropped + /// to make room. + fn push(&mut self, group: QueuedMediaGroup) -> bool { + let (queue, cap) = match group.kind { + MediaKind::Audio => (&mut self.audio, MEDIA_SEND_AUDIO_GROUP_CAP), + MediaKind::Video => (&mut self.video, MEDIA_SEND_VIDEO_GROUP_CAP), + }; + let dropped = queue.len() >= cap; + if dropped { + queue.pop_front(); + } + queue.push_back(group); + dropped + } + + fn is_empty(&self) -> bool { + self.audio.is_empty() && self.video.is_empty() + } +} + +/// Counted where it happens. `groups_dropped_*` is a cap crossing; +/// `groups_expired` is a group whose deadline passed with none of it sent; +/// `groups_cut_short` is one whose deadline passed with part of it already on +/// the wire, which is the only way a partial frame can leave. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct MediaSendStats { + pub groups_sent: u64, + pub payloads_sent: u64, + pub groups_dropped_audio: u64, + pub groups_dropped_video: u64, + pub groups_expired: u64, + pub groups_cut_short: u64, +} + +impl MediaSendStats { + pub fn groups_lost(&self) -> u64 { + self.groups_dropped_audio + + self.groups_dropped_video + + self.groups_expired + + self.groups_cut_short + } + + /// Accounts for one group the send loop has finished with. + fn record_group(&mut self, outcome: &GroupSend, group_payloads: usize) { + match outcome { + GroupSend::Complete => { + self.groups_sent += 1; + self.payloads_sent += group_payloads as u64; + } + GroupSend::DeadlinePassed { payloads_out: 0 } => self.groups_expired += 1, + GroupSend::DeadlinePassed { payloads_out } => { + self.payloads_sent += *payloads_out as u64; + self.groups_cut_short += 1; + } + } + } +} + +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct MuninnRudpReceiverFeedbackStats { + pub feedback_records: u64, + pub requested_keyframes: u64, + pub late_frames: u64, + pub missing_video_chunks: u64, + pub repaired_video_chunks: u64, + pub deferred_repair_chunks: u64, + pub repair_chunks_per_second: usize, + pub highest_decodable_frame_id: Option, +} + +#[derive(Debug)] +pub struct MuninnRudpRepairBudget { + chunks_per_second: usize, + min_chunks_per_second: usize, + max_chunks_per_second: usize, + add_chunks_per_second: usize, + recovery_interval: Duration, + max_available_chunks: usize, + available_chunks: usize, + last_refill_at: Instant, + last_rate_adjust_at: Instant, + last_queue_dropped: u64, +} + +impl MuninnRudpRepairBudget { + pub fn new(chunks_per_second: usize, max_available_chunks: usize) -> Self { + let now = Instant::now(); + let max_available_chunks = max_available_chunks.max(1); + Self { + chunks_per_second: chunks_per_second.max(1), + min_chunks_per_second: REPAIR_MIN_CHUNKS_PER_SECOND, + max_chunks_per_second: REPAIR_MAX_CHUNKS_PER_SECOND, + add_chunks_per_second: REPAIR_ADD_CHUNKS_PER_SECOND, + recovery_interval: Duration::from_millis(REPAIR_RECOVERY_INTERVAL_MS), + max_available_chunks, + available_chunks: max_available_chunks, + last_refill_at: now, + last_rate_adjust_at: now, + last_queue_dropped: 0, + } + } + + pub fn chunks_per_second(&self) -> usize { + self.chunks_per_second + } + + pub fn take(&mut self, requested_chunks: usize, now: Instant, queue_dropped: u64) -> usize { + self.adjust_rate(now, queue_dropped, requested_chunks); + self.refill(now); + let allowed = requested_chunks.min(self.available_chunks); + self.available_chunks -= allowed; + allowed + } + + fn adjust_rate(&mut self, now: Instant, queue_dropped: u64, requested_chunks: usize) { + if queue_dropped > self.last_queue_dropped { + self.chunks_per_second = (self.chunks_per_second / 2).max(self.min_chunks_per_second); + self.available_chunks = self.available_chunks.min(self.chunks_per_second); + self.last_queue_dropped = queue_dropped; + self.last_rate_adjust_at = now; + return; + } + self.last_queue_dropped = queue_dropped; + if requested_chunks == 0 + || now.saturating_duration_since(self.last_rate_adjust_at) < self.recovery_interval + { + return; + } + if self.chunks_per_second < self.max_chunks_per_second { + self.chunks_per_second = self + .chunks_per_second + .saturating_add(self.add_chunks_per_second) + .min(self.max_chunks_per_second); + self.last_rate_adjust_at = now; + } + } + + fn refill(&mut self, now: Instant) { + let elapsed_ms = now + .saturating_duration_since(self.last_refill_at) + .as_millis() as usize; + if elapsed_ms == 0 { + return; + } + let refill_chunks = elapsed_ms.saturating_mul(self.chunks_per_second) / 1_000; + if refill_chunks == 0 { + return; + } + self.available_chunks = self + .available_chunks + .saturating_add(refill_chunks) + .min(self.max_available_chunks); + self.last_refill_at = now; + } +} + +#[derive(Debug)] +struct RepairEntry { + payload: MuninnMediaSendPayload, + /// The deadline of the frame group the chunk left in. A repair never + /// gets a deadline of its own. + deadline: Instant, +} + +#[derive(Debug)] +pub struct RecentVideoChunkRepairCache { + max_entries: usize, + order: VecDeque, + entries: HashMap, +} + +impl RecentVideoChunkRepairCache { + pub fn new(max_entries: usize) -> Self { + Self { + max_entries, + order: VecDeque::new(), + entries: HashMap::new(), + } + } + + pub fn remember(&mut self, payload: &MuninnMediaSendPayload, deadline: Instant) -> Result<()> { + let Some(key) = video_repair_cache_key_from_payload(payload)? else { + return Ok(()); + }; + let entry = RepairEntry { + payload: payload.clone(), + deadline, + }; + if self.entries.contains_key(&key) { + self.entries.insert(key, entry); + return Ok(()); + } + self.order.push_back(key.clone()); + self.entries.insert(key, entry); + while self.entries.len() > self.max_entries { + let Some(expired) = self.order.pop_front() else { + break; + }; + self.entries.remove(&expired); + } + Ok(()) + } + + /// The chunks the receiver is missing that are still inside their frame's + /// deadline at `now`, each with that deadline. + pub fn repair_payloads_for_feedback( + &self, + feedback: &GameCultMediaReceiverFeedbackRecord, + now: Instant, + ) -> Vec<(MuninnMediaSendPayload, Instant)> { + feedback + .missing_video_chunk_keys + .iter() + .filter_map(|chunk_key| { + self.entries.get(&video_repair_cache_key( + &feedback.stream_id, + &feedback.session_id, + chunk_key, + )) + }) + .filter(|entry| now <= entry.deadline) + .map(|entry| (entry.payload.clone(), entry.deadline)) + .collect() + } +} + +fn video_repair_cache_key(stream_id: &str, session_id: &str, chunk_key: &str) -> String { + format!("{stream_id}:{session_id}:video:{chunk_key}") +} + +fn video_repair_cache_key_from_payload(payload: &MuninnMediaSendPayload) -> Result> { + if payload.channel_id != MUNINN_MEDIA_RUDP_CHANNEL { + return Ok(None); + } + let GameCultMediaWireRecord::Video(video) = decode_media_wire_record(&payload.payload)? else { + return Ok(None); + }; + Ok(Some(video_repair_cache_key( + &video.stream_id, + &video.session_id, + &video_chunk_feedback_key(video.frame_id, video.chunk_index), + ))) +} + +#[derive(Debug)] +pub struct MuninnRudpMediaSendPacer { + payloads_since_pause: usize, + every_payloads: usize, + sleep_for: Duration, +} + +impl MuninnRudpMediaSendPacer { + pub fn new(every_payloads: usize, sleep_for: Duration) -> Self { + Self { + payloads_since_pause: 0, + every_payloads: every_payloads.max(1), + sleep_for, + } + } + + fn observe_sent_payload(&mut self) { + if self.sleep_for.is_zero() { + return; + } + self.payloads_since_pause = self.payloads_since_pause.saturating_add(1); + if self.payloads_since_pause < self.every_payloads { + return; + } + self.payloads_since_pause = 0; + thread::sleep(self.sleep_for); + } +} + +pub fn is_would_block_error(error: &anyhow::Error) -> bool { + error.chain().any(|cause| { + cause + .downcast_ref::() + .is_some_and(|io| io.kind() == ErrorKind::WouldBlock) + || cause.to_string().contains("os error 10035") + }) +} + +#[derive(Debug, PartialEq, Eq)] +enum SendOutcome { + Sent, + /// The socket is full: resends were polled, and the caller tries again on + /// its next step, choosing again what is most urgent. + SocketFull, + /// The session this send was addressed to no longer exists, or was + /// replaced by a newer generation. The receiver left; that is not an error. + ReceiverGone, +} + +/// Whether the hub still holds exactly the session `receiver` names. +fn receiver_is_live(hub: &CultNetRudpServerHub, receiver: &CultNetRudpServerSessionContext) -> bool { + hub.session(receiver.remote_addr) + .is_some_and(|live| live.session_generation == receiver.session_generation) +} + +/// One payload to one receiver, once. It never waits, so a full socket cannot +/// hold a queued audio packet behind video. A receiver that has left is +/// reported as gone, not as a failure: the send loop serves every receiver and +/// one leaving must not stop it. Every other hub error propagates. +fn try_send( + hub: &mut CultNetRudpServerHub, + receiver: &CultNetRudpServerSessionContext, + payload: &MuninnMediaSendPayload, + socket_full: bool, +) -> Result { + if !receiver_is_live(hub, receiver) { + return Ok(SendOutcome::ReceiverGone); + } + let sent = if socket_full { + Err(std::io::Error::from(ErrorKind::WouldBlock).into()) + } else { + hub.send(receiver, payload.channel_id, payload.payload.clone()) + }; + match sent { + Ok(()) => Ok(SendOutcome::Sent), + Err(error) if is_would_block_error(&error) => { + poll_resends(hub)?; + thread::yield_now(); + Ok(SendOutcome::SocketFull) + } + Err(error) => Err(error).context("sending typed Muninn media payload"), + } +} + +fn poll_resends(hub: &mut CultNetRudpServerHub) -> Result<()> { + match hub.poll_resends() { + Ok(()) => Ok(()), + Err(error) if is_would_block_error(&error) => Ok(()), + Err(error) => Err(error).context("polling Muninn RUDP media resends"), + } +} + +#[derive(Debug)] +enum GroupSend { + Complete, + /// The deadline passed after `payloads_out` payloads had gone out. + DeadlinePassed { payloads_out: usize }, +} + +/// A group being sent, one payload at a time, to the receivers there were when +/// it started. A payload with nobody to send it to is not a failure; the +/// progress line says how many receivers there are. +struct InFlight { + group: QueuedMediaGroup, + receivers: Vec, + payload: usize, + receiver: usize, +} + +impl InFlight { + /// Payloads that have reached at least one receiver. + fn payloads_out(&self) -> usize { + self.payload + usize::from(self.receiver > 0) + } +} + +/// A repair chunk waiting for the socket: one payload to the receiver that +/// asked, dead at the deadline of the frame it repairs. +struct PendingRepair { + receiver: CultNetRudpServerSessionContext, + payload: MuninnMediaSendPayload, + deadline: Instant, +} + +pub struct MediaSendCore { + hub: CultNetRudpServerHub, + queues: PendingMediaGroups, + repair_cache: RecentVideoChunkRepairCache, + repair_budget: MuninnRudpRepairBudget, + video_pacer: MuninnRudpMediaSendPacer, + audio_pacer: MuninnRudpMediaSendPacer, + audio_in_flight: Option, + video_in_flight: Option, + repairs: VecDeque, + /// Test seam: while set, the socket reports itself full. + #[cfg(test)] + pub(crate) socket_full: std::sync::Arc, + stats: MediaSendStats, + feedback: MuninnRudpReceiverFeedbackStats, + handled_keyframe_requests: u64, + disconnected: bool, +} + +impl MediaSendCore { + pub fn new(hub: CultNetRudpServerHub, policy: &MediaSendPolicy) -> Self { + Self { + hub, + queues: PendingMediaGroups::default(), + repair_cache: RecentVideoChunkRepairCache::new(REPAIR_CACHE_CHUNKS), + repair_budget: MuninnRudpRepairBudget::new( + REPAIR_INITIAL_CHUNKS_PER_SECOND, + REPAIR_BURST_CHUNKS, + ), + video_pacer: MuninnRudpMediaSendPacer::new( + policy.video_pace_every_payloads, + policy.video_pace_sleep, + ), + audio_pacer: MuninnRudpMediaSendPacer::new(0, Duration::ZERO), + audio_in_flight: None, + video_in_flight: None, + repairs: VecDeque::new(), + #[cfg(test)] + socket_full: Default::default(), + stats: MediaSendStats::default(), + feedback: MuninnRudpReceiverFeedbackStats::default(), + handled_keyframe_requests: 0, + disconnected: false, + } + } + + #[cfg(test)] + pub fn stats(&self) -> &MediaSendStats { + &self.stats + } + + #[cfg(test)] + pub fn feedback(&self) -> &MuninnRudpReceiverFeedbackStats { + &self.feedback + } + + #[cfg(test)] + pub fn hub(&self) -> &CultNetRudpServerHub { + &self.hub + } + + /// Nothing queued and every reader gone: the encoders have ended. + pub fn finished(&self) -> bool { + self.disconnected && !self.has_work() + } + + fn has_work(&self) -> bool { + !self.queues.is_empty() + || self.audio_in_flight.is_some() + || self.video_in_flight.is_some() + || !self.repairs.is_empty() + } + + /// Takes what the reader threads have produced. Waits up to `wait` for the + /// first group only when nothing is queued to send. + pub fn intake(&mut self, rx: &MediaIntakeReceiver, wait: Duration) -> Result<()> { + if self.disconnected { + return Ok(()); + } + if !self.has_work() { + match rx.recv_timeout(wait) { + Ok(item) => self.accept(item?), + Err(mpsc::RecvTimeoutError::Timeout) => return Ok(()), + Err(mpsc::RecvTimeoutError::Disconnected) => { + self.disconnected = true; + return Ok(()); + } + } + } + loop { + match rx.try_recv() { + Ok(item) => self.accept(item?), + Err(mpsc::TryRecvError::Empty) => return Ok(()), + Err(mpsc::TryRecvError::Disconnected) => { + self.disconnected = true; + return Ok(()); + } + } + } + } + + fn accept(&mut self, item: MediaIntake) { + match item { + MediaIntake::Group(group) => self.enqueue(group), + MediaIntake::VideoDropped(count) => { + self.stats.groups_dropped_video += count; + self.log_loss_milestone(); + } + } + } + + pub fn enqueue(&mut self, group: QueuedMediaGroup) { + let kind = group.kind; + if self.queues.push(group) { + match kind { + MediaKind::Audio => self.stats.groups_dropped_audio += 1, + MediaKind::Video => self.stats.groups_dropped_video += 1, + } + self.log_loss_milestone(); + } + } + + /// One step of the send loop: moves at most one payload toward the wire and + /// says whether there was anything to do. The next payload is chosen afresh + /// every step, audio first, then repairs, then video, so a video group in + /// progress or a full socket never holds audio back. A group whose + /// deadline has passed at `now`, before or after part of it went out, is + /// abandoned whole. + pub fn send_next(&mut self, now: Instant) -> Result { + #[cfg(test)] + let socket_full = self.socket_full.load(std::sync::atomic::Ordering::Relaxed); + #[cfg(not(test))] + let socket_full = false; + if self.step_group(MediaKind::Audio, now, socket_full)? + || self.step_repair(now, socket_full)? + { + return Ok(true); + } + self.step_group(MediaKind::Video, now, socket_full) + } + + fn step_group(&mut self, kind: MediaKind, now: Instant, socket_full: bool) -> Result { + let in_flight = match kind { + MediaKind::Audio => &mut self.audio_in_flight, + MediaKind::Video => &mut self.video_in_flight, + }; + if in_flight.is_none() { + let queue = match kind { + MediaKind::Audio => &mut self.queues.audio, + MediaKind::Video => &mut self.queues.video, + }; + let Some(group) = queue.pop_front() else { + return Ok(false); + }; + *in_flight = Some(InFlight { + group, + receivers: self.hub.sessions(), + payload: 0, + receiver: 0, + }); + } + let flight = in_flight.as_mut().expect("in flight was just filled"); + + if flight.group.expired(now) { + let outcome = GroupSend::DeadlinePassed { + payloads_out: flight.payloads_out(), + }; + let group_payloads = flight.group.payloads.len(); + *in_flight = None; + self.stats.record_group(&outcome, group_payloads); + self.log_loss_milestone(); + return Ok(true); + } + + if let Some(payload) = flight.group.payloads.get(flight.payload) { + if let Some(receiver) = flight.receivers.get(flight.receiver) { + match try_send(&mut self.hub, receiver, payload, socket_full)? { + SendOutcome::SocketFull => return Ok(true), + SendOutcome::Sent => flight.receiver += 1, + // Leaves the group; the next receiver slides into this slot. + SendOutcome::ReceiverGone => { + flight.receivers.remove(flight.receiver); + } + } + if flight.receiver < flight.receivers.len() { + return Ok(true); + } + } + flight.receiver = 0; + flight.payload += 1; + match kind { + MediaKind::Video => self.video_pacer.observe_sent_payload(), + MediaKind::Audio => self.audio_pacer.observe_sent_payload(), + } + if flight.payload < flight.group.payloads.len() { + return Ok(true); + } + } + + let flight = in_flight.take().expect("in flight is set"); + self.stats + .record_group(&GroupSend::Complete, flight.group.payloads.len()); + if kind == MediaKind::Video { + for payload in &flight.group.payloads { + self.repair_cache.remember(payload, flight.group.deadline)?; + } + } + if self.stats.groups_sent == 1 || self.stats.groups_sent % 900 == 0 { + eprintln!("{}", self.progress_detail()); + } + Ok(true) + } + + /// Sends the oldest queued repair chunk that is still inside its frame's + /// deadline at `now`; the ones already past it are discarded. + fn step_repair(&mut self, now: Instant, socket_full: bool) -> Result { + while let Some(repair) = self.repairs.front() { + if now > repair.deadline { + self.repairs.pop_front(); + continue; + } + match try_send(&mut self.hub, &repair.receiver, &repair.payload, socket_full)? { + SendOutcome::Sent => { + self.repairs.pop_front(); + self.feedback.repaired_video_chunks = + self.feedback.repaired_video_chunks.saturating_add(1); + self.video_pacer.observe_sent_payload(); + } + SendOutcome::SocketFull => {} + SendOutcome::ReceiverGone => { + let gone = repair.receiver.clone(); + self.repairs.retain(|queued| queued.receiver != gone); + } + } + return Ok(true); + } + Ok(false) + } + + /// Receiver feedback, repairs, keyframe pressure and resends. + pub fn service_control(&mut self, now: Instant) -> Result<()> { + self.poll_feedback(now)?; + if self.feedback.requested_keyframes > self.handled_keyframe_requests { + self.handled_keyframe_requests = self.feedback.requested_keyframes; + eprintln!( + "Muninn RUDP receiver requested a fresh keyframe; continuing current low-latency encoder session until explicit encoder control exists." + ); + } + poll_resends(&mut self.hub) + } + + fn poll_feedback(&mut self, now: Instant) -> Result<()> { + for gone in self.hub.remove_timed_out_sessions(RECEIVER_TIMEOUT_MS) { + eprintln!( + "Muninn media receiver {} at {} went silent and was dropped.", + String::from_utf8_lossy(&gone.connect_payload), + gone.remote_addr + ); + } + let mut feedback_processed = 0_usize; + loop { + match self.hub.receive_event_once() { + Ok(Some(CultNetRudpServerEvent::Connected { session })) => { + eprintln!( + "Muninn media receiver {} attached from {}.", + String::from_utf8_lossy(&session.connect_payload), + session.remote_addr + ); + } + Ok(Some(CultNetRudpServerEvent::Disconnected { session, reason })) => { + eprintln!( + "Muninn media receiver {} at {} disconnected: {}.", + String::from_utf8_lossy(&session.connect_payload), + session.remote_addr, + String::from_utf8_lossy(&reason) + ); + } + Ok(Some(CultNetRudpServerEvent::Frame { session, frame })) => { + if feedback_processed >= REPAIR_MAX_FEEDBACK_PER_POLL { + return Ok(()); + } + feedback_processed += 1; + let repairs = record_receiver_feedback( + &frame, + &mut self.feedback, + &self.repair_cache, + now, + )?; + let requested = repairs.len(); + let allowed = self.repair_budget.take( + requested.min(REPAIR_MAX_CHUNKS_PER_POLL), + now, + self.stats.groups_lost(), + ); + self.feedback.repair_chunks_per_second = self.repair_budget.chunks_per_second(); + self.feedback.deferred_repair_chunks = self + .feedback + .deferred_repair_chunks + .saturating_add(requested.saturating_sub(allowed) as u64); + // Repairs are queued for the receiver that asked, not for + // everyone; the send step sends each one inside the + // deadline of its own frame, after any waiting audio. The + // queue is bounded by the repair budget times the deadline. + self.repairs.extend( + repairs + .into_iter() + .take(allowed) + .map(|(payload, deadline)| PendingRepair { + receiver: session.clone(), + payload, + deadline, + }), + ); + } + Ok(Some(CultNetRudpServerEvent::Pong { .. })) => {} + Ok(None) => return Ok(()), + Err(error) if is_would_block_error(&error) => return Ok(()), + Err(error) => return Err(error).context("polling Muninn RUDP media feedback"), + } + } + } + + fn log_loss_milestone(&self) { + let lost = self.stats.groups_lost(); + // Loss can arrive in the hundreds per second; the first and every + // 300th is enough to see it without flooding the log. + if lost == 1 || lost % 300 == 0 { + eprintln!("{}", self.progress_detail()); + } + } + + pub fn progress_detail(&self) -> String { + format!( + "Muninn RUDP media progress: receivers={} groups_sent={} payloads_sent={} groups_dropped_audio={} groups_dropped_video={} groups_expired={} groups_cut_short={} reliable_expired={} receiver_feedback={} receiver_keyframes={} receiver_late_frames={} receiver_missing_chunks={} receiver_repaired_chunks={} receiver_deferred_repairs={} repair_rate={} receiver_highest_decodable={}; pending_audio={} pending_video={}", + self.hub.sessions().len(), + self.stats.groups_sent, + self.stats.payloads_sent, + self.stats.groups_dropped_audio, + self.stats.groups_dropped_video, + self.stats.groups_expired, + self.stats.groups_cut_short, + self.hub.stats().reliable_packets_expired, + self.feedback.feedback_records, + self.feedback.requested_keyframes, + self.feedback.late_frames, + self.feedback.missing_video_chunks, + self.feedback.repaired_video_chunks, + self.feedback.deferred_repair_chunks, + self.feedback.repair_chunks_per_second, + self.feedback + .highest_decodable_frame_id + .map(|frame_id| frame_id.to_string()) + .unwrap_or_else(|| "none".to_string()), + self.queues.audio.len(), + self.queues.video.len(), + ) + } + + #[cfg(test)] + pub(crate) fn queued_groups(&self, kind: MediaKind) -> usize { + match kind { + MediaKind::Audio => self.queues.audio.len(), + MediaKind::Video => self.queues.video.len(), + } + } + + #[cfg(test)] + pub(crate) fn queued_payload_bytes(&self, kind: MediaKind) -> usize { + match kind { + MediaKind::Audio => &self.queues.audio, + MediaKind::Video => &self.queues.video, + } + .iter() + .flat_map(|group| &group.payloads) + .map(|payload| payload.payload.len()) + .sum() + } + + #[cfg(test)] + pub(crate) fn oldest_deadline(&self, kind: MediaKind) -> Option { + match kind { + MediaKind::Audio => self.queues.audio.front(), + MediaKind::Video => self.queues.video.front(), + } + .map(|group| group.deadline) + } +} + +fn record_receiver_feedback( + frame: &CultNetTransportFrame, + stats: &mut MuninnRudpReceiverFeedbackStats, + repair_cache: &RecentVideoChunkRepairCache, + now: Instant, +) -> Result> { + if frame.channel_id != MUNINN_MEDIA_RUDP_CHANNEL { + return Ok(Vec::new()); + } + + let GameCultMediaWireRecord::Feedback(feedback) = decode_media_wire_record(&frame.payload)? + else { + return Ok(Vec::new()); + }; + + let repairs = repair_cache.repair_payloads_for_feedback(&feedback, now); + stats.feedback_records = stats.feedback_records.saturating_add(1); + if feedback.requested_keyframe { + stats.requested_keyframes = stats.requested_keyframes.saturating_add(1); + } + stats.late_frames = stats + .late_frames + .saturating_add(feedback.late_frame_ids.len() as u64); + stats.missing_video_chunks = stats + .missing_video_chunks + .saturating_add(feedback.missing_video_chunk_keys.len() as u64); + if let Some(frame_id) = feedback.highest_decodable_frame_id { + stats.highest_decodable_frame_id = Some( + stats + .highest_decodable_frame_id + .map(|current| current.max(frame_id)) + .unwrap_or(frame_id), + ); + } + Ok(repairs) +} + +/// Reads Annex B from `reader`, packetizes it, and hands one group per access +/// unit to the send loop, stamped with the request's deadline. +pub fn spawn_video_group_reader( + tx: MediaIntakeSender, + mut reader: R, + config: VideoAnnexBStreamSendConfig, + policy: MediaSendPolicy, +) -> thread::JoinHandle<()> +where + R: Read + Send + 'static, +{ + thread::spawn(move || { + if let Err(error) = read_video_groups(&tx, &mut reader, config, &policy) { + let _ = tx.send(Err(error)); + } + }) +} + +pub fn spawn_audio_group_reader( + tx: MediaIntakeSender, + mut reader: R, + config: AudioPcmStreamSendConfig, + policy: MediaSendPolicy, +) -> thread::JoinHandle<()> +where + R: Read + Send + 'static, +{ + thread::spawn(move || { + if let Err(error) = read_audio_groups(&tx, &mut reader, config, &policy) { + let _ = tx.send(Err(error)); + } + }) +} + +fn send_intake(tx: &MediaIntakeSender, item: MediaIntake) -> Result<()> { + tx.send(Ok(item)).context("queueing typed Muninn media") +} + +fn read_video_groups( + tx: &MediaIntakeSender, + reader: &mut R, + config: VideoAnnexBStreamSendConfig, + policy: &MediaSendPolicy, +) -> Result<()> { + let mut sender = VideoAnnexBStreamSendState::new(config)?; + let mut buffer = vec![0_u8; 64 * 1024]; + let mut dropped_reported = 0_u64; + loop { + let read = reader + .read(&mut buffer) + .context("reading encoded Annex B video from ffmpeg stdout")?; + let stored_at = crate::timestamp()?; + let (groups, done) = if read == 0 { + (sender.finish(&stored_at)?, true) + } else { + (sender.push(&stored_at, &buffer[..read])?, false) + }; + for payloads in groups { + send_intake( + tx, + MediaIntake::Group(QueuedMediaGroup::new( + MediaKind::Video, + Instant::now(), + policy, + payloads, + )), + )?; + } + let dropped = sender.dropped_access_units(); + if dropped > dropped_reported { + send_intake(tx, MediaIntake::VideoDropped(dropped - dropped_reported))?; + dropped_reported = dropped; + } + if done { + return Ok(()); + } + } +} + +fn read_audio_groups( + tx: &MediaIntakeSender, + reader: &mut R, + config: AudioPcmStreamSendConfig, + policy: &MediaSendPolicy, +) -> Result<()> { + let mut sender = AudioPcmStreamSendState::new(config)?; + let mut buffer = vec![0_u8; 16 * 1024]; + loop { + let read = reader + .read(&mut buffer) + .context("reading PCM audio from ffmpeg stdout")?; + let stored_at = crate::timestamp()?; + let (payloads, done) = if read == 0 { + (sender.finish(&stored_at)?, true) + } else { + (sender.push(&stored_at, &buffer[..read])?, false) + }; + for payload in payloads { + send_intake( + tx, + MediaIntake::Group(QueuedMediaGroup::new( + MediaKind::Audio, + Instant::now(), + policy, + vec![payload], + )), + )?; + } + if done { + return Ok(()); + } + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/muninn-daemon/src/media_send/tests.rs b/crates/muninn-daemon/src/media_send/tests.rs new file mode 100644 index 0000000..873afd2 --- /dev/null +++ b/crates/muninn-daemon/src/media_send/tests.rs @@ -0,0 +1,1523 @@ +use super::*; +use crate::media_packetizer::{MediaWireProvenance, encode_media_wire_record}; +use cultnet_rs::{ + CultNetRudpPacketType, CultNetRudpSocketTransportConnection, CultNetRudpSocketTransportOptions, + CultNetTransportDelivery, ReceiverFeedbackOptions, build_receiver_feedback, decode_rudp_packet, +}; +use std::collections::{BTreeMap, BTreeSet}; +use std::io::Cursor; +use std::net::{SocketAddr, UdpSocket}; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::{Arc, Mutex}; + +const CLIP: &[u8] = include_bytes!("../../testdata/clip.h264"); +const STREAM_ID: &str = "muninn.harness.rudp"; +const VIDEO_SESSION_ID: &str = "harness:video"; +const AUDIO_SESSION_ID: &str = "harness:audio"; +const WAIT: Duration = Duration::from_secs(5); + +fn wait_until(timeout: Duration, mut done: impl FnMut() -> bool) -> bool { + let start = Instant::now(); + while start.elapsed() < timeout { + if done() { + return true; + } + thread::sleep(Duration::from_millis(1)); + } + done() +} + +fn video_config() -> VideoAnnexBStreamSendConfig { + VideoAnnexBStreamSendConfig { + stream_id: STREAM_ID.to_string(), + session_id: VIDEO_SESSION_ID.to_string(), + codec: "h264".to_string(), + first_frame_id: 0, + first_pts_ticks: 0, + frame_duration_ticks: 3_000, + timebase_num: 1, + timebase_den: 90_000, + deadline_delay_ticks: 22_500, + max_payload_bytes: 848, + max_pending_bytes: 848 * 4096, + source_runtime_id: "harness".to_string(), + source_role: "muninn.rudp.video".to_string(), + } +} + +fn audio_config() -> AudioPcmStreamSendConfig { + AudioPcmStreamSendConfig { + stream_id: STREAM_ID.to_string(), + session_id: AUDIO_SESSION_ID.to_string(), + codec: "pcm-f32le-interleaved".to_string(), + first_packet_id: 0, + first_pts_ticks: 0, + packet_duration_ticks: 480, + timebase_num: 1, + timebase_den: 48_000, + deadline_delay_ticks: 24_000, + channels: 2, + bytes_per_sample: 4, + max_pending_bytes: 480 * 2 * 4 * 128, + source_runtime_id: "harness".to_string(), + source_role: "muninn.rudp.audio".to_string(), + } +} + +/// Ten audio packets of an ascending f32 ramp: every byte position is +/// distinct, so a reordered or dropped packet cannot pass for the ramp. +fn pcm_ramp() -> Vec { + let samples = 480 * 2 * 10; + (0..samples) + .flat_map(|index| (index as f32 / samples as f32).to_le_bytes()) + .collect() +} + +/// The clip's access units as the packetizer sends them: one group each. +fn clip_groups() -> Vec { + let mut sender = VideoAnnexBStreamSendState::new(video_config()).unwrap(); + let mut groups = sender.push("unix-0", CLIP).unwrap(); + groups.extend(sender.finish("unix-0").unwrap()); + groups +} + +fn group_at( + kind: MediaKind, + produced_at: Instant, + policy: &MediaSendPolicy, + payloads: MuninnMediaPayloadGroup, +) -> QueuedMediaGroup { + QueuedMediaGroup::new(kind, produced_at, policy, payloads) +} + +fn marker_payload(marker: u8) -> MuninnMediaSendPayload { + MuninnMediaSendPayload { + channel_id: MUNINN_MEDIA_RUDP_CHANNEL, + payload: vec![marker], + } +} + +/// `(frame_id, is_parity, chunk or parity index)` of a video wire record. +fn frame_of(payload: &[u8]) -> Option<(u64, bool, u16)> { + match decode_media_wire_record(payload).ok()? { + GameCultMediaWireRecord::Video(record) => Some((record.frame_id, false, record.chunk_index)), + GameCultMediaWireRecord::VideoParity(record) => { + Some((record.frame_id, true, record.parity_index)) + } + _ => None, + } +} + +/// Sends until the core has nothing left to do at `now`. Only for runs where +/// the socket is never full. +fn drain(core: &mut MediaSendCore, now: Instant) { + while core.send_next(now).unwrap() {} +} + +/// `count` one-slice access units with distinct frame ids 0..count, each a +/// single small group. +fn synthetic_groups(count: usize) -> Vec { + let mut sender = VideoAnnexBStreamSendState::new(video_config()).unwrap(); + let mut stream = Vec::new(); + for index in 0..count { + let nal = if index == 0 { 0x65 } else { 0x41 }; + stream.extend_from_slice(&[0, 0, 0, 1, nal, 0x80, index as u8]); + } + let mut groups = sender.push("unix-0", &stream).unwrap(); + groups.extend(sender.finish("unix-0").unwrap()); + assert_eq!(groups.len(), count); + groups +} + +fn one_audio_group() -> MuninnMediaPayloadGroup { + let mut sender = AudioPcmStreamSendState::new(audio_config()).unwrap(); + vec![sender.push("unix-0", &pcm_ramp()).unwrap().remove(0)] +} + +/// Hands the reader one chunk per `read`, so a test decides where a push ends. +struct ChunkedReader(std::collections::VecDeque>); + +impl Read for ChunkedReader { + fn read(&mut self, buffer: &mut [u8]) -> std::io::Result { + match self.0.pop_front() { + Some(chunk) => { + buffer[..chunk.len()].copy_from_slice(&chunk); + Ok(chunk.len()) + } + None => Ok(0), + } + } +} + +fn test_hub(policy: &MediaSendPolicy) -> CultNetRudpServerHub { + let socket = UdpSocket::bind("127.0.0.1:0").unwrap(); + socket.set_nonblocking(true).unwrap(); + CultNetRudpServerHub::new(crate::muninn_media_rudp_hub_options( + socket, + &crate::muninn_rudp_media_profile(), + policy, + )) + .unwrap() +} + +/// The request's budget and no pacing sleeps: the harness is about what the +/// core decides, not about how fast a Windows sender is allowed to go. +fn quiet_policy(latency_budget_ms: u32) -> MediaSendPolicy { + let mut policy = MediaSendPolicy::from_request(latency_budget_ms); + policy.video_pace_sleep = Duration::ZERO; + policy +} + +/// One datagram the hub sent toward the receiver, as the relay saw it. +#[derive(Clone, Debug)] +struct Sent { + packet_type: CultNetRudpPacketType, + channel: String, + payload: Vec, + dropped: bool, +} + +/// A UDP relay between the receiver and the hub. The hub's data packets are +/// dropped by a seeded schedule. Everything is logged before the drop, so +/// tests assert on what the sender put on the wire. +struct DropRelay { + addr: SocketAddr, + log: Arc>>, + stop: Arc, + thread: Option>, +} + +impl DropRelay { + fn start(hub_addr: SocketAddr, drop_percent: u64, seed: u64) -> Self { + let socket = UdpSocket::bind("127.0.0.1:0").unwrap(); + socket + .set_read_timeout(Some(Duration::from_millis(1))) + .unwrap(); + let addr = socket.local_addr().unwrap(); + let log = Arc::new(Mutex::new(Vec::new())); + let stop = Arc::new(AtomicBool::new(false)); + let thread = { + let log = Arc::clone(&log); + let stop = Arc::clone(&stop); + thread::spawn(move || { + let mut client: Option = None; + let mut state = seed.wrapping_mul(0x9E37_79B9_7F4A_7C15) | 1; + let mut buffer = vec![0_u8; 65_535]; + while !stop.load(Ordering::Relaxed) { + let Ok((received, from)) = socket.recv_from(&mut buffer) else { + continue; + }; + if from != hub_addr { + client = Some(from); + let _ = socket.send_to(&buffer[..received], hub_addr); + continue; + } + let Some(client) = client else { continue }; + let Ok(packet) = decode_rudp_packet(&buffer[..received]) else { + continue; + }; + let is_data = packet.packet_type == CultNetRudpPacketType::Data; + state ^= state << 13; + state ^= state >> 7; + state ^= state << 17; + let dropped = is_data && state % 100 < drop_percent; + log.lock().unwrap().push(Sent { + packet_type: packet.packet_type, + channel: packet.channel_id, + payload: packet.payload, + dropped, + }); + if !dropped { + let _ = socket.send_to(&buffer[..received], client); + } + } + }) + }; + Self { + addr, + log, + stop, + thread: Some(thread), + } + } + + fn data(&self) -> Vec { + self.log + .lock() + .unwrap() + .iter() + .filter(|sent| sent.packet_type == CultNetRudpPacketType::Data) + .cloned() + .collect() + } + + fn channels_on_wire(&self) -> Vec { + self.data().into_iter().map(|sent| sent.channel).collect() + } + + fn frame_ids_on_wire(&self) -> BTreeSet { + self.video_frames_on_wire() + .into_iter() + .map(|(frame_id, _, _)| frame_id) + .collect() + } + + fn video_frames_on_wire(&self) -> Vec<(u64, bool, u16)> { + self.data() + .iter() + .filter(|sent| sent.channel == MUNINN_MEDIA_RUDP_CHANNEL) + .filter_map(|sent| frame_of(&sent.payload)) + .collect() + } +} + +impl Drop for DropRelay { + fn drop(&mut self) { + self.stop.store(true, Ordering::Relaxed); + if let Some(thread) = self.thread.take() { + let _ = thread.join(); + } + } +} + +struct Rig { + core: MediaSendCore, + client: CultNetRudpSocketTransportConnection, + relay: DropRelay, + policy: MediaSendPolicy, +} + +fn rig(latency_budget_ms: u32, drop_percent: u64, seed: u64) -> Rig { + let policy = quiet_policy(latency_budget_ms); + let hub = test_hub(&policy); + let relay = DropRelay::start(hub.local_addr().unwrap(), drop_percent, seed); + let socket = UdpSocket::bind("127.0.0.1:0").unwrap(); + socket.set_nonblocking(true).unwrap(); + let mut options = CultNetRudpSocketTransportOptions::client( + "harness-receiver", + socket, + relay.addr, + crate::MUNINN_MEDIA_RUDP_CONNECTION_ID, + ); + options.media_delivery = Some(CultNetTransportDelivery::Unreliable); + options.max_fragment_bytes = Some(crate::MUNINN_RUDP_MEDIA_MAX_FRAGMENT_BYTES as u32); + let mut client = CultNetRudpSocketTransportConnection::new(options).unwrap(); + let mut core = MediaSendCore::new(hub, &policy); + client.connect(b"harness-receiver".to_vec()).unwrap(); + assert!( + wait_until(WAIT, || { + core.service_control(Instant::now()).unwrap(); + let _ = client.receive_once().unwrap(); + client.connected() && core.hub().sessions().len() == 1 + }), + "receiver never attached through the relay" + ); + Rig { + core, + client, + relay, + policy, + } +} + +// ---- policy, groups and queues ----------------------------------------------------- + +#[test] +fn a_group_is_expired_only_after_its_deadline_and_never_at_it() { + let policy = quiet_policy(250); + let produced_at = Instant::now(); + let group = group_at(MediaKind::Video, produced_at, &policy, Vec::new()); + + assert!(!group.expired(group.deadline)); + assert!(!group.expired(group.deadline - Duration::from_millis(1))); + assert!(group.expired(group.deadline + Duration::from_millis(1))); +} + +#[test] +fn a_zero_request_budget_still_leaves_the_stream_a_millisecond() { + assert_eq!( + MediaSendPolicy::from_request(0).latency_budget, + Duration::from_millis(1) + ); +} + +#[test] +fn a_request_cannot_claim_more_than_the_maximum_latency_budget() { + assert_eq!(MEDIA_SEND_MAX_LATENCY_BUDGET_MS, 2_000); + let millis = |request| MediaSendPolicy::from_request(request).latency_budget; + assert_eq!(millis(u32::MAX), Duration::from_millis(2_000)); + assert_eq!(millis(2_001), Duration::from_millis(2_000)); + assert_eq!(millis(2_000), Duration::from_millis(2_000)); + assert_eq!(millis(1_999), Duration::from_millis(1_999)); + assert_eq!(millis(250), Duration::from_millis(250)); + + // Everything derived from the request follows the clamped budget. + let policy = MediaSendPolicy::from_request(u32::MAX); + let produced_at = Instant::now(); + let group = group_at(MediaKind::Video, produced_at, &policy, Vec::new()); + assert_eq!(group.deadline - produced_at, Duration::from_millis(2_000)); + assert_eq!(policy.latency_budget_ms(), 2_000); + assert_eq!(policy.video_deadline_delay_ticks(), 180_000); + assert_eq!(policy.audio_deadline_delay_ticks(48_000), 96_000); + let hub_options = crate::muninn_media_rudp_hub_options( + UdpSocket::bind("127.0.0.1:0").unwrap(), + &crate::muninn_rudp_media_profile(), + &policy, + ); + assert_eq!(hub_options.media_reliable_expire_after_ms, Some(2_000)); +} + +#[test] +fn the_queue_caps_groups_per_kind_and_drops_the_oldest_first() { + const VIDEO_CAP: usize = 512; + const AUDIO_CAP: usize = 256; + assert_eq!(MEDIA_SEND_VIDEO_GROUP_CAP, VIDEO_CAP); + assert_eq!(MEDIA_SEND_AUDIO_GROUP_CAP, AUDIO_CAP); + let policy = quiet_policy(250); + let mut core = MediaSendCore::new(test_hub(&policy), &policy); + let t0 = Instant::now(); + let over = 37; + for index in 0..(VIDEO_CAP + over) { + core.enqueue(group_at( + MediaKind::Video, + t0 + Duration::from_millis(index as u64), + &policy, + vec![marker_payload(1)], + )); + } + for index in 0..(AUDIO_CAP + 5) { + core.enqueue(group_at( + MediaKind::Audio, + t0 + Duration::from_millis(index as u64), + &policy, + vec![marker_payload(2)], + )); + } + + assert_eq!(core.queued_groups(MediaKind::Video), VIDEO_CAP); + assert_eq!(core.queued_groups(MediaKind::Audio), AUDIO_CAP); + // One byte per group: resident bytes are bounded by the cap times the group size. + assert_eq!(core.queued_payload_bytes(MediaKind::Video), VIDEO_CAP); + assert_eq!(core.queued_payload_bytes(MediaKind::Audio), AUDIO_CAP); + assert_eq!(core.stats().groups_dropped_video, over as u64); + assert_eq!(core.stats().groups_dropped_audio, 5); + // The survivors are the newest: the oldest deadline left is the 38th group's. + assert_eq!( + core.oldest_deadline(MediaKind::Video), + Some(t0 + Duration::from_millis(over as u64) + policy.latency_budget) + ); + assert_eq!( + core.oldest_deadline(MediaKind::Audio), + Some(t0 + Duration::from_millis(5) + policy.latency_budget) + ); +} + +#[test] +fn the_intake_channel_holds_the_reader_at_its_bound_instead_of_growing() { + let policy = quiet_policy(5_000); + let (tx, rx) = media_intake_channel(); + let frames = clip_groups().len(); + assert!(frames > MEDIA_GROUP_CHANNEL_BOUND + 1); + let reader = spawn_video_group_reader(tx, Cursor::new(CLIP.to_vec()), video_config(), policy); + + // Nothing drains, so the reader parks with the channel full. + thread::sleep(Duration::from_millis(300)); + assert!( + !reader.is_finished(), + "an unbounded channel let the reader run to the end" + ); + + let mut received = 0; + wait_until(WAIT, || { + while rx.try_recv().is_ok() { + received += 1; + } + received == frames + }); + assert_eq!(received, frames); + assert!(wait_until(WAIT, || reader.is_finished())); +} + +#[test] +fn a_full_socket_is_recognised_and_any_other_send_error_is_an_error() { + assert!(is_would_block_error(&std::io::Error::from(ErrorKind::WouldBlock).into())); + assert!(is_would_block_error(&anyhow::anyhow!("send failed: os error 10035"))); + assert!(!is_would_block_error(&anyhow::anyhow!("socket closed"))); + + let mut rig = rig(250, 0, 1); + + // A live receiver and a payload the hub refuses is an error. + let receiver = rig.core.hub().sessions()[0].clone(); + let oversize = MuninnMediaSendPayload { + channel_id: MUNINN_MEDIA_RUDP_CHANNEL, + payload: vec![0; 17 * 1024 * 1024], + }; + let error = try_send(&mut rig.core.hub, &receiver, &oversize, false).unwrap_err(); + assert!(!is_would_block_error(&error)); + assert!(format!("{error:#}").contains("sending typed Muninn media payload")); + + // A full socket is not an error: nothing is sent and the caller tries again. + assert_eq!( + try_send(&mut rig.core.hub, &receiver, &marker_payload(1), true).unwrap(), + SendOutcome::SocketFull + ); + thread::sleep(Duration::from_millis(50)); + assert!(rig.relay.data().is_empty()); + assert_eq!( + try_send(&mut rig.core.hub, &receiver, &marker_payload(1), false).unwrap(), + SendOutcome::Sent + ); +} + +#[test] +fn a_receiver_that_is_gone_is_not_an_error_whether_it_left_or_was_replaced() { + let mut rig = rig(250, 0, 1); + let receiver = rig.core.hub().sessions()[0].clone(); + + // Never a session at that endpoint. + let mut stranger = receiver.clone(); + stranger.remote_addr = "127.0.0.1:9".parse().unwrap(); + assert_eq!( + try_send(&mut rig.core.hub, &stranger, &marker_payload(1), false).unwrap(), + SendOutcome::ReceiverGone + ); + + // A session at the endpoint, but not the generation this send was made for. + let mut older = receiver.clone(); + older.session_generation -= 1; + assert_eq!( + try_send(&mut rig.core.hub, &older, &marker_payload(1), false).unwrap(), + SendOutcome::ReceiverGone + ); + + // A session that was live and has left, even with the socket reporting full. + assert!(rig.core.hub.disconnect(&receiver, b"left".to_vec()).unwrap()); + for socket_full in [false, true] { + assert_eq!( + try_send(&mut rig.core.hub, &receiver, &marker_payload(1), socket_full).unwrap(), + SendOutcome::ReceiverGone + ); + } +} + +fn session_named(core: &MediaSendCore, name: &str) -> CultNetRudpServerSessionContext { + core.hub() + .sessions() + .into_iter() + .find(|session| session.connect_payload == name.as_bytes()) + .unwrap_or_else(|| panic!("no session named {name}")) +} + +/// How many video payloads `receiver` has been sent so far. +fn video_heard_by(receiver: &mut CultNetRudpSocketTransportConnection) -> usize { + let mut heard = 0; + while let Some(frame) = receiver.receive_once().unwrap() { + heard += usize::from(frame_of(&frame.payload).is_some()); + } + heard +} + +#[test] +fn the_only_receiver_leaving_mid_frame_ends_the_frame_without_an_error() { + let mut rig = rig(2_000, 0, 1); + let t0 = Instant::now(); + let group = clip_groups() + .into_iter() + .find(|group| group.len() > 3) + .unwrap(); + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, group)); + for _ in 0..2 { + assert!(rig.core.send_next(t0).unwrap()); + } + + let receiver = session_named(&rig.core, "harness-receiver"); + assert!(rig.core.hub.disconnect(&receiver, b"left".to_vec()).unwrap()); + drain(&mut rig.core, t0); + + assert!(!rig.core.has_work()); + assert_eq!(rig.core.stats().groups_sent, 1); + assert_eq!(rig.core.stats().groups_lost(), 0); +} + +#[test] +fn a_receiver_that_asked_for_repairs_and_left_takes_its_queued_repairs_with_it() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let mut other = attach_direct_receiver(&mut rig); + let (_, frame_id, frame_payloads) = send_repairable_frame(&mut rig, t0); + ask_for_chunks(&mut rig, frame_id, &[0, 1], t0, 1); + other + .send( + MUNINN_MEDIA_RUDP_CHANNEL, + feedback_wire(feedback_for( + vec![video_chunk_feedback_key(frame_id, 0)], + false, + )), + ) + .unwrap(); + assert!(wait_until(WAIT, || { + rig.core.service_control(t0).unwrap(); + rig.core.feedback().feedback_records == 2 + })); + assert_eq!(rig.core.repairs.len(), 3); + let asker = session_named(&rig.core, "harness-receiver"); + assert!(rig.core.hub.disconnect(&asker, b"left".to_vec()).unwrap()); + + drain(&mut rig.core, t0); + + assert!(rig.core.repairs.is_empty()); + assert_eq!( + rig.core.feedback().repaired_video_chunks, + 1, + "only the receiver still attached was repaired" + ); + let mut heard = 0; + assert!(wait_until(WAIT, || { + heard += video_heard_by(&mut other); + heard == frame_payloads + 1 + })); +} + +#[test] +fn a_receiver_leaving_mid_frame_does_not_stop_the_other_receivers_stream() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let mut other = attach_direct_receiver(&mut rig); + let group = clip_groups() + .into_iter() + .find(|group| group.len() > 3) + .unwrap(); + let expected = group.len() * 2; + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, group.clone())); + for _ in 0..3 { + assert!(rig.core.send_next(t0).unwrap()); + } + + let leaver = session_named(&rig.core, "harness-receiver"); + assert!(rig.core.hub.disconnect(&leaver, b"left".to_vec()).unwrap()); + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, group)); + drain(&mut rig.core, t0); + + assert_eq!(rig.core.stats().groups_sent, 2); + assert_eq!(rig.core.stats().groups_lost(), 0); + let mut heard = 0; + assert!( + wait_until(WAIT, || { + heard += video_heard_by(&mut other); + heard == expected + }), + "the receiver that stayed heard {heard} of {expected} payloads" + ); +} + +#[test] +fn a_blocked_group_is_abandoned_at_its_own_deadline_not_a_budget_after_it_was_dequeued() { + // A 2 s budget, but this group's deadline is 80 ms out: a deadline taken + // from the moment the group left the queue would hold it for two seconds. + let mut rig = rig(MEDIA_SEND_MAX_LATENCY_BUDGET_MS, 0, 1); + let started = Instant::now(); + let mut group = group_at( + MediaKind::Video, + started, + &rig.policy, + (1..=6).map(marker_payload).collect(), + ); + group.deadline = started + Duration::from_millis(80); + rig.core.enqueue(group); + assert!(rig.core.send_next(started).unwrap()); + + rig.core.socket_full.store(true, Ordering::Relaxed); + while rig.core.stats().groups_cut_short == 0 && started.elapsed() < Duration::from_secs(1) { + assert!(rig.core.send_next(Instant::now()).unwrap()); + } + + let elapsed = started.elapsed(); + assert_eq!(rig.core.stats().groups_cut_short, 1); + assert_eq!(rig.core.stats().groups_expired, 0); + assert_eq!(rig.core.stats().groups_sent, 0); + assert_eq!(rig.core.stats().payloads_sent, 1); + assert!( + elapsed >= Duration::from_millis(80), + "abandoned before its deadline, after {elapsed:?}" + ); + assert!( + elapsed < Duration::from_millis(500), + "held past its deadline, until {elapsed:?}" + ); + assert!(!rig.core.has_work()); +} + +#[test] +fn a_group_whose_deadline_passes_mid_send_is_cut_short_and_counted() { + let mut rig = rig(50, 0, 1); + rig.core.video_pacer = MuninnRudpMediaSendPacer::new(1, Duration::from_millis(20)); + let payloads: MuninnMediaPayloadGroup = (1..=6).map(marker_payload).collect(); + rig.core.enqueue(group_at( + MediaKind::Video, + Instant::now(), + &rig.policy, + payloads, + )); + + while rig.core.send_next(Instant::now()).unwrap() {} + + let stats = rig.core.stats().clone(); + assert_eq!(stats.groups_cut_short, 1); + assert_eq!((stats.groups_sent, stats.groups_expired), (0, 0)); + assert!( + (1..6).contains(&stats.payloads_sent), + "some but not all of the group went out: {}", + stats.payloads_sent + ); + assert!(wait_until(WAIT, || rig.relay.data().len() as u64 + == stats.payloads_sent)); + thread::sleep(Duration::from_millis(100)); + assert_eq!(rig.relay.data().len() as u64, stats.payloads_sent); + assert!(rig.core.progress_detail().contains("groups_cut_short=1")); +} + +// ---- priority: audio goes first, one payload at a time ------------------------------- + +#[test] +fn audio_that_arrives_mid_frame_goes_out_before_the_frames_next_payload() { + let mut rig = rig(2_000, 0, 1); + let t0 = Instant::now(); + let video = clip_groups() + .into_iter() + .max_by_key(|group| group.len()) + .unwrap(); + assert!(video.len() >= 6, "the clip has a large frame"); + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, video.clone())); + for _ in 0..3 { + assert!(rig.core.send_next(t0).unwrap()); + } + + // The audio comes in through the reader channel while the frame is half sent. + let (tx, rx) = media_intake_channel(); + tx.send(Ok(MediaIntake::Group(group_at( + MediaKind::Audio, + t0, + &rig.policy, + one_audio_group(), + )))) + .unwrap(); + rig.core.intake(&rx, Duration::ZERO).unwrap(); + drain(&mut rig.core, t0); + + // An audio packet is more than one datagram; it is all sent before the + // frame's next payload. + assert!(wait_until(WAIT, || { + rig.relay.video_frames_on_wire().len() == video.len() + && rig.relay.channels_on_wire().iter().any(|channel| channel == "audio") + })); + let channels = rig.relay.channels_on_wire(); + assert_eq!( + channels.iter().position(|channel| channel == "audio"), + Some(3), + "audio waited for exactly the payload already in progress: {channels:?}" + ); + let last_audio = channels.iter().rposition(|channel| channel == "audio").unwrap(); + assert!( + channels[3..=last_audio].iter().all(|channel| channel == "audio"), + "the audio packet went out whole before video resumed: {channels:?}" + ); + assert_eq!(rig.core.stats().groups_sent, 2); +} + +#[test] +fn a_full_socket_never_holds_audio_behind_video() { + let mut rig = rig(2_000, 0, 1); + let t0 = Instant::now(); + let video = clip_groups() + .into_iter() + .max_by_key(|group| group.len()) + .unwrap(); + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, video.clone())); + for _ in 0..2 { + assert!(rig.core.send_next(t0).unwrap()); + } + + rig.core.socket_full.store(true, Ordering::Relaxed); + rig.core.enqueue(group_at( + MediaKind::Audio, + t0, + &rig.policy, + one_audio_group(), + )); + for _ in 0..50 { + let step = Instant::now(); + assert!(rig.core.send_next(t0).unwrap()); + assert!( + step.elapsed() < Duration::from_millis(50), + "a blocked step must hand control back, not wait for the socket" + ); + } + thread::sleep(Duration::from_millis(100)); + assert_eq!(rig.relay.data().len(), 2, "nothing went out while it was full"); + + rig.core.socket_full.store(false, Ordering::Relaxed); + assert!(rig.core.send_next(t0).unwrap()); + assert!(wait_until(WAIT, || rig.relay.data().len() >= 3)); + assert_eq!(rig.relay.data()[2].channel, "audio"); + drain(&mut rig.core, t0); + assert_eq!(rig.core.stats().groups_sent, 2); +} + +#[test] +fn audio_goes_out_between_repair_payloads() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let (_, frame_id, frame_payloads) = send_repairable_frame(&mut rig, t0); + ask_for_chunks(&mut rig, frame_id, &[0, 1], t0, 1); + assert_eq!(rig.core.repairs.len(), 2); + + assert!(rig.core.send_next(t0).unwrap()); + rig.core.enqueue(group_at( + MediaKind::Audio, + t0, + &rig.policy, + one_audio_group(), + )); + drain(&mut rig.core, t0); + + assert!(wait_until(WAIT, || rig.relay.video_frames_on_wire().len() + == frame_payloads + 2)); + let channels = rig.relay.channels_on_wire(); + let tail = &channels[frame_payloads..]; + assert_eq!(tail.first().map(String::as_str), Some(MUNINN_MEDIA_RUDP_CHANNEL)); + assert_eq!(tail.last().map(String::as_str), Some(MUNINN_MEDIA_RUDP_CHANNEL)); + let audio = &tail[1..tail.len() - 1]; + assert!( + !audio.is_empty() && audio.iter().all(|channel| channel == "audio"), + "the audio packet went out between the two repairs: {tail:?}" + ); + assert_eq!(rig.core.feedback().repaired_video_chunks, 2); +} + +#[test] +fn the_send_loop_is_not_finished_while_a_group_or_a_repair_is_still_going_out() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let (_, frame_id, _) = send_repairable_frame(&mut rig, t0); + rig.core.disconnected = true; + assert!(rig.core.finished(), "nothing left to send"); + + ask_for_chunk(&mut rig, frame_id, t0, 1); + assert!(!rig.core.finished(), "a repair is waiting"); + drain(&mut rig.core, t0); + assert!(rig.core.finished()); + + let group = clip_groups() + .into_iter() + .find(|group| group.len() > 2) + .unwrap(); + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, group)); + assert!(rig.core.send_next(t0).unwrap()); + assert!( + !rig.core.finished(), + "the queue is empty but the frame is half sent" + ); + drain(&mut rig.core, t0); + assert!(rig.core.finished()); +} + +// ---- loss leaves a gap the receiver can see -------------------------------------------- + +#[test] +fn a_group_dropped_by_the_queue_cap_leaves_its_frame_id_missing_on_the_wire() { + let mut rig = rig(2_000, 0, 1); + let t0 = Instant::now(); + let over = 3; + let mut groups = synthetic_groups(1 + MEDIA_SEND_VIDEO_GROUP_CAP + over).into_iter(); + rig.core.enqueue(group_at( + MediaKind::Video, + t0, + &rig.policy, + groups.next().unwrap(), + )); + drain(&mut rig.core, t0); + for group in groups { + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, group)); + } + drain(&mut rig.core, t0); + + let expected: BTreeSet = std::iter::once(0) + .chain((1 + over as u64)..=(MEDIA_SEND_VIDEO_GROUP_CAP + over) as u64) + .collect(); + assert!(wait_until(WAIT, || rig.relay.frame_ids_on_wire() == expected)); + assert_eq!(rig.core.stats().groups_dropped_video, over as u64); + assert!(!rig.relay.frame_ids_on_wire().contains(&1), "frame 1 is the gap"); +} + +#[test] +fn an_expired_group_leaves_its_frame_id_missing_on_the_wire() { + let mut rig = rig(250, 0, 1); + let t0 = Instant::now(); + let budget = rig.policy.latency_budget; + let groups = synthetic_groups(3); + for (group, produced_at) in groups.into_iter().zip([t0 + 5 * budget, t0, t0 + 5 * budget]) { + rig.core + .enqueue(group_at(MediaKind::Video, produced_at, &rig.policy, group)); + } + + drain(&mut rig.core, t0 + 2 * budget); + + assert!(wait_until(WAIT, || rig.relay.frame_ids_on_wire() + == BTreeSet::from([0, 2]))); + assert_eq!(rig.core.stats().groups_expired, 1); +} + +#[test] +fn an_overflow_drop_leaves_its_frame_id_missing_and_no_partial_frame_on_the_wire() { + let mut rig = rig(2_000, 0, 1); + let mut config = video_config(); + config.max_pending_bytes = 16; + let start = [0, 0, 0, 1]; + let mut first = Vec::new(); + // Frame 0, whole; then the head of a frame that outgrows the ceiling. + first.extend_from_slice(&[&start[..], &[0x65, 0x80, 0xA1]].concat()); + first.extend_from_slice(&[&start[..], &[0x41, 0x80], &[0xB2; 30]].concat()); + let mut second = Vec::new(); + // Its second slice, then two whole frames. + second.extend_from_slice(&[&start[..], &[0x41, 0x40, 0xC3, 0xC3]].concat()); + second.extend_from_slice(&[&start[..], &[0x41, 0x80, 0xD4]].concat()); + second.extend_from_slice(&[&start[..], &[0x41, 0x80, 0xE5]].concat()); + let (tx, rx) = media_intake_channel(); + let reader = spawn_video_group_reader( + tx, + ChunkedReader([first, second].into()), + config, + rig.policy.clone(), + ); + + let started = Instant::now(); + while !rig.core.finished() && started.elapsed() < WAIT { + rig.core.intake(&rx, Duration::from_millis(2)).unwrap(); + drain(&mut rig.core, Instant::now()); + } + assert!(rig.core.finished()); + reader.join().unwrap(); + + assert!(wait_until(WAIT, || rig.relay.frame_ids_on_wire() + == BTreeSet::from([0, 2, 3]))); + assert_eq!(rig.core.stats().groups_dropped_video, 1); + assert_eq!(rig.core.stats().groups_sent, 3); +} + +// ---- moved from the mux: repair budget, feedback intake, repair cache --------------- + +#[test] +fn rudp_repair_budget_backs_off_on_media_drops_and_recovers_when_stable() { + let start = Instant::now(); + let mut budget = MuninnRudpRepairBudget { + chunks_per_second: 64, + min_chunks_per_second: 8, + max_chunks_per_second: 128, + add_chunks_per_second: 8, + recovery_interval: Duration::from_secs(2), + max_available_chunks: 4, + available_chunks: 4, + last_refill_at: start, + last_rate_adjust_at: start, + last_queue_dropped: 0, + }; + + assert_eq!(budget.take(4, start, 0), 4); + assert_eq!(budget.chunks_per_second(), 64); + assert_eq!(budget.take(3, start + Duration::from_millis(10), 1), 0); + assert_eq!(budget.chunks_per_second(), 32); + assert_eq!(budget.take(3, start + Duration::from_secs(1), 1), 3); + assert_eq!(budget.chunks_per_second(), 32); + assert_eq!(budget.take(3, start + Duration::from_secs(3), 1), 3); + assert_eq!(budget.chunks_per_second(), 40); +} + +#[test] +fn default_rudp_repair_budget_has_lan_stream_headroom() { + let mut budget = + MuninnRudpRepairBudget::new(REPAIR_INITIAL_CHUNKS_PER_SECOND, REPAIR_BURST_CHUNKS); + let start = budget.last_refill_at; + + assert_eq!(budget.chunks_per_second(), 4_096); + assert_eq!(budget.take(2_048, start, 0), 2_048); + assert_eq!(budget.take(8_192, start + Duration::from_secs(1), 0), 2_048); + assert_eq!(budget.take(8_192, start + Duration::from_secs(3), 0), 2_048); + assert_eq!(budget.chunks_per_second(), 6_144); + assert_eq!(budget.take(512, start + Duration::from_secs(4), 1), 512); + assert_eq!(budget.chunks_per_second(), 3_072); +} + +fn feedback_for( + missing_chunk_keys: Vec, + requested_keyframe: bool, +) -> GameCultMediaReceiverFeedbackRecord { + build_receiver_feedback(ReceiverFeedbackOptions { + stream_id: STREAM_ID, + session_id: VIDEO_SESSION_ID, + receiver_id: "harness-receiver", + highest_decodable_frame_id: Some(41), + missing_frame_ids: Vec::new(), + missing_video_chunk_keys: missing_chunk_keys, + late_frame_ids: vec![42, 43], + requested_keyframe, + jitter_us: 500, + decode_queue_us: 2_000, + observed_at: "unix:1000", + }) + .unwrap() +} + +fn feedback_wire(feedback: GameCultMediaReceiverFeedbackRecord) -> Vec { + encode_media_wire_record( + &GameCultMediaWireRecord::Feedback(feedback), + MediaWireProvenance { + stored_at: "unix:1000", + runtime_id: "harness", + role: "harness.receiver", + producer: "harness", + }, + ) + .unwrap() +} + +#[test] +fn rudp_media_receiver_feedback_updates_sender_pressure_stats() { + let frame = CultNetTransportFrame { + channel_id: MUNINN_MEDIA_RUDP_CHANNEL.to_string(), + payload: feedback_wire(feedback_for(vec!["42:1".into(), "42:3".into()], true)), + }; + let mut stats = MuninnRudpReceiverFeedbackStats::default(); + let repair_cache = RecentVideoChunkRepairCache::new(16); + + let repairs = + record_receiver_feedback(&frame, &mut stats, &repair_cache, Instant::now()).unwrap(); + + assert_eq!(stats.feedback_records, 1); + assert_eq!(stats.requested_keyframes, 1); + assert_eq!(stats.late_frames, 2); + assert_eq!(stats.missing_video_chunks, 2); + assert_eq!(stats.repaired_video_chunks, 0); + assert_eq!(stats.highest_decodable_frame_id, Some(41)); + assert!(repairs.is_empty()); +} + +#[test] +fn repair_cache_returns_recent_missing_video_chunks_with_their_frames_deadline() { + let groups = clip_groups(); + let payload = groups[0][0].clone(); + let (frame_id, _, chunk_index) = frame_of(&payload.payload).unwrap(); + let feedback = feedback_for( + vec![ + video_chunk_feedback_key(frame_id, chunk_index), + "999:0".to_string(), + ], + false, + ); + let deadline = Instant::now() + Duration::from_millis(250); + + let mut cache = RecentVideoChunkRepairCache::new(16); + cache.remember(&payload, deadline).unwrap(); + let repairs = cache.repair_payloads_for_feedback(&feedback, deadline); + + assert_eq!(repairs, vec![(payload.clone(), deadline)]); + assert!( + cache + .repair_payloads_for_feedback(&feedback, deadline + Duration::from_millis(1)) + .is_empty(), + "a chunk past its frame's deadline is not offered for repair" + ); +} + +// ---- the wire: whole groups, repairs inside their frame's deadline ------------------ + +#[test] +fn a_group_past_its_deadline_puts_nothing_on_the_wire_and_a_live_one_puts_all_of_it() { + let mut rig = rig(250, 0, 1); + let groups = clip_groups(); + let stale = groups[0].clone(); + let live = groups + .iter() + .skip(1) + .find(|group| group.len() > 2) + .expect("the clip has a later multi-chunk frame") + .clone(); + let live_frame = frame_of(&live[0].payload).unwrap().0; + let t0 = Instant::now(); + let budget = rig.policy.latency_budget; + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, stale)); + rig.core.enqueue(group_at( + MediaKind::Video, + t0 + 5 * budget, + &rig.policy, + live.clone(), + )); + + // Two budgets after the stale group was made, inside the live group's. + drain(&mut rig.core, t0 + 2 * budget); + + assert_eq!(rig.core.stats().groups_expired, 1); + assert_eq!(rig.core.stats().groups_sent, 1); + assert!(wait_until(WAIT, || { + rig.relay.video_frames_on_wire().len() == live.len() + })); + thread::sleep(Duration::from_millis(100)); + let on_wire = rig.relay.video_frames_on_wire(); + assert_eq!( + on_wire.len(), + live.len(), + "every payload of the live group, and no other" + ); + assert!(on_wire.iter().all(|(frame, _, _)| *frame == live_frame)); + assert!(rig.core.progress_detail().contains("groups_sent=1")); + assert!(rig.core.progress_detail().contains("groups_expired=1")); +} + +#[test] +fn audio_leaves_before_video_on_the_wire() { + let mut rig = rig(250, 0, 1); + let t0 = Instant::now(); + let video = clip_groups().remove(1); + let mut audio_sender = AudioPcmStreamSendState::new(audio_config()).unwrap(); + let audio = audio_sender.push("unix-0", &pcm_ramp()).unwrap().remove(0); + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, video)); + rig.core + .enqueue(group_at(MediaKind::Audio, t0, &rig.policy, vec![audio])); + + drain(&mut rig.core, t0); + + assert!(wait_until(WAIT, || !rig.relay.data().is_empty())); + assert_eq!(rig.relay.data()[0].channel, "audio"); +} + +/// Sends the clip's first multi-chunk frame at `t0` and returns its deadline, +/// its frame id and how many payloads it put on the wire. +fn send_repairable_frame(rig: &mut Rig, t0: Instant) -> (Instant, u64, usize) { + let group = clip_groups() + .into_iter() + .find(|group| group.len() > 2) + .unwrap(); + let (frame_id, _, _) = frame_of(&group[0].payload).unwrap(); + let queued = group_at(MediaKind::Video, t0, &rig.policy, group.clone()); + let deadline = queued.deadline; + rig.core.enqueue(queued); + drain(&mut rig.core, t0); + assert!(wait_until(WAIT, || rig.relay.video_frames_on_wire().len() + == group.len())); + (deadline, frame_id, group.len()) +} + +/// The receiver asks for chunks and the sender takes the request in at `at`. +/// Nothing is sent: that is the send step's job, at its own `now`. +fn ask_for_chunk(rig: &mut Rig, frame_id: u64, at: Instant, records_seen: u64) { + ask_for_chunks(rig, frame_id, &[0], at, records_seen); +} + +fn ask_for_chunks(rig: &mut Rig, frame_id: u64, chunks: &[u16], at: Instant, records_seen: u64) { + rig.client + .send( + MUNINN_MEDIA_RUDP_CHANNEL, + feedback_wire(feedback_for( + chunks + .iter() + .map(|chunk| video_chunk_feedback_key(frame_id, *chunk)) + .collect(), + false, + )), + ) + .unwrap(); + assert!( + wait_until(WAIT, || { + rig.core.service_control(at).unwrap(); + rig.core.feedback().feedback_records == records_seen + }), + "the hub never received the feedback" + ); +} + +#[test] +fn a_repair_is_sent_inside_its_frames_deadline_and_not_after_it() { + // Taken before the handshake, so real time is well past it by the time + // anything is sent: a repair that took its deadline from the clock + // instead of its frame would still be alive at the probe below. + let t0 = Instant::now(); + let mut rig = rig(250, 0, 1); + let (deadline, frame_id, frame_payloads) = send_repairable_frame(&mut rig, t0); + let epsilon = Duration::from_millis(2); + + ask_for_chunk(&mut rig, frame_id, deadline - epsilon, 1); + drain(&mut rig.core, deadline - epsilon); + assert!( + wait_until(WAIT, || rig.relay.video_frames_on_wire().len() + == frame_payloads + 1), + "a repair asked for just before the deadline is sent" + ); + assert_eq!(rig.core.feedback().repaired_video_chunks, 1); + + ask_for_chunk(&mut rig, frame_id, deadline + epsilon, 2); + assert!( + rig.core.repairs.is_empty(), + "a chunk already past its frame's deadline is not queued" + ); + drain(&mut rig.core, deadline + epsilon); + thread::sleep(Duration::from_millis(150)); + assert_eq!( + rig.relay.video_frames_on_wire().len(), + frame_payloads + 1, + "a repair asked for just after the deadline is not sent" + ); + assert_eq!(rig.core.feedback().repaired_video_chunks, 1); + assert_eq!(rig.core.feedback().missing_video_chunks, 2); +} + +#[test] +fn a_queued_repair_is_dropped_if_its_frames_deadline_passes_before_it_is_sent() { + let t0 = Instant::now(); + let mut rig = rig(250, 0, 1); + let (deadline, frame_id, frame_payloads) = send_repairable_frame(&mut rig, t0); + let epsilon = Duration::from_millis(2); + + // Alive when the feedback is taken in, dead by the time it is sent. + ask_for_chunk(&mut rig, frame_id, deadline - epsilon, 1); + assert_eq!(rig.core.repairs.len(), 1); + drain(&mut rig.core, deadline + epsilon); + + thread::sleep(Duration::from_millis(150)); + assert_eq!(rig.relay.video_frames_on_wire().len(), frame_payloads); + assert_eq!(rig.core.feedback().repaired_video_chunks, 0); + assert!(rig.core.repairs.is_empty()); +} + +#[test] +fn a_repair_goes_only_to_the_receiver_that_asked_for_it() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let mut other = attach_direct_receiver(&mut rig); + let (_, frame_id, frame_payloads) = send_repairable_frame(&mut rig, t0); + let heard_by_other = |other: &mut CultNetRudpSocketTransportConnection| { + let mut heard = 0; + while let Some(frame) = other.receive_once().unwrap() { + heard += usize::from(frame_of(&frame.payload).is_some()); + } + heard + }; + let mut other_heard = 0; + assert!(wait_until(WAIT, || { + other_heard += heard_by_other(&mut other); + other_heard == frame_payloads + })); + + ask_for_chunk(&mut rig, frame_id, t0, 1); + drain(&mut rig.core, t0); + + assert!(wait_until(WAIT, || rig.relay.video_frames_on_wire().len() + == frame_payloads + 1)); + thread::sleep(Duration::from_millis(150)); + other_heard += heard_by_other(&mut other); + assert_eq!(other_heard, frame_payloads, "the repair was not for this receiver"); +} + +fn attach_direct_receiver(rig: &mut Rig) -> CultNetRudpSocketTransportConnection { + let socket = UdpSocket::bind("127.0.0.1:0").unwrap(); + socket.set_nonblocking(true).unwrap(); + let mut options = CultNetRudpSocketTransportOptions::client( + "harness-receiver-b", + socket, + rig.core.hub().local_addr().unwrap(), + crate::MUNINN_MEDIA_RUDP_CONNECTION_ID, + ); + options.media_delivery = Some(CultNetTransportDelivery::Unreliable); + options.max_fragment_bytes = Some(crate::MUNINN_RUDP_MEDIA_MAX_FRAGMENT_BYTES as u32); + let mut client = CultNetRudpSocketTransportConnection::new(options).unwrap(); + client.connect(b"harness-receiver-b".to_vec()).unwrap(); + assert!( + wait_until(WAIT, || { + rig.core.service_control(Instant::now()).unwrap(); + let _ = client.receive_once().unwrap(); + rig.client.receive_once().unwrap(); + client.connected() && rig.core.hub().sessions().len() == 2 + }), + "the second receiver never attached" + ); + client +} + +// ---- the harness end to end: the fixture clip and the PCM ramp --------------------- + +#[derive(Default)] +struct Received { + chunks: BTreeMap>, + chunk_counts: BTreeMap, + audio: BTreeMap>, +} + +impl Received { + fn take(&mut self, rig: &mut Rig) { + while let Some(frame) = rig.client.receive_once().unwrap() { + match decode_media_wire_record(&frame.payload).unwrap() { + GameCultMediaWireRecord::Video(record) => { + self.chunks + .entry(record.frame_id) + .or_default() + .insert(record.chunk_index); + self.chunk_counts + .insert(record.frame_id, record.chunk_count); + } + GameCultMediaWireRecord::Audio(record) => { + self.audio.insert(record.packet_id, record.payload); + } + _ => {} + } + } + } + + fn complete_frames(&self) -> BTreeSet { + self.chunks + .iter() + .filter(|(frame, chunks)| chunks.len() == self.chunk_counts[frame] as usize) + .map(|(frame, _)| *frame) + .collect() + } +} + +/// Feeds the fixture through the real readers and the send loop, over the +/// relay, and returns what the receiver assembled. +fn run_clip(rig: &mut Rig, with_audio: bool) -> Received { + let (tx, rx) = media_intake_channel(); + let video = spawn_video_group_reader( + tx.clone(), + Cursor::new(CLIP.to_vec()), + video_config(), + rig.policy.clone(), + ); + let audio = with_audio.then(|| { + spawn_audio_group_reader( + tx.clone(), + Cursor::new(pcm_ramp()), + audio_config(), + rig.policy.clone(), + ) + }); + drop(tx); + let mut received = Received::default(); + let start = Instant::now(); + while !rig.core.finished() && start.elapsed() < WAIT { + rig.core.intake(&rx, Duration::from_millis(2)).unwrap(); + rig.core.send_next(Instant::now()).unwrap(); + rig.core.service_control(Instant::now()).unwrap(); + received.take(rig); + } + assert!(rig.core.finished(), "the send loop never finished the clip"); + let settle = Instant::now(); + while settle.elapsed() < Duration::from_millis(300) { + rig.core.service_control(Instant::now()).unwrap(); + received.take(rig); + thread::sleep(Duration::from_millis(1)); + } + video.join().unwrap(); + if let Some(audio) = audio { + audio.join().unwrap(); + } + received +} + +#[test] +fn the_clip_and_the_pcm_ramp_arrive_whole_through_a_lossless_relay() { + // A budget far above the run time: nothing here may expire. + let mut rig = rig(5_000, 0, 1); + let frames = clip_groups().len() as u64; + + let received = run_clip(&mut rig, true); + + assert_eq!( + received.complete_frames(), + (0..frames).collect::>() + ); + assert_eq!(rig.core.stats().groups_lost(), 0); + let heard: Vec = received.audio.values().flatten().copied().collect(); + assert_eq!(received.audio.len(), 10); + assert_eq!(heard, pcm_ramp(), "the ramp arrived complete and in order"); +} + +#[test] +fn the_seeded_relay_drops_the_same_datagrams_every_run_and_the_sender_carries_on() { + let run = |seed| { + let mut rig = rig(5_000, 30, seed); + let received = run_clip(&mut rig, false); + let dropped: Vec = rig.relay.data().iter().map(|sent| sent.dropped).collect(); + (received.complete_frames(), dropped, rig.core.stats().clone()) + }; + + let (complete_a, dropped_a, stats_a) = run(7); + let (complete_b, dropped_b, _) = run(7); + let (_, dropped_other, _) = run(8); + let frames = clip_groups().len(); + + assert_eq!(dropped_a, dropped_b, "same seed, same drop schedule"); + assert_ne!( + dropped_a, dropped_other, + "a different seed drops different datagrams" + ); + assert_eq!(complete_a, complete_b); + assert!(dropped_a.iter().any(|dropped| *dropped)); + assert!( + complete_a.len() < frames, + "30% loss without parity or repair leaves incomplete frames" + ); + assert_eq!(stats_a.groups_sent, frames as u64); + assert_eq!( + stats_a.groups_lost(), + 0, + "loss on the wire is not a sender-side drop" + ); +} + +#[test] +fn a_group_is_counted_by_what_the_deadline_let_reach_the_wire() { + let mut stats = MediaSendStats::default(); + + stats.record_group(&GroupSend::Complete, 6); + assert_eq!((stats.groups_sent, stats.payloads_sent), (1, 6)); + + // Deadline passed before the first payload: nothing left, so nothing was cut. + stats.record_group(&GroupSend::DeadlinePassed { payloads_out: 0 }, 6); + assert_eq!((stats.groups_expired, stats.groups_cut_short), (1, 0)); + assert_eq!(stats.payloads_sent, 6); + + // Deadline passed with part of the group already out: a partial frame. + stats.record_group(&GroupSend::DeadlinePassed { payloads_out: 2 }, 6); + assert_eq!((stats.groups_expired, stats.groups_cut_short), (1, 1)); + assert_eq!(stats.payloads_sent, 8); + assert_eq!(stats.groups_lost(), 2); +} + +#[test] +fn an_oversize_access_unit_reaches_the_sender_as_a_dropped_video_group_not_an_error() { + let policy = quiet_policy(250); + let mut core = MediaSendCore::new(test_hub(&policy), &policy); + let (tx, rx) = media_intake_channel(); + let mut config = video_config(); + config.max_pending_bytes = 8; + let mut oversize = vec![0, 0, 0, 1, 0x65, 0x80]; + oversize.extend_from_slice(&[7; 20]); + let reader = spawn_video_group_reader(tx, Cursor::new(oversize), config, policy); + + assert!(wait_until(WAIT, || reader.is_finished())); + core.intake(&rx, Duration::from_millis(50)).unwrap(); + core.intake(&rx, Duration::from_millis(50)).unwrap(); + + assert_eq!(core.stats().groups_dropped_video, 1); + assert!(core.finished(), "the stream ended cleanly, it was not restarted by an error"); +} + +// ---- the rules each get a test that fails without them -------------------------------- + +#[test] +fn an_audio_group_past_its_deadline_is_dropped_and_counted_like_a_video_group() { + let mut rig = rig(250, 0, 1); + let t0 = Instant::now(); + let budget = rig.policy.latency_budget; + rig.core.enqueue(group_at( + MediaKind::Audio, + t0, + &rig.policy, + one_audio_group(), + )); + + drain(&mut rig.core, t0 + 2 * budget); + + assert_eq!(rig.core.stats().groups_expired, 1); + assert_eq!(rig.core.stats().groups_sent, 0); + thread::sleep(Duration::from_millis(100)); + assert!(rig.relay.data().is_empty(), "stale audio reached the wire"); +} + +#[test] +fn a_repair_waiting_on_a_full_socket_stays_queued_and_goes_out_when_it_clears() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let (_, frame_id, frame_payloads) = send_repairable_frame(&mut rig, t0); + ask_for_chunk(&mut rig, frame_id, t0, 1); + assert_eq!(rig.core.repairs.len(), 1); + + rig.core.socket_full.store(true, Ordering::Relaxed); + for _ in 0..5 { + assert!(rig.core.send_next(t0).unwrap()); + } + assert_eq!(rig.core.repairs.len(), 1, "the repair was popped unsent"); + assert_eq!(rig.core.feedback().repaired_video_chunks, 0); + + rig.core.socket_full.store(false, Ordering::Relaxed); + drain(&mut rig.core, t0); + assert!(rig.core.repairs.is_empty()); + assert_eq!(rig.core.feedback().repaired_video_chunks, 1); + assert!(wait_until(WAIT, || rig.relay.video_frames_on_wire().len() + == frame_payloads + 1)); +} + +#[test] +fn a_full_socket_still_polls_resends() { + // Every datagram is dropped, so the audio packets stay unacknowledged and + // the hub owes them a resend. + let mut rig = rig(2_000, 100, 1); + let t0 = Instant::now(); + rig.core.enqueue(group_at( + MediaKind::Audio, + t0, + &rig.policy, + one_audio_group(), + )); + drain(&mut rig.core, t0); + assert!(wait_until(WAIT, || !rig.relay.data().is_empty())); + thread::sleep(Duration::from_millis(50)); + let first_pass = rig.relay.data().len(); + + // Only the full-socket path runs here: no service_control, no other poll. + rig.core.enqueue(group_at( + MediaKind::Video, + t0, + &rig.policy, + vec![marker_payload(1)], + )); + rig.core.socket_full.store(true, Ordering::Relaxed); + let started = Instant::now(); + while started.elapsed() < Duration::from_millis(300) { + assert!(rig.core.send_next(t0).unwrap()); + thread::sleep(Duration::from_millis(5)); + } + + assert!( + wait_until(WAIT, || rig.relay.data().len() > first_pass), + "no resend went out while the socket was full" + ); +} + +#[test] +fn losing_groups_slows_the_repair_budget() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let (_, frame_id, _) = send_repairable_frame(&mut rig, t0); + + // One group is lost at the sender: it dies before it is sent. + let mut doomed = group_at(MediaKind::Audio, t0, &rig.policy, one_audio_group()); + doomed.deadline = t0; + rig.core.enqueue(doomed); + drain(&mut rig.core, t0 + Duration::from_millis(1)); + assert_eq!(rig.core.stats().groups_lost(), 1); + + ask_for_chunk(&mut rig, frame_id, t0, 1); + + assert_eq!( + rig.core.feedback().repair_chunks_per_second, + REPAIR_INITIAL_CHUNKS_PER_SECOND / 2, + "the budget did not see the loss" + ); +} diff --git a/crates/muninn-daemon/testdata/clip.h264 b/crates/muninn-daemon/testdata/clip.h264 new file mode 100644 index 0000000..860d9e0 Binary files /dev/null and b/crates/muninn-daemon/testdata/clip.h264 differ diff --git a/crates/muninn-daemon/testdata/clip.h264.provenance.txt b/crates/muninn-daemon/testdata/clip.h264.provenance.txt new file mode 100644 index 0000000..3c0029b --- /dev/null +++ b/crates/muninn-daemon/testdata/clip.h264.provenance.txt @@ -0,0 +1,7 @@ +clip.h264: 15 frames of the ffmpeg testsrc2 pattern, 160x120 at 30 fps, H.264 Constrained +Baseline in Annex B with access unit delimiters, one IDR every 8 frames, no B-frames. +Generated once and committed so the media send harness needs no ffmpeg. + +Command (ffmpeg 8.1.1 full build, libx264, 2026-09-29): + +ffmpeg -f lavfi -i "testsrc2=size=160x120:rate=30:duration=0.5" -c:v libx264 -profile:v baseline -preset veryslow -crf 28 -bf 0 -g 8 -x264-params "threads=1:aud=1:repeat-headers=1:keyint=8:min-keyint=8:scenecut=0" -f h264 clip.h264 diff --git a/crates/sleipnir-daemon/Cargo.toml b/crates/sleipnir-daemon/Cargo.toml new file mode 100644 index 0000000..09e4533 --- /dev/null +++ b/crates/sleipnir-daemon/Cargo.toml @@ -0,0 +1,23 @@ +[package] +name = "sleipnir-daemon" +version = "0.1.0" +edition.workspace = true +license.workspace = true +publish.workspace = true + +[[bin]] +name = "sleipnir" +path = "src/main.rs" + +[dependencies] +anyhow = "1" +cultmesh-rs = { workspace = true } +cultnet-rs = { workspace = true } +cultcache-rs = { workspace = true } +muninn-contracts = { path = "../muninn-contracts" } +odin-core = { workspace = true } +rmp-serde = "1.3" +serde_json = "1" + +[target.'cfg(windows)'.dependencies] +vigem-client = "0.1.4" diff --git a/crates/sleipnir-daemon/src/main.rs b/crates/sleipnir-daemon/src/main.rs new file mode 100644 index 0000000..43675ce --- /dev/null +++ b/crates/sleipnir-daemon/src/main.rs @@ -0,0 +1,3112 @@ +use anyhow::{Context, Result, anyhow}; +use cultmesh_rs::{ + CultMesh, CultMeshNodeOptions, CultMeshRudpDocumentPublishOptions, CultMeshRudpSnapshotOptions, +}; +use cultnet_rs::{ + CultNetMessage, CultNetRawDocumentRecord, CultNetRawPayloadEncoding, CultNetRudpSocketMode, + CultNetRudpSocketTransportConnection, CultNetRudpSocketTransportOptions, CultNetWireContract, + encode_cultnet_message_to_vec, +}; +use muninn_contracts::{MUNINN_HID_CONTROLLER_STATE_SCHEMA, MuninnHidControllerStateRecord}; +use odin_core::{ + EVE_PROVIDER_ADVERTISEMENT_SCHEMA, EveProviderAdvertisementRecord, + IdunnDaemonHealthRecord, OdinDocuments, OdinEndpointQuery, SleipnirInputMappingRecord, + discover_provider_endpoints, +}; +use std::collections::HashMap; +use std::env; +use std::fs; +use std::net::{SocketAddr, ToSocketAddrs, UdpSocket}; +use std::path::PathBuf; +use std::thread; +use std::time::{Duration, Instant}; + +const SLEIPNIR_HID_RUDP_CONNECTION_ID: u32 = 0x6d75_0005; +const SLEIPNIR_COMMAND_ROUTE: &str = "cultmesh://odin/command/sleipnir/input_mapping"; +const SLEIPNIR_INPUT_MAPPING_SCHEMA: &str = "sleipnir.input_mapping.v1"; +const IDUNN_HEALTH_RUDP_CONNECTION_ID: u32 = 0x1d0d_0001; +const CULTNET_RUDP_PROTOCOL_ID: &str = "cultnet.transport.rudp.v0"; +const INPUT_STALE_NEUTRAL_AFTER: Duration = Duration::from_millis(1_500); +const INPUT_STREAM_RECONNECT_AFTER: Duration = Duration::from_secs(3); +const DEFAULT_STICK_DEADZONE: f32 = 0.12; +const HID_RUDP_MAX_FRAGMENT_BYTES: u32 = 1_200; + +#[derive(Clone, Debug, PartialEq, Eq)] +struct Options { + store_path: PathBuf, + discovery_store_path: Option, + mapping_path: Option, + device_filter: Option, + host_id: String, + interval_ms: u64, + odin_cultmesh_uri: Option, + rudp_bind: Option, + command_route: String, + idunn_rudp_health: Option, + once: bool, + dry_run: bool, + trace: bool, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +struct IdunnRudpHealthOptions { + endpoint: SocketAddr, + daemon_id: String, + health_contract: String, +} + +struct ActiveRudpStream { + transport: CultNetRudpSocketTransportConnection, + target: Option, + last_connect_attempt_at: Option, + connected_logged: bool, + last_frame_at: Option, + last_stale_log_at: Option, + last_subscription: Option, + last_subscription_at: Option, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +struct HidControllerRudpSubscription { + device_filter: Option, + stream_id: Option, +} + +#[derive(Clone, Debug)] +struct SleipnirRuntimeState { + provider_id: String, + selected_muninn_endpoint: Option, + selected_device_filter: Option, + presentation: String, + virtual_backend: String, + stream_state: String, + last_device_id: Option, + last_device_kind: Option, + last_sequence: Option, + last_frame_age_ms: Option, + last_input_latency: Option, + ignored_stream_frames: u64, + available_devices: Vec, + axis_map: HashMap, + button_map: HashMap, + pending_learn: Option, + updated_at: String, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +struct SleipnirInputLatencySnapshot { + device_id: String, + sequence: u64, + source_to_arrival_ms: Option, + arrival_to_buffer_ms: u128, + buffer_to_axis_ms: u128, + axis_to_hid_ms: u128, + source_to_hid_ms: Option, + total_observed_ms: u128, + axis_summary: Vec, + emitted: bool, +} + +#[derive(Clone, Debug, PartialEq)] +struct SleipnirDesiredMapping { + enabled: bool, + device_filter: Option, + stream_id: Option, + presentation: String, + axis_map: HashMap, + button_map: HashMap, + pending_learn: Option, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +struct LearnRequest { + target: String, + binding_kind: String, + requested_at: Option, +} + +#[derive(Clone, Debug, PartialEq)] +struct AxisBinding { + source: usize, + invert: bool, + scale: f32, + deadzone: f32, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +struct AvailableHidDevice { + device_id: String, + device_kind: String, + source_path: String, + stream_id: String, + host_id: String, + endpoint: String, +} + +#[derive(Clone, Debug, PartialEq)] +struct VirtualPadState { + buttons: Vec, + left_x: i16, + left_y: i16, + left_trigger: u8, + right_trigger: u8, +} + +#[derive(Clone, Debug)] +struct TimedHidRecord { + record: MuninnHidControllerStateRecord, + timing: HidRecordTiming, +} + +#[derive(Clone, Debug)] +struct HidRecordTiming { + frame_received_at: Instant, + frame_received_unix_ns: i64, + buffer_ready_at: Instant, +} + +impl Default for VirtualPadState { + fn default() -> Self { + Self { + buttons: Vec::new(), + left_x: 0, + left_y: 0, + left_trigger: 0, + right_trigger: 0, + } + } +} + +trait VirtualPadBackend { + fn update(&mut self, state: &VirtualPadState) -> Result<()>; +} + +struct LoggingBackend; + +impl VirtualPadBackend for LoggingBackend { + fn update(&mut self, state: &VirtualPadState) -> Result<()> { + println!( + "Sleipnir dry-run virtual pad lx={} ly={} lt={} rt={} buttons=[{}]", + state.left_x, + state.left_y, + state.left_trigger, + state.right_trigger, + state.buttons.join(",") + ); + Ok(()) + } +} + +#[cfg(windows)] +struct VigemXboxBackend { + target: vigem_client::Xbox360Wired, +} + +#[cfg(windows)] +impl VigemXboxBackend { + fn connect() -> Result { + let client = vigem_client::Client::connect().context("connecting to ViGEmBus")?; + let mut target = + vigem_client::Xbox360Wired::new(client, vigem_client::TargetId::XBOX360_WIRED); + target + .plugin() + .context("plugging in virtual Xbox 360 controller")?; + target + .wait_ready() + .context("waiting for virtual Xbox 360 controller readiness")?; + Ok(Self { target }) + } +} + +#[cfg(windows)] +impl VirtualPadBackend for VigemXboxBackend { + fn update(&mut self, state: &VirtualPadState) -> Result<()> { + let mut raw_buttons = 0u16; + for button in &state.buttons { + raw_buttons |= xbutton_mask(button); + } + let gamepad = vigem_client::XGamepad { + buttons: vigem_client::XButtons::from(raw_buttons), + left_trigger: state.left_trigger, + right_trigger: state.right_trigger, + thumb_lx: state.left_x, + thumb_ly: state.left_y, + thumb_rx: 0, + thumb_ry: 0, + ..Default::default() + }; + self.target + .update(&gamepad) + .context("updating virtual Xbox 360 controller") + } +} + +#[cfg(windows)] +fn xbutton_mask(button: &str) -> u16 { + match button { + "up" => vigem_client::XButtons::UP, + "down" => vigem_client::XButtons::DOWN, + "left" => vigem_client::XButtons::LEFT, + "right" => vigem_client::XButtons::RIGHT, + "start" => vigem_client::XButtons::START, + "select" | "back" => vigem_client::XButtons::BACK, + "l3" => vigem_client::XButtons::LTHUMB, + "r3" => vigem_client::XButtons::RTHUMB, + "l1" => vigem_client::XButtons::LB, + "r1" => vigem_client::XButtons::RB, + "ps" | "guide" => vigem_client::XButtons::GUIDE, + "cross" | "a" => vigem_client::XButtons::A, + "circle" | "o" | "b" => vigem_client::XButtons::B, + "square" | "x" => vigem_client::XButtons::X, + "triangle" | "y" => vigem_client::XButtons::Y, + _ => 0, + } +} + +fn main() -> Result<()> { + let options = Options::parse(env::args().skip(1))?; + let mut node = CultMesh::create_node( + &options.store_path, + OdinDocuments, + CultMeshNodeOptions { + runtime_id: "sleipnir-daemon".to_string(), + pull_on_start: true, + }, + ) + .with_context(|| format!("opening CultMesh store {}", options.store_path.display()))?; + let mut discovery_node = + if let Some(discovery_store_path) = options.discovery_store_path.as_ref() { + Some( + CultMesh::create_node( + discovery_store_path, + OdinDocuments, + CultMeshNodeOptions { + runtime_id: "sleipnir-discovery".to_string(), + pull_on_start: true, + }, + ) + .with_context(|| { + format!( + "opening Sleipnir discovery CultMesh store {}", + discovery_store_path.display() + ) + })?, + ) + } else { + None + }; + pull_odin_catalog_snapshot(discovery_node.as_mut().unwrap_or(&mut node), &options); + + let mut desired_mapping = + read_desired_mapping_from_sources(&mut node, discovery_node.as_mut(), &options); + let mut backend: Box = if options.dry_run { + Box::new(LoggingBackend) + } else { + create_backend()? + }; + let mut current_device_filter = effective_device_filter(&options, &desired_mapping); + let discovered_endpoint = if desired_mapping.enabled { + effective_muninn_hid_endpoint( + discovery_node.as_ref().unwrap_or(&node), + current_device_filter.as_deref(), + desired_mapping.stream_id.as_deref(), + options.trace, + ) + } else { + None + }; + if options.trace { + if !desired_mapping.enabled { + eprintln!("Sleipnir input consumption is disabled; publishing control surface only"); + } else { + match discovered_endpoint.as_deref() { + Some(endpoint) => eprintln!("Sleipnir selected Muninn HID endpoint {endpoint}"), + None => eprintln!("Sleipnir found no Odin-discovered Muninn HID endpoint; waiting"), + } + } + } + let mut rudp_stream = + create_rudp_stream(options.rudp_bind, discovered_endpoint, options.trace)?; + let mut last_rudp_discovery_attempt_at = Instant::now(); + let initial_state = { + let discovery_ref = discovery_node.as_ref().unwrap_or(&node); + SleipnirRuntimeState::from_runtime( + &options, + current_device_filter.as_deref(), + discovery_ref, + rudp_stream.as_ref(), + None, + 0, + &desired_mapping, + None, + ) + }; + publish_sleipnir_provider(&mut node, &options, &initial_state, true)?; + let mut last_idunn_health_attempt_at = Instant::now() - Duration::from_secs(60); + publish_idunn_health_if_configured(&options, &initial_state, &mut last_idunn_health_attempt_at); + + let mut last_sequence_by_device = HashMap::::new(); + let mut ignored_stream_frames = 0u64; + let mut last_surface_publish_at = Instant::now() - Duration::from_secs(60); + let mut last_odin_catalog_pull_at = Instant::now() - Duration::from_secs(60); + let mut recent_applied_record: Option = None; + let mut recent_input_latency: Option = None; + let mut output_is_neutral = true; + let mut last_output_frame_at: Option = None; + let mut last_output_source_timestamp_ns: Option = None; + loop { + let input_stream_needs_discovery = rudp_stream + .as_ref() + .is_none_or(|stream| stream.target.is_none()); + if input_stream_needs_discovery + && last_odin_catalog_pull_at.elapsed() >= Duration::from_secs(2) + { + pull_odin_catalog_snapshot(discovery_node.as_mut().unwrap_or(&mut node), &options); + last_odin_catalog_pull_at = Instant::now(); + } + let next_desired_mapping = + read_desired_mapping_from_sources(&mut node, discovery_node.as_mut(), &options); + if next_desired_mapping != desired_mapping { + desired_mapping = next_desired_mapping; + current_device_filter = effective_device_filter(&options, &desired_mapping); + let rediscovered_endpoint = if desired_mapping.enabled { + effective_muninn_hid_endpoint( + discovery_node.as_ref().unwrap_or(&node), + current_device_filter.as_deref(), + desired_mapping.stream_id.as_deref(), + options.trace, + ) + } else { + None + }; + if options.trace { + eprintln!( + "Sleipnir mapping changed device={:?} discovered_muninn_endpoint={:?}", + current_device_filter, rediscovered_endpoint + ); + } + backend.update(&VirtualPadState::default())?; + output_is_neutral = true; + last_output_frame_at = Some(Instant::now()); + last_output_source_timestamp_ns = None; + drop(rudp_stream.take()); + rudp_stream = + create_rudp_stream(options.rudp_bind, rediscovered_endpoint, options.trace)?; + last_sequence_by_device.clear(); + } + let mut last_applied_record: Option = None; + if let Some(stream) = rudp_stream.as_mut() { + if ensure_rudp_connected(stream, options.trace)? { + if !output_is_neutral { + backend.update(&VirtualPadState::default())?; + output_is_neutral = true; + last_output_frame_at = Some(Instant::now()); + last_output_source_timestamp_ns = None; + if options.trace { + eprintln!( + "Sleipnir neutralized virtual pad before recreating stale Muninn HID RUDP connection for filter={:?}", + current_device_filter + ); + } + } + let rediscovered_endpoint = if desired_mapping.enabled { + effective_muninn_hid_endpoint( + discovery_node.as_ref().unwrap_or(&node), + current_device_filter.as_deref(), + desired_mapping.stream_id.as_deref(), + options.trace, + ) + } else { + None + }; + drop(rudp_stream.take()); + rudp_stream = + create_rudp_stream(options.rudp_bind, rediscovered_endpoint, options.trace)?; + last_rudp_discovery_attempt_at = Instant::now(); + } else { + send_hid_subscription_if_due( + stream, + current_device_filter.clone(), + desired_mapping.stream_id.clone(), + options.trace, + )?; + let records = receive_rudp_records(stream, options.trace)?; + for timed_record in records { + let record = timed_record.record; + let timing = timed_record.timing; + if record_matches_filter(&record, current_device_filter.as_deref()) { + stream.last_frame_at = Some(Instant::now()); + stream.last_stale_log_at = None; + if desired_mapping.pending_learn.is_some() { + if let Some(updated_mapping) = + apply_pending_learn(&mut node, &options, &desired_mapping, &record)? + { + desired_mapping = updated_mapping; + } + } + let previous = last_sequence_by_device + .insert(record.device_id.clone(), record.sequence) + .unwrap_or_default(); + let has_new_sequence = record.sequence != previous || options.once; + let has_new_source_timestamp = last_output_source_timestamp_ns + .is_none_or(|last| record.source_timestamp_ns > last); + if has_new_sequence && has_new_source_timestamp { + let state = map_record_to_virtual_pad(&record, &desired_mapping); + let axis_classified_at = Instant::now(); + let output_frame_at = Instant::now(); + if options.trace { + let source_age_ms = unix_nanos_i64() + .saturating_sub(record.source_timestamp_ns) + / 1_000_000; + eprintln!( + "Sleipnir applying fast HID frame device={} seq={} source_age_ms={} lx={} ly={} lt={} rt={} buttons=[{}]", + record.device_id, + record.sequence, + source_age_ms, + state.left_x, + state.left_y, + state.left_trigger, + state.right_trigger, + state.buttons.join(",") + ); + } + match backend.update(&state) { + Ok(()) => { + let hid_emitted_at = Instant::now(); + recent_input_latency = Some(input_latency_snapshot( + &record, + &timing, + axis_classified_at, + hid_emitted_at, + &desired_mapping, + true, + )); + output_is_neutral = state == VirtualPadState::default(); + last_output_frame_at = Some(output_frame_at); + last_output_source_timestamp_ns = + Some(record.source_timestamp_ns); + last_applied_record = Some(record); + } + Err(error) => { + eprintln!( + "Sleipnir virtual pad update failed for device={} seq={}: {error:#}", + record.device_id, record.sequence + ); + recent_input_latency = Some(input_latency_snapshot( + &record, + &timing, + axis_classified_at, + Instant::now(), + &desired_mapping, + false, + )); + last_applied_record = Some(record); + } + } + } + } else if options.trace { + ignored_stream_frames = ignored_stream_frames.saturating_add(1); + if ignored_stream_frames <= 5 || ignored_stream_frames % 120 == 0 { + eprintln!( + "Sleipnir ignored fast HID frame device={} kind={} stream={} filter={:?}", + record.device_id, + record.device_kind, + record.stream_id, + options.device_filter + ); + } + } + } + if desired_mapping.enabled + && !output_is_neutral + && last_output_frame_at + .is_none_or(|last_frame| last_frame.elapsed() >= INPUT_STALE_NEUTRAL_AFTER) + { + let stale_for = last_output_frame_at.map(|last_frame| last_frame.elapsed()); + backend.update(&VirtualPadState::default())?; + output_is_neutral = true; + last_output_frame_at = Some(Instant::now()); + if options.trace { + eprintln!( + "Sleipnir neutralized virtual pad after {:?} without a new selected input sequence for filter={:?}", + stale_for, current_device_filter + ); + } + } + } + } else if last_rudp_discovery_attempt_at.elapsed() >= Duration::from_secs(2) { + let rediscovered_endpoint = if desired_mapping.enabled { + effective_muninn_hid_endpoint( + discovery_node.as_ref().unwrap_or(&node), + current_device_filter.as_deref(), + desired_mapping.stream_id.as_deref(), + options.trace, + ) + } else { + None + }; + if rediscovered_endpoint.is_some() { + drop(rudp_stream.take()); + rudp_stream = + create_rudp_stream(options.rudp_bind, rediscovered_endpoint, options.trace)?; + let runtime_state = { + let discovery_ref = discovery_node.as_ref().unwrap_or(&node); + SleipnirRuntimeState::from_runtime( + &options, + current_device_filter.as_deref(), + discovery_ref, + rudp_stream.as_ref(), + recent_applied_record.as_ref(), + ignored_stream_frames, + &desired_mapping, + recent_input_latency.as_ref(), + ) + }; + publish_sleipnir_provider(&mut node, &options, &runtime_state, true)?; + publish_idunn_health_if_configured( + &options, + &runtime_state, + &mut last_idunn_health_attempt_at, + ); + } else if options.trace && desired_mapping.enabled { + eprintln!("Sleipnir still has no Odin-discovered Muninn HID endpoint"); + } + last_rudp_discovery_attempt_at = Instant::now(); + } + let surface_age = last_surface_publish_at.elapsed(); + let has_new_applied_record = last_applied_record.is_some(); + let missing_input_target = rudp_stream + .as_ref() + .is_none_or(|stream| stream.target.is_none()); + if let Some(record) = last_applied_record.as_ref() { + recent_applied_record = Some(record.clone()); + } + if (has_new_applied_record && surface_age >= Duration::from_secs(1)) + || (missing_input_target && surface_age >= Duration::from_secs(5)) + { + let runtime_state = { + let discovery_ref = discovery_node.as_ref().unwrap_or(&node); + SleipnirRuntimeState::from_runtime( + &options, + current_device_filter.as_deref(), + discovery_ref, + rudp_stream.as_ref(), + recent_applied_record.as_ref(), + ignored_stream_frames, + &desired_mapping, + recent_input_latency.as_ref(), + ) + }; + publish_sleipnir_provider( + &mut node, + &options, + &runtime_state, + has_new_applied_record, + )?; + publish_idunn_health_if_configured( + &options, + &runtime_state, + &mut last_idunn_health_attempt_at, + ); + last_surface_publish_at = Instant::now(); + } + if options.once { + break; + } + thread::sleep(Duration::from_millis(options.interval_ms.max(1))); + } + Ok(()) +} + +impl SleipnirRuntimeState { + fn from_runtime( + options: &Options, + selected_device_filter: Option<&str>, + discovery_node: &cultmesh_rs::CultMeshNode, + stream: Option<&ActiveRudpStream>, + last_record: Option<&MuninnHidControllerStateRecord>, + ignored_stream_frames: u64, + desired_mapping: &SleipnirDesiredMapping, + last_input_latency: Option<&SleipnirInputLatencySnapshot>, + ) -> Self { + let has_recent_frame = stream + .and_then(|stream| stream.last_frame_at) + .is_some_and(|last_frame| last_frame.elapsed() < Duration::from_secs(3)); + let stream_state = match stream { + _ if !desired_mapping.enabled => "idle", + Some(_) if has_recent_frame => "connected", + Some(stream) if stream.transport.connected() => "connected", + Some(stream) if stream.target.is_some() => "connecting", + Some(_) => "listening", + None => "discovering", + } + .to_string(); + let selected_muninn_endpoint = stream + .and_then(|stream| stream.target) + .map(|target| target.to_string()); + let mut available_devices = discover_available_hid_devices(discovery_node); + if let (Some(record), Some(endpoint)) = (last_record, selected_muninn_endpoint.as_deref()) { + upsert_available_hid_device( + &mut available_devices, + AvailableHidDevice { + device_id: record.device_id.clone(), + device_kind: record.device_kind.clone(), + source_path: record.source_path.clone(), + stream_id: record.stream_id.clone(), + host_id: record.host_id.clone(), + endpoint: endpoint.to_string(), + }, + ); + } + Self { + provider_id: sleipnir_provider_id(options), + selected_muninn_endpoint, + selected_device_filter: selected_device_filter.map(ToString::to_string), + presentation: default_presentation(), + virtual_backend: if options.dry_run { + "logging.dry-run" + } else if cfg!(windows) { + "vigem.xbox360" + } else { + "unavailable" + } + .to_string(), + stream_state, + last_device_id: last_record.map(|record| record.device_id.clone()), + last_device_kind: last_record.map(|record| record.device_kind.clone()), + last_sequence: last_record.map(|record| record.sequence), + last_frame_age_ms: stream + .and_then(|stream| stream.last_frame_at) + .map(|last_frame| last_frame.elapsed().as_millis()), + last_input_latency: last_input_latency.cloned(), + ignored_stream_frames, + available_devices, + axis_map: desired_mapping.axis_map.clone(), + button_map: desired_mapping.button_map.clone(), + pending_learn: desired_mapping.pending_learn.clone(), + updated_at: timestamp(), + } + } +} + +fn publish_sleipnir_provider( + node: &mut cultmesh_rs::CultMeshNode, + options: &Options, + state: &SleipnirRuntimeState, + publish_remote: bool, +) -> Result<()> { + let mut advertisement = EveProviderAdvertisementRecord { + value: serde_json::json!({ + "schema": "gamecult.eve.provider_advertisement.v1", + "providerId": state.provider_id, + "daemonId": sleipnir_daemon_id(options), + "title": sleipnir_provider_title(options), + "description": "Sleipnir mirrors Muninn-discovered input streams into a local virtual HID backend.", + "canonicalService": "asgard.sleipnir", + "locatedService": format!("asgard.{}.sleipnir", options.host_id), + "verseId": format!("{}.local", options.host_id), + "cultMeshAddress": format!("asgard.{}.sleipnir/input-mirror", options.host_id), + "status": state.stream_state, + "mode": "daemon-live", + "updatedAt": state.updated_at, + "stateStore": options.store_path.display().to_string(), + "surfaceId": state.provider_id, + "capabilities": [ + "muninn.input.discovery", + "cultmesh.input.stream.consumer", + "virtual-hid.xinput" + ], + "endpoints": [ + { + "transport": "cultcache-store", + "address": options.store_path.display().to_string() + } + ], + "routes": [ + { + "transport": "cultcache-store", + "address": options.store_path.display().to_string() + } + ] + }), + }; + if let Some(routes) = advertisement + .value + .get_mut("routes") + .and_then(|value| value.as_array_mut()) + { + routes.push(serde_json::json!({ + "transport": "cultnet.transport.rudp.v0", + "address": options.command_route, + "resolver": "odin-cultmesh", + "schema": SLEIPNIR_INPUT_MAPPING_SCHEMA, + "role": "sleipnir.input_mapping.command", + "channel": "schema" + })); + } + node.put(&state.provider_id, &advertisement)?; + if publish_remote && let Some(target) = resolve_odin_cultmesh_uri(options) { + if let Err(error) = node.publish_document_to_rudp_catalog( + &state.provider_id, + &advertisement, + CultMeshRudpDocumentPublishOptions { + target, + runtime_id: sleipnir_daemon_id(options), + source_role: Some("sleipnir.input-mirror-provider".to_string()), + tags: vec!["sleipnir".to_string(), "odin-verse-discovery".to_string()], + ..CultMeshRudpDocumentPublishOptions::default() + }, + ) { + if options.trace { + eprintln!("Sleipnir could not publish provider advertisement to Odin: {error:#}"); + } + } + } + Ok(()) +} + +fn publish_idunn_health_if_configured( + options: &Options, + state: &SleipnirRuntimeState, + last_attempt_at: &mut Instant, +) { + let Some(idunn) = options.idunn_rudp_health.as_ref() else { + return; + }; + if last_attempt_at.elapsed() < Duration::from_secs(5) { + return; + } + *last_attempt_at = Instant::now(); + let health_state = if state.stream_state == "connected" || state.stream_state == "idle" { + "active" + } else { + "degraded" + }; + let detail = format!( + "Sleipnir {}: endpoint={} device={} sequence={} age_ms={}", + state.stream_state, + state + .selected_muninn_endpoint + .as_deref() + .unwrap_or("discovering"), + state + .selected_device_filter + .as_deref() + .unwrap_or("unselected"), + state + .last_sequence + .map(|sequence| sequence.to_string()) + .unwrap_or_else(|| "none".to_string()), + state + .last_frame_age_ms + .map(|age| age.to_string()) + .unwrap_or_else(|| "none".to_string()) + ); + if let Err(error) = publish_idunn_rudp_health(idunn, health_state, &detail, &state.updated_at) { + if options.trace { + eprintln!( + "Sleipnir could not publish Idunn RUDP health for {} at {}: {error:#}", + idunn.daemon_id, state.updated_at + ); + } + } +} + +fn publish_idunn_rudp_health( + options: &IdunnRudpHealthOptions, + state: &str, + detail: &str, + observed_at: &str, +) -> Result<()> { + let health = IdunnDaemonHealthRecord { + daemon_id: options.daemon_id.clone(), + state: state.to_string(), + detail: detail.to_string(), + observed_at: observed_at.to_string(), + health_contract: options.health_contract.clone(), + publication_source: "daemon-published".to_string(), + transport: CULTNET_RUDP_PROTOCOL_ID.to_string(), + }; + let message = CultNetMessage::DocumentPutRaw { + message_id: format!( + "sleipnir-health:{}:{}", + options.daemon_id, + observed_at.replace(':', "-") + ), + document: CultNetRawDocumentRecord { + schema_id: "idunn.daemon_health".to_string(), + record_key: options.daemon_id.clone(), + stored_at: observed_at.to_string(), + payload_encoding: CultNetRawPayloadEncoding::Messagepack, + payload: rmp_serde::to_vec(&health).context("encoding Idunn daemon health")?, + source_runtime_id: Some("sleipnir-daemon".to_string()), + source_agent_id: None, + source_role: Some("daemon-health-publisher".to_string()), + tags: Some(vec![CULTNET_RUDP_PROTOCOL_ID.to_string()]), + }, + }; + let bind_address = if options.endpoint.is_ipv4() { + "0.0.0.0:0" + } else { + "[::]:0" + }; + let socket = UdpSocket::bind(bind_address) + .with_context(|| format!("binding Sleipnir Idunn RUDP sender at {bind_address}"))?; + socket.set_read_timeout(Some(Duration::from_millis(100)))?; + let mut transport = + CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions::client( + "sleipnir-daemon", + socket, + options.endpoint, + IDUNN_HEALTH_RUDP_CONNECTION_ID, + ))?; + transport.connect(Vec::new())?; + let deadline = Instant::now() + Duration::from_millis(300); + while !transport.connected() { + let _ = transport.receive_once()?; + transport.poll_resends()?; + if Instant::now() >= deadline { + return Err(anyhow!( + "timed out connecting Sleipnir RUDP sender to {}", + options.endpoint + )); + } + } + let payload = encode_cultnet_message_to_vec(&message, CultNetWireContract::CultNetSchemaV0) + .context("encoding Idunn health CultNet message")?; + transport + .send("schema", payload) + .with_context(|| format!("sending Sleipnir Idunn health to {}", options.endpoint))?; + Ok(()) +} + +fn resolve_odin_cultmesh_uri(options: &Options) -> Option { + let uri = options.odin_cultmesh_uri.as_deref()?.trim(); + if uri.is_empty() { + return None; + } + match CultMesh::resolve_rudp_endpoint(uri) { + Ok(target) => Some(target), + Err(error) => { + if options.trace { + eprintln!("Sleipnir could not resolve Odin CultMesh URI {uri}: {error:#}"); + } + None + } + } +} + +fn pull_odin_catalog_snapshot(node: &mut cultmesh_rs::CultMeshNode, options: &Options) { + let Some(target) = resolve_odin_cultmesh_uri(options) else { + return; + }; + let hid_result = node.pull_rudp_catalog_snapshot(CultMeshRudpSnapshotOptions { + target, + runtime_id: format!("sleipnir-{}-catalog-client", options.host_id), + schema_ids: Some(vec![ + MUNINN_HID_CONTROLLER_STATE_SCHEMA.to_string(), + SLEIPNIR_INPUT_MAPPING_SCHEMA.to_string(), + ]), + connect_timeout: Duration::from_millis(150), + response_timeout: Duration::from_millis(150), + resend_delay_ms: 15, + ..CultMeshRudpSnapshotOptions::default() + }); + match hid_result { + Ok(count) if options.trace => { + eprintln!("Sleipnir pulled {count} Odin HID/mapping discovery records from {target}"); + } + Ok(_) => {} + Err(error) if options.trace => { + eprintln!("Sleipnir Odin HID/mapping snapshot pull failed from {target}: {error:#}"); + } + Err(_) => return, + } + + let provider_keys = muninn_provider_keys_for_discovered_hid_hosts(node); + if provider_keys.is_empty() { + return; + } + let provider_result = node.pull_rudp_catalog_snapshot(CultMeshRudpSnapshotOptions { + target, + runtime_id: format!("sleipnir-{}-provider-catalog-client", options.host_id), + schema_ids: Some(vec![EVE_PROVIDER_ADVERTISEMENT_SCHEMA.to_string()]), + record_keys: Some(provider_keys), + connect_timeout: Duration::from_millis(150), + response_timeout: Duration::from_millis(150), + resend_delay_ms: 15, + ..CultMeshRudpSnapshotOptions::default() + }); + match provider_result { + Ok(count) if options.trace => { + eprintln!("Sleipnir pulled {count} Odin Muninn provider records from {target}"); + } + Ok(_) => {} + Err(error) if options.trace => { + eprintln!( + "Sleipnir Odin Muninn provider snapshot pull failed from {target}: {error:#}" + ); + } + Err(_) => {} + } +} + +fn muninn_provider_keys_for_discovered_hid_hosts(node: &cultmesh_rs::CultMeshNode) -> Vec { + let mut keys = node + .cache() + .get_all::() + .ok() + .into_iter() + .flatten() + .map(|record| format!("muninn.telemetry.{}", record.host_id)) + .collect::>(); + for envelope in node.cache().snapshot() { + if envelope.schema_id.as_deref() != Some(MUNINN_HID_CONTROLLER_STATE_SCHEMA) + && envelope.r#type != "muninn.hid_controller_state" + { + continue; + } + let Ok(value) = rmp_serde::from_slice::(&envelope.payload) else { + continue; + }; + if let Some(host_id) = hid_state_host_id_from_value(&value) { + keys.push(format!("muninn.telemetry.{host_id}")); + } + } + keys.sort(); + keys.dedup(); + keys +} + +fn hid_state_host_id_from_value(value: &serde_json::Value) -> Option { + let payload = value + .as_array() + .and_then(|items| { + (items.len() == 1) + .then(|| items.first()) + .flatten() + .filter(|item| item.is_object() || item.is_array()) + }) + .unwrap_or(value); + if let Some(items) = payload.as_array() { + return items.get(1)?.as_str().map(ToString::to_string); + } + string_field(payload, &["host_id", "hostId"]) +} + +fn read_desired_mapping( + node: &mut cultmesh_rs::CultMeshNode, + options: &Options, +) -> SleipnirDesiredMapping { + read_desired_mapping_from_sources(node, None, options) +} + +fn read_desired_mapping_from_sources( + local_node: &mut cultmesh_rs::CultMeshNode, + discovery_node: Option<&mut cultmesh_rs::CultMeshNode>, + options: &Options, +) -> SleipnirDesiredMapping { + let local_record = read_desired_mapping_record(local_node, options); + let discovery_record = + discovery_node.and_then(|node| read_desired_mapping_record(node, options)); + if let Some(record) = newest_sleipnir_mapping_record(local_record, discovery_record) { + return desired_mapping_from_record(record); + } + options + .mapping_path + .as_ref() + .and_then(|path| read_legacy_mapping_file(path)) + .unwrap_or_else(default_desired_mapping) +} + +fn read_desired_mapping_record( + node: &mut cultmesh_rs::CultMeshNode, + options: &Options, +) -> Option { + let _ = node.pull_all_backing_stores(); + node.get::(&sleipnir_provider_id(options)) + .ok() + .flatten() +} + +fn newest_sleipnir_mapping_record( + local: Option, + discovery: Option, +) -> Option { + match (local, discovery) { + (Some(local), Some(discovery)) if discovery.updated_at > local.updated_at => { + Some(discovery) + } + (Some(local), Some(_)) => Some(local), + (Some(local), None) => Some(local), + (None, Some(discovery)) => Some(discovery), + (None, None) => None, + } +} + +fn default_desired_mapping() -> SleipnirDesiredMapping { + SleipnirDesiredMapping { + enabled: false, + device_filter: None, + stream_id: None, + presentation: default_presentation(), + axis_map: default_axis_map(), + button_map: default_button_map(), + pending_learn: None, + } +} + +fn desired_mapping_from_record(record: SleipnirInputMappingRecord) -> SleipnirDesiredMapping { + SleipnirDesiredMapping { + enabled: record.enabled, + device_filter: Some(record.device_filter) + .filter(|value| !value.trim().is_empty()) + .map(|value| value.to_string()), + stream_id: Some(record.stream_id) + .filter(|value| !value.trim().is_empty()) + .map(|value| value.to_string()), + presentation: normalize_presentation(&record.presentation), + axis_map: parse_axis_map(Some(&record.axis_map)), + button_map: parse_button_map(Some(&record.button_map)), + pending_learn: parse_learn_request(Some(&record.pending_learn)), + } +} + +fn read_legacy_mapping_file(path: &PathBuf) -> Option { + let text = fs::read_to_string(path).ok()?; + let value = + serde_json::from_str::(text.trim_start_matches('\u{feff}')).ok()?; + Some(SleipnirDesiredMapping { + enabled: false, + device_filter: value + .get("deviceFilter") + .or_else(|| value.get("device_filter")) + .and_then(|value| value.as_str()) + .filter(|value| !value.trim().is_empty()) + .map(ToString::to_string), + stream_id: value + .get("streamId") + .or_else(|| value.get("stream_id")) + .and_then(|value| value.as_str()) + .filter(|value| !value.trim().is_empty()) + .map(ToString::to_string), + presentation: normalize_presentation( + value + .get("presentation") + .or_else(|| value.get("presentationProfile")) + .or_else(|| value.get("presentation_profile")) + .and_then(|value| value.as_str()) + .filter(|value| !value.trim().is_empty()) + .unwrap_or("xbox360"), + ), + axis_map: parse_axis_map(value.get("axisMap").or_else(|| value.get("axis_map"))), + button_map: parse_button_map(value.get("buttonMap").or_else(|| value.get("button_map"))), + pending_learn: parse_learn_request( + value + .get("pendingLearn") + .or_else(|| value.get("pending_learn")) + .or_else(|| value.get("learn")), + ), + }) +} + +fn parse_learn_request(value: Option<&serde_json::Value>) -> Option { + let map = value?.as_object()?; + let target = map + .get("target") + .or_else(|| map.get("buttonTarget")) + .or_else(|| map.get("axisTarget")) + .and_then(|value| value.as_str()) + .filter(|value| !value.trim().is_empty())? + .to_string(); + let binding_kind = map + .get("bindingKind") + .or_else(|| map.get("kind")) + .and_then(|value| value.as_str()) + .filter(|value| !value.trim().is_empty()) + .unwrap_or("button") + .to_string(); + Some(LearnRequest { + target, + binding_kind, + requested_at: map + .get("requestedAt") + .or_else(|| map.get("requested_at")) + .and_then(|value| value.as_str()) + .map(ToString::to_string), + }) +} + +fn default_presentation() -> String { + "xbox360".to_string() +} + +fn normalize_presentation(_presentation: &str) -> String { + default_presentation() +} + +fn default_axis_map() -> HashMap { + HashMap::from([ + ("leftX".to_string(), AxisBinding::stick_source(0)), + ( + "leftY".to_string(), + AxisBinding { + source: 1, + invert: true, + scale: 1.0, + deadzone: DEFAULT_STICK_DEADZONE, + }, + ), + ("leftTrigger".to_string(), AxisBinding::source(2)), + ("rightTrigger".to_string(), AxisBinding::source(5)), + ]) +} + +fn default_button_map() -> HashMap { + HashMap::from([ + ("trigger".to_string(), "none".to_string()), + ("l2".to_string(), "none".to_string()), + ]) +} + +impl AxisBinding { + fn source(source: usize) -> Self { + Self { + source, + invert: false, + scale: 1.0, + deadzone: 0.0, + } + } + + fn stick_source(source: usize) -> Self { + Self { + source, + invert: false, + scale: 1.0, + deadzone: DEFAULT_STICK_DEADZONE, + } + } +} + +fn parse_axis_map(value: Option<&serde_json::Value>) -> HashMap { + let mut axis_map = default_axis_map(); + let Some(map) = value.and_then(|value| value.as_object()) else { + return axis_map; + }; + for (target, binding) in map { + if let Some(binding) = parse_axis_binding(binding) { + axis_map.insert(target.clone(), binding); + } + } + axis_map +} + +fn parse_axis_binding(value: &serde_json::Value) -> Option { + if let Some(source) = value.as_u64() { + return Some(AxisBinding::source(source as usize)); + } + let map = value.as_object()?; + let source = map + .get("source") + .or_else(|| map.get("axis")) + .and_then(|value| value.as_u64())? as usize; + Some(AxisBinding { + source, + invert: map + .get("invert") + .and_then(|value| value.as_bool()) + .unwrap_or(false), + scale: map + .get("scale") + .and_then(|value| value.as_f64()) + .unwrap_or(1.0) as f32, + deadzone: map + .get("deadzone") + .and_then(|value| value.as_f64()) + .unwrap_or(0.0) as f32, + }) +} + +fn parse_button_map(value: Option<&serde_json::Value>) -> HashMap { + value + .and_then(|value| value.as_object()) + .map(|map| { + map.iter() + .filter_map(|(source, target)| { + target + .as_str() + .filter(|target| !target.trim().is_empty()) + .map(|target| (source.clone(), target.to_string())) + }) + .collect() + }) + .unwrap_or_else(default_button_map) +} + +fn apply_pending_learn( + node: &mut cultmesh_rs::CultMeshNode, + options: &Options, + mapping: &SleipnirDesiredMapping, + record: &MuninnHidControllerStateRecord, +) -> Result> { + let Some(learn) = mapping.pending_learn.as_ref() else { + return Ok(None); + }; + let mut updated = mapping.clone(); + let learned = if learn.binding_kind == "axis" { + if let Some(source) = most_active_axis(&record.axes) { + updated.axis_map.insert( + learn.target.clone(), + AxisBinding { + source, + invert: learn.target == "leftY" || learn.target == "rightY", + scale: 1.0, + deadzone: 0.0, + }, + ); + true + } else { + false + } + } else if let Some(source) = record.buttons.first() { + updated + .button_map + .insert(source.clone(), learn.target.clone()); + true + } else { + false + }; + if !learned { + return Ok(None); + } + updated.pending_learn = None; + updated.enabled = true; + write_desired_mapping(node, options, &updated, "sleipnir.auto-bind")?; + Ok(Some(updated)) +} + +fn most_active_axis(axes: &[f32]) -> Option { + axes.iter() + .enumerate() + .filter(|(_, value)| value.abs() >= 0.45) + .max_by(|(_, left), (_, right)| { + left.abs() + .partial_cmp(&right.abs()) + .unwrap_or(std::cmp::Ordering::Equal) + }) + .map(|(index, _)| index) +} + +fn write_desired_mapping( + node: &mut cultmesh_rs::CultMeshNode, + options: &Options, + mapping: &SleipnirDesiredMapping, + source: &str, +) -> Result<()> { + let provider_id = sleipnir_provider_id(options); + let record = SleipnirInputMappingRecord { + provider_id: provider_id.clone(), + enabled: mapping.enabled, + device_filter: mapping.device_filter.clone().unwrap_or_default(), + stream_id: mapping.stream_id.clone().unwrap_or_default(), + presentation: mapping.presentation.clone(), + axis_map: axis_map_json(&mapping.axis_map), + button_map: serde_json::Value::Object( + mapping + .button_map + .iter() + .map(|(source, target)| (source.clone(), serde_json::Value::String(target.clone()))) + .collect(), + ), + pending_learn: mapping + .pending_learn + .as_ref() + .map(|learn| { + serde_json::json!({ + "target": learn.target, + "bindingKind": learn.binding_kind, + "requestedAt": learn.requested_at + }) + }) + .unwrap_or(serde_json::Value::Null), + updated_at: timestamp(), + source: source.to_string(), + }; + node.put(&provider_id, &record)?; + Ok(()) +} + +fn axis_map_json(axis_map: &HashMap) -> serde_json::Value { + serde_json::Value::Object( + axis_map + .iter() + .map(|(target, binding)| { + ( + target.clone(), + serde_json::json!({ + "source": binding.source, + "invert": binding.invert, + "scale": binding.scale, + "deadzone": binding.deadzone + }), + ) + }) + .collect(), + ) +} + +fn effective_muninn_hid_endpoint( + node: &cultmesh_rs::CultMeshNode, + device_filter: Option<&str>, + stream_id: Option<&str>, + trace: bool, +) -> Option { + discover_muninn_hid_endpoint(node, device_filter, stream_id, trace) +} + +fn effective_device_filter( + options: &Options, + desired_mapping: &SleipnirDesiredMapping, +) -> Option { + desired_mapping + .device_filter + .clone() + .or_else(|| options.device_filter.clone()) +} + +fn discover_available_hid_devices(node: &cultmesh_rs::CultMeshNode) -> Vec { + let mut devices = Vec::new(); + for record in node + .cache() + .get_all::() + .ok() + .into_iter() + .flatten() + { + upsert_available_hid_device( + &mut devices, + available_hid_device_from_record( + node, + &record, + discover_muninn_hid_endpoint( + node, + Some(record.device_id.as_str()), + Some(record.stream_id.as_str()), + false, + ), + ), + ); + } + for provider in node + .cache() + .get_all::() + .ok() + .into_iter() + .flatten() + { + for device in available_hid_devices_from_value(&provider.value) { + upsert_available_hid_device(&mut devices, device); + } + } + for envelope in node.cache().snapshot() { + if envelope.schema_id.as_deref() == Some(MUNINN_HID_CONTROLLER_STATE_SCHEMA) + || envelope.r#type == "muninn.hid_controller_state" + { + if let Ok(value) = rmp_serde::from_slice::(&envelope.payload) { + if let Some(device) = available_hid_device_from_hid_value(node, &value) { + upsert_available_hid_device(&mut devices, device); + } + } + continue; + } + if envelope.schema_id.as_deref() == Some(EVE_PROVIDER_ADVERTISEMENT_SCHEMA) + || envelope.r#type == "gamecult.eve.provider_advertisement" + { + if let Ok(value) = rmp_serde::from_slice::(&envelope.payload) { + for device in available_hid_devices_from_value(&value) { + upsert_available_hid_device(&mut devices, device); + } + } + continue; + } + } + devices.retain(|device| endpoint_looks_like_socket(&device.endpoint)); + devices.sort_by(|left, right| { + (&left.host_id, &left.device_id, &left.endpoint).cmp(&( + &right.host_id, + &right.device_id, + &right.endpoint, + )) + }); + devices + .dedup_by(|left, right| left.host_id == right.host_id && left.device_id == right.device_id); + devices +} + +fn available_hid_device_from_hid_value( + node: &cultmesh_rs::CultMeshNode, + value: &serde_json::Value, +) -> Option { + let payload = value + .as_array() + .and_then(|items| { + (items.len() == 1) + .then(|| items.first()) + .flatten() + .filter(|item| item.is_object() || item.is_array()) + }) + .unwrap_or(value); + let (stream_id, host_id, device_id, device_kind, source_path) = + if let Some(items) = payload.as_array() { + ( + items.first()?.as_str()?.to_string(), + items.get(1)?.as_str()?.to_string(), + items.get(2)?.as_str()?.to_string(), + items.get(3)?.as_str()?.to_string(), + items + .get(10) + .and_then(|item| item.as_str()) + .unwrap_or("unknown") + .to_string(), + ) + } else { + ( + string_field(payload, &["stream_id", "streamId"])?, + string_field(payload, &["host_id", "hostId"])?, + string_field(payload, &["device_id", "deviceId"])?, + string_field(payload, &["device_kind", "deviceKind"])?, + string_field(payload, &["source_path", "sourcePath"]) + .unwrap_or_else(|| "unknown".to_string()), + ) + }; + let endpoint = discover_muninn_hid_endpoint( + node, + Some(device_id.as_str()), + Some(stream_id.as_str()), + false, + ) + .unwrap_or_else(|| "discovering".to_string()); + Some(AvailableHidDevice { + device_id, + device_kind, + source_path, + stream_id, + host_id, + endpoint, + }) +} + +fn string_field(value: &serde_json::Value, names: &[&str]) -> Option { + names + .iter() + .find_map(|name| value.get(*name).and_then(|field| field.as_str())) + .map(ToString::to_string) +} + +fn available_hid_device_from_record( + node: &cultmesh_rs::CultMeshNode, + record: &MuninnHidControllerStateRecord, + endpoint: Option, +) -> AvailableHidDevice { + AvailableHidDevice { + device_id: record.device_id.clone(), + device_kind: record.device_kind.clone(), + source_path: record.source_path.clone(), + stream_id: record.stream_id.clone(), + host_id: record.host_id.clone(), + endpoint: endpoint.unwrap_or_else(|| { + discover_muninn_hid_endpoint( + node, + Some(record.device_id.as_str()), + Some(record.stream_id.as_str()), + false, + ) + .unwrap_or_else(|| "discovering".to_string()) + }), + } +} + +fn upsert_available_hid_device(devices: &mut Vec, device: AvailableHidDevice) { + if let Some(existing) = devices.iter_mut().find(|existing| { + existing.host_id == device.host_id && existing.device_id == device.device_id + }) { + if should_replace_available_hid_device(existing, &device) { + *existing = device; + } + } else { + devices.push(device); + } + devices.sort_by(|left, right| { + (&left.host_id, &left.device_id, &left.endpoint).cmp(&( + &right.host_id, + &right.device_id, + &right.endpoint, + )) + }); +} + +fn should_replace_available_hid_device( + existing: &AvailableHidDevice, + candidate: &AvailableHidDevice, +) -> bool { + let existing_score = available_hid_device_discovery_score(existing); + let candidate_score = available_hid_device_discovery_score(candidate); + candidate_score >= existing_score +} + +fn available_hid_device_discovery_score(device: &AvailableHidDevice) -> u8 { + let mut score = 0; + if device.endpoint != "discovering" { + score += 4; + } + if device.stream_id.contains(&device.device_id) { + score += 2; + } + if !device.source_path.trim().is_empty() && device.source_path != "unknown" { + score += 1; + } + score +} + +fn available_hid_devices_from_value(value: &serde_json::Value) -> Vec { + let mut devices = Vec::new(); + let Some(streams) = value + .get("inputStreams") + .or_else(|| value.get("input_streams")) + .and_then(|streams| streams.as_array()) + else { + return devices; + }; + for stream in streams { + let endpoint = stream + .get("address") + .and_then(|value| value.as_str()) + .unwrap_or_default() + .to_string(); + let stream_id = stream + .get("streamId") + .or_else(|| stream.get("stream_id")) + .and_then(|value| value.as_str()) + .unwrap_or("muninn:hid") + .to_string(); + if !is_muninn_fast_hid_stream(stream, &stream_id, &endpoint) { + continue; + } + let host_id = value + .get("verseId") + .or_else(|| value.get("verse_id")) + .and_then(|value| value.as_str()) + .unwrap_or("") + .trim_end_matches(".local") + .to_string(); + if let Some(stream_devices) = stream.get("devices").and_then(|value| value.as_array()) { + for device in stream_devices { + let device_id = device + .get("deviceId") + .or_else(|| device.get("device_id")) + .and_then(|value| value.as_str()) + .unwrap_or_default() + .to_string(); + if device_id.is_empty() { + continue; + } + devices.push(AvailableHidDevice { + device_id, + device_kind: device + .get("deviceKind") + .or_else(|| device.get("device_kind")) + .and_then(|value| value.as_str()) + .unwrap_or("hid") + .to_string(), + source_path: device + .get("sourcePath") + .or_else(|| device.get("source_path")) + .and_then(|value| value.as_str()) + .unwrap_or("") + .to_string(), + stream_id: stream_id.clone(), + host_id: host_id.clone(), + endpoint: endpoint.clone(), + }); + } + } + } + devices +} + +fn is_muninn_fast_hid_stream(stream: &serde_json::Value, stream_id: &str, endpoint: &str) -> bool { + if stream.get("schema").and_then(|value| value.as_str()) + != Some("muninn.hid_controller_state.v1") + { + return false; + } + if !stream_id.contains(":hid-controller-state") || stream_id.contains("move-evidence") { + return false; + } + if !endpoint_looks_like_socket(endpoint) { + return false; + } + stream + .get("transport") + .and_then(|value| value.as_str()) + .is_some_and(|transport| transport.contains("rudp")) +} + +fn endpoint_looks_like_socket(endpoint: &str) -> bool { + let Some((host, port)) = endpoint.rsplit_once(':') else { + return false; + }; + !host.trim().is_empty() + && port + .parse::() + .is_ok_and(|parsed_port| parsed_port != 0) +} + +fn stable_id(value: &str) -> String { + let normalized = value + .chars() + .map(|ch| if ch.is_ascii_alphanumeric() { ch } else { '-' }) + .collect::() + .trim_matches('-') + .to_ascii_lowercase(); + if normalized.is_empty() { + "device".to_string() + } else { + normalized + } +} + +fn sleipnir_provider_id(options: &Options) -> String { + format!("sleipnir.input-mirror.{}", options.host_id) +} + +fn sleipnir_daemon_id(options: &Options) -> String { + format!("{}-sleipnir", options.host_id) +} + +fn sleipnir_provider_title(options: &Options) -> String { + format!("Sleipnir {} Input Mirror", title_case(&options.host_id)) +} + +fn timestamp() -> String { + use std::time::{SystemTime, UNIX_EPOCH}; + match SystemTime::now().duration_since(UNIX_EPOCH) { + Ok(duration) => format!("unix-{}", duration.as_secs()), + Err(_) => "unix-0".to_string(), + } +} + +fn unix_millis_i64() -> i64 { + use std::time::{SystemTime, UNIX_EPOCH}; + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|duration| i64::try_from(duration.as_millis()).unwrap_or(i64::MAX)) + .unwrap_or_default() +} + +fn unix_nanos_i64() -> i64 { + use std::time::{SystemTime, UNIX_EPOCH}; + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|duration| i64::try_from(duration.as_nanos()).unwrap_or(i64::MAX)) + .unwrap_or_default() +} + +fn title_case(value: &str) -> String { + let mut chars = value.chars(); + match chars.next() { + Some(first) => first.to_uppercase().collect::() + chars.as_str(), + None => String::new(), + } +} + +fn create_rudp_stream( + bind: Option, + connect_endpoint: Option, + trace: bool, +) -> Result> { + if let Some(endpoint) = connect_endpoint { + let target = resolve_socket_addr(&endpoint) + .with_context(|| format!("resolving Muninn HID RUDP endpoint {endpoint}"))?; + let bind_address = bind.unwrap_or_else(|| { + if target.is_ipv4() { + SocketAddr::from(([0, 0, 0, 0], 0)) + } else { + SocketAddr::from(([0, 0, 0, 0, 0, 0, 0, 0], 0)) + } + }); + let socket = UdpSocket::bind(bind_address) + .with_context(|| format!("binding Sleipnir RUDP HID client at {bind_address}"))?; + socket + .set_read_timeout(Some(Duration::from_millis(1))) + .context("setting Sleipnir RUDP HID client timeout")?; + if trace { + eprintln!( + "Sleipnir connecting to Muninn HID RUDP at {target} connection_id={SLEIPNIR_HID_RUDP_CONNECTION_ID:08x}" + ); + } + let mut transport = + CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { + runtime_id: "sleipnir-hid-rudp".to_string(), + socket, + mode: CultNetRudpSocketMode::Client, + remote_addr: Some(target), + connection_id: SLEIPNIR_HID_RUDP_CONNECTION_ID, + initial_sequence: 1, + resend_delay_ms: 5, + transport_id: Some("sleipnir-hid-rudp".to_string()), + max_payload_bytes: None, + max_fragment_bytes: Some(HID_RUDP_MAX_FRAGMENT_BYTES), + max_pending_reliable_packets: Some(256), + media_reliable_expire_after_ms: Some(25), + media_delivery: None, + reconnect_policy: None, + })?; + transport.connect(Vec::new())?; + return Ok(Some(ActiveRudpStream { + transport, + target: Some(target), + last_connect_attempt_at: Some(Instant::now()), + connected_logged: false, + last_frame_at: Some(Instant::now()), + last_stale_log_at: None, + last_subscription: None, + last_subscription_at: None, + })); + } + let Some(bind) = bind else { + return Ok(None); + }; + let socket = UdpSocket::bind(bind) + .with_context(|| format!("binding Sleipnir RUDP HID stream at {bind}"))?; + socket + .set_read_timeout(Some(Duration::from_millis(1))) + .with_context(|| format!("setting Sleipnir RUDP HID stream {bind} timeout"))?; + if trace { + eprintln!( + "Sleipnir listening for fast HID RUDP on {bind} connection_id={SLEIPNIR_HID_RUDP_CONNECTION_ID:08x}" + ); + } + Ok(Some(ActiveRudpStream { + transport: CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { + runtime_id: "sleipnir-hid-rudp".to_string(), + socket, + mode: CultNetRudpSocketMode::Server, + remote_addr: None, + connection_id: SLEIPNIR_HID_RUDP_CONNECTION_ID, + initial_sequence: 1, + resend_delay_ms: 5, + transport_id: Some("sleipnir-hid-rudp".to_string()), + max_payload_bytes: None, + max_fragment_bytes: Some(HID_RUDP_MAX_FRAGMENT_BYTES), + max_pending_reliable_packets: Some(256), + media_reliable_expire_after_ms: Some(25), + media_delivery: None, + reconnect_policy: None, + })?, + target: None, + last_connect_attempt_at: None, + connected_logged: false, + last_frame_at: None, + last_stale_log_at: None, + last_subscription: None, + last_subscription_at: None, + })) +} + +fn send_hid_subscription_if_due( + stream: &mut ActiveRudpStream, + device_filter: Option, + stream_id: Option, + trace: bool, +) -> Result<()> { + if !stream.transport.connected() { + return Ok(()); + } + let subscription = HidControllerRudpSubscription { + device_filter: device_filter.filter(|filter| !filter.trim().is_empty()), + stream_id: stream_id.filter(|stream_id| !stream_id.trim().is_empty()), + }; + let changed = stream.last_subscription.as_ref() != Some(&subscription); + let due = stream + .last_subscription_at + .is_none_or(|sent_at| sent_at.elapsed() >= Duration::from_secs(1)); + if !changed && !due { + return Ok(()); + } + let payload = serde_json::to_vec(&serde_json::json!({ + "deviceFilter": subscription.device_filter, + "streamId": subscription.stream_id, + })) + .context("encoding Sleipnir HID RUDP subscription")?; + stream + .transport + .send("hid.subscribe", payload) + .context("sending Sleipnir HID RUDP subscription")?; + if trace || changed { + eprintln!( + "Sleipnir subscribed to Muninn HID device_filter={:?} stream_id={:?}", + subscription.device_filter, subscription.stream_id + ); + } + stream.last_subscription = Some(subscription); + stream.last_subscription_at = Some(Instant::now()); + Ok(()) +} + +fn resolve_socket_addr(endpoint: &str) -> Result { + endpoint + .to_socket_addrs() + .with_context(|| format!("resolving {endpoint}"))? + .next() + .ok_or_else(|| anyhow!("no socket addresses resolved for {endpoint}")) +} + +fn ensure_rudp_connected(stream: &mut ActiveRudpStream, trace: bool) -> Result { + let Some(target) = stream.target else { + return Ok(false); + }; + if stream.transport.connected() { + if !stream.connected_logged && trace { + eprintln!("Sleipnir connected to Muninn HID RUDP at {target}"); + } + stream.connected_logged = true; + if stream + .last_frame_at + .is_some_and(|last_frame| last_frame.elapsed() >= INPUT_STREAM_RECONNECT_AFTER) + { + let should_log = stream + .last_stale_log_at + .is_none_or(|logged| logged.elapsed() >= INPUT_STREAM_RECONNECT_AFTER); + if should_log && trace { + eprintln!( + "Sleipnir Muninn HID RUDP is connected to {target} but has received no frames for {:?}; recreating connection", + stream.last_frame_at.map(|last_frame| last_frame.elapsed()) + ); + } + stream.last_stale_log_at = Some(Instant::now()); + stream.connected_logged = false; + return Ok(true); + } else { + return Ok(false); + } + } + let should_attempt = stream + .last_connect_attempt_at + .is_none_or(|attempt| attempt.elapsed() >= Duration::from_millis(250)); + if should_attempt { + stream.last_connect_attempt_at = Some(Instant::now()); + stream.transport.connect(Vec::new())?; + } + Ok(false) +} + +fn discover_muninn_hid_endpoint( + node: &cultmesh_rs::CultMeshNode, + device_filter: Option<&str>, + stream_id: Option<&str>, + trace: bool, +) -> Option { + if let Some(endpoint) = discover_available_hid_endpoint(node, device_filter, stream_id) { + return Some(endpoint); + } + let host_hint = stream_host_hint(stream_id); + let endpoints = discover_provider_endpoints( + node, + OdinEndpointQuery { + schema: Some(MUNINN_HID_CONTROLLER_STATE_SCHEMA), + transport_contains: Some("rudp"), + host_hint: host_hint.as_deref(), + device_filter, + }, + ); + if trace && endpoints.is_empty() { + eprintln!( + "Sleipnir found no Muninn HID endpoints for host_hint={:?} device_filter={:?}", + host_hint, device_filter + ); + } + endpoints + .into_iter() + .next() + .map(|endpoint| endpoint.address) +} + +fn discover_available_hid_endpoint( + node: &cultmesh_rs::CultMeshNode, + device_filter: Option<&str>, + stream_id: Option<&str>, +) -> Option { + for provider in node + .cache() + .get_all::() + .ok() + .into_iter() + .flatten() + { + if let Some(endpoint) = + matching_provider_advertised_hid_endpoint(&provider.value, device_filter, stream_id) + { + return Some(endpoint); + } + } + for envelope in node.cache().snapshot() { + if envelope.schema_id.as_deref() != Some(EVE_PROVIDER_ADVERTISEMENT_SCHEMA) + && envelope.r#type != "gamecult.eve.provider_advertisement" + { + continue; + } + let Ok(value) = rmp_serde::from_slice::(&envelope.payload) else { + continue; + }; + if let Some(endpoint) = + matching_provider_advertised_hid_endpoint(&value, device_filter, stream_id) + { + return Some(endpoint); + } + } + None +} + +fn matching_provider_advertised_hid_endpoint( + value: &serde_json::Value, + device_filter: Option<&str>, + stream_id: Option<&str>, +) -> Option { + let host_hint = stream_host_hint(stream_id); + let filter = device_filter + .map(str::trim) + .filter(|value| !value.is_empty()); + available_hid_devices_from_value(value) + .into_iter() + .filter(|device| { + host_hint + .as_deref() + .is_none_or(|host| device.host_id.eq_ignore_ascii_case(host)) + }) + .find(|device| { + stream_id.is_none_or(|stream_id| device.stream_id == stream_id) + || filter.is_some_and(|filter| { + device.device_id == filter + || device.device_kind == filter + || device.stream_id == filter + || device.source_path.contains(filter) + }) + }) + .map(|device| device.endpoint) +} + +fn stream_host_hint(stream_id: Option<&str>) -> Option { + let stream_id = stream_id?; + let parts = stream_id + .split(':') + .filter(|part| !part.trim().is_empty()) + .collect::>(); + let host = match parts.as_slice() { + ["muninn", host, ..] => *host, + [host, ..] => *host, + _ => return None, + }; + let normalized = host.trim().trim_end_matches(".local").to_ascii_lowercase(); + (!normalized.is_empty()).then_some(normalized) +} + +fn receive_rudp_records(stream: &mut ActiveRudpStream, trace: bool) -> Result> { + let mut records = Vec::new(); + let mut empty_polls = 0usize; + for _ in 0..64 { + match stream.transport.receive_once() { + Ok(Some(frame)) if frame.channel_id == "latest" || frame.channel_id == "hid" => { + empty_polls = 0; + let frame_received_at = Instant::now(); + let frame_received_unix_ns = unix_nanos_i64(); + if trace { + eprintln!( + "Sleipnir received fast HID frame channel={} bytes={}", + frame.channel_id, + frame.payload.len() + ); + } + records.push(TimedHidRecord { + record: serde_json::from_slice(&frame.payload) + .context("decoding Sleipnir RUDP HID frame")?, + timing: HidRecordTiming { + frame_received_at, + frame_received_unix_ns, + buffer_ready_at: frame_received_at, + }, + }); + } + Ok(Some(frame)) => { + empty_polls = 0; + if trace { + eprintln!( + "Sleipnir ignored RUDP channel={} bytes={}", + frame.channel_id, + frame.payload.len() + ); + } + } + Ok(None) => { + empty_polls += 1; + if empty_polls >= 4 { + break; + } + } + Err(error) => { + if trace { + eprintln!("Sleipnir RUDP receive/control warning: {error:#}"); + } + break; + } + } + } + if let Err(error) = stream.transport.poll_resends() { + if trace { + eprintln!("Sleipnir RUDP resend warning: {error:#}"); + } + } + let buffer_ready_at = Instant::now(); + let mut records = coalesce_latest_timed_hid_records_by_device(records); + for record in &mut records { + record.timing.buffer_ready_at = buffer_ready_at; + } + Ok(records) +} + +fn coalesce_latest_timed_hid_records_by_device( + records: Vec, +) -> Vec { + let mut latest_by_device = HashMap::::new(); + for (index, record) in records.into_iter().enumerate() { + latest_by_device + .entry(record.record.device_id.clone()) + .and_modify(|(latest_index, latest_record)| { + if record.record.source_timestamp_ns > latest_record.record.source_timestamp_ns + || (record.record.source_timestamp_ns + == latest_record.record.source_timestamp_ns + && record.record.sequence > latest_record.record.sequence) + { + *latest_index = index; + *latest_record = record.clone(); + } + }) + .or_insert((index, record)); + } + let mut latest = latest_by_device.into_values().collect::>(); + latest.sort_by_key(|(index, _)| *index); + latest.into_iter().map(|(_, record)| record).collect() +} + +fn coalesce_latest_hid_records_by_device( + records: Vec, +) -> Vec { + let mut latest_by_device = HashMap::::new(); + for (index, record) in records.into_iter().enumerate() { + latest_by_device + .entry(record.device_id.clone()) + .and_modify(|(latest_index, latest_record)| { + if record.source_timestamp_ns > latest_record.source_timestamp_ns + || (record.source_timestamp_ns == latest_record.source_timestamp_ns + && record.sequence > latest_record.sequence) + { + *latest_index = index; + *latest_record = record.clone(); + } + }) + .or_insert((index, record)); + } + let mut latest = latest_by_device.into_values().collect::>(); + latest.sort_by_key(|(index, _)| *index); + latest.into_iter().map(|(_, record)| record).collect() +} + +#[cfg(windows)] +fn create_backend() -> Result> { + Ok(Box::new(VigemXboxBackend::connect()?)) +} + +#[cfg(not(windows))] +fn create_backend() -> Result> { + Err(anyhow!( + "Sleipnir's ViGEm Xbox virtual controller backend is currently implemented on Windows; use --dry-run on this platform" + )) +} + +fn record_matches_filter( + record: &MuninnHidControllerStateRecord, + device_filter: Option<&str>, +) -> bool { + device_filter.is_none_or(|filter| { + record.device_id == filter + || record.stream_id == filter + || record.source_path.contains(filter) + || record.device_kind == filter + }) +} + +fn input_latency_snapshot( + record: &MuninnHidControllerStateRecord, + timing: &HidRecordTiming, + axis_classified_at: Instant, + hid_emitted_at: Instant, + mapping: &SleipnirDesiredMapping, + emitted: bool, +) -> SleipnirInputLatencySnapshot { + let source_to_arrival_ms = (record.source_timestamp_ns > 0).then(|| { + timing + .frame_received_unix_ns + .saturating_sub(record.source_timestamp_ns) + / 1_000_000 + }); + let source_to_hid_ms = (record.source_timestamp_ns > 0) + .then(|| unix_nanos_i64().saturating_sub(record.source_timestamp_ns) / 1_000_000); + SleipnirInputLatencySnapshot { + device_id: record.device_id.clone(), + sequence: record.sequence, + source_to_arrival_ms, + arrival_to_buffer_ms: timing + .buffer_ready_at + .saturating_duration_since(timing.frame_received_at) + .as_millis(), + buffer_to_axis_ms: axis_classified_at + .saturating_duration_since(timing.buffer_ready_at) + .as_millis(), + axis_to_hid_ms: hid_emitted_at + .saturating_duration_since(axis_classified_at) + .as_millis(), + source_to_hid_ms, + total_observed_ms: hid_emitted_at + .saturating_duration_since(timing.frame_received_at) + .as_millis(), + axis_summary: axis_classification_summary(record, mapping), + emitted, + } +} + +fn axis_classification_summary( + record: &MuninnHidControllerStateRecord, + mapping: &SleipnirDesiredMapping, +) -> Vec { + let mut axes = mapping + .axis_map + .iter() + .map(|(target, binding)| { + let value = record.axes.get(binding.source).copied(); + format!( + "{}<-axis{}{}{}", + target, + binding.source, + if binding.invert { " inverted" } else { "" }, + value + .map(|value| format!(" value={:.3}", value)) + .unwrap_or_else(|| " missing".to_string()) + ) + }) + .collect::>(); + axes.sort(); + axes +} + +fn map_record_to_virtual_pad( + record: &MuninnHidControllerStateRecord, + mapping: &SleipnirDesiredMapping, +) -> VirtualPadState { + let left_x = signed_axis_to_i16(mapped_axis(record, mapping, "leftX", 0.0)); + let left_y = signed_axis_to_i16(mapped_axis(record, mapping, "leftY", 0.0)); + let mut buttons = mapped_buttons(record, mapping); + let left_trigger = mapped_trigger(record, mapping, "leftTrigger", 2); + let right_trigger = mapped_trigger(record, mapping, "rightTrigger", 5); + if buttons.iter().any(|button| button == "l2") && left_trigger == 0 { + buttons.push("left-trigger-button".to_string()); + } + VirtualPadState { + buttons, + left_x, + left_y, + left_trigger, + right_trigger, + } +} + +fn mapped_axis( + record: &MuninnHidControllerStateRecord, + mapping: &SleipnirDesiredMapping, + target: &str, + default: f32, +) -> f32 { + let Some(binding) = mapping.axis_map.get(target) else { + return default; + }; + let mut value = record.axes.get(binding.source).copied().unwrap_or(default); + if value.abs() < binding.deadzone { + value = 0.0; + } + if binding.invert { + value = -value; + } + (value * binding.scale).clamp(-1.0, 1.0) +} + +fn mapped_trigger( + record: &MuninnHidControllerStateRecord, + mapping: &SleipnirDesiredMapping, + target: &str, + fallback_source: usize, +) -> u8 { + if mapping.axis_map.contains_key(target) { + if mapping + .axis_map + .get(target) + .is_some_and(|binding| record.axes.get(binding.source).is_none()) + { + return 0; + } + trigger_from_axis( + Some(mapped_axis(record, mapping, target, 0.0)), + record.device_kind.as_str(), + ) + } else { + trigger_from_axis( + record.axes.get(fallback_source).copied(), + record.device_kind.as_str(), + ) + } +} + +fn mapped_buttons( + record: &MuninnHidControllerStateRecord, + mapping: &SleipnirDesiredMapping, +) -> Vec { + let mut buttons = Vec::new(); + for button in &record.buttons { + let mapped = mapping + .button_map + .get(button) + .map(String::as_str) + .unwrap_or(button.as_str()); + if mapped.eq_ignore_ascii_case("none") || mapped.trim().is_empty() { + continue; + } + if !buttons.iter().any(|existing| existing == mapped) { + buttons.push(mapped.to_string()); + } + } + buttons +} + +fn signed_axis_to_i16(value: f32) -> i16 { + let clamped = value.clamp(-1.0, 1.0); + if clamped < 0.0 { + (clamped * 32768.0).round() as i16 + } else { + (clamped * 32767.0).round() as i16 + } +} + +fn trigger_from_axis(value: Option, device_kind: &str) -> u8 { + let Some(value) = value else { + return 0; + }; + if device_kind == "xinput" || device_kind == "xinput-controller" { + return (value.clamp(0.0, 1.0) * 255.0).round() as u8; + } + (((value.clamp(-1.0, 1.0) + 1.0) * 0.5) * 255.0).round() as u8 +} + +impl Options { + fn parse(args: impl Iterator) -> Result { + let mut options = Options { + store_path: PathBuf::from("C:/Meta/Odin/state/starfire.muninn.telemetry.cc"), + discovery_store_path: None, + mapping_path: None, + device_filter: None, + host_id: "starfire".to_string(), + interval_ms: 8, + odin_cultmesh_uri: Some("cultmesh://odin/rendezvous/provider-catalog".to_string()), + rudp_bind: None, + command_route: SLEIPNIR_COMMAND_ROUTE.to_string(), + idunn_rudp_health: None, + once: false, + dry_run: false, + trace: env::var("SLEIPNIR_TRACE") + .ok() + .is_some_and(|value| value != "0" && !value.eq_ignore_ascii_case("false")), + }; + let mut idunn_rudp_health_endpoint = None; + let mut idunn_daemon_id = None; + let mut idunn_health_contract = None; + let mut args = args.peekable(); + while let Some(arg) = args.next() { + match arg.as_str() { + "--store" => options.store_path = PathBuf::from(next_value(&mut args, "--store")?), + "--discovery-store" => { + options.discovery_store_path = + Some(PathBuf::from(next_value(&mut args, "--discovery-store")?)) + } + "--mapping" | "--mapping-path" => { + options.mapping_path = Some(PathBuf::from(next_value(&mut args, &arg)?)); + } + "--device" => options.device_filter = Some(next_value(&mut args, "--device")?), + "--host" => options.host_id = next_value(&mut args, "--host")?, + "--interval-ms" => { + options.interval_ms = next_value(&mut args, "--interval-ms")? + .parse() + .context("--interval-ms must be an integer")? + } + "--rudp-bind" | "--udp-bind" => { + options.rudp_bind = Some( + next_value(&mut args, &arg)? + .parse() + .context("--rudp-bind must be a socket address")?, + ) + } + "--command-rudp-bind" => { + let _ = next_value(&mut args, "--command-rudp-bind")?; + return Err(anyhow!( + "--command-rudp-bind has been removed; Sleipnir reads input mapping commands from Odin/CultMesh discovery" + )); + } + "--command-route" => { + options.command_route = next_value(&mut args, "--command-route")? + } + "--command-rudp-advertise" => { + return Err(anyhow!( + "--command-rudp-advertise has been removed; use --command-route with a cultmesh:// Odin command route" + )); + } + "--odin-cultmesh-rudp" => { + let _ = next_value(&mut args, "--odin-cultmesh-rudp")?; + return Err(anyhow!( + "--odin-cultmesh-rudp has been removed; use --odin-cultmesh-uri cultmesh://odin/rendezvous/provider-catalog and let CultMesh resolve Odin's transport" + )); + } + "--odin-cultmesh-uri" => { + options.odin_cultmesh_uri = Some(next_value(&mut args, "--odin-cultmesh-uri")?) + } + "--idunn-rudp-health" => { + idunn_rudp_health_endpoint = Some( + next_value(&mut args, "--idunn-rudp-health")? + .parse() + .context("--idunn-rudp-health must be a socket address")?, + ) + } + "--idunn-daemon" => { + idunn_daemon_id = Some(next_value(&mut args, "--idunn-daemon")?) + } + "--idunn-health-contract" => { + idunn_health_contract = Some(next_value(&mut args, "--idunn-health-contract")?) + } + "--once" => options.once = true, + "--dry-run" => options.dry_run = true, + "--trace" => options.trace = true, + "--help" | "-h" => { + println!("{}", usage()); + std::process::exit(0); + } + other => return Err(anyhow!("unrecognized argument {other}\n{}", usage())), + } + } + options.idunn_rudp_health = match ( + idunn_rudp_health_endpoint, + idunn_daemon_id, + idunn_health_contract, + ) { + (None, None, None) => None, + (Some(endpoint), Some(daemon_id), Some(health_contract)) => { + Some(IdunnRudpHealthOptions { + endpoint, + daemon_id, + health_contract, + }) + } + _ => { + return Err(anyhow!( + "--idunn-rudp-health, --idunn-daemon, and --idunn-health-contract must be provided together" + )); + } + }; + Ok(options) + } +} + +fn next_value(args: &mut impl Iterator, flag: &str) -> Result { + args.next() + .filter(|value| !value.trim().is_empty()) + .ok_or_else(|| anyhow!("{flag} requires a value")) +} + +fn usage() -> &'static str { + "usage: sleipnir [--store PATH] [--discovery-store PATH] [--mapping-path LEGACY_PATH] [--host HOST] [--device DEVICE_OR_KIND] [--odin-cultmesh-uri cultmesh://...] [--rudp-bind ADDR] [--command-route cultmesh://...] [--idunn-rudp-health ADDR --idunn-daemon ID --idunn-health-contract CONTRACT] [--interval-ms N] [--trace] [--dry-run] [--once]" +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + use std::fs; + + fn record(axes: Vec, buttons: Vec<&str>, sequence: u64) -> MuninnHidControllerStateRecord { + MuninnHidControllerStateRecord { + stream_id: "nightwing:nav:hid-controller-state".to_string(), + host_id: "nightwing".to_string(), + device_id: "nav".to_string(), + device_kind: "ps3-navigation".to_string(), + sequence, + source_timestamp_ns: 0, + axes, + buttons: buttons.into_iter().map(String::from).collect(), + battery01: f32::NAN, + observed_at: "unix:0".to_string(), + source_path: "/dev/input/js0".to_string(), + } + } + + fn default_mapping() -> SleipnirDesiredMapping { + SleipnirDesiredMapping { + enabled: false, + device_filter: None, + stream_id: None, + presentation: default_presentation(), + axis_map: default_axis_map(), + button_map: default_button_map(), + pending_learn: None, + } + } + + fn test_node(name: &str) -> (cultmesh_rs::CultMeshNode, PathBuf) { + let store_path = + std::env::temp_dir().join(format!("sleipnir-{name}-{}.cc", unix_millis_i64())); + let node = CultMesh::create_node( + &store_path, + OdinDocuments, + CultMeshNodeOptions { + runtime_id: format!("sleipnir-test-{name}"), + pull_on_start: true, + }, + ) + .unwrap(); + (node, store_path) + } + + #[test] + fn coalesces_latest_hid_records_per_device() { + let mut old_nav = record(vec![1.0, 0.0, -1.0], Vec::new(), 1); + old_nav.device_id = "nav".to_string(); + old_nav.source_timestamp_ns = 1_000; + let mut xbox = record(vec![0.25, 0.0, -1.0], Vec::new(), 7); + xbox.device_id = "xbox".to_string(); + xbox.source_timestamp_ns = 1_500; + let mut latest_nav = record(vec![0.0, 0.0, -1.0], Vec::new(), 2); + latest_nav.device_id = "nav".to_string(); + latest_nav.source_timestamp_ns = 2_000; + + let records = coalesce_latest_hid_records_by_device(vec![old_nav, xbox, latest_nav]); + + assert_eq!(records.len(), 2); + assert_eq!(records[0].device_id, "xbox"); + assert_eq!(records[0].sequence, 7); + assert_eq!(records[1].device_id, "nav"); + assert_eq!(records[1].sequence, 2); + assert_eq!(records[1].axes[0], 0.0); + } + + #[test] + fn coalesces_by_source_timestamp_not_arrival_order() { + let mut newer_nav = record(vec![0.0, 1.0, -1.0], Vec::new(), 10); + newer_nav.device_id = "nav".to_string(); + newer_nav.source_timestamp_ns = 2_000; + let mut older_nav = record(vec![-1.0, 0.0, -1.0], Vec::new(), 9); + older_nav.device_id = "nav".to_string(); + older_nav.source_timestamp_ns = 1_000; + + let records = coalesce_latest_hid_records_by_device(vec![newer_nav, older_nav]); + + assert_eq!(records.len(), 1); + assert_eq!(records[0].sequence, 10); + assert_eq!(records[0].axes[1], 1.0); + } + + #[test] + fn maps_nav_stick_and_buttons_to_xinput_shape() { + let state = map_record_to_virtual_pad( + &record( + vec![1.0, -1.0, -1.0], + vec!["cross", "circle", "l1", "l3", "up"], + 7, + ), + &default_mapping(), + ); + + assert_eq!(state.left_x, 32767); + assert_eq!(state.left_y, 32767); + assert_eq!(state.left_trigger, 0); + assert_eq!(state.right_trigger, 0); + assert!(state.buttons.contains(&"cross".to_string())); + assert!(state.buttons.contains(&"circle".to_string())); + assert!(state.buttons.contains(&"l1".to_string())); + assert!(state.buttons.contains(&"l3".to_string())); + assert!(state.buttons.contains(&"up".to_string())); + } + + #[test] + fn remaps_buttons_and_axes_from_mapping() { + let mut mapping = default_mapping(); + mapping + .button_map + .insert("cross".to_string(), "b".to_string()); + mapping.axis_map.insert( + "leftX".to_string(), + AxisBinding { + source: 1, + invert: false, + scale: 0.5, + deadzone: 0.0, + }, + ); + + let state = + map_record_to_virtual_pad(&record(vec![1.0, 1.0, -1.0], vec!["cross"], 7), &mapping); + + assert_eq!(state.left_x, 16384); + assert!(state.buttons.contains(&"b".to_string())); + assert!(!state.buttons.contains(&"cross".to_string())); + } + + #[test] + fn default_mapping_deadzones_small_stick_noise() { + let state = map_record_to_virtual_pad( + &record(vec![0.05, -0.04, -1.0], Vec::new(), 7), + &default_mapping(), + ); + + assert_eq!(state.left_x, 0); + assert_eq!(state.left_y, 0); + assert_eq!(state.left_trigger, 0); + assert_eq!(state.right_trigger, 0); + assert!(state.buttons.is_empty()); + } + + #[test] + fn pending_learn_maps_next_active_input() { + let mut mapping = default_mapping(); + mapping.pending_learn = Some(LearnRequest { + target: "a".to_string(), + binding_kind: "button".to_string(), + requested_at: None, + }); + let (mut node, store_path) = test_node("learn"); + let options = Options::parse( + ["--store", store_path.to_str().unwrap(), "--dry-run"] + .into_iter() + .map(String::from), + ) + .unwrap(); + let updated = apply_pending_learn( + &mut node, + &options, + &mapping, + &record(vec![0.0, 0.0], vec!["cross"], 2), + ) + .unwrap() + .unwrap(); + assert_eq!( + updated.button_map.get("cross").map(String::as_str), + Some("a") + ); + assert!(updated.pending_learn.is_none()); + let persisted = read_desired_mapping(&mut node, &options); + assert_eq!( + persisted.button_map.get("cross").map(String::as_str), + Some("a") + ); + let _ = fs::remove_file(store_path); + } + + #[test] + fn runtime_state_prefers_recent_frames_over_handshake_churn() { + let (node, store_path) = test_node("runtime-fresh-frame"); + let options = Options::parse( + ["--store", store_path.to_str().unwrap(), "--dry-run"] + .into_iter() + .map(String::from), + ) + .unwrap(); + let mut mapping = default_mapping(); + mapping.enabled = true; + let stream = create_rudp_stream(None, Some("127.0.0.1:9".to_string()), false).unwrap(); + + let state = SleipnirRuntimeState::from_runtime( + &options, + Some("nav"), + &node, + stream.as_ref(), + None, + 0, + &mapping, + None, + ); + + assert_eq!(state.stream_state, "connected"); + let _ = fs::remove_file(store_path); + } + + #[test] + fn available_hid_devices_ignore_move_evidence_streams() { + let provider = json!({ + "verseId": "starfire.local", + "inputStreams": [ + { + "streamId": "muninn:nightwing:move-evidence", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0", + "address": "198.51.100.75:17888", + "devices": [ + { + "deviceId": "nav-ghost", + "deviceKind": "ps3-navigation", + "sourcePath": "/dev/input/js0" + } + ] + }, + { + "streamId": "muninn:starfire:hid-controller-state", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0", + "address": "198.51.100.66:17888", + "devices": [ + { + "deviceId": "nav-windows-psnav-0", + "deviceKind": "ps3-navigation", + "sourcePath": "windows-psmove://nav" + } + ] + } + ] + }); + + let devices = available_hid_devices_from_value(&provider); + + assert_eq!(devices.len(), 1); + assert_eq!(devices[0].device_id, "nav-windows-psnav-0"); + assert_eq!(devices[0].host_id, "starfire"); + assert_eq!(devices[0].endpoint, "198.51.100.66:17888"); + } + + #[test] + fn discovers_hid_endpoint_from_odin_provider_routes() { + let (mut node, store_path) = test_node("hid-endpoint-routes"); + node.put( + "muninn.telemetry.starfire", + &EveProviderAdvertisementRecord { + value: json!({ + "providerId": "muninn.telemetry.starfire", + "endpoints": [ + { + "address": "C:\\Meta\\Odin\\state\\starfire.muninn.telemetry.cc", + "transport": "cultcache-store" + }, + { + "address": "198.51.100.66:17888", + "channel": "latest", + "connectionId": 1836384261, + "role": "muninn.hid_controller_state", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0" + } + ], + "routes": [ + { + "address": "C:\\Meta\\Odin\\state\\starfire.muninn.telemetry.cc", + "transport": "cultcache-store" + } + ] + }), + }, + ) + .unwrap(); + + assert_eq!( + discover_muninn_hid_endpoint( + &node, + Some("nav-windows-psnav-0"), + Some("starfire:nav-windows-psnav-0:hid-controller-state"), + false, + ) + .as_deref(), + Some("198.51.100.66:17888") + ); + let _ = fs::remove_file(store_path); + } + + #[test] + fn discovers_available_hid_devices_from_typed_muninn_state_records() { + let (mut node, store_path) = test_node("hid-record-discovery"); + node.put( + "muninn.telemetry.starfire", + &EveProviderAdvertisementRecord { + value: json!({ + "providerId": "muninn.telemetry.starfire", + "endpoints": [{ + "address": "198.51.100.66:17888", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0" + }] + }), + }, + ) + .unwrap(); + node.put( + "starfire:nav-windows-psnav-0:hid-controller-state", + &MuninnHidControllerStateRecord { + stream_id: "starfire:nav-windows-psnav-0:hid-controller-state".to_string(), + host_id: "starfire".to_string(), + device_id: "nav-windows-psnav-0".to_string(), + device_kind: "ps3-navigation".to_string(), + sequence: 1, + source_timestamp_ns: 0, + axes: vec![0.0, 0.0, 0.0], + buttons: Vec::new(), + battery01: f32::NAN, + observed_at: "unix:0".to_string(), + source_path: "windows-psmove://nav".to_string(), + }, + ) + .unwrap(); + + let devices = discover_available_hid_devices(&node); + + assert_eq!(devices.len(), 1); + assert_eq!(devices[0].device_id, "nav-windows-psnav-0"); + assert_eq!(devices[0].host_id, "starfire"); + assert_eq!( + devices[0].stream_id, + "starfire:nav-windows-psnav-0:hid-controller-state" + ); + assert_eq!(devices[0].endpoint, "198.51.100.66:17888"); + let _ = fs::remove_file(store_path); + } + + #[test] + fn normalizes_tuple_shaped_hid_state_payloads_for_discovery() { + let (mut node, store_path) = test_node("hid-tuple-discovery"); + node.put( + "muninn.telemetry.raven", + &EveProviderAdvertisementRecord { + value: json!({ + "providerId": "muninn.telemetry.raven", + "endpoints": [{ + "address": "198.51.100.84:17888", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0" + }] + }), + }, + ) + .unwrap(); + let device = available_hid_device_from_hid_value( + &node, + &json!([ + "raven:xbox-raven:hid-controller-state", + "raven", + "xbox-raven", + "xbox-controller", + 42, + 0, + [], + [], + null, + "unix:0", + "xinput://raven/xbox" + ]), + ) + .unwrap(); + + assert_eq!(device.device_id, "xbox-raven"); + assert_eq!(device.host_id, "raven"); + assert_eq!(device.endpoint, "198.51.100.84:17888"); + let _ = fs::remove_file(store_path); + } + + #[test] + fn available_hid_device_upsert_deduplicates_endpoint_variants() { + let mut devices = Vec::new(); + upsert_available_hid_device( + &mut devices, + AvailableHidDevice { + device_id: "nav-windows-psnav-0".to_string(), + device_kind: "ps3-navigation".to_string(), + source_path: "windows-psmove://nav".to_string(), + stream_id: "starfire:nav-windows-psnav-0:hid-controller-state".to_string(), + host_id: "starfire".to_string(), + endpoint: "discovering".to_string(), + }, + ); + upsert_available_hid_device( + &mut devices, + AvailableHidDevice { + device_id: "nav-windows-psnav-0".to_string(), + device_kind: "ps3-navigation".to_string(), + source_path: "windows-psmove://nav".to_string(), + stream_id: "starfire:nav-windows-psnav-0:hid-controller-state".to_string(), + host_id: "starfire".to_string(), + endpoint: "198.51.100.66:17888".to_string(), + }, + ); + upsert_available_hid_device( + &mut devices, + AvailableHidDevice { + device_id: "nav-windows-psnav-0".to_string(), + device_kind: "ps3-navigation".to_string(), + source_path: "windows-psmove://nav".to_string(), + stream_id: "muninn:starfire:hid-controller-state".to_string(), + host_id: "starfire".to_string(), + endpoint: "198.51.100.66:17888".to_string(), + }, + ); + + assert_eq!(devices.len(), 1); + assert_eq!(devices[0].endpoint, "198.51.100.66:17888"); + assert_eq!( + devices[0].stream_id, + "starfire:nav-windows-psnav-0:hid-controller-state" + ); + } + + #[test] + fn stream_id_host_hint_filters_provider_routes() { + let (mut node, store_path) = test_node("hid-host-hint"); + node.put( + "muninn.telemetry.nightwing", + &EveProviderAdvertisementRecord { + value: json!({ + "providerId": "muninn.telemetry.nightwing", + "verseId": "nightwing.local", + "endpoints": [{ + "address": "198.51.100.75:17888", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0" + }] + }), + }, + ) + .unwrap(); + node.put( + "muninn.telemetry.starfire", + &EveProviderAdvertisementRecord { + value: json!({ + "providerId": "muninn.telemetry.starfire", + "verseId": "starfire.local", + "endpoints": [{ + "address": "198.51.100.66:17888", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0" + }] + }), + }, + ) + .unwrap(); + let hint = stream_host_hint(Some("starfire:nav-windows-psnav-0:hid-controller-state")); + + assert_eq!(hint.as_deref(), Some("starfire")); + assert_eq!( + discover_muninn_hid_endpoint( + &node, + Some("nav-windows-psnav-0"), + Some("starfire:nav-windows-psnav-0:hid-controller-state"), + false, + ) + .as_deref(), + Some("198.51.100.66:17888") + ); + let _ = fs::remove_file(store_path); + } + + #[test] + fn selected_provider_device_resolves_input_stream_endpoint() { + let (mut node, store_path) = test_node("hid-provider-device-endpoint"); + node.put( + "muninn.telemetry.starfire", + &EveProviderAdvertisementRecord { + value: json!({ + "providerId": "muninn.telemetry.starfire", + "verseId": "starfire.local", + "inputStreams": [{ + "address": "198.51.100.66:17888", + "channel": "latest", + "connectionId": 1836384261, + "schema": "muninn.hid_controller_state.v1", + "streamId": "muninn:starfire:hid-controller-state", + "transport": "cultnet.transport.rudp.v0", + "devices": [{ + "deviceId": "nav-windows-psnav-0", + "deviceKind": "ps3-navigation", + "sourcePath": "windows-psmove://nav" + }] + }] + }), + }, + ) + .unwrap(); + + assert_eq!( + discover_muninn_hid_endpoint( + &node, + Some("nav-windows-psnav-0"), + Some("muninn:starfire:hid-controller-state"), + false, + ) + .as_deref(), + Some("198.51.100.66:17888") + ); + let _ = fs::remove_file(store_path); + } + + #[test] + fn desired_mapping_ignores_transport_endpoint_shortcuts() { + let (mut node, store_path) = test_node("mapping"); + let options = Options::parse( + ["--store", store_path.to_str().unwrap()] + .into_iter() + .map(String::from), + ) + .unwrap(); + node.put( + &sleipnir_provider_id(&options), + &SleipnirInputMappingRecord { + provider_id: sleipnir_provider_id(&options), + enabled: true, + device_filter: "nav-windows-psnav-0".to_string(), + stream_id: String::new(), + presentation: "xbox360".to_string(), + axis_map: serde_json::Value::Null, + button_map: serde_json::Value::Null, + pending_learn: json!({ + "muninnRudp": "198.51.100.66:17888" + }), + updated_at: timestamp(), + source: "test".to_string(), + }, + ) + .unwrap(); + + let mapping = read_desired_mapping(&mut node, &options); + + assert_eq!( + mapping.device_filter.as_deref(), + Some("nav-windows-psnav-0") + ); + assert_eq!(mapping.stream_id, None); + let _ = fs::remove_file(store_path); + } + + #[test] + fn desired_mapping_reads_newest_odin_discovery_mapping() { + let (mut local_node, local_store_path) = test_node("mapping-local"); + let (mut discovery_node, discovery_store_path) = test_node("mapping-discovery"); + let options = Options::parse( + ["--store", local_store_path.to_str().unwrap()] + .into_iter() + .map(String::from), + ) + .unwrap(); + let provider_id = sleipnir_provider_id(&options); + local_node + .put( + &provider_id, + &SleipnirInputMappingRecord { + provider_id: provider_id.clone(), + enabled: true, + device_filter: "local-old".to_string(), + stream_id: String::new(), + presentation: "xbox360".to_string(), + axis_map: serde_json::Value::Null, + button_map: serde_json::Value::Null, + pending_learn: serde_json::Value::Null, + updated_at: "2026-07-04T00:00:00.000Z".to_string(), + source: "local".to_string(), + }, + ) + .unwrap(); + discovery_node + .put( + &provider_id, + &SleipnirInputMappingRecord { + provider_id: provider_id.clone(), + enabled: true, + device_filter: "odin-new".to_string(), + stream_id: String::new(), + presentation: "xbox360".to_string(), + axis_map: serde_json::Value::Null, + button_map: serde_json::Value::Null, + pending_learn: serde_json::Value::Null, + updated_at: "2026-07-04T00:00:01.000Z".to_string(), + source: "odin".to_string(), + }, + ) + .unwrap(); + + let mapping = + read_desired_mapping_from_sources(&mut local_node, Some(&mut discovery_node), &options); + + assert_eq!(mapping.device_filter.as_deref(), Some("odin-new")); + let _ = fs::remove_file(local_store_path); + let _ = fs::remove_file(discovery_store_path); + } + + #[test] + fn rejects_removed_command_rudp_bind() { + let error = Options::parse( + ["--command-rudp-bind", "127.0.0.1:17889"] + .into_iter() + .map(String::from), + ) + .unwrap_err() + .to_string(); + + assert!(error.contains("--command-rudp-bind has been removed")); + } + + #[test] + fn accepts_odin_cultmesh_uri() { + let options = Options::parse( + [ + "--odin-cultmesh-uri", + "cultmesh://odin/rendezvous/provider-catalog", + ] + .into_iter() + .map(String::from), + ) + .unwrap(); + + assert_eq!( + options.odin_cultmesh_uri.as_deref(), + Some("cultmesh://odin/rendezvous/provider-catalog") + ); + } + + #[test] + fn rejects_removed_odin_cultmesh_rudp() { + let error = Options::parse( + ["--odin-cultmesh-rudp", "127.0.0.1:17871"] + .into_iter() + .map(String::from), + ) + .unwrap_err() + .to_string(); + + assert!(error.contains("--odin-cultmesh-rudp has been removed")); + } + + #[cfg(windows)] + #[test] + fn xbox_face_button_names_stay_distinct() { + assert_eq!(xbutton_mask("a"), vigem_client::XButtons::A); + assert_eq!(xbutton_mask("b"), vigem_client::XButtons::B); + assert_eq!(xbutton_mask("x"), vigem_client::XButtons::X); + assert_eq!(xbutton_mask("y"), vigem_client::XButtons::Y); + assert_eq!(xbutton_mask("cross"), vigem_client::XButtons::A); + assert_eq!(xbutton_mask("square"), vigem_client::XButtons::X); + } +} diff --git a/docs/muninn-media-streaming.md b/docs/muninn-media-streaming.md index d3105ff..e5689c6 100644 --- a/docs/muninn-media-streaming.md +++ b/docs/muninn-media-streaming.md @@ -237,9 +237,10 @@ a temporary PCM/AAC compatibility bridge. Recommended first LAN profile: - Profile id: `muninn.rudp.low_latency_h264_lan.v1`. -- Video: H.264 NVENC, `p1`, ultra-low-latency tune, CBR high enough that LAN +- Video: H.264 NVENC, `p5` (`main.rs:9504`), ultra-low-latency tune, CBR high enough that LAN bandwidth is not the constraint, no B-frames, no lookahead, short GOP or - intra-refresh, periodic IDR/keyframe on feedback pressure. + intra-refresh, keyframe actuation on feedback pressure (not built: keyframe requests are only + counted and logged today; Cut 6 builds it). - VBV: derive `bufsize` from roughly one frame of bitrate (`bitrate_kbps / framerate`) instead of a large fixed encoder reservoir. The point is bounded latency, not hoarding compressed video in a nicer hat. @@ -247,7 +248,7 @@ Recommended first LAN profile: temporary PCM/AAC bridge with separate packet identity and clock. - Transport: payload elementary access units as typed media records, never a muxed container as the unit of truth. -- Packet size: default typed media chunks are `480` bytes. That leaves headroom +- Packet size: default typed media chunks are `848` bytes (`main.rs:81`). That leaves headroom for CultNet/MessagePack/RUDP headers inside a normal Ethernet MTU so the OBS bridge does not depend on IP fragmentation or private RUDP fragment reassembly. The sender also sets CultNet RUDP `max_fragment_bytes` to `1431` @@ -255,8 +256,9 @@ Recommended first LAN profile: minus the five-byte `media` channel id), so oversized typed records fragment in CultNet deliberately instead of falling through to accidental IP fragmentation. -- Resend cadence: sender RUDP media resends are scheduled every `5` ms while - the packet is still inside the `75` ms reliable-expiry budget. +- Resend cadence: sender RUDP media resends are scheduled every `30` ms (`main.rs:94`) while + the packet is still inside its expiry, which is the request's latency budget (a request that names none gets `250` ms, `main.rs:98`, and the advertisement offers the same as `default_latency_budget_ms`). +- Send queue: `media_send.rs` owns it. The unit is a group, one access unit with its parity or one audio packet, stamped `produced_at + latency budget` when the packetizer emits it. A request's latency budget is clamped to 1..=2000 ms. The send loop moves one payload per step and picks it afresh each time: audio, then repairs, then video, so audio never waits behind more than the payload in progress, full socket or not. The group deadline is checked before every payload; a group that outlives it mid-send is abandoned and counted `groups_cut_short`. Queues are capped per kind (audio 256, video 512 groups) and drop the oldest group, counted as `groups_dropped_audio` and `groups_dropped_video`. Every access unit the sender drops (queue cap, expiry, packetizer overflow) has already consumed its frame id, so the receiver sees a gap; an overflow also discards the dropped frame's remaining slices instead of emitting them as a frame. A repair keeps the deadline of the frame it repairs, goes only to the receiver that asked, and is not sent after that deadline. - Control: sender may adapt bitrate, keyframe cadence, chunk size, and playout budget from receiver feedback; the receiver must not silently stretch latency to preserve visual perfection. diff --git a/docs/muninn.md b/docs/muninn.md index 6b7df20..b262640 100644 --- a/docs/muninn.md +++ b/docs/muninn.md @@ -22,7 +22,7 @@ microphones, cameras, and future sensors. ```powershell cargo build -p muninn-daemon -muninn serve --store C:\Meta\Odin\state\muninn.telemetry.cc --interval-seconds 15 --idunn-rudp-health $env:IDUNN_RUDP_HEALTH --idunn-daemon starfire-muninn --idunn-health-contract muninn.cultnet-rudp-local-telemetry-and-quest-access +muninn serve --store C:\Meta\Odin\state\muninn.telemetry.cc --interval-seconds 15 muninn --health --store C:\Meta\Odin\state\muninn.telemetry.cc ``` @@ -97,10 +97,7 @@ E:\Projects\Odin\scripts\restart-starfire-muninn.cmd E:\Projects\Odin\scripts\health-starfire-muninn.cmd ``` -The restart script launches Muninn hidden with `--host starfire --quest-adb`, -`--idunn-rudp-health` from explicit `-IdunnRudpHealth` or -`IDUNN_RUDP_HEALTH`, `--idunn-daemon starfire-muninn`, and -`--idunn-health-contract muninn.cultnet-rudp-local-telemetry-and-quest-access`. +The restart script launches Muninn hidden with `--host starfire --quest-adb`. If the CultCache store at `C:\Meta\Odin\state\starfire.muninn.telemetry.cc` fails MessagePack decode on boot, the restart path archives the corrupt file, clears the stale `.lock`, and relaunches the daemon instead of leaving the lane @@ -192,11 +189,7 @@ muninn move-light-status \ Idunn keeps the Muninn daemon alive. Idunn does not learn a Move-specific watcher, and Mimir does not write HID directly except through temporary smoke scripts used to prove hardware behavior before a Muninn daemon is available. -When `serve` is launched with `--idunn-rudp-health`, `--idunn-daemon`, and -`--idunn-health-contract`, the long-running Muninn body publishes -`idunn.daemon_health` directly to Idunn over `cultnet.transport.rudp.v0` on its -normal cadence. `--health` keeps the same publication path for manual proof and -compatibility probes, but the live owner is the daemon's `serve` process. +`--health` reads the telemetry store and reports; it publishes nothing. Quest ADB probing is a telemetry input, not daemon liveness. If `adb` is missing or the Quest is unavailable, Muninn publishes `muninn.quest_access` as `unavailable` and keeps serving the local telemetry surface. @@ -235,10 +228,6 @@ actuators only, not lifecycle owners. The binary is installed at `/home/metacrat/.local/state/gamecult/muninn/muninn.telemetry.cc`, and the restart actuator launches `serve --host nightwing --interval-seconds 15` with `--move-state move-usb=/dev/input/by-id/usb-Sony_Computer_Entertainment_Motion_Controller-joystick`, -`--idunn-rudp-health` supplied by explicit `-IdunnRudpHealth` or -`IDUNN_RUDP_HEALTH`, -`--idunn-daemon nightwing-muninn`, -`--idunn-health-contract muninn.cultnet-rudp-remote-telemetry-and-move-hid`, PID, and logs under `/home/metacrat/.local/state/gamecult/muninn`. With that Move state source attached, `serve` also publishes the @@ -248,10 +237,12 @@ Nightwing source discovery must emit one Move source per controller id. The USB pairing collection and Bluetooth joystick can expose the same controller as separate `/dev/input/js*` paths; `nightwing-move-state-sources.sh` prefers the Bluetooth `HID_ID=0005:0000054C:000003D5` path so Idunn health does not demand -fresh records from two faces of the same controller. The Nightwing health -actuator requires the same configured Idunn RUDP endpoint, but that command is -fallback proof only; the live keepalive contract is now published by the -long-running Nightwing `serve` process. +fresh records from two faces of the same controller. + +Starfire and Nightwing binaries and their `scripts/*-muninn.ps1` actuators +must be installed together: a binary that rejects the retired +`--idunn-rudp-health`, `--idunn-daemon` and `--idunn-health-contract` flags +fails to start under an old restart script, and a new script never passes them. Each private PSMoveAPI Eye worker owns optical observation admission before the parent aggregates evidence. Positions older than 50 ms, blobs below 2 px, diff --git a/docs/realtime-robustness-cut.md b/docs/realtime-robustness-cut.md new file mode 100644 index 0000000..04ba0d6 --- /dev/null +++ b/docs/realtime-robustness-cut.md @@ -0,0 +1,2145 @@ +# Muninn realtime media robustness: cut map (v2) + +Imagination pass 2, 2026-09-30. **Draft, uncommitted.** Self places it over +`Muninn/docs/realtime-robustness-cut.md` on Muninn `main` (pass 1 is `e70db69`, +and the rulings are `eb332b0`). Name that branch in every brief. + +Campaign (operator, 2026-09-30): FEC, parity, receiver-requested IDR, bitrate +adaptation, and a loss-tolerant HID edge for remote play. + +## Status header + +| | | +|---|---| +| Map state | Imagination pass 3. Q1-Q10 are ruled (below). Pass 2 mapped Cut 6 in full (Q6 = a); pass 3 re-maps the HID cuts H0-H5 to Q9 (Sleipnir is a crate in Muninn's workspace) and Q10 (Muninn advertises an input-stream capability; the consumer requests it and dials). Three new forks are open: Q11 (who owns the input-stream records), Q12 (Move evidence rides the HID listener), Q13 (whether Raven's Sleipnir is live, which gates the H2/H4 merge). | +| In Hands | Cuts 0-1 on `hands/rr-cut0-1` (`2c120c9`, `f2a5db9`, `a189363`). This pass does not touch those sections. | +| Ready for Hands | Cut 2 (the latency default is settled by Q7); Cut 3 (Q2-Q4, Q8 settled); H1 (after H0, and after Q11); H3 (any time; behaviour-neutral); Cut 6a (after Cut 2) | +| Blocked | Cut 4 (on Cut 3's tag); Cut 5 (on the pin gate); Cut 6b (on Cut 2 and Cut 5); Cut 6c (on Idunn B3 and `route/b3-declare` merging, and on FFmpeg provisioning on Raven); H2 (on Q12); the H2+H4 merge to `main` (on Q13 and H5 readiness, because `raven-muninn` deploys `main`'s head); H5 (on Idunn B3) | +| Heads read | Muninn `origin/main` `eb332b0` (code identical to `cee7b9c`), `route/b3-declare` `2260853`; CultLib `069ecc3`; Ratatoskr `488b5b1`; Odin `main` `379b826`; donor Odin `80adfd3`; Odin tag `attic/claude-cultlib-pin-c2a9a6e` `3e96c6c`; Idunn `771138a`; gamecult-ops working tree (binding `idunn/yggdrasil/bindings/raven-muninn.toml.in`, `scripts/idunn/idunn-deployment-targets.ps1`) | + +The CultLib media plane is byte-identical between Muninn's pin `c2a9a6e` and +`main` `069ecc3`: `git diff c2a9a6e main` over `media_stream_contracts.rs`, +`media_stream_wire.rs`, `rudp.rs` and `transport.rs` is empty. Every CultLib +anchor below holds at both SHAs. `M` anchors are at `eb332b0` and equal +`cee7b9c` for code. `S` = Sleipnir at Odin `main` `379b826` +(`crates/sleipnir-daemon/src/main.rs`), `DS` = the donor's Sleipnir at `80adfd3`, +and `I` = Idunn `771138a`. + +--- + +## Rulings (operator, 2026-09-30) + +- **Q1: remote play.** A viewer's controller drives a game on another host over LAN or mesh, so quick + taps must survive loss. The HID edge record is born in Muninn after named cut 1, and delivery uses + CultLib's profile-owned channels. Imagination maps the HID cuts next; nothing is specified yet. +- **Q2 (a): a pinned side-commit for now.** A single-purpose Odin commit bumps `odin-core` to Cut 3's + CultLib, and a `pins/` tag keeps it alive rather than `attic/`. Severing Muninn from `odin-core` + continues as Muninn's own cuts. Every CultLib bump repays this debt. +- **Q3: depend on `reed-solomon-erasure` 6, without simd.** A known-answer test pins the wire bytes, so + the library can be replaced without changing the wire. +- **Q4: delete the reliable `audio` channel.** Audio goes lossy with parity on `media`. This reverses the + 2026-09-10 decision. +- **Q5: audio parity comes after Opus.** Video parity ships in Cut 5. Audio stays on the reliable channel + until the Opus cut, then moves. +- **Q6 (a), against the recommendation: port the native encoder.** This is the libavdevice/NVENC child, + with an Idunn recipe step on Raven. Cut 6 gives IDR on request and bitrate adaptation, and it is the + campaign's one new native target. +- **Q7: 250 ms default, owned by the request.** It goes in the advertisement, and both ends derive from + the request. +- **Q8: fixed parity first.** Video uses `k ≤ 16`, `m = max(2, ⌈0.25k⌉)`; audio uses 4+2. The rate is + carried per record. Adaptive parity is a later cut. + + +**Pass-2 consequences of the rulings.** Every section below is rewritten to +the ruled design. The earlier options survive only in git (`e70db69`). +- Q2 names the `pins/` mechanism. The first `pins/` commit is **not** needed + for HID: `3e96c6c` already pins CultLib `c2a9a6e`, which is Muninn's current + pin. Retag it `pins/odin-core-cultlib-c2a9a6e` now, keep the `attic/` tag + until nothing references it, and cut the next `pins/` commit only at Cut 3's + CultLib tag. +- Q6 = (a) makes Cut 6 a real cut (6a-6c below). +**HID rulings, 2026-09-30.** +- **Q9: Sleipnir becomes a crate in Muninn's workspace.** It does not get its own repo, and it does not + stay in Odin. Odin's copy is deleted after the StreamPixels ship. +- **Q10: the consumer asks Muninn, and Muninn advertises the capability.** This is the opposite of the map's + viewer-dials recommendation. Operator: "Ratatoskr is asking Muninn to open a video stream, Sleipnir asks + Muninn to open an input stream. Both should be Muninn capabilities which it chooses to broadcast via + CultMesh." So Muninn publishes an input-stream capability through CultMesh beside its media capability, + and Sleipnir requests it the way Ratatoskr requests video. Both consumers dial the producing Muninn. + Pass 3 re-mapped H0-H5 to this shape. + +**Rulings, 2026-09-30 (operator), pass 3 forks:** +- **Q11 (a): the input-stream records live in `muninn-contracts` as `muninn.input_stream_*`.** The input track + needs no CultLib change. Promote them to CultLib if a second producer appears. +- **Q12 (a): Mimir's Move proof is in use.** Move evidence becomes a channel on the input-stream session, and a + small Mimir cut switches over. H2 waits for that Mimir cut. +- **Q13 (c): no live Sleipnir, so accept the gap.** H2 and H4 may merge independently. The operator said + (2026-09-30): "If Sleipnir is running, feel free to take it down; we're certainly not using it". + - Checked read-only on Raven the same day: no Sleipnir process is running. + - Only an on-demand scheduled task, `\Codex-Sleipnir-LAN-Proof`, remains. It last ran on 2026-07-17. + - Raven runs `muninn.exe` alone. + +**Cut 2 Soul pass, 2026-09-30: fix first.** The queues, caps and budget ownership hold. Findings: +- Audio waits behind a whole video group send. +- The deadline is checked only when the socket blocks. +- Whole-frame drops leave the receiver no trace. +- A packetizer overflow can emit a corrupt access unit. +- The budget has no upper clamp. + +**Ruling (Self, 2026-09-30): the receiver owns loss signalling.** A frame lost whole on the network looks the +same as one the sender dropped, so there is one owner for both: +- Ratatoskr requests a keyframe on a `frame_id` gap. This is a Cut 4 requirement. +- Cut 2 makes every sender-side drop (queue cap, expiry, packetizer overflow) consume a `frame_id`, so the gap + is visible. +- The latency budget is clamped to 2000 ms. + +## Target: ends and invariants + +**End.** A Muninn stream that loses packets degrades by what each signal class +permits, and recovers inside one latency budget without a human. Loss is +repaired by parity first, then by selective retransmit, then by a keyframe. The +sender never holds more than it can send in time, and every figure it reports +comes from observation. + +Invariants. Each one must be falsifiable by a test or a probe. + +1. **One latency budget, owned by the request.** `latency_budget_ms` on + `gamecult.media_stream_request.v1` is the only deadline source. The sender's + queue age, repair eligibility and parity grouping, and the receiver's + assembly age, all derive from it. Nothing else mints a deadline. Two + constants disagree today (finding B6). +2. **No unbounded buffers on the media path.** Every queue between the encoder + and the socket has a count bound and a time bound. Crossing the bound drops + **whole frame groups** (chunks together with their parity), oldest first. It + never returns an error that restarts the stream, and it never sends a partial + frame whose parity is then useless. +3. **Deterministic parity.** Parity bytes are a pure function of the data + shards, `(k, m)` and the scheme id. They involve no clock, no randomness and + no per-process state. A known-answer vector pins the scheme, so a library + upgrade that changes its matrix fails a test. +4. **MDS recovery guarantee.** Any `≤ m` erasures in a `k+m` block recover the + data exactly. Any `> m` erasures report failure and never produce wrong + bytes. This is proved exhaustively for every shipped `(k, m)`. +5. **One codec, both ends.** The encoder and decoder of the erasure code live in + one place, CultLib, with the record that carries it. A producer and a + consumer that disagree on the math cannot both compile against the same pin. + This is the split that stranded audio recovery in Mimir's C++ (teardown-map + L241-247). +6. **Each media payload fits one datagram, parity included.** Encoded wire size + is `≤ MUNINN_RUDP_MEDIA_MAX_FRAGMENT_BYTES` (1431; `main.rs:82-86`) for + data and parity shards alike. The fragment amplification `1-(1-p)^n` + (teardown-map L417-419) must not return through parity. +7. **Health is observed, never configured** (teardown-map L210-211). Parity + recovered, parity failed, repairs sent, IDRs requested and bitrate changes + are counted where they happen, per leg. +8. **A keyframe request is an edge, not a level.** One decode-chain + invalidation produces at most one IDR per cooldown. A recoverable missing + chunk never forces an IDR. That is already true on the receiver side: + Ratatoskr `feedback.rs:92` and CultLib `4160ab5`. +9. **The transport stays semantics-free.** CultNet RUDP gains no media-, HID- + or producer-named channel behaviour beyond what it has. The donor's + `"hid.edge"` / `"hid.edge.assist"` arms in a vendored `rudp.rs` (`9af2edb`, + `80adfd3`) are the pattern this forbids. + + +10. **One commit primitive per virtual pad.** Snapshot axes, ordered edges, + epoch baselines and staleness neutralisation all reach ViGEm through one + Sleipnir function. Within an epoch, button visibility is owned **only** by + the edge stream. The snapshot's `buttons` field is a baseline at epoch start + and nothing else. The donor overwrote snapshot buttons with the previous + record's (`DS main.rs:573-578`); that split is forbidden. +11. **A tap survives loss without transport retransmission.** A press and + release captured between two transport ticks reach the pad, in order, under + the Cut 3b profiles up to `loss-5pct` and `burst-8`. The mechanism is + redundancy: every unacknowledged edge rides every frame until it is + acknowledged. No reliable channel carries input, so there is no + retransmit debt and no head-of-line blocking. +12. **Input memory is bounded on both ends.** + - The sender keeps at most 256 unacknowledged edges **per (subscriber + session, device) window**, and rotates that window's epoch on overflow + (donor rule, `D main.rs:5846-5854`). One lossy subscriber never forces + another to rebaseline. + - A frame carries at most `MAX_EDGES_PER_FRAME` (32, or less if H1's + worst-case encode test says 32 does not fit one datagram). + - The receiver buffers nothing beyond the window it was sent. + - Stale epochs are fenced by monotonic comparison, not by a growing set + (the donor's `retired_epochs: HashSet`, `DS main.rs:210`, grows forever). +13. **Input latency is bounded, and the bound is owned by the request.** A + queued edge is held visible for 24 ms (`DS main.rs:32-35`, one 60 Hz game + sample plus margin) **unless** it is older than `input_budget_ms`. Then it + is actuated without the hold. A tap is compressed, never dropped. The + budget is Q7's shape applied to input: the advertisement carries the + default (100 ms), the request carries the value, and both ends derive from + the request. +14. **No JSON on a live wire.** Muninn↔Sleipnir today speaks JSON both ways + (B14), and the donor did too (`D main.rs:6117,6141`, `DS main.rs:693-699`). + Every HID and encoder-control message becomes a typed CultCache record in + a CultNet message. +15. **Encoder commands are typed and fire-and-forget; their effect is + observed.** Muninn writes `muninn.video_encoder_command.v1` records to the + encoder's stdin as CultNet frames. Whether an IDR happened is read from the + Annex B stream (keyframe access units). Whether a bitrate took is read from + measured bytes per second. Neither is read from what was asked (invariant 7). +16. **One video encoder path.** When Cut 6b lands, the ffmpeg CLI video child is + deleted. A missing encoder binary fails the request with a typed `detail`. + There is no fallback, because the donor's + `video_encoder_path.is_some()` switch (`D main.rs:1942`) kept two paths + alive. + +Explicitly **not** in scope: +- Mimir's `Mimir.CultMeshMedia`: a separate MPEG-TS-over-documents relay, + `mimir.cultmesh_media_frame`, `Program.cs:11`. It is not a + `gamecult.media_*` consumer. +- The retired C++ OBS receiver. It is "deliberately no longer understood" + (teardown-map L672-674). +- Opus itself, which is Muninn's own named cut. It is sequenced here, not + mapped here. + +--- + +## Probed mechanism claims + +These were run, not inferred from names. + +| Claim | How it was established | Result | +|---|---|---| +| What Muninn's sender emits | Read `media_packetizer.rs` @`cee7b9c`; Yggdrasil `cargo test -p muninn-daemon --bin muninn -- media parity repair rudp` | 78 pass. Video: data chunks plus XOR stripe parity (`gamecult.media_video_parity_shard.v2`) on `media`, unreliable. Audio: `pcm-f32le-interleaved`, 3,840-byte packets, on `audio`, **reliable**. **No audio parity.** | +| Receiver recovery present | Read Ratatoskr @`488b5b1` | Video: XOR stripe recovery, one chunk per stripe (`video.rs:224-269`). Audio: **none**; it passes straight through (`receiver.rs:320-323`). Keyframe request: yes, edge-triggered with a cooldown (`feedback.rs:92,130`). `cargo test -p ratatoskr-core` on Yggdrasil: 31 + 2 pass, including `parity_gives_back_one_lost_chunk_per_stripe` and `two_losses_in_one_stripe_are_beyond_repair`. | +| Donor GF(256) tested | Yggdrasil `cargo test -p muninn-daemon --bin muninn -- fec parity gf audio_fec video_wire` @`80adfd3` | 9 pass. Audio 4+2: exhaustive over every 1- and 2-erasure pattern (`donor media_packetizer.rs:4919`). **Video 8+4 Cauchy: only one single-erasure recovery, done by hand inside the test (`:2957`). There is no Rust multi-erasure video decoder** (it lived in Mimir's C++). **There is no known-answer vector for `gf256_mul`/0x11d**: a consistent wrong polynomial passes every round-trip. | +| An established codec fits | Scratch crate `rs-probe` on Yggdrasil, `--release` | `reed-solomon-erasure` 6 (GF(2^8)): any shard length (849 OK), exhaustive `≤m` recovery true for 4+2 and 8+4, `m+1` erasures fail cleanly. It costs 13.5 µs to encode and 11 µs to decode an 8+4 block of 850 bytes, and 2.6 µs / 3.4 µs for 4+2 at 864 bytes. `reed-solomon-simd` 3: **refuses odd shard sizes** (`InvalidShardSize{849}`), decode about 230 µs per block. | +| Current XOR vs RS at equal overhead | iid model, `python` (arithmetic, not a harness) | For a 200-chunk keyframe at 3% loss, XOR16 fails the frame **63%** of the time at 8% overhead, and RS 8+4 fails 4e-4 at 50%. For frames of `n ≤ 16` chunks, XOR16 is **duplication**: each stripe holds one chunk, so the overhead is 100%. | + +| Muninn↔Sleipnir HID wire today | Read `M main.rs` and `S main.rs` | **JSON both ways.** Subscription: `S :2303-2310` → `M :6216-6217`. State: `M :6298-6300` (ingress server) and `M :6835-6836` (outbound client) → `S :2485-2498`. Sleipnir coalesces "latest wins" per device (`S :2543-2590`), so a tap between two received frames never reaches ViGEm. | +| CultLib channel delivery | Read `C rudp.rs:2339-2410` | Only `media` takes its delivery from the profile, plus `audio` hardcoded Reliable. `schema`, `latest` and `_` are fixed by name. `latest` is Unreliable and **Sequenced per channel** (`:2384-2390`, `:185-191`), so a late older packet is dropped. The window-per-frame design fits this exactly, because each frame supersedes the last. **No CultLib change is needed for HID.** | +| Idunn host-native runner for the encoder | Read `I src/host.rs:934-960`, `I src/deployment.rs:55-110`, the binding | The Raven runner's `allowed_programs = ["cargo"]`. **Host-native materialisation refuses `external_inputs`** (`I host.rs:953-956`), so a sha-pinned FFmpeg download cannot be a recipe input on Raven. Runner environment comes from the binding (`[runners.rust-host.environment]`, precedent `CARGO_NET_GIT_FETCH_WITH_CLI`). `[service] required_adjacent_artifacts` exists (`I deployment.rs:113`). Recipe phases include `acceptance` (`:71-77`). | +| Donor encoder shape | `git show 80adfd3:native/muninn-video-encoder/*` | 265 lines of C++20, CMake with `FFMPEG_ROOT`. lavfi `ddagrab` → decoder → `h264_nvenc`. A `std::getline` stdin thread parses `IDR` / `BITRATE n` / `QUIT`. `fail()` calls `exit(1)`. Bitrate is reconfigured by mutating `AVCodecContext` before `send_frame`, and IDR by `pict_type = I` with `forced-idr=1`. The build script links the OBS deps snapshot at an `E:\Projects\Mimir` path that no longer exists. | +--- + +## Body findings + +`M` = Muninn `cee7b9c`, `C` = CultLib `069ecc3`, `R` = Ratatoskr `488b5b1`, +`D` = donor Odin `80adfd3`, `O` = Odin `main` `379b826`. + +**B1. Audio has no parity and rides a reliable channel.** +- `M media_packetizer.rs:1055-1063` sends audio on `MUNINN_AUDIO_RUDP_CHANNEL`. +- `C rudp.rs:2218-2228` profiles `"audio"` as `Reliable` whatever the options + say. Only `media` is configurable (`C rudp.rs:2208-2211`). +- `C media_stream_contracts.rs:34-41` says outright that audio has no parity + record. +- The `audio` channel exists only so that audio could be reliable + (`C media_stream_wire.rs:41-44`). Once audio is lossy with parity, it has no + reason to exist. + +**B2. PCM packets fragment.** 480 ticks × 2 ch × 4 B = 3,840 B +(`M main.rs:2455-2470`) against a 1,431-byte fragment limit (`M main.rs:82-86`). +So every audio packet is 3 datagrams. Parity over PCM protects 3-fragment +shards (roughly 3p shard loss) and costs 1.5 Mbps at 4+2. Opus at about 183 kbps +(teardown-map L475) fits one datagram. + +**B3. Video parity is XOR stripes, per frame.** +- `M media_packetizer.rs:625` sets `STRIPES = 16`. +- `:627-724` builds the stripes and `:726-754` writes data and then parity. +- The recovery guarantee is one loss per stripe. See the probe table for what + that costs on keyframes and small frames. +- The v2 record carries only stripe geometry (`C media_stream_contracts.rs:466-517`). + It cannot describe an RS block. + +**B4. A keyframe request is counted and ignored.** +- `M main.rs:3036-3048` `record_receiver_keyframe_pressure` logs "continuing + current low-latency encoder session until explicit encoder control exists". +- teardown-map L666-668 claims "the sender turns every new keyframe request into + an IDR". **That is false.** +- Recovery today is the fixed all-IDR GOP: `framerate/4` + (`M main.rs:10309-10311`) with `-g`, `-keyint_min` and `-forced-idr 1` + (`:10405-10410`). A lost reference therefore freezes for up to 250 ms. Ratatoskr + shows nothing until the next keyframe (`R video.rs` test + `nothing_is_delivered_between_a_loss_and_the_next_keyframe`, `:720`). + +**B5. No bitrate adaptation.** +- Bitrate is fixed per command (`M main.rs:1481-1487`, `:10399-10404`). +- What adapts is the **repair** rate (`MuninnRudpRepairBudget`, + `M main.rs:2744-2827`), not the encode rate. +- The ffmpeg CLI child (`:10343-10421`) has no live control surface. A change + of bitrate is a restart (`:1475`). + +**B6. The latency budget has two owners.** +- Producer: an empty request budget becomes + `MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS = 2_000` + (`M main.rs:95,1489-1495`). That default drives the sender queue deadline, + audio expiry and the advertisement default (`:10286-10291`, `:1159`). +- Consumer: Ratatoskr sends 0, so it gets the 2 s default + (`R catalog.rs:174,198`), but it ages frames at its own **250 ms** + (`R video.rs:99-101`). +- So the sender will queue video for up to 2 s that the receiver has already + given up on. + +**B7. The sender's buffers are unbounded in count.** +- `M main.rs:2427` is `mpsc::channel` (unbounded), and + `PendingMuninnMediaSendQueues` (`:2701-2731`) is two unbounded `VecDeque`s. +- Payloads expire **individually** by age (`:2505-2532`). Half a frame can be + sent after its other half expired, which spends bandwidth on an undecodable + frame and its useless parity. +- The Annex B reader errors the whole stream when `pending > max_pending_bytes` + (`M media_packetizer.rs:296-306`) instead of dropping. +- Backpressure spins with `thread::sleep(1 ms)` (`M main.rs:2981`). + +**B8. Repairs renew their own send deadline.** +`poll_rudp_media_receiver_feedback` passes `Instant::now()` as `queued_at` for +every repair (`M main.rs:3125-3132`). A repair's age budget therefore starts +when it is asked for, not at the frame's deadline. This breaks invariant 1 +(donor doctrine: "a repair cache must not mint a new deadline", +`D docs/realtime-delivery-authority.md`). + +**B9. Receiver residue is still in the producer.** +- `AudioPacketBuffer` (`M media_packetizer.rs:847-987`) is a receiver jitter + buffer. +- The whole-stream helpers `packetize_video_annex_b_stream` (`:756-805`), + `encode_video_annex_b_stream_wire_records` (`:1017-1029`), + `video_annex_b_stream_send_payloads` (`:1031-1036`) and + `encode_record_payload`/`decode_record_payload` (`:1080-1090`) are called + only from tests. The tests are `media_packetizer.rs` `#[test]`s at + 1533/1570/1602/1820-1930/1992/2033/2078/2467, and `main.rs:12353,12395`. +- teardown-map L463-465 ("Muninn now holds only the producer half") is false. + +**B10. The mux loop has no seam.** `run_rudp_mux_once` (`M main.rs:2292-~2680`) +fuses process spawning, hub opening, catalog publishing, queueing, feedback, +repair and progress logging. No test can drive the send path without +PowerShell, ffmpeg and WASAPI. That is why "not exercised live" only ever meant +exercised on Raven. + +**B11. The CultLib pin is welded to an attic tag.** +- Muninn builds `odin-core` from Odin `3e96c6c` (`M Cargo.toml:25`). That + commit is on **no Odin branch**. Only the tag + `refs/tags/attic/claude-cultlib-pin-c2a9a6e` holds it + (`git ls-remote origin`). +- Odin `main` itself pins CultLib `a8aedda` (`O crates/odin-core/Cargo.toml:14-17`), + which is **older** than Muninn's `c2a9a6e`. +- odin-core's types are `DatabaseEntry`. Any CultLib bump in Muninn therefore + reopens the two-`cultcache-rs` diamond (teardown-map L616-619) unless odin-core + moves too. +- Muninn uses 21 odin-core symbols (`M main.rs:27-37`). Four are Odin's: + `EveProviderAdvertisementRecord`, `EveSurfaceStateRecord`, + `IdunnDaemonHealthRecord` and `OdinDocuments`. teardown-map L621-626 says 23 + and 7; `discover_provider_endpoints` and `OdinEndpointQuery` are no longer + imported. + +**B12. The donor's shape.** 29 commits, `2796884..80adfd3`, 2026-07-12..17. It +predates Muninn's extraction (teardown-map L628-629), the CultLib media +contract (`a250ec6` onward), and the consumer-dials-producer inversion. +- Its records are `muninn.*` in odin-core: video parity **v4**, audio parity + v1 (`D odin-core documents.rs`). +- Its transport is a single dialled client (`CultNetRudpSocketTransportConnection`, + `D main.rs:684`), not the hub. +- Its encoder control is a native C++ child, + `native/muninn-video-encoder/main.cpp` (265 lines, libavdevice with + `h264_nvenc`, stdin `IDR` / `BITRATE `). +- Its doc and code disagree on bitrate recovery: the doc says 5% every 2 s, + the code does `max/50` every 10 s (`D main.rs:2502-2507`). +- Its bitrate ceiling is **half** the configured rate, because "Block FEC can + roughly double the encoder payload" (`D main.rs:2454-2458`). +- Its "dispersed video parity" (`e58e0a7`) is not cross-frame: it was + bookending, then superseded by a within-frame round-robin over blocks + (`4e2abee`; `D media_packetizer.rs:1295-1360`). + +**B13. The donor's HID edge rewrites the transport.** +- `9af2edb` and `80adfd3` hardcode `"hid.edge"`, `"hid.edge.ack"`, + `"hid.subscribe"` and `"hid.edge.assist"` into a vendored `rudp.rs`, plus an + ACK-state change. +- The consumer, `sleipnir-daemon`, is in **Odin** (`O crates/sleipnir-daemon`, + 3,658 lines). The record is `MuninnHidControllerStateRecord` in odin-core + (latest-state snapshot, `buttons: Vec`; `3e96c6c documents.rs:1524-1547`). +- Today Muninn sends snapshots only (`M main.rs:6172-6200, 6758-6800`), so a tap + shorter than one sample, or lost with its packet, never happens. + +**B14. The HID wire is JSON, and a tap dies at two places.** +- The wire: `M main.rs:6137-6142, 6216-6217, 6298-6300, 6835-6836`; + `S main.rs:2303-2310, 2497-2498`. The 2026-09 repo census flagged the same + lines (`gamecult-ops/docs/repo-census-2026-09/repos/Odin.md:48`). +- **Muninn reads a source once per transport tick** + (`read_hid_controller_state_for_stream`, `M :6286`, `:6370`). A press and + release inside one tick never exist as data. +- **Sleipnir keeps only the latest record per device** (`S :2543-2590`), so a + tap that survived capture dies again at the sink. + +**B15. Muninn has two HID transport paths, and so does Sleipnir.** +`M` here is Muninn `main` `c3520d1`; HID lines moved +7 to +9 since `eb332b0`. +- Muninn listens: `--hid-controller-rudp-bind`, `M :6151-6340`. This is the one + Raven runs (recipe `raven-muninn.toml:62-65`, advertised `10.77.0.4:17887`), + and Starfire's legacy script can run it too + (`restart-starfire-muninn.ps1:14-15, 74-79`). +- Muninn dials: `--hid-controller-rudp-target`, `M :6724-6863`, parsed at + `:10899-10904`. +- Sleipnir mirrors both: it dials a discovered endpoint, or listens on + `--rudp-bind` (`S :2191-2281`, server branch `:2244-2281`). +- **Q10 settles it:** the consumer dials the producer's advertised endpoint, + exactly as Ratatoskr dials Muninn for video. The surviving direction is + "Muninn listens, Sleipnir dials". Muninn's outbound client and Sleipnir's + listening mode are the losing paths; H2 and H4 delete them. + +**B16. Sleipnir is welded into Odin's pin.** +- `S` is a member of Odin's workspace. It takes `odin-core` by path + (`Odin crates/sleipnir-daemon/Cargo.toml`) and CultLib at `a8aedda`, which is + Odin `main`'s pin, the one StreamPixels ships on. +- It imports 10 odin-core symbols (`S :10-14`). One is Muninn's HID record, + and one is its own `SleipnirInputMappingRecord`. +- Any Sleipnir change that consumes a Muninn-owned record at Muninn's CultLib + (`c2a9a6e`) reopens the two-`cultcache-rs` diamond **inside Odin's + workspace**, and that can only be closed by moving Odin `main`'s pin. +- Its deployment target is the legacy script-driven `raven-sleipnir` + (`gamecult-ops/scripts/idunn/idunn-deployment-targets.ps1:126-138`, + `Repo = "Odin"`, scheduled task plus SSH). It has no Idunn recipe. **Whether + it runs on Raven today is unverified.** + +**B17. The sink already has the seam a harness needs.** +`trait VirtualPadBackend { fn update(&mut self, state: &VirtualPadState) }` +(`S :179-181`) has a `LoggingBackend` (`:183`) beside the ViGEm one +(`:200-240`, `cfg(windows)`). A recording backend gives a pad timeline on Linux. + +**B18. Raven cannot fetch the encoder's FFmpeg through Idunn.** +Host-native materialisation refuses `external_inputs` (`I host.rs:953-956`), and +the runner may execute only `cargo`. So the FFmpeg development root must be: +- pre-provisioned on Raven (operator action, recorded in gamecult-ops with its + sha256); +- named by the binding's runner environment; +- compiled against by `build.rs`, through the `cc` crate for the C++ and link + directives for FFmpeg. No CMake step and no new allowed program. + +`ffmpeg_path` today points at a WinGet static `ffmpeg.exe` (binding +`raven-muninn.toml.in`, `ffmpeg_path`), which has no headers or import +libraries. + +**B19. The recipe is mid-edit by another campaign.** `route/b3-declare` +(`2260853`, unmerged) adds `[[dependencies]] odin.verse-rendezvous` to +`deployment/idunn/raven-muninn.toml`. Cut 6c edits the same file and must build +on it after it merges. + +**B20. Move evidence rides the HID listener, and Mimir consumes it.** +- `serve` gets the Move-evidence sender back from + `start_hid_controller_rudp_ingress` (`M :429-437`), and the ingress thread + sends it on channel `move-evidence` over the HID connection id + (`M :6271-6283`). +- It sends only while an HID subscription is selected (`M :6258-6269`), so a + consumer that wants Move evidence must speak the JSON `hid.subscribe`. +- Mimir does exactly that: `MimirOdinMoveProofEvidenceRingProvider.cs:223` + (Mimir `d88f2e6`) sends `{"streamId": ...}` on `hid.subscribe`. It discovers + the endpoint from the JSON `inputStreams` in Muninn's Eve provider + advertisement (`M :3713-3722`), channel `move-evidence`. +- The local ring is switched on by the absence of the HID bind + (`local_ring_enabled: options.hid_controller_rudp_bind.is_none()`, + `M :4238`). +- So deleting the JSON subscription (H2) silently stops Move evidence reaching + Mimir. The pass-2 map did not know this second consumer existed. Q12. + +**B21. HID discovery is JSON scraped out of Eve advertisements.** +- Muninn writes its HID endpoint and devices as JSON into three places in + `publish_runtime_boundary_records`: the transport profile's `input_streams` + (`M :3674-3699`, key at `:3856`), the provider advertisement's + `inputStreams` (`M :3701-3727`, key at `:3885`) and its `endpoints` + (`M :3729-3750`), in two casings. +- Sleipnir recovers it by pulling `muninn.hid_controller_state.v1` records to + learn host ids (`S :978-1003`), then pulling those hosts' provider + advertisements (`S :950-975`), then parsing JSON in either casing and in + tuple shape (`S :1845-2131`, `:2370-2478`), with Odin's generic + `discover_provider_endpoints` as a fallback (`S :2380-2398`). +- The video capability has none of this: one typed advertisement, one typed + request (`R catalog.rs:64-145`, `M :971-1166`). That typed path is what Q10 + orders input to mirror. +- The Odin-facing `publish_hid_controller_state_to_odin` (`M :6865-6875`, a + store `put` keyed by stream id) has **one reader**: Sleipnir's discovery. + Nothing else in Odin, Mimir, Ratatoskr, StreamPixels, Eve, VoidBot, Heimdall + or Idunn names the schema (`git grep`, 2026-09-30). + +**B22. Two readers own the same HID devices.** +- The serve tick reads every source to build receipts + (`publish_move_controller_states`, `M :4976-5134`). +- The ingress thread reads the same sources again at its own tick + (`read_hid_controller_state_for_stream`, `M :6377-6528`). +- The collision is fenced, not removed: on Windows the tick skips PS Move + sources whenever the HID bind is set (`M :5081-5086`), because the report + reader thread would otherwise have two consumers. +- Neither reader samples fast enough for a tap. The ingress loop sleeps 8 ms + (`M :6338`), and Sleipnir's default interval is 8 ms (`S :2791`). The + pass-2 map's "2 ms at the current poll (`HID_CONTROLLER_RUDP_POLL_INTERVAL`)" + is the **donor's** constant (`D main.rs:5879`). It does not exist at `c3520d1`. + +**B23. A producer restart orphans every running request.** +- `sync_media_stream_requests` admits only requests in state `pending` + (`M :1004`). The "already answered" memory is process-local + (`answered_requests`, `M :463`). +- So after a Muninn restart, every request it had answered `running` stays + `running` on Odin and is never admitted again. The consumer must notice and + publish a fresh request. +- Whether Ratatoskr re-requests is **unverified** (the redial lives in + `R receiver.rs`, and the request lives in the OBS plugin's C). +- H2 does not copy this. An input request is admitted as **demand**, by + `action`, and its `state` is only the producer's answer. The same change for + media belongs to Muninn's media owner and is recorded, not made, here. + +--- + +## Donor ledger: port, rewrite, drop + +| Donor piece | Verdict | Why | +|---|---|---| +| `gf256_mul`/`gf256_inv`, `recover_audio_fec_data`, `video_fec_coefficient` (`D media_packetizer.rs:1177-1180, 1525-1612`) | **Drop; replace with `reed-solomon-erasure`** (Q3) | No video decoder, no KAT, and it solves a matrix per byte for audio. The probed crate is MDS-exhaustive at the shipped sizes and fast enough by 3 orders of magnitude. Owned math is a liability we need not carry. | +| 4+2 audio block and 8+4 video block sizing | **Port as defaults**, parameterised as `(k, m)` in the record | Field-chosen numbers, but carried by the record so a decoder needs no config. | +| Within-frame round-robin send order over blocks (`D :1295-1360`) | **Port** (rewrite against CultLib types) | Turns a burst into one loss per block. It is policy, not math. | +| `pad_audio_codec_frame` 2-byte BE length prefix (`D media_packetizer.rs:674-686`) | **Port** into the Opus cut's framing (`opus-padded-v1`) | Constant shard size for variable codec frames. Matches the `aac-adts-padded-v1` precedent (teardown-map L477-479). | +| Datagram-fit tests (`D :3065`, `production_aac_audio_fec_shards_fit_one_rudp_datagram`) | **Port as behavioural tests** at the CultLib codec and in Muninn | They pin invariant 6. | +| Exhaustive erasure test (`D :4919`) | **Port**, generalised to every shipped `(k, m)` | Pins invariant 4. | +| `MuninnKeyframeRequestGate` (`D main.rs:2864-2884`, cooldown 500 ms at `:102`) | **Port** (Cut 6) | Small and correct: an edge with a cooldown. | +| `MuninnVideoBitrateController` (`D :2439-2512`) | **Rewrite** (Cut 6b) | Its ceiling halving assumes 50% FEC overhead, and its doc and code disagree. The rewrite keys the ceiling on the ruled parity rate and aggregates across hub receivers, which the donor predates. | +| `native/muninn-video-encoder/main.cpp` (265 lines) | **Port** the capture and encode loop (Cut 6a). **Rewrite** its shell. | Kept: the lavfi → decode → encode loop, NVENC options, `pict_type = I` and `AVCodecContext` bitrate mutation. Deleted: `main`, `parse_options`, the `std::getline` text command thread, `fail()`/`exit`, and `fwrite` to stdout. They become a C ABI (`muninn_encoder_run` with poll and write callbacks) under a Rust `main` that decodes typed command records (invariant 15). | +| `CMakeLists.txt`, `scripts/build-muninn-video-encoder.ps1` | **Drop** | `build.rs` with the `cc` crate compiles the C++. The Idunn runner may run only `cargo` (B18). The script's FFmpeg path no longer exists. | +| `capture_button_edges`, `ActiveHidControllerRudpSource` edge fields, overflow epoch rotation (`D main.rs:5732-5856`) | **Rewrite** as two pieces in `muninn-contracts::hid` (H1): `EdgeDetector` (diffs samples; runs on the capture thread, H2) and `EdgeWindow` (per subscriber session and device; owns epoch, pending bound and acks; runs on the input transport tick, H2). | The rotation and bound rules are right. The donor ran detection at transport-tick time, which loses sub-tick taps (B14); it kept one window per source, which cannot serve two subscribers; it cloned `epoch` needlessly; and it sent JSON. | +| Donor's `hid.edge` (reliable) + `hid.edge.assist` (unreliable resend) channels and the `hid.subscribe`/`hid.edge.ack` JSON | **Drop** | Two mechanisms for one job, plus four transport name arms (invariant 9). Replaced by one frame on the profile-declared `latest` channel that carries state and the unacknowledged window (invariant 11). | +| `HidSemanticCursor` (`DS main.rs:204-256`) | **Port** into `muninn-contracts::hid::EdgeCursor` (H1), with the `retired_epochs` set **replaced** by a monotonic epoch fence | The ordering, dedupe and gap bound (256) are right. The unbounded set is not (invariant 12). | +| `INPUT_EDGE_MINIMUM_VISIBILITY` 24 ms and the actuation queue (`DS main.rs:32-35, 655-700`) | **Port** into Sleipnir (H4), with the budget override added | Invariant 13. The donor queue has no latency ceiling. | +| Snapshot-buttons overwrite (`DS main.rs:573-578`) | **Drop** | Split button ownership (invariant 10). | +| Donor capture-thread split (`fb4f331`), 1 ms XInput sampling (`D main.rs:5881, 6880-6940`) | **Port** (H2) | This is where a tap first exists as data. | +| `crates/sleipnir-daemon/examples/xinput_edge_observer.rs` (`80adfd3`, 127 lines) | **Port** as Sleipnir's live probe (H5) | It reads the virtual pad through XInput, as the game does. That is the layer where a lost tap is visible (SKILL: instrument the layer the user sees). | +| Bounded `sync_channel` plus per-frame groups, capacities 256/512 (`D main.rs:85-87, 2023-2028, 2356-2369`) | **Port the shape**, rewrite against the hub loop (Cut 2) | Exactly invariant 2. | +| `cultnet-impair` (696 lines, seeded loss/burst/jitter/reorder/dup/stall, CSV) | **Port to CultLib** `packages/cultnet-rs/examples/` (Cut 3b) | It is a CultNet transport tool. `media_delivery_probe.rs` already sits there and expects it (its header, `C examples/media_delivery_probe.rs:5`). | +| Vendored `rudp.rs` ACK changes (`9af2edb` `direct_ack_state`, ACK reliable duplicates) | **Drop** | CultLib evolved separately (`75c1807` acknowledges retransmits across horizons; `47b9fc4` changes reader semantics). Anything still missing is a CultLib finding with its own proof, not a port. | +| `muninn.*` v4/v1 parity schemas | **Drop** | Superseded by `gamecult.*` in CultLib. No live reader. | + +Recommend Self tags the donor `parked/muninn-bounded-realtime-send` at `80adfd3` +before anything cites it again. This is the parked-not-dead pattern: the branch +is untracked per the morning file item 11. + +--- + +## Where FEC lives: owner decision + +**Owner: CultLib `cultnet-rs`, a new `media_fec.rs` module beside +`media_stream_wire.rs`.** It holds pure functions and no I/O. + +- **Not Muninn.** The receiver needs the decoder, so a codec in Muninn is either + duplicated in Ratatoskr or missing there. The first reproduces the Mimir split + (invariant 5). The second reproduces today's audio situation. +- **Not CultNet RUDP (transport FEC).** + - Transport FEC would group datagrams by send time, not by frame and + deadline. A block spanning two frames delays the first frame's recovery + past its deadline. + - It would also sit beside the frame-level NACK repair that Muninn and + Ratatoskr already run through `gamecult.media_receiver_feedback`, giving + two recovery authorities for one loss. + - The media plane's rule "a media payload fits one datagram" (invariant 6) + removes the one advantage transport FEC would have, which is protecting + fragments. + - The transport stays semantics-free (invariant 9). +- **Not CultMesh.** CultMesh carries state and discovery documents through Odin, + the advertisement and the request. Media records are CultNet wire records on a + live session and are never stored. FEC has no document to live in. +- **Not a new crate.** Authority separation does not buy a package. The media + plane is two files in `cultnet-rs` today, and every consumer (Muninn, + Ratatoskr, StreamPixels' vendored copy) already links it. + +What the module owns: +- the scheme id; +- `protect(frame_records, policy) -> send-ordered wire records` for video; +- `protect_audio(block) -> parity records`; +- `recover(block shards) -> Result`. + +What it does **not** own: +- the `(k, m)` choice, which is policy and belongs to the producer (Q8); +- when to give up, which is the receiver's deadline (invariant 1); +- sockets. + +--- + +## Identity, lifecycle and authority (0b) + +| Kind | What names it | What happens to it over time | Who decides | +|---|---|---|---| +| Video parity shard `gamecult.media_video_parity_shard.v3` | `(stream_id, session_id, frame_id, block_index, parity_index)`; the key extends today's (`C media_stream_wire.rs:92-110`) | Emitted with its frame's group, and dropped with the group at the deadline. Never repaired, never cached for repair. v2 is **deleted**, not kept beside it. | Producer emits. CultLib codec defines the bytes. Receiver consumes until the frame deadline. | +| Audio parity shard `gamecult.media_audio_parity_shard.v1` | `(stream_id, session_id, base_packet_id, parity_index)` | Emitted after its k-th data packet. It expires with the block's latest deadline. Lands only after Opus (Q5). | Same. | +| FEC scheme id (`rs-gf256-v1`) | A string on each parity record | Changes only with a new schema version. A KAT pins it. | CultLib. | +| `(k, m)` policy | Carried per parity record (`block_data_count`, `parity_count`) | Fixed (Q8): video `k ≤ 16`, `m = max(2, ⌈k/4⌉)`; audio 4+2. | Producer (Muninn). | +| Latency budget | `gamecult.media_stream_request.v1.latency_budget_ms` (key 11) | Fixed for a request. Default 250 ms in the advertisement (Q7). A new request restarts the child (teardown-map L533). | **Consumer** asks; producer honours it. | +| Keyframe request | `requested_keyframe` on feedback | Counted per receiver. It is an edge: at most one IDR per 500 ms cooldown per stream. | Receiver asserts. Muninn's gate decides (6b). | +| Encoder command `muninn.video_encoder_command.v1` | `(encoder process, command_sequence)`. The sequence is monotonic from 1 per spawned encoder process. | Lives only on the stdin pipe. Never stored. It dies with the process; a respawn restarts the sequence at 1. | Muninn's `EncoderControl` writes. The encoder applies at the next frame. **Effect is observed from the bitstream**, not acknowledged. | +| Live encode bitrate | Observed bytes per second over a 1 s window | Moves within `[floor, ceiling]` from the request's `video_bitrate_kbps` and the parity rate | Muninn's bitrate controller (6b) | +| Input-stream advertisement `muninn.input_stream_advertisement.v1` (Q11) | `stream_id` (`muninn..input`) | Republished on the same cadence and at the same site as the media advertisement. State `available` / `streaming` / `unavailable`. | Muninn (producer). | +| Input-stream request `muninn.input_stream_request.v1` (Q11) | `input_stream_request_key(stream_id, receiver_id)` | The consumer publishes `start` or `stop`. The producer admits it **as demand**, by `action`, not by `state` (B23), and writes its answer (`running` / `stopped` / `failed` with `detail`) onto the same key. A new request supersedes the old one under the key. | **Consumer** asks (Sleipnir); producer answers. | +| Input session | The hub session whose connect payload is the request's `receiver_id` (the Ratatoskr rule, `R receiver.rs:40-42`) | Lives while the consumer is attached. A session with no admitted request is served nothing. | Consumer dials; Muninn's input hub admits. | +| HID epoch | `(session, device_id, epoch: u64)`. The epoch is the window's monotonic creation time in ns, and `+1` on overflow rotation. | New per window (session attach, device change, process start) and per overflow. The receiver fences any epoch below its current one. | Muninn's `EdgeWindow`. Sleipnir only fences. | +| HID state sequence | `(session, device_id, epoch, state_sequence)` | Monotonic per epoch. Each frame supersedes the last (the `latest` channel is sequenced per session). | Muninn. | +| HID edge | `(session, device_id, epoch, edge_sequence)`, contiguous from 1 per epoch | Detected once, at sample time, on the capture thread. Pending per window until acknowledged. Resent in every frame while pending, at most `MAX_EDGES_PER_FRAME` per frame and 256 held. Overflow rotates that window's epoch and drops its history. | Muninn detects (capture) and delivers (window). Sleipnir applies in order and acknowledges cumulatively. | +| HID edge ack `muninn.hid_edge_ack.v1` | `(device_id, epoch, applied_through)` on the consumer's session | Cumulative and idempotent. Resent each Sleipnir tick while nonzero. | Sleipnir. | + +--- + +## Cut 0: correct the Muninn maps against git (docs only) + +**Status: in Hands on `hands/rr-cut0-1` (`2c120c9`, `f2a5db9`, `a189363`). Unchanged by pass 2.** + +Repo Muninn, `main`. Hands, doc-only. Nothing is deleted from history. Superseded +claims are marked as history in place and not left as two live designs. + +Corrections to `docs/teardown-map.md` @`cee7b9c`: + +| Line | Says | Git says | +|---|---|---| +| 1-3 | "(pre-rebuild)", dated 09-09, body at `Odin\crates\muninn-daemon` | Live repo `GameCult/Muninn`. `main.rs` is 15,134 lines and `media_packetizer.rs` 2,633. | +| 24 | CultLib pin `c13b6ba0` | `c2a9a6e` (`Cargo.toml:21-23`) | +| 50, 65 | "19 muninn.* schemas… in odin-core", "20 symbols" | The four media schemas moved to CultLib (`gamecult.*`). 21 odin-core symbols (`main.rs:27-37`). | +| 450 | Ratatoskr "Pinned to CultLib `d1a9eda`" | `c2a9a6e` (Ratatoskr `Cargo.toml:16-18`) | +| 463-465 | "Muninn now holds only the producer half" | `AudioPacketBuffer` and the whole-stream helpers remain (B9). Cut 1 makes the sentence true. | +| 611 | CultLib `main` `05e0925` | Contract unchanged since `c2a9a6e`. `main` is `069ecc3`. | +| 615-642 | "The one thing blocking a clean Muninn build… uncommitted `[patch]`… `Cargo.lock` untracked" | Resolved (L684-686). `Cargo.lock` is tracked (`60ed6b2`). Mark as history. **Add:** odin-core comes from `3e96c6c`, which is reachable only through the attic tag (B11). | +| 621-626 | 23 symbols, 7 Odin's | 21 symbols, 4 Odin's (B11) | +| 656-659 | "Not yet exercised live: Raven runs a pre-b679fc2 Muninn" | Contradicted by L536-603. Both legs were proven 2026-09-10/11 on `bc43e1b`+. | +| 666-668 | "the sender turns every new keyframe request into an IDR" | False. `main.rs:3036-3048` logs only (B4). | + +Corrections to `docs/muninn-media-streaming.md` @`cee7b9c`: + +| Line | Says | Code says | +|---|---|---| +| 240 | preset `p1` | `p5` (`main.rs:10279`) | +| 249 | chunks `480` bytes | `848` (`main.rs:81`) | +| 258-259 | resend `5` ms inside a `75` ms expiry | `30` ms (`main.rs:94`). Expiry is the latency budget, default 2,000 ms (`main.rs:95`). | + +Verification: `git diff --stat` shows only the two docs. Soul checks each row +against `git show cee7b9c:`. Ledger: ±0 code. + +--- + +## Cut 1: subtract the receiver residue from the producer + +**Status: in Hands on `hands/rr-cut0-1` (`2c120c9`, `f2a5db9`, `a189363`). Unchanged by pass 2.** + +Repo Muninn, `main`. This is a subtraction cut, kept separate from behaviour +cuts. No pin change. + +**Deletes first** (`media_packetizer.rs` @`cee7b9c`): +- `AudioPacketBuffer` plus its impl, `:847-987`, and its 5 tests + (`audio_packet_buffer_*`, around `:1820-1935`); +- `VideoAnnexBStreamPacketizeOptions` `:162-173`, + `VideoAnnexBStreamWireOptions` `:175-180`, `packetize_video_annex_b_stream` + `:756-805`, `encode_video_annex_b_stream_wire_records` `:1017-1029` and + `video_annex_b_stream_send_payloads` `:1031-1036`; +- `encode_record_payload` / `decode_record_payload` `:1080-1090`; +- empty-line runs left by earlier cuts (`:230-240`, `:403-406`, `:552-556`, + `:1091-1099`). + +**Keeps and moves.** These tests prove real packetizer behaviour and are +**re-homed onto `VideoAnnexBStreamSendState`**, not deleted: +- `packetizes_annex_b_stream_into_timed_video_records` (`:1533`); +- `packetizes_non_reference_h264_p_frames_without_dependency` (`:1570`); +- `rejects_negative_annex_b_stream_deadline_delay` (`:1602`); +- `media_wire_batches_annex_b_video_records` / `media_wire_encodes_annex_b_stream_for_sender` / `media_send_payloads_pin_video_to_media_channel` (`:1992, 2033, 2078`); +- `main.rs:12340-12420`, the two fragment-limit tests. + +`feedback_payload_decodes_legacy_record_without_chunk_keys` (`:2467`) proves a +CultLib `default` key. Delete it here if `C tests/media_stream_contracts.rs` +already pins key 10's default. Otherwise move it there. Hands checks which +applies and reports. + +**Adds:** none. + +**Verification:** +- `cargo build --release -p muninn-daemon` and + `cargo test -p muninn-daemon --bin muninn` on Yggdrasil via ygg-verify. +- A negative grep: `rg "AudioPacketBuffer|packetize_video_annex_b_stream\b|decode_record_payload" crates/` + returns nothing. +- `cargo mutants --in-diff` scoped to `media_packetizer.rs`. + +**Ledger:** about −330 lines, no new surface. + +--- + +## Cut 2: bounded sender, one deadline owner, and a drivable seam + +Repo Muninn, `main`. No pin change. Cut 5's parity rides on it. + +Q7 ruled: the default is 250 ms, owned by the request. It goes in the advertisement, and Ratatoskr derives its `max_frame_age` from its request (Cut 4). + +**Authority map.** +- **Owner:** a new `MediaSendCore` in Muninn. It holds the queues, the hub, the + feedback intake, the repair cache and budget, and the progress stats. +- **Inputs:** `Read` sources for encoded video and audio, a `MediaSendPolicy` + derived **only** from the request (`latency_budget_ms`, `video_bitrate_kbps`, + `media_packet_bytes`), a `CultNetRudpServerHub`, and a clock. +- **Outputs:** payloads on the hub, repairs to the asking receiver, stats. +- **Derived state:** + - the queue deadline, repair eligibility and audio expiry derive from + `policy.latency_budget`; + - `MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS` is **no longer an owner**. + It dies, and the advertisement's `default_latency_budget_ms` takes the + 250 ms constant (Q7). +- **Forbidden writers:** + - `Instant::now()` as a repair's `queued_at` (`main.rs:3129`). A repair + inherits its frame's deadline. + - Per-payload expiry. Expiry is per group. + - `VideoAnnexBStreamSendState` erroring on overflow + (`media_packetizer.rs:296-306`). Overflow drops the oldest complete access + unit and counts it. +- **Shared paths:** live sends, repairs and the harness all go through + `MediaSendCore`. `run_rudp_mux_once` keeps process spawning and publishing, + and nothing else. +- **Deletion line:** `mpsc::channel` at `main.rs:2427`, the unbounded + `PendingMuninnMediaSendQueues` (`:2701-2731`), per-payload expiry (`:2505-2532`), + and the 1 ms sleep spin (`:2981`), which becomes a bounded poll of resends + that stops at the group deadline. + +**Adds (types and rules only):** +- `QueuedMediaGroup { kind, deadline: Instant, payloads }`. One access unit with + its parity, or one audio packet. +- `mpsc::sync_channel` with a small bound, as in the donor (`capacity 1` of + groups). +- Per-kind group caps: audio 256, video 512 in the donor. Cap them in **groups**, + and name the byte ceiling they imply. +- Drop-oldest-group on cap, counted as `groups_dropped_{audio,video}`. +- Audio before video, as today (`:2705-2716`). + +**Harness seam (the reason B10 matters).** A `#[cfg(test)]` driver feeds +`MediaSendCore` from a committed Annex B fixture. It needs: +- a short H.264 clip, generated once and committed with its ffmpeg command + recorded beside it (provenance); +- a PCM ramp. + +It serves over a loopback hub, through a seeded **drop relay thread** (a UDP +relay between two sockets that drops by a seeded schedule), to an in-test +`CultNetRudpSocketTransportConnection` client. The client counts received and +expired groups. It needs no ffmpeg, PowerShell or GPU, so it runs on Yggdrasil. + +**Verification (rules each test pins):** +- Push faster than the hub drains: resident queue memory stays `≤` the stated + ceiling, and the stream is not restarted. This kills a mutant that removes + the cap or turns it into `usize::MAX`. +- Expire mid-frame: either every payload of a frame group is sent or none is. + Assert on the relay's captured datagrams, not on stats. The observation sits + at the wire (invariant 2). +- A repair asked for after its frame's deadline is not sent. A repair asked + for before it is sent. Probe at `deadline − ε` and `deadline + ε`, with ε + under 5 ms, so that a mutant that re-derives the deadline from `now` is + caught. **At least one mutant must be a function of the budget**, a clamp or + an offset (SKILL: "weakest thing that would still pass"). +- The request's `latency_budget_ms` reaches the queue deadline exactly. Use a + dev-only seam that records the computed `Duration` and assert exact equality + at two budget values. Both must differ from the default, and both must be + unequal to each other. +- `cargo mutants --in-diff`. Survivors are triaged by name. + +**Only live proves:** that dropping whole groups under Raven's CPU pressure (93%, +teardown-map L603) keeps the stream watchable. That needs a Raven run after +Idunn B3 (see Sequencing). + +**Ledger:** roughly −150 in `run_rudp_mux_once` and +250 for `MediaSendCore` +plus the harness. About +100 net. It buys invariant 2 and the only test path +into the sender. + +--- + +## Cut 3: the CultLib media FEC codec and records + +Repo CultLib, a branch from `main`. Tag and publish per CultLib's release +rules. A release is a cut: Soul passes before the tag (SKILL step 5). Q3, Q4 +and Q8 are ruled. Consumption waits on the pin gate (Q2, Sequencing step 11). + +**3a. Deletes first:** +- `GameCultMediaVideoParityShardRecord` v2 (`C media_stream_contracts.rs:466-517`), + its schema const (`:46`), `validate_video_parity_record` + (`C media_stream_wire.rs:323-388`), the `VideoParity` wire arm's v2 decode + (`:98-103`, `:183-186`), and the v2 tests in `tests/media_stream_wire.rs` + and `tests/media_stream_contracts.rs`. +- Per Q4: `GAMECULT_MEDIA_AUDIO_CHANNEL` (`C media_stream_wire.rs:41-44`), + the `"audio"` channel profile (`C rudp.rs:2218-2228`), `"audio"` in the + `channel_send_options` arm (`:2394`), and the test rows + (`tests/cultnet.rs:436, 3023-3030`). + +**Adds:** +- `gamecult.media_video_parity_shard.v3`. It carries the frame framing fields as + v2 does, plus `fec_scheme: String`, `block_index`, `block_count`, + `block_data_start`, `block_data_count` (k), `parity_index`, `parity_count` + (m), `shard_payload_bytes`, `last_chunk_payload_bytes` and `payload` (bin). + The donor's v4 field list (`B12`) plus the scheme id is the right shape. +- `gamecult.media_audio_parity_shard.v1`. Fields: `fec_scheme`, + `base_packet_id`, `base_pts_ticks`, `packet_duration_ticks`, `timebase_*`, + `deadline_ticks` (the maximum in the block), `data_shard_count`, + `parity_index`, `parity_shard_count`, `shard_payload_bytes` and `payload`. + This is the donor's v1 shape plus the scheme id. +- `GameCultMediaWireRecord::AudioParity`, with its validation, record key + (`B` identity table) and decode arm. +- `media_fec.rs`: + - `MediaFecPolicy`, fixed per Q8. Video frames split into `⌈n/16⌉` near-equal + blocks (`k ≤ 16`), with `m = max(2, ⌈k/4⌉)`. Audio is 4+2. The rate is + carried per record. + - `protect_video_frame(&[VideoAccessUnitRecord], &policy) -> Vec` + in **send order**, round-robin over blocks (donor `4e2abee`); + - `protect_audio_block(&[AudioPacketRecord; k]) -> Vec`; + - `recover_video_block` / `recover_audio_block(present) -> Result, BeyondRepair>`. + - Backing: `reed-solomon-erasure = "6"` (Q3), default features, no + `simd-accel`. The KAT pins the wire, so the library is replaceable. +- Update the module doc `C media_stream_contracts.rs:34-41`: audio now has + parity. + +**Rules that must die under their own mutation:** +- Every `≤ m` erasure pattern recovers exactly, for **every** shipped `(k, m)`: + `k = 1..16` with its ruled `m`, and 4+2. This is exhaustive. The largest is + `k = 16, m = 4`, about 6,200 patterns, which the probe shows is cheap. +- `m+1` erasures return `BeyondRepair`. They never return `Ok` with wrong bytes. +- KAT: fixed 4×37-byte input, then the exact parity bytes, committed as hex. + This kills any change of matrix, polynomial or shard order. +- Every data and parity wire record at the policy's maximum shard size is + `≤ 1431` bytes encoded (invariant 6). The bound is a named constant, not a + literal copied from Muninn. +- Blocks never span frames. A `protect_video_frame` call with mixed `frame_id` + errors. +- Send order: within any window of `block_count` consecutive records, no two + come from one block. That is the burst property. Assert it on the output + sequence, not on a helper. +- Parity carries its frame's `deadline_ticks` unchanged. + +**3b. Port `cultnet-impair`** from the donor +(`D crates/cultnet-impair/src/main.rs`, 696 lines, and +`tests/realtime-impairment/*.toml`) to +`packages/cultnet-rs/examples/cultnet_impair.rs` plus profiles under +`packages/cultnet-rs/tests/impairment/`. This is a separate commit. +- Keep the donor's six deterministic policy tests. +- Drop anything that imports the donor's vendored transport. +- Add a **seeded loss matrix** as a codec test, with no sockets: data plus + parity through a seeded iid/burst erasure schedule, then `recover`, then a + recovered-frame ratio per cell. `clean`, `loss-1/3/5pct`, `burst-4/8` are the + donor's profiles. Commit the table the test prints as the evidence record. + Assert only the guarantee (for example, `burst-4` against round-robin + `k=8, m=4`: every block with ≤ m losses recovers), not a tuned ratio. + +**Runtime parity.** The media plane is Rust-only today. `grep` finds no +`media_video_parity_shard` outside `packages/cultnet-rs`. Record that the scheme +id names the construction, so a future C# or TypeScript decoder has a KAT to +meet. `reed-solomon-erasure` states it is compatible with Backblaze JavaReedSolomon +and klauspost/reedsolomon. **This claim is not probed**; the KAT is the contract, +not the claim. + +**Verification:** +- `cd packages/cultnet-rs && cargo test` +- `cargo mutants --in-diff` on Yggdrasil. +- Negative grep: `rg "media_video_parity_shard.v2|GAMECULT_MEDIA_AUDIO_CHANNEL" packages/` + is empty. +- A **StreamPixels check**: its vendored CultLib carries `media_stream_*` + (`StreamPixels/vendor/CultLib/...`). Confirm that StreamPixels compiles + nothing that names the deleted symbols before the tag. StreamPixels is on the + ship path, so this is read-only; do not bump it. + +**Ledger:** +- deletes: about −180 (v2 record, validator, tests, audio channel); +- adds: +140 (records and validation), +200 (`media_fec.rs` with tests), + +700 (impair port, an example rather than library surface); +- one new dependency, `reed-solomon-erasure`, which pulls `lru 0.7` and + `parking_lot 0.11` (seen in the probe build). + +Net library surface is about +160. The impair tool is tooling. + +--- + +## Cut 4: Ratatoskr decodes with the CultLib codec + +Repo Ratatoskr, `main`. It lands **before** Cut 5, so that the receiver +understands v3 before the producer emits it. + +**Deletes first:** +- the XOR stripe recovery: `ParityShard` (`R video.rs:180-186`), `repair()` + `:224-269`, the stripe doc `:1-8`, and the stripe tests `:638-683`; +- the `insert_parity` v2 path `:346-374`. + +**Keeps:** the assembler's lifecycle: admit, expire, evict, repair cadence, and +the keyframe wait. + +**Adds:** +- `insert_parity` for v3. It calls `recover_video_block` when a block has + `≥ k` shards. +- An audio hole recoverer: + - hold a missing packet only until its block can recover **or** its deadline + passes, whichever comes first, bounded by the request's budget + (invariant 1); + - then recover, or report a hole; + - "Stamp live audio with the receive clock" (`d11f533`) stays the playout + owner. +- Stats counted from observation: `parity_recovered_chunks`, + `parity_beyond_repair_blocks`, `audio_recovered_packets` and `audio_holes`. + +**Rules:** +- A v3 block missing `≤ m` shards completes without a repair request. Assert + that no feedback record names its chunks. +- A block missing `m+1` shards falls through to the repair path and names only + the unrecovered chunks. +- An audio packet recovered by parity is delivered once, with its original + `packet_id` and `pts`. +- An audio hole past its deadline is reported and never delivered late. +- `max_frame_age` derives from the request's `latency_budget_ms`, not + `Duration::from_millis(250)` (`R video.rs:101`). The same two-value exact + check as Cut 2. + +**Verification:** +- Bump the CultLib pin to Cut 3's tag. +- `cargo test -p ratatoskr-core` and the C checks per Ratatoskr's README on + Yggdrasil. +- `cargo mutants --in-diff`. + +**Only live proves:** that OBS renders through recovered frames, and that audio +recovery does not add audible delay. That needs the plugin on Starfire, which +is operator-installed. + +**Ledger:** −90 XOR, +150 (v3 intake and audio recoverer). About +60. + +--- + +## Cut 5: Muninn emits CultLib parity, and audio goes lossy + +Repo Muninn, `main`. It is gated by the pin gate (Q2, Sequencing step 11). +Per Q5, **video parity ships here, and the audio half waits for Opus**: audio +stays on the reliable `audio` channel until then. + +**Deletes first:** +- `MUNINN_VIDEO_PARITY_STRIPES`, `build_video_parity_shards` and + `video_wire_records_with_parity` (`M media_packetizer.rs:625-754`), and + their tests; +- `audio_packet_send_payload`'s audio-channel pin (`:1055-1063`) and + `MUNINN_AUDIO_RUDP_CHANNEL` (`:15-16`), per Q4, in the audio half after Opus; +- the `media_send_payload_pins_audio_to_media_channel` test's assertion + (`:2252-2280`), which is rewritten to its new truth. + +**Adds:** +- The video send state calls `cultnet_rs::protect_video_frame(records, &policy)`. + Each output becomes one `QueuedMediaGroup` (Cut 2). +- The audio send state accumulates `k` packets and emits parity after the + k-th. This is the donor's `fec_block` pattern (`D media_packetizer.rs:618-632`, `:812-826`), + against CultLib types. +- A partial block at stream end or restart is emitted without parity and + counted. It is not padded with invented packets. +- Audio on the `media` channel, lossy. +- The advertisement names the FEC scheme it emits, only if Ratatoskr needs to + know before the first record arrives. The default is not to add a field: + parity is self-describing. +- `MUNINN_RUDP_MEDIA_PROFILE_ID` (`main.rs:76`) bumps to `…lan.v2`, because the + profile's wire behaviour changed. + +**Rules:** +- End to end through Cut 2's drop relay, with the `loss-3pct` seed: + - every frame whose blocks each lost `≤ m` shards is decodable at the client + with **zero** repair requests; + - audio packets lost `≤ m` per block are delivered. + - The in-test client decodes with CultLib's `recover_*`, so this does not need + Ratatoskr as a dependency. +- The wire contains no `v2` parity and no `audio`-channel frames. Assert on the + relay's captured datagrams. + +**Harness run on Yggdrasil (the loss-injection acceptance):** +- Cut 2's test driver with the Cut 3b profiles matrix: + `clean`, `loss-1pct`, `loss-3pct`, `loss-5pct`, `burst-4`, `burst-8`, + `reorder`, `duplicate`. +- Report per cell: + - frames complete without repair; + - frames complete via repair; + - frames expired; + - audio recovered and holes; + - wire overhead, measured as bytes on the relay divided by encoded payload + bytes. +- Run it once at Muninn `cee7b9c`-equivalent behaviour (XOR, reliable audio) + and once after, and commit both tables. **The before-and-after table is the + evidence that the campaign bought something.** + +**Only live proves:** +- that NVENC's real frame-size distribution, including IDR spikes of hundreds of + chunks, fits the chosen `(k, m)` without the overhead pushing past the link; +- that the Raven → Starfire LAN and the mesh-hairpin path (28 Mbps, + teardown-map L292) both hold. + +Protocol: the operator runs the stream for N minutes on each path with the +receive probe's stats captured. Parity overhead against the 28 Mbps hairpin is +the number that decides whether the later adaptive-parity cut (Q8) is needed. + +**Ledger:** −130 XOR, +60 of calls into CultLib. **Net about −70.** + +--- + +## Cut 6: native encoder, IDR on request and bitrate adaptation (Q6 = a) + +The ruling was against Imagination's recommendation, which was to decide on +harness evidence. This map carries out the ruling. The one cost to name: this is +the campaign's only new native target, and its Windows build is proven nowhere +but Raven. + +Three parts, each with its own verification: +- **6a** builds the encoder and needs no GPU; +- **6b** wires Muninn to it; +- **6c** deploys it and accepts it on Raven. + +Build hosts and target platforms are named separately throughout, per the +global Build budget rule. + +### 6a: the `muninn-video-encoder` package (Muninn repo) + +**Why a package.** +- **Owner:** Muninn. +- **Live consumer:** Muninn's activation child, which spawns it. +- **Protected invariants:** invariant 15 (typed commands, observed effect) and + invariant 16 (one encoder path). +- **Why the existing owner cannot serve:** FFmpeg's C API must be linked. Linking + libav into `muninn-daemon` would make every Muninn build, on Nightwing, + Starfire and in CI, need an FFmpeg development root. A separate package + confines that to one target. +- **What it replaces:** the ffmpeg CLI video child (6b deletes it). +- **Build fan-out:** add `muninn-video-encoder` to the workspace `members`, and + **not** to `default-members`, so that a plain `cargo build` or `cargo test` + never needs FFmpeg. + +**Layout.** +- `crates/muninn-video-encoder/Cargo.toml`: `[[bin]] muninn-video-encoder`. + Dependencies: `muninn-contracts` (the command record, H0/H1), + `cultnet-rs` (framing and message envelope), `anyhow`. Build-dependencies: + `cc`, plus `pkg-config` for the Linux path only. +- `native/encoder_core.cpp`: the donor loop, **ported**, with these changes: + - `main`, `parse_options`, the `command_reader` thread and `fail()` are + deleted. Errors return a code and a message into a caller buffer. + - Its only entry point is: + ```c + int muninn_encoder_run(const muninn_encoder_options*, + int (*poll)(void* ctx, muninn_encoder_control* out), + int (*write)(void* ctx, const uint8_t* data, size_t len), + void* ctx, char* error, size_t error_len); + ``` + `poll` is called once per captured frame. It returns + `{force_idr, bitrate_kbps (0 = unchanged), stop}`. + - The encoder name is an option. `h264_nvenc` (with the donor's option + dictionary) is for production. `libx264` (`preset=ultrafast`, + `tune=zerolatency`) is only for the Linux verification build. The capture + input is an option too: `ddagrab=...` in production, `testsrc2=...` in + verification. +- `build.rs`: + - On Windows, read `MUNINN_FFMPEG_ROOT` (required), compile + `encoder_core.cpp` with `cc` (MSVC, `/std:c++20`), emit + `cargo:rustc-link-search` for `lib/`, and link `avcodec avdevice avfilter + avformat avutil`. + - Refuse to build unless `include/libavcodec/version_major.h` has the pinned + `LIBAVCODEC_VERSION_MAJOR`. The pin is a named constant in `build.rs`; the + operator's provisioned build sets it. + - Emit `cargo:rerun-if-env-changed=MUNINN_FFMPEG_ROOT`. + - On Linux, find the same libraries through `pkg-config`. +- `src/main.rs`: + - parses argv: `--input`, `--encoder`, `--framerate`, `--bitrate-kbps`, + `--gop-frames`, `--frames N` (verification bound); + - runs a stdin reader thread: `cultnet_rs::LengthPrefixedMessageFramer`, + then `decode_cultnet_message_from_slice`, then `MuninnVideoEncoderCommandRecord`, + then validation, then a **bounded** `sync_channel(16)`; + - implements `poll` by draining that channel into one control value: + - any IDR sets `force_idr`; + - the **last** bitrate wins, so coalescing matches the donor's atomic + exchange; + - `stop` ends the run; + - implements `write` to stdout; + - guards the framer with a maximum frame length of 4 KiB. The framer buffers + whatever arrives, so a garbage length prefix must not grow memory + (invariant 2's spirit). + +**The command record** `muninn.video_encoder_command.v1`, in `muninn-contracts`. +It is Muninn-owned and process-local, and published to no store. + +| key | field | rule | +|---|---|---| +| 0 | `command_sequence: u64` | starts at 1 per encoder process and increases by exactly 1. A gap or repeat is refused and counted, which exposes a writer bug. | +| 1 | `kind: String` | `idr`, `bitrate` or `stop`. Anything else is refused and counted. | +| 2 | `bitrate_kbps: u32` | nonzero only for `bitrate`, within `[250, 100_000]` (the donor's bounds, from its command thread) | +| 3 | `cause: String` | for example `keyframe-request` or `receiver-pressure`. Telemetry only. | +| 4 | `issued_at: String` | telemetry only | + +**Verification on Yggdrasil.** Build host Linux x86_64. Target platform Linux, +**not** the Windows shipping target. +- Image: the rust verify image plus + `apt-get install -y libavdevice-dev libavfilter-dev libavformat-dev libavcodec-dev libx264-dev pkg-config`. + This runs inside the job's command. A dedicated image is a later optimisation + if the apt time hurts. +- Unit tests, `cargo test -p muninn-video-encoder`: + - the record round-trips; + - a stream of framed commands split at every byte boundary decodes + identically; + - `bitrate_kbps` of 249 and 100_001 is refused, and 250 and 100_000 are + accepted. At least one tested value must sit where a clamp would change + it; per SKILL, a clamp is the mutant to beat; + - a sequence gap or repeat is refused; + - many bitrate commands between two polls yield the last one; + - an IDR and a bitrate in one poll yield both. +- Integration test, spawning the built binary with `--input testsrc2=size=320x240:rate=30`, + `--encoder libx264`, `--gop-frames 1000` and `--frames 120`: + - Parse stdout with Muninn's `h264_annex_b_access_units`. The test + lives in `muninn-daemon`'s test module so it can reach the parser. + - After the 20th access unit, write an `idr` command. **Exactly one** keyframe + access unit appears in AUs 21-23. There is none elsewhere except AU 0, + because the GOP is 1000. + - After the 60th AU, write `bitrate 150` (down from 1500). The mean non-key + AU size over 90-120 is at most half the mean over 30-60. + - If libx264's in-session reconfigure does not honour this, the test must + say so, and fall back to asserting that the core received the value + (a dev-only counter on the C ABI). That fallback is recorded as **not yet + reached** for Linux, never as unreachable. +- `cargo mutants` on the Rust shell's diff. The C++ core has no mutation tool, + so it is defended behaviourally by the integration scenario (SKILL). + +### 6b: Muninn drives the encoder (Muninn repo) + +Depends on: +- Cut 2's `MediaSendCore` seam; +- Cut 5's parity policy, for the ceiling. + +**Deletes first:** +- `record_receiver_keyframe_pressure` (`M main.rs:3036-3048`) and its two call + sites in `run_rudp_mux_once`. +- The ffmpeg CLI video child: + - `rudp_video_ffmpeg_args` (`M :10343-10421`); + - `muninn_rudp_video_bitrate_arg`, `muninn_rudp_video_vbv_buffer_arg` and + `muninn_rudp_video_gop_frames` (`:10296-10311`), which move into encoder + options; + - the video `Command::new(&options.ffmpeg_path)` spawn in `run_rudp_mux_once`; + - `ffmpeg_args`; + - the CLI-argument tests (around `:12180-12335`), re-homed as encoder-options + tests where they pin a rule: GOP equals a quarter of the frame rate, and + the explicit bitrate. +- The `MuninnRudpMediaProfile` fields that fed only the CLI (`video_preset`, + `video_tune`, `video_b_frames`, `video_rc_lookahead`, `:10279-10285`). The + runtime-boundary JSON at `:3830-3847` loses them, and its `"recovery"` string + changes to what is now true. +- `ffmpeg_path` stays for the **audio** child until the Opus cut. + +**Adds:** +- `trait EncoderControl { fn request_idr(&mut self, cause: &str); fn set_bitrate(&mut self, kbps: u32, cause: &str); }` + as a port in `MediaSendCore`. + - The production implementation owns the encoder's `ChildStdin` on a + **writer thread** behind `sync_channel(8)`. + - **Rule: a control write never blocks the send loop.** When the channel is + full, a pending bitrate command is replaced by the newer one, and an IDR is + kept. + - The test implementation records the commands. +- `KeyframeRequestGate`, ported from `D main.rs:2864-2884` with the 500 ms + cooldown (`D :102`). It is fed the aggregate `requested_keyframes` counter + across hub receivers. Any receiver's new edge counts. +- `BitrateController`, rewritten from `D :2439-2512`: + - ceiling `= request.video_bitrate_kbps / (1 + r)`, where `r` is the video + parity overhead from Cut 5's policy, measured as parity bytes over data + bytes in the last second, not assumed; + - floor `= max(ceiling / 4, 1_000)`; + - start at the ceiling; + - each 500 ms sample, **back off** to ×0.85 on damage. Damage is new late + frames, a new keyframe request, new deferred repairs, new + `groups_dropped_video` (Cut 2), or jitter plus decode queue at or above 75% + of the request's budget; + - otherwise, **step up** by `ceiling / 50` after 10 s stable. These are the + donor code's values (`D :2502-2507`); its doc disagreed, and the Cut 5 + harness may retune the named constants; + - known limit, recorded: with many viewers, the worst receiver sets the + rate. +- Spawn: + - `--video-encoder ` resolves relative to the release directory, like + the loopback script; + - `--video-encoder-runtime-dir ` is prepended to the child's `PATH`, so + that the FFmpeg DLLs resolve; + - the child runs at the existing video priority class + (`media_child_priority`). + - A missing or failing encoder fails the request with a typed `detail` + (invariant 16). +- Observation (invariant 15): + - `idr_commands`, and `idr_observed` (a keyframe access unit from + `VideoAnnexBStreamSendState` within 3 frames of a command); + - `bitrate_commanded_kbps`, and `bitrate_observed_kbps` (encoded bytes per + second, 1 s window); + - all four in the progress line and the telemetry surface. + +**Rules (each pinned by a test on `MediaSendCore` with the recording +`EncoderControl`):** +- One keyframe-request edge gives exactly one `idr`. A second edge inside + 500 ms gives none. One edge at `cooldown + ε` gives one. The cooldown is + probed on both sides. +- A recoverable missing chunk (a feedback record with + `missing_video_chunk_keys` and `requested_keyframe = false`) gives no `idr` + (invariant 8). +- Damage in one sample gives exactly one ×0.85. It never goes below the floor. +- Stable for 10 s gives exactly one step. It never goes above the ceiling. +- The ceiling is **derived from the request**: test two request bitrates and + two parity ratios, with exact equality through a dev-only seam that records + the computed ceiling. Kill a clamp mutant. +- A stalled encoder stdin (the test writer never drains) does not stall + `MediaSendCore`. Assert the send loop's tick count keeps advancing. +- The Cut 2 harness, driven by a fake encoder that honours `idr` (a + file-backed Annex B source that emits a keyframe on command): under + `loss-3pct`, the receiver's frozen interval after a lost reference is + ≤ RTT + 2 frames, not the 250 ms GOP. + +**Verification:** Yggdrasil, `cargo test -p muninn-daemon` and +`cargo mutants --in-diff`. No GPU is needed. + +**Ledger:** about −220 (CLI child, args, tests and the log-only keyframe +handler) and +260 (port, gate, controller, spawn and observation). 6a adds +roughly +400: 230 of ported C++ and 170 of Rust shell and tests. + +### 6c: recipe, binding and Raven acceptance + +Build host **Raven** (Windows 11, MSVC, the NVIDIA driver). Target platform +**Raven**. Builder: Idunn's host actuator, `rust-host` runner, `cargo` only. + +**Prerequisites (not Hands):** +- Idunn B3 and `route/b3-declare` merged to Muninn `main` (B19). +- **Operator provisioning on Raven**, a one-time step like the firewall rule: + - unpack a pinned FFmpeg **shared** build with NVENC enabled (headers, import + libraries, DLLs) to `C:\GameCult\deps\ffmpeg--shared\`; + - record its URL and sha256 in `gamecult-ops/inventory.md` under Raven. + - Nothing in the deploy path can fetch it (B18). This gap is recorded for + Idunn (Substrate missing). + +**Recipe** (`Muninn/deployment/idunn/raven-muninn.toml`, on top of `2260853`): + + [[steps]] + id = "build-muninn-video-encoder" + phase = "build" + runner = "rust-host" + required_environment = ["MUNINN_FFMPEG_ROOT"] + argv = ["cargo", "build", "--locked", "--release", + "-p", "muninn-video-encoder", "--bin", "muninn-video-encoder"] + + [[steps]] + id = "accept-nvenc-control" + phase = "acceptance" + runner = "rust-host" + required_environment = ["MUNINN_FFMPEG_ROOT"] + argv = ["cargo", "test", "--locked", "--release", + "-p", "muninn-video-encoder", "--features", "nvenc-acceptance", + "--", "--exact", "nvenc_honours_idr_and_bitrate_commands"] + + [[artifacts]] + id = "muninn-video-encoder" + source_kind = "runner-output" + runner = "rust-host" + source = "target/release/muninn-video-encoder.exe" + destination = "muninn-video-encoder.exe" + executable = true + +In `[service]`: +- `required_adjacent_artifacts = ["muninn-video-encoder", "wasapi-loopback-capture"]`; +- the arguments gain `--video-encoder` → literal `muninn-video-encoder.exe`, and + `--video-encoder-runtime-dir` → binding `ffmpeg_runtime_dir`. + +The acceptance test sits behind a feature so that CI and Yggdrasil never select +it. It is the 6a integration scenario with `--encoder h264_nvenc` and +`--input testsrc2`, hardware encode from system-memory frames (no desktop +needed). So **the deploy itself refuses a Raven where NVENC cannot honour a +typed IDR or bitrate command**. Hands confirms that host-native `acceptance` +steps run before promotion (`I src/deployment.rs:71-77` declares the phase). +If they do not, this becomes a build-phase step, and that is recorded. + +**Binding** (`gamecult-ops/idunn/yggdrasil/bindings/raven-muninn.toml.in`, +gamecult-ops owns it, an operator-approved ops change): + + [runners.rust-host.environment] + MUNINN_FFMPEG_ROOT = 'C:\GameCult\deps\ffmpeg--shared' + [workload.argument_bindings] + ffmpeg_runtime_dir = 'C:\GameCult\deps\ffmpeg--shared\bin' + +Both are open maps. The binding vocabulary does not grow, so the actuator needs +no rebuild (`Idunn docs/host-actuator.md:112`). Hands verifies this against the +actuator's binding parser before sealing. + +**Deploy:** `sudo idunn up raven-muninn` from yggdrasil, per +`gamecult-ops/runbooks/idunn-host-raven.md`. It is the operator's action; Raven +is a human-used workstation (teardown-map L268-271). + +**What only Raven proves, live, with the operator present:** +- `ddagrab` with `h264_nvenc`: a receiver-requested IDR is **observed at + Ratatoskr** as a keyframe within one RTT plus one frame, while a game is + running (Raven at 93% CPU is the known condition). +- NVENC in-session reconfigure under a game. The donor recorded 12 → 6 Mbps at + frame 35 on 2026-07-17, on a pre-extraction body. +- `bitrate_observed_kbps` follows commands on the mesh-hairpin path (28 Mbps) + and backs off under it. +- DLL resolution from the release directory under the actuator's launch. +- **The payoff step.** Lengthening the scheduled GOP beyond a quarter second is + what IDR-on-request buys. Do it only after this acceptance, as a one-constant + change measured against the Cut 5 table and the live run. Until then the + 250 ms GOP stays as the fallback ceiling. + +**Ledger 6c:** recipe +25 lines, binding +4. + +--- + +## HID edge for remote play: cuts H0-H5 (Q1, Q9, Q10 ruled) + +**What it is for** (Q1, 2026-09-30): a viewer's controller drives a game on +another host, over LAN or mesh, so quick taps must survive loss. +- The **producer** is Muninn on the viewer's host, capturing the pad. +- The **consumer** is Sleipnir on the game host, which drives ViGEm. +- Today the consumer is `raven-sleipnir`, Raven being the game host (B16). + +**Anchors in this section.** +- `M` = Muninn `main` `c3520d1`. +- `S` = Sleipnir at Odin `main` `379b826`, `crates/sleipnir-daemon/src/main.rs`. + H3 moves that file verbatim, so after H3 the same line numbers hold at + `Muninn/crates/sleipnir-daemon/src/main.rs` until H4 edits it. +- `R` = Ratatoskr `488b5b1`. +- `C` = CultLib `c2a9a6e`, Muninn's pin. +- `Mi` = Mimir `d88f2e6`. +- `Ops` = gamecult-ops `8554e60`. + +### The capability mechanism, verified: video today, input mirrored + +Q10 orders input to be requested the way Ratatoskr requests video. This is +that request path, read at the SHAs above. + +| Step | Video today | Input after H2/H4 | +|---|---|---| +| Producer advertises through CultMesh | Muninn builds `gamecult.media_stream_advertisement.v1` (`M :1122-1166`). It stores it and publishes it to Odin's catalog under its `stream_id`, with role `media-stream-producer` (`M :4146-4166`). | Muninn builds `muninn.input_stream_advertisement.v1` in `input_stream.rs`, and publishes it at the same site with role `input-stream-producer`. | +| Advertised endpoint | `media_endpoint` is explicit (`--media-rudp-advertise`), or derived, **never guessed** (`advertised_media_endpoint`, `M :1173-1196`). `media_connection_id` is `MUNINN_MEDIA_RUDP_CONNECTION_ID`. | `input_endpoint` comes from the same function, parameterised (`advertised_endpoint(explicit, bind)`). `input_connection_id` is `0x6d75_0005`, today's HID id (`M :74`, `S :23`). | +| Recipe declares the capability | `[[provides]] capability = "muninn.media-producer"` (`raven-muninn.toml:93-96`) | `[[provides]] capability = "muninn.input-producer"`, schema `muninn.input_stream_advertisement.v1` | +| Consumer discovers | Ratatoskr pulls the advertisement schema from Odin (`R catalog.rs:64-91`) | Sleipnir pulls the input advertisement schema and its own mapping schema: one pull, typed, with no JSON scraping (B21). | +| Consumer asks | Ratatoskr publishes a request under `media_stream_request_key(stream, receiver)`, role `media-stream-consumer` (`R catalog.rs:95-122`). The request names the sources, and the latency budget defaults from the advertisement (`R :151-179`). | Sleipnir publishes `muninn.input_stream_request.v1` under `input_stream_request_key(stream, receiver)`, role `input-stream-consumer`. It names `device_id`, and `input_budget_ms` defaults from the advertisement. | +| Producer admits and answers | Muninn pulls request documents from Odin each tick (`M :971-1034`), turns them into `MuninnCaptureStreamCommandRecord`s, and writes the answer onto the request key (`M :1038-1117`). | The **same pull** takes both request schemas in one snapshot. Input requests go to the input organ as demand (B23), with **no** detour through a command record, and are answered on the same key. | +| Who dials | The consumer dials the advertised endpoint (`R receiver.rs:4-7`). Its connect payload is its `receiver_id` (`R receiver.rs:40-42`). Muninn listens on a `CultNetRudpServerHub` (`M :3192-3213`). | The consumer (Sleipnir, on the game host) dials the viewer's Muninn. Muninn listens on a `CultNetRudpServerHub` and serves a session only the device its request names. | + +**One rule for both streams:** the consumer dials the Muninn that produces the +stream, and that Muninn listens. For video, the producing Muninn is on the game +host. For input, it is on the viewer's machine, because the controller is +there. Every host whose Muninn produces a stream admits inbound UDP on that +stream's port. Raven already does this for video. H5 adds the same rule on each +viewer that produces input. + +**Two deliberate differences from the video path**, each protecting a named +invariant: +- **Admission as demand, not as `state == pending`** (B23). A restarted + producer resumes serving every live consumer without a re-request. The video + path should adopt this too, under its own owner. +- **No command-record detour.** `MuninnCaptureStreamCommandRecord` exists for + the media child's lifecycle and for legacy readers (teardown-map, item 2 of + "Next unblocked work"). Input has neither, so it does not grow a second + command vocabulary. + +### Ownership + +| Organ | Owns | Does not own | +|---|---|---| +| Muninn capture thread, one per source (H2) | The **only** device reader (B22); sampling (XInput 1 ms, Windows HID every report, joystick events as they arrive); `EdgeDetector`; the latest-state slot; the per-source edge queue | Sessions, windows, epochs, frames | +| Muninn input organ, `crates/muninn-daemon/src/input_stream.rs` (H2) | The advertisement; admission of input requests as demand, and their answers; the input hub and its sessions; one `EdgeWindow` per (session, device); frame emission on `latest`; applying acks | Device reads; mapping; deciding that an edge was applied | +| `muninn-contracts` (H0, H1) | The input records and their key and validation; the HID wire records and their CultNet envelope; `EdgeDetector`, `EdgeWindow` and `EdgeCursor` as pure code | Sockets, threads, devices, Odin | +| Sleipnir (`crates/sleipnir-daemon`, Muninn workspace, H3/H4) | Choosing the device from typed advertisements plus its mapping record; publishing the request; dialling; the `EdgeCursor`; **the single `commit_pad` primitive** (invariant 10); the hold and the request-owned budget (invariant 13); acks; neutralising on staleness | Edge creation, epochs, capture, discovery JSON | +| CultLib | The `latest` channel: Unreliable and Sequenced, fixed by name (`C rudp.rs:2189-2192, 2384-2390`); `CultNetRudpServerHub` with per-session send (`C rudp.rs:1384, 1464, 1475`) | Anything HID-named (invariant 9). **No CultLib change** (under Q11's recommendation). | +| Odin | Catalog storage for the advertisement and request documents. It is schema-agnostic: `odin-daemon` names no media schema either (`git grep`, Odin `379b826`). | Anything input-specific. **No Odin change.** | + +**Why one frame on `latest`, and not the donor's reliable `hid.edge` channel.** +- A frame carries the current state **and** every unacknowledged edge of that + session's window, up to `MAX_EDGES_PER_FRAME`. +- Each frame therefore supersedes the last, which is exactly what a sequenced + channel delivers: an older frame arriving late is dropped, and nothing is + lost by that. +- Loss costs one transport tick. H2 sets that tick to 2 ms. Today it is 8 ms + (B22). +- There is no retransmit timer, no reliable window to stall, and no second + "assist" path. +- The ruling's "profile-owned channels" is met by using a channel the profile + already declares, with the delivery it declares. + +**How Odin `main`'s pin stays untouched while StreamPixels ships.** +- Nothing in H0-H5 commits to Odin `main`. +- Sleipnir moves into Muninn's workspace (Q9) at Muninn's pins: CultLib + `c2a9a6e`, and odin-core from Odin `3e96c6c`. That is the commit Odin made + for exactly this ("CultLib pin a8aedda -> c2a9a6e so a consumer can build + odin-core without a path override"). It already bumps `sleipnir-daemon`'s + own manifest to `c2a9a6e`, and its odin-core API equals Odin `main`'s: + `git diff 3e96c6c 379b826 -- crates/odin-core` touches only `Cargo.toml` and + two examples. +- From H3 on, Odin `main`'s `crates/sleipnir-daemon` is a **forbidden writer**. +- After StreamPixels ships, **one** Odin commit deletes the crate from Odin's + workspace. It is a deletion, with no pin change and no other edit. +- Until then two copies of the source exist, and only Muninn's is built and + deployed from H5 on. Recorded as debt, with its deletion line. + +### H0: shape of Muninn's named cut 1 (a constraint, not a new cut) + +Named cut 1 moves Muninn's 16 records out of odin-core. For H, it must place +them in a **library** crate in Muninn's workspace, `crates/muninn-contracts` +(`crate-type = rlib`), not in `muninn-daemon`'s binary. + +- **Owner:** Muninn. +- **Live consumers:** + - `muninn-daemon`; + - `sleipnir-daemon`, a workspace member from H3. It imports + `MuninnHidControllerStateRecord` today (`S :12`), until H4. + - `muninn-video-encoder` (6a). +- **Protected invariant:** each Muninn wire record has one definition, and + every crate that links it resolves one `cultcache-rs`. With Sleipnir in the + workspace that is structural: one `Cargo.lock`, a path dependency, and no + git pin to drift. The pass-2 guard test for a cross-repo pin is **not** + written. +- **Why the existing owner cannot serve:** a binary crate cannot be a + dependency, and two binaries (`muninn`, `sleipnir`) share these records. +- **What it replaces:** Muninn records defined in Odin's odin-core. + +Its dependencies are `cultcache-rs`, `cultnet-rs`, `serde` and `anyhow`, taken +from `[workspace.dependencies]` (H3 hoists the pins there). + +**Ordering against H3.** Neither waits for the other. If H3 lands first, +Sleipnir keeps importing the HID record from odin-core. Named cut 1 then +switches both importers in one commit, which is the practical gain of Q9. + +### H1: input-stream records, HID wire records and protocol state machines (`muninn-contracts`) + +Location per Q11 (recommended): `crates/muninn-contracts/src/input_stream.rs` +(the capability records) and `crates/muninn-contracts/src/hid.rs` (the wire +records and state machines). If Q11 rules CultLib, the same types go to +`CultLib packages/cultnet-rs/src/input_stream_contracts.rs` under `gamecult.*` +ids, and H1 waits for Cut 3's CultLib tag and the pin gate. + +**Adds, the capability pair** (types and rules; bodies are Hands'). It is +modelled field-for-field on `C media_stream_contracts.rs:71-183`. +- `muninn.input_stream_advertisement.v1`: + - `stream_id`, `producer_id`, `label`; + - `state`, one of `available`, `streaming`, `unavailable`; + - `device_ids`, `device_labels`, `device_kinds`: parallel, equal length; + - `default_input_budget_ms`: the default, 100; + - `input_endpoint`, `input_connection_id`; + - `updated_at`. +- `muninn.input_stream_request.v1`: + - `request_id`, `stream_id`, `producer_id`, `receiver_id`; + - `action`, one of `start` or `stop`; + - `state`, one of `pending`, `running`, `stopped`, `failed`; + - `device_id`, `input_budget_ms`, `detail`, `updated_at`. +- `input_stream_request_key(stream_id, receiver_id)`, with the same shape as + `media_stream_request_key` (`C media_stream_contracts.rs:180`). +- `validate_input_stream_advertisement` and `validate_input_stream_request`. + They mirror `C :184-290`. Validation refuses: + - unequal device arrays; + - `start` without a `device_id`; + - an `input_budget_ms` of 0 on a `start`, because the consumer fills in the + advertised default, as Ratatoskr does (`R catalog.rs:174`); + - an unknown action or state. + +**Adds, the wire:** +- `muninn.hid_input_frame.v1`: + - `device_id`, `stream_id`; + - `epoch: u64`, never 0; + - `state_sequence: u64`; + - `source_timestamp_ns: i64`, telemetry only; + - `axes: Vec`; + - `buttons: Vec`, the held set **after** the last edge in this + frame's window; + - `edge_first_sequence: u64`; + - `edge_buttons: Vec`, `edge_pressed: Vec`, + `edge_captured_ns: Vec`: parallel arrays, equal length, at most + `MAX_EDGES_PER_FRAME`, contiguous from `edge_first_sequence`. + - Hands may use a nested record list instead of parallel arrays if the + `cultcache-rs` derive supports it at the pin. The rule, not the spelling, is + the contract. +- `muninn.hid_edge_ack.v1`: `device_id`, `epoch`, `applied_through: u64`. +- `MuninnHidWireRecord { Frame, Ack }` with `encode`/`decode` through the + CultNet message envelope. This is the pattern of CultLib's + `encode_media_wire_record` (`C media_stream_wire.rs:134-190`), with + validation on both encode and decode. +- **Deleted from the design:** pass 2's `muninn.hid_subscription.v1`. Device + selection is the request's `device_id`, and the subscriber's identity is the + session's connect payload. There is no in-session subscription message. + +**Adds, the state machines:** +- `EdgeDetector` (runs on the capture thread): + - `sample(buttons_now, captured_ns) -> impl Iterator` diffs against the + previous sample: releases first, then presses (the donor order); + - edges carry no sequence and no epoch. Those belong to a window. +- `EdgeWindow` (one per session and device, on the input tick): + - `new(epoch_ns)`; + - `push(edge)` appends, with a sequence contiguous from 1; + - `frame_edges() -> ≤ MAX_EDGES_PER_FRAME oldest pending`; + - `ack(epoch, applied_through)`; + - `rebaseline()`. Past 256 pending it sets the epoch to `+1`, + `state_sequence` to 0, clears pending, and reports the rotation to the + caller, which counts it. +- `EdgeCursor` (receiver): + - `accept_frame(epoch, state_sequence, first_seq, edges) -> Admission`; + - an epoch below the current one: fenced (a monotonic comparison, with no + set); + - a new, higher epoch: take `buttons` as the baseline, set + `applied_through = first_seq + len - 1`, and return no edges. Taps inside + the first frame of an epoch are carried by the baseline, not replayed. + **This is recorded as a deliberate loss at epoch start only.** + - the same epoch: return the edges with sequence above `applied_through`, in + order. Duplicates are dropped by sequence, and a gap past 256 is refused. + +**Rules that must die under their own mutation.** A property-style test drives +`EdgeDetector` → two `EdgeWindow`s (two subscribers, independent drop seeds) → +frames → a seeded drop, reorder or duplicate → one `EdgeCursor` per +subscriber. +- Every edge captured is delivered **exactly once, in capture order, to each + subscriber**, under every Cut 3b profile. Use the **same seed tables** as the + media harness, so one impairment vocabulary serves both. +- One subscriber at `burst-8` never rotates the other subscriber's epoch. +- A press and release captured in one sampling interval arrive as two edges, + press then release. +- The window in a frame never exceeds `MAX_EDGES_PER_FRAME`. Pending is never + above 256. At 257 the epoch rotates, and the next frame's epoch is exactly + one more. +- An ack for a stale epoch changes nothing. An ack for `n` trims exactly + through `n`. +- The cursor rejects a frame from any epoch below its current one, including + `current − 1`. Kill the off-by-one comparison mutant. +- **Fit.** A frame with a full window, the longest button names, 16 axes and + a full held set encodes to ≤ 1,200 bytes (`HID_CONTROLLER_RUDP_MAX_FRAGMENT_BYTES`, + `M :6140`), so it never fragments (invariant 6's rule, applied to input). + - A rough count puts 32 edges with 16-character names at about 1,270 bytes. + **The test sets the constant.** Start at 32, and lower it until the worst + case fits. + - Never raise the fragment limit to make it fit. +- The frame round-trips. A frame with unequal parallel arrays, or a + non-contiguous window, is refused on decode. +- The request and advertisement round-trip. Each refusal listed above has a + test. + +**Verification:** `cargo test -p muninn-contracts` and `cargo mutants --in-diff` +on Yggdrasil, one job. + +**Build budget:** one library crate that already exists from named cut 1. +It gains no dependencies and no new target. + +**Ledger:** about +550 (the capability pair ~100, the wire and three state +machines ~250, tests ~200). It retires the donor's ~350 HID lines, which never +land. + +### H2: Muninn serves input streams (Muninn repo) + +Depends on H1 and Q12. It is developed on the same Hands branch as H4 and +merged with it (see Sequencing). + +**Authority map.** +- **Owner:** + - edges: `EdgeDetector` on each source's capture thread; + - delivery: the input organ in `input_stream.rs`, one `EdgeWindow` per + (session, device). +- **Inputs:** + - device samples, capture only; + - admitted input requests, from the serve tick's single Odin pull; + - hub sessions and their connect payloads; + - `hid_edge_ack` frames. +- **Outputs:** + - `hid_input_frame` per session on `latest`; + - the advertisement; + - answers on request keys; + - counters (frames, rotations, acks, sessions). +- **Derived state:** + - `muninn.hid_controller_state.v1` receipts become **observation-only**, + projected from the capture slot. They are no longer read from the device, + and they are no longer a discovery source. + - The Eve provider advertisement lists no input streams. +- **Forbidden writers:** + - the transport tick deciding edges; + - the serve tick reading a device that a capture thread owns; + - wall-clock time deciding freshness (telemetry only; donor doctrine, + `D docs/realtime-delivery-authority.md`); + - JSON anywhere on this path; + - an in-session subscription message. +- **Shared paths:** live capture, reconnect, restart (demand re-admission) and + tests all go through `EdgeDetector` → `EdgeWindow`. A reattaching session + gets a new window, a new epoch, and a baseline. + +**Deletes first** (`M`): +1. **The losing path per Q10: Muninn's outbound client.** + - `ActiveHidControllerStream` (`:6077-6086`); + - `create_hid_controller_stream` (`:6724-6763`); + - `publish_hid_controller_state_to_stream` (`:6765-6778`) and `_inner` + (`:6780-6863`); + - in `serve`: `let mut hid_controller_stream` (`:418`) and its argument + (`:506`); + - the `hid_controller_stream` parameter of `publish_move_controller_states` + (`:4982`), and its three calls (`:5026-5029`, `:5073-5076`, + `:5112-5115`); + - the option field (`:229`), its default (`:10628`) and its parse arm + `--hid-controller-rudp-target` | `--hid-controller-udp-target` + (`:10899-10904`). +2. **The JSON listener body.** Its direction survives; its body does not. + - `HidControllerRudpSubscription` (`:6143-6149`); + - `start_hid_controller_rudp_ingress` (`:6151-6177`); + - `run_hid_controller_rudp_ingress` (`:6179-6340`); + - `hid_controller_source_matches_subscription` (`:6342-6360`); + - `hid_controller_record_matches_subscription` (`:6362-6375`); + - `sanitize_hid_controller_record` (`:6710-6722`); + - the `serve` wiring at `:429-437`, per Q12. +3. **The per-tick reader as the place where HID state is made.** + - `read_hid_controller_state_for_stream` (`:6377-6528`), + `emit_hid_controller_record_if_due` (`:6530-6554`), + `hid_controller_stream_heartbeat_due` (`:6556-6560`) and + `hid_controller_axes_changed` (`:6562-6570`). + - The device-read bodies inside them move to the capture thread; they are + not rewritten. The emit-if-due throttling dies, because the window + decides what to send. + - `ActiveHidControllerRudpSource`, `active_hid_controller_rudp_source` and + `sync_hid_controller_rudp_sources` (`:6088-6129`) become the capture-set + reconciler. The hot-plug test `rudp_sources_reconcile_hotplugged_physical_identity` + (`:14620-14636`) is kept and retargeted. +4. **The double-read fence** (`:5081-5086`), because the capture thread is + now the only reader (B22). +5. **The JSON discovery surface** (B21). + - `hid_controller_endpoint` (`:3626-3631`); + - the device JSON (`:3653-3672`); + - `transport_input_streams` and `provider_input_streams` (`:3673-3727`); + - the provider `endpoints` pushes (`:3729-3750`); + - the `"input_streams"` key (`:3856`) and the `"inputStreams"` key + (`:3885`). + - The test `runtime_boundary_advertises_hid_and_move_evidence_streams` + (`:14072-14172`) is rewritten against the typed advertisement. +6. **The discovery write** `publish_hid_controller_state_to_odin` + (`:6865-6875`) and its three calls (`:5030`, `:5077`, `:5116`). Its only + reader is Sleipnir's discovery, which H4 deletes (B21). Receipts through + `put_hid_controller_state_receipt` (`:5970`) stay. +7. **Rename, not keep beside.** The options `hid_controller_rudp_bind` and + `_advertise` (`:230-231`, parse `:10906-10916`) become + `--input-rudp-bind` and `--input-rudp-advertise`. The old spellings are + refused with a message naming the new ones (the house pattern, + `M :10890-10894`). `local_ring_enabled` (`:4238`) follows Q12. + +**Adds:** +- `crates/muninn-daemon/src/input_stream.rs`, so `main.rs` shrinks. It holds: + - `input_stream_advertisement(options, live_sources)`, published at `:4146` + beside the media advertisement, with role `input-stream-producer` and tag + `muninn.input-stream-advertisement`; + - `InputDemand`: the admitted requests, keyed by `receiver_id`. It is + written by the serve tick and read by the input thread (a latest-wins + `Arc>`); + - `run_input_hub`: a `CultNetRudpServerHub` on `--input-rudp-bind`, open for + the life of `serve` when configured (`muninn_input_rudp_hub_options`, on + the model of `M :3232-3241`). On a 2 ms tick it: + - drains each source's edge queue into the windows of every session that + requested that device; + - sends one frame per (session, device) on `latest`, with a 50 ms + heartbeat when a window holds nothing new + (`HID_CONTROLLER_RUDP_HEARTBEAT_AFTER`, `:6138`); + - applies acks; + - drops sessions after timeout, as the media hub does (`M :3090-3096`). +- **Request intake: one owner for both capabilities.** + - `sync_media_stream_requests` (`M :971-1034`) becomes + `sync_stream_requests`. It makes **one** `pull_rudp_catalog_snapshot` with + `schema_ids = [media request, input request]`. + - Media requests continue exactly as today. + - Input requests addressed to `options.host_id` are admitted by `action` + (B23). An unknown `device_id` is answered `failed` with a typed `detail`. + A `stop`, or a newer request under the same key, withdraws the demand. + - `answer_media_stream_request` (`M :1069-1117`) gets an input twin with + the same keying and dedupe (`answered`). A generic helper is not + introduced for two call sites. +- `advertised_media_endpoint` (`M :1173-1196`) is parameterised as + `advertised_endpoint(explicit, bind, command_advertise)`. Media and input + call the one function, so input inherits "explicit or derived, never + guessed". +- `MuninnDocuments` (`M :10503-10542`) registers the two input records. +- **A capture thread per source**, ported from `fb4f331`: + - XInput sampled every 1 ms (`D main.rs:5881`); + - Windows HID through the existing report reader + (`start_windows_hid_report_reader_if_supported`, `M :8813`), every report; + - joystick events as they arrive. + - Each sample goes through `EdgeDetector` **on the capture thread**. The + edges go to a bounded per-source queue (256; overflow rebaselines every + window on that device), and the latest state goes to a slot. + - The serve tick's HID receipts (`M :5016-5025`, `:5064-5072`, + `:5102-5111`) read the slot, not the device. +- `raven-muninn.toml`: + - the argument pair `:62-65` becomes `--input-rudp-bind 0.0.0.0:17887` and + `--input-rudp-advertise` (binding `input_rudp_advertise`); + - a second `[[provides]]` block: `muninn.input-producer`, + `muninn.input_stream_advertisement.v1`, `v1`. + - The binding rename lands in gamecult-ops with H5. + - This edits the file `route/b3-declare` also edits, in a different block. + Rebase onto it if it has merged. + +**Rules:** +- A tap shorter than one transport tick, from a scripted fake XInput source, + becomes two edges in the next frame. +- Two sessions requesting one device each receive every edge once. Dropping + all frames to one session for 600 ms rotates only that session's epoch. +- A session whose `receiver_id` has no admitted request receives no frame. + So does a session whose request names another device. +- After a simulated restart, with fresh `InputDemand` and an Odin fixture + still holding the request at `running`, the session is served again with no + new request (B23). +- The frame stream from a fake source through a seeded drop relay matches + H1's property on the wire. Assert on captured datagrams. +- The serve tick never opens a device that a capture thread owns: a dev-only + per-device open counter reads 1. +- `rg serde_json crates/muninn-daemon/src/input_stream.rs` is empty, and no HID + path in `main.rs` calls `serde_json`. +- The typed advertisement round-trips through a local CultMesh node fixture, + as `R tests/catalog.rs:162-180` does for media. + +**Verification:** Yggdrasil, `cargo test -p muninn-daemon`, one job. The +XInput and Windows HID readers are `cfg(windows)`, so the scenario uses a +scripted source behind the same capture trait. +- **Starfire:** one Windows compile check of `muninn-daemon`. It is batched + with H4's, one job and no burners (load budget). +- **Only live proves:** real XInput sampling jitter on the viewer's host (H5). + +**Build budget:** `muninn-daemon` only. One new module, no new target and no +new dependency. + +**Ledger:** about −750 (the outbound client ~150, the JSON listener and match +functions ~235, the per-tick reader and emit ~195 (its read bodies relocate), +the JSON advertisement ~105, the discovery write and fence ~20, the rewritten +test ~60 net) and about +450 (the organ ~300, capture threads ~100, +intake/answer twin ~50). **Net about −300.** + +### H3: Sleipnir moves into Muninn's workspace (Q9); behaviour-neutral + +**Source:** Odin `379b826` `crates/sleipnir-daemon/{Cargo.toml, src/main.rs}`, +3,658 lines. That is 8 commits by path, the oldest through `4ad8bdb`, and +`--follow` finds no earlier rename. + +**How history moves.** This is the Muninn extraction precedent: Muninn's own +history came out of Odin whole (316 commits, root `2d88408`). +- In a scratch clone of Odin, run + `git filter-repo --path crates/sleipnir-daemon`. +- In Muninn, `git merge --allow-unrelated-histories` that result. It lands at + the same path, `crates/sleipnir-daemon/`. +- `git log -- crates/sleipnir-daemon` then works in Muninn. Odin keeps its own + copy of the history after its deletion commit. + +**Per-file changes, all in Muninn:** +- `Cargo.toml` (workspace): + - add `crates/sleipnir-daemon` to `members`; + - add a `[workspace.dependencies]` table holding the one CultLib rev + (`c2a9a6e526390808ef195759056fda0b9a55d8a3`) for `cultcache-rs`, + `cultmesh-rs` and `cultnet-rs`, plus `odin-core` at Odin `3e96c6c`. +- `crates/muninn-daemon/Cargo.toml:18-20, 24`: the four git pins become + `{ workspace = true }`. From here, "pins move in lockstep" is one line, not + a discipline. +- `crates/sleipnir-daemon/Cargo.toml`: + - the CultLib pins become `{ workspace = true }`. They were `a8aedda` in + Odin: the pin moves from Odin `main`'s to Muninn's; + - `odin-core = { path = "../odin-core" }` becomes `{ workspace = true }`; + - `edition`, `license` and `publish` already read `.workspace`, and + Muninn's workspace defines all three. +- `crates/sleipnir-daemon/src/main.rs`: **no edit**. The pin move from + `a8aedda` to `c2a9a6e` is the only behavioural exposure. Odin made the + same move for this crate in `3e96c6c`. +- `Cargo.lock`: regenerated. It gains `vigem-client` for Windows only, and + Muninn's recipe keeps building `-p muninn-daemon --bin muninn` (`:14-22`), + so Raven's Muninn build is unchanged. + +**Deletes:** none in Muninn. Odin `main`'s copy becomes a forbidden writer, +and its removal is the post-ship Odin commit. + +**Verification:** +- `cargo test -p sleipnir-daemon` on Yggdrasil (Linux, `LoggingBackend`). The + existing 22 tests (`S :2959-3660`) pass unchanged at the new pin. +- `cargo test -p muninn-daemon` passes unchanged. The workspace-dependency + hoist is proved by an unchanged `cargo tree -d -p muninn-daemon` for + `cultcache-rs`: exactly one. +- Starfire: one Windows `cargo check -p sleipnir-daemon`, because + `vigem-client` is `cfg(windows)`. +- `SleipnirInputMappingRecord` keeps coming from odin-core (`S :13`). Moving + it into Sleipnir is a later subtraction, not this cut. + +**Build budget:** one binary target, `sleipnir`, joins the workspace. It +leaves Odin's workspace at the post-ship commit, so the estate's target count +is unchanged. + +**Ledger:** 0 (a move) plus about −10 manifest lines (the pins hoisted). + +### H4: Sleipnir requests input and applies edges (Muninn repo) + +Developed with H2 on one Hands branch, and merged with it. + +**Authority map.** +- **Owner:** `commit_pad(state)` is the only caller of + `VirtualPadBackend::update`. Today there are five direct calls: `S :387`, + `:400`, `:472`, `:525`, and the `LoggingBackend` path. +- **Inputs:** + - typed input advertisements; + - the mapping record; + - the answered request; + - frames on its own session. +- **Outputs:** the request, acks, the pad timeline, and the Eve surface. +- **Derived state:** + - "available devices" is derived from advertisements; + - the selected endpoint is derived from the chosen advertisement; + - neither is discovered from JSON. +- **Forbidden writers:** + - any `backend.update` outside `commit_pad`; + - a snapshot writing `buttons` inside an epoch; + - JSON; + - `discover_provider_endpoints`. +- **Shared paths:** frames, epoch baselines, staleness neutralisation, mapping + change and reconnect all reach the pad through `commit_pad`. + +**Deletes first** (`S`, identical lines after H3): +1. **The losing path per Q10: Sleipnir's listening mode.** + - `Options.rudp_bind` (`:42`); + - the `--rudp-bind` | `--udp-bind` arm (`:2823-2829`); + - the server branch of `create_rudp_stream` (`:2244-2281`); + - `[--rudp-bind ADDR]` in `usage` (`:2906`). +2. **The JSON subscription.** + - `HidControllerRudpSubscription` (`:68-72`); + - `ActiveRudpStream.last_subscription*` (`:64-65`); + - `send_hid_subscription_if_due` (`:2283-2321`) and its call (`:426-431`). +3. **The JSON decode and the button coalescing.** + - `receive_rudp_records` (`:2480-2541`) is rewritten to decode + `MuninnHidWireRecord`; + - `coalesce_latest_timed_hid_records_by_device` (`:2543-2565`) and + `coalesce_latest_hid_records_by_device` (`:2567-2588`) are deleted, + with their tests (`:2959-2996`). Axes stay latest-wins, because the + frame carries only current axes. +4. **JSON and Odin-generic discovery** (B21). + - The second, provider-key pull in `pull_odin_catalog_snapshot` + (`:950-975`). The first pull's schema list becomes + `[muninn.input_stream_advertisement.v1, sleipnir.input_mapping.v1]`, + plus the request schema for the answer. + - `muninn_provider_keys_for_discovered_hid_hosts` (`:978-1003`) and + `hid_state_host_id_from_value` (`:1005-1019`). + - `effective_muninn_hid_endpoint` (`:1826-1833`). + - `discover_available_hid_devices` through `endpoint_looks_like_socket` + (`:1845-2131`). + - `resolve_socket_addr` stays. `discover_muninn_hid_endpoint` through + `stream_host_hint` (`:2370-2478`) goes. + - The eight discovery tests (`:3164-3513`) are replaced by three tests over + typed advertisements. + - Imports go: `EVE_PROVIDER_ADVERTISEMENT_SCHEMA` (used only at `:957`, + `:1890` and `:2420`), `MUNINN_HID_CONTROLLER_STATE_SCHEMA`, + `MuninnHidControllerStateRecord`, `OdinEndpointQuery` and + `discover_provider_endpoints` (`:10-14`). Sleipnir's odin-core symbols + fall from 10 to 4: the Eve advertisement and surface records, + `OdinDocuments`, and `SleipnirInputMappingRecord`. Pass 1 of H5 takes + `IdunnDaemonHealthRecord` too. +5. **Direct pad writes:** the five `backend.update` sites listed above. +6. **Removed-flag stubs that only reject old spellings:** + `--command-rudp-bind`, `--command-rudp-advertise` and + `--odin-cultmesh-rudp` (`:2830-2849`), with their tests (`:3605-3647`). + They are older than a Muninn-workspace body, and nothing passes them now + (`Ops idunn-deployment-targets.ps1:131`: `sleipnir --host raven`). + +**Adds:** +- `SleipnirDocuments`: `OdinDocuments` plus the two input records, on the + model of `MuninnDocuments` (`M :10503-10542`). It replaces `OdinDocuments` + at `S :269, 281`. +- `select_input_device(advertisements, mapping) -> Option<(advertisement, device_id)>`. + This is **one** function. It matches `mapping.stream_id` against the + advertisement's `stream_id`, and `mapping.device_filter` against + `device_ids` and `device_kinds`. The rules of `record_matches_filter` + (`S :2602-2612`) are kept. + - Persisted mapping records hold the old stream-id format + (`host:move_id:hid-controller-state`). They fall through to + `device_filter` and are rewritten on the next Eve mapping command. No + migration shim. +- **The request lifecycle,** the Ratatoskr pattern (`R catalog.rs:95-179`): + - publish `start` on selection, with `receiver_id = sleipnir.` and + `input_budget_ms` from the advertisement's default; + - publish `stop` on deselection, on mapping disable, and on clean exit; + - publish a **new** `start` (a fresh `request_id`) when the session is lost + or silent for `INPUT_STREAM_RECONNECT_AFTER` (`S :29`). A restarted + producer re-admits by demand anyway (B23); this covers the Odin document + being lost. +- **Dial:** the client branch of `create_rudp_stream` (`S :2196-2243`), with + `connect(receiver_id bytes)` in place of `connect(Vec::new())` + (`S :2232`, `:2365`), because the hub binds the session to the request by + its connect payload. +- `EdgeCursor` per selected device. +- An actuation queue drained by `commit_pad`. Frame axes, cursor edges, epoch + baselines, staleness neutralisation (`INPUT_STALE_NEUTRAL_AFTER`, `S :28`) + and a mapping change all go through it (invariant 10). +- The 24 ms visibility hold, overridden at the **request's** + `input_budget_ms`: an edge older than the budget is committed without the + hold (invariant 13). +- `hid_edge_ack` for `applied_through` after each commit, and every tick while + nonzero, on `latest`. +- `map_record_to_virtual_pad` (`S :2677-2696`), `apply_pending_learn` + (`S :1714-1754`) and `input_latency_snapshot` (`S :2614-2651`) take the + cursor's pad input (axes plus held buttons plus the frame's timestamps) + instead of `MuninnHidControllerStateRecord`. The mapping logic is unchanged. +- The loop's sleep uses a 2 ms default for `--interval-ms` (`S :2791` + today: 8). + +**Rules** (on a recording backend, asserting the pad timeline, which is the +layer the game samples): +- A quick tap under `loss-5pct` and `burst-8`: the timeline shows press, then + release; the press is held ≥ 24 ms; nothing is doubled. +- Reordered and duplicated frames produce the same timeline as clean. +- A burst of 20 taps: every one appears. The last is committed no later than + `input_budget_ms` plus one tick after capture. Kill a mutant that removes the + budget override. Probe at `budget ± ε`, with the budget taken from a request + of 60 ms and one of 100 ms. The hold follows the request, not a constant. +- A frame from epoch `current − 1` after a rotation is ignored, and the pad + shows the new baseline. +- Silence for 1.5 s neutralises through `commit_pad`. Assert that the backend + was called only from that function (a dev-only call-site counter). +- Selection: + - a mapping naming a device kind picks the right advertisement among two + hosts; + - a mapping naming an absent device publishes no request; + - a `failed` answer surfaces its `detail` on the Eve surface. +- **End to end on Yggdrasil**, now inside one workspace: + - H2's `run_input_hub` with a scripted source, through a seeded drop relay + (the Cut 3b tool's relay and profiles), to Sleipnir's session loop with a + recording backend; + - an in-process CultMesh node stands in for Odin, holding the advertisement + and request. + - The test lives in `crates/sleipnir-daemon/tests/`, with `muninn-daemon`'s + organ reached as a dev-dependency only if Hands can make it a lib target + cheaply. Otherwise the test drives the hub from `muninn-contracts`'s state + machines plus a thin test driver, as in pass 2. + +**Verification:** `cargo test -p sleipnir-daemon` and `cargo mutants --in-diff` +on Yggdrasil, one job batched with H2's. One Starfire Windows check covers both +crates. + +**Build budget:** `sleipnir-daemon` only. It gains the `muninn-contracts` path +dependency and drops `serde_json` if nothing else in `main.rs` still needs it. +The Eve surface builds JSON (`S :1021-1455`), so it probably stays. + +**Ledger:** about −1,050 (listening mode ~45, JSON subscription ~50, +JSON decode and coalesce ~110, discovery ~420, removed-flag stubs ~20, their +tests ~450) and about +350 (selection and request ~120, cursor, queue and +commit ~130, tests ~250 minus the retired). **Net about −600.** + +### H5: deploy, and the viewer's side + +**Preflight (Q13):** establish whether `raven-sleipnir` runs today (B16 says +unverified). On Raven, read: +- the scheduled task the legacy target keeps alive + (`Ops idunn-deployment-targets.ps1:126-138`); +- Sleipnir's published health `sleipnir.cultnet-rudp-input-mirror-health` on + Odin. + +If it runs, Raven's local pad mirror is live. It dials Raven's Muninn at +`10.77.0.4:17887` with JSON, and it breaks the moment Idunn deploys a +`main` that contains H2 (`raven-muninn` admits `refs/heads/main` by +`ref-head`, binding `raven-muninn.toml.in:7-9`). + +**Steps:** +- **Sleipnir recipe** `deployment/idunn/raven-sleipnir.toml` in **Muninn's** + repo, beside `raven-muninn.toml`: + - a `rust-host` build step, `cargo build --locked --release -p sleipnir-daemon + --bin sleipnir`, which builds `vigem-client` on Windows; + - `[[dependencies]] odin.verse-rendezvous`, per Idunn's B3 ruling ("the + recipe declares readiness"), because Sleipnir publishes its Eve surface + and its requests to Odin; + - its presence contract. +- **Presence:** `M src/idunn_presence.rs` (229 lines; Muninn-specific only in + one doc line and one error string, `:14`, `:146`) moves **verbatim** into + `muninn-contracts` as `idunn_presence`. Both daemons call it. + - Delete Sleipnir's legacy `publish_idunn_health_if_configured` and + `publish_idunn_rudp_health` (`S :792-905`), their three flags + (`S :2853-2867`), and the `IdunnDaemonHealthRecord` import. That leaves + three odin-core symbols. + - Presence's rightful owner is CultLib, because every Idunn-launched daemon + needs it. Recorded under "Substrate missing"; not moved here. +- **Binding** `idunn/yggdrasil/bindings/raven-sleipnir.toml.in` in + gamecult-ops, modelled on `raven-muninn.toml.in`, with the same repository + (`GameCult/Muninn`) and a different `recipe_path`. + - In the same change, `raven-muninn.toml.in`'s argument binding + `hid_controller_rudp_advertise` (`:38`) becomes `input_rudp_advertise`. +- **Retire** the legacy `raven-sleipnir` script target + (`Ops idunn-deployment-targets.ps1:126-138`, `Repo = "Odin"`) and + `scripts/deploy-raven-sleipnir.ps1` / `restart-raven-sleipnir.ps1`, in the + same gamecult-ops change. gamecult-ops owns them. +- **The viewer's Muninn.** + - Starfire's is the legacy `starfire-muninn` script target + (`Ops :74-86`). `restart-starfire-muninn.ps1:14-15, 74-79` already passes + an optional HID bind and advertise; these become `--input-rudp-bind` and + `--input-rudp-advertise`, with Starfire's mesh address advertised. + - Rebinding `starfire-muninn` to an Idunn recipe is its own ops item, not + this cut. + - A viewer outside GameCult's hosts runs Muninn by hand. That limit is + recorded, not solved here. +- **Firewall:** a host whose Muninn produces input admits inbound UDP on its + input port (17887) from the game host, as a video producer does on its media port. Starfire needs one + Windows Firewall rule. It is scoped to the mesh interface where possible, + and recorded in gamecult-ops inventory beside Raven's 5220/17887. Raven + keeps 17887 open only while it also produces input for its own local + mirror. +- **What only live proves.** Raven with a game, the operator present, and the + ported `xinput_edge_observer` example (`80adfd3`, 127 lines, into + `crates/sleipnir-daemon/examples/`) reading the ViGEm pad as the game does: + - Sleipnir on Raven finds Starfire's advertisement, requests, dials, and the + request is answered `running`; + - taps from Starfire's pad reach the game over LAN and over the mesh + hairpin; + - the observer shows every tap at ≥ 24 ms visibility; + - end-to-end input latency, from `edge_captured_ns` to the observer; + - a `serve` restart on Starfire resumes input with no operator action (B23). + +**Ledger (repo code only):** about −115 (legacy health) and +40 (presence +wiring). The recipe and binding are declarations. + +--- + +## Sequencing + +Two tracks, media and input. From H3 on they share one repository, Muninn, +and `muninn-daemon/src/main.rs`, so their Hands run **serially in Muninn**, +and in parallel only across repositories and worktrees. + +**Now:** +1. **Cuts 0-1** (merged to `main` at `c3520d1`). +2. **Retag `3e96c6c` as `pins/odin-core-cultlib-c2a9a6e`** (Q2 note). This is a + tag only; Odin `main` is untouched. +3. **Muninn named cut 3** (retire `--idunn-rudp-health`). It removes one of + Muninn's four Odin symbols. It runs serially with the next item. +4. **Cut 2** (bounded sender and seam; Q7's 250 ms default). Muninn. +5. **Muninn named cut 1 in H0's shape** (`muninn-contracts`). Muninn, serially + after Cut 2 or before it; never in parallel on `main.rs`. +6. **In parallel, other repos:** Cut 3 (CultLib worktree; Soul passes before + the tag). + +**Input track:** +7. **H3** (Sleipnir into Muninn's workspace). Behaviour-neutral and + independent of named cut 1. It touches only manifests, the lock and the + imported crate, so it may run beside Cut 2 without touching `main.rs`. +8. **H1** (`muninn-contracts`), after step 5 and Q11. If Q11 rules CultLib, H1 + joins Cut 3's CultLib work and the input track waits for the pin gate + (step 12). +9. **H2 and H4** on one Hands branch, after Q12. Soul verifies each cut + separately. They **merge to `main` together, and only when H5 is ready to + deploy in the same window**, or with `raven-muninn`'s deployment brake + engaged, because `raven-muninn` deploys `main`'s head and a new-wire + Muninn breaks the legacy Sleipnir (Q13). +10. **H5**, after Idunn B3 (the recipe declares its Odin dependency), and the + Q13 preflight. This is operator deployment. + +**Media track:** +11. **Pin gate:** a single-purpose Odin commit bumps odin-core to Cut 3's + CultLib tag, parented on `3e96c6c`, tagged + `pins/odin-core-cultlib-`. Muninn's `[workspace.dependencies]` (H3) + moves once, which moves Muninn and Sleipnir together by construction. + Ratatoskr moves in lockstep. +12. **Cut 4** (Ratatoskr), then **Cut 5** (Muninn video parity). +13. **Cut 6a** (after Cut 2; independent of Cut 5), then **6b** (after Cut 5, + for the ceiling), then **6c** (after `route/b3-declare` merges, Idunn B3, + and FFmpeg provisioning on Raven). +14. **Opus** (Muninn named cut 2), then **Cut 5's audio half** (Q5) and the + `audio` channel deletion taking effect (Q4). +15. **GOP lengthening:** the payoff of 6c, a single-constant change after live + acceptance. + +**StreamPixels ship:** +- no Odin `main` commits; +- no Odin pin change; +- no Idunn edits; +- no StreamPixels CultLib bump. + +After the ship: the Odin commit that deletes `crates/sleipnir-daemon`, and +optionally Odin's own CultLib bump, which is the Odin Stability session's call. + +**Recipe contention.** 6c and H2 both edit `raven-muninn.toml`, in different +blocks (H2: the input arguments `:62-65` and a `[[provides]]`; 6c: the encoder), +and both sit on top of `2260853` after it merges. Whichever lands second +rebases. H5 creates `raven-sleipnir.toml` beside it. + +**Yggdrasil load.** One job at a time for this campaign while StreamPixels' +verification runs. 6a's apt install makes its jobs longer, so batch its unit +and integration runs into one job. H2 and H4 run as one job. + +--- + +## Operator questions + +Q1-Q10 are ruled; see the Rulings block. Three forks are open. None blocks the +media track. + +**Q11. Who owns the input-stream capability records?** +- Context: + - The video capability's pair is CultLib's producer-agnostic + `gamecult.media_stream_*` (`C media_stream_contracts.rs:71-183`). Muninn, + Ratatoskr and StreamPixels' vendored copy share it across three repos. + - Input has one producer (Muninn) and one consumer (Sleipnir), and after Q9 + they share one workspace. + - Any CultLib change moves Muninn off `c2a9a6e`, and only the pin gate + closes the odin-core diamond that reopens (B11). +- Options: + - (a) **`muninn-contracts`, as `muninn.input_stream_*`.** H1 needs no CultLib + change and runs before Cut 3's tag. When a second producer or consumer + appears, the records move to CultLib under `gamecult.*`. They are live + documents republished every tick, not stored truth, so that move is a + schema rename with no migration. + - (b) **CultLib, as `gamecult.input_stream_*`,** beside the media pair. This + is the general-library shape a reasonable CultLib consumer would expect, + and it is the exact mirror. H1 joins Cut 3's CultLib tag, and the whole + input track waits for the pin gate (step 12), behind Cuts 3 and 4. +- Recommendation: **(a)**. The mechanism is mirrored exactly; only the + schema's owner differs, and it differs because the capability has one + implementation today. +- What depends on it: H1's location and ids; whether the input track waits + for the pin gate; `MuninnDocuments` and `SleipnirDocuments` registrations. + +**Q12. Move evidence rides the HID listener. What happens to it?** (B20) +- Context: + - Muninn sends Move-evidence frames (MessagePack + `mimir.muninn_move_evidence_stream_frame.v1`) on channel `move-evidence` + of the HID connection, only to a session that sent the JSON + `hid.subscribe`. + - Mimir's runtime does that (`Mi MimirOdinMoveProofEvidenceRingProvider.cs:223`), + after finding the endpoint in the JSON `inputStreams` H2 deletes. + - Mimir's provider was last changed on 2026-07-14 (`345c46b`). Raven's + recipe sets no `--move-evidence-stream`. Nightwing and Starfire configure + it. +- Options: + - (a) **Fold Move evidence into the input-stream capability.** Muninn + advertises a second `muninn.input_stream_advertisement.v1` per host, with + a `payload_schema` field distinguishing HID frames from Move-evidence + frames. Mimir requests it by document and dials with its `receiver_id`. + This needs a Mimir (C#) cut, "H2m", landing with H2. + - (b) **Keep a Move-evidence-only JSON `hid.subscribe` arm** on the new hub + until Mimir moves. This keeps JSON on a live wire (invariant 14) and a + second admission path (Q10), so it needs a named deletion line. + - (c) **Drop the remote Move-evidence transport**, if Mimir's move proof is + dormant. Delete the RUDP hand-off (`M :4267-4275`), `rudp_sender`, and the + bind coupling of `local_ring_enabled` (`:4238`). Mimir re-enters through + (a) when it next needs the stream. +- Recommendation: **(a) if anyone runs Mimir's move proof today, else (c).** + (b) only as a bounded bridge under (a). +- What depends on it: H2's deletion list items 2 and 7; whether a Mimir cut + joins the input track. + +**Q13. Is Raven's legacy Sleipnir live, and may its local mirror go dark +between the H2/H4 merge and H5?** +- Context: + - B16 left "whether it runs on Raven today" unverified. + - `raven-muninn` deploys `main`'s head. The moment `main` holds H2, Raven's + Muninn speaks the new wire, and a legacy JSON Sleipnir on Raven stops + receiving input. +- Options: + - (a) **Hold the H2/H4 merge until H5 deploys in the same window.** No dark + interval; the merge waits on Idunn B3. + - (b) **Merge when Soul passes, with `raven-muninn`'s deployment brake + engaged** until H5. Raven's Muninn stays on the previous release, and + media Cuts behind it wait too. + - (c) **Accept a dark interval** for Raven's local mirror, if the preflight + shows it is not in use. +- Recommendation: run H5's preflight first. If the mirror is live, choose + **(a)**. If not, choose **(c)**. (b) blocks the media track and is the + worst trade. +- What depends on it: when H2 and H4 may merge; whether H5 waits on B3 before + any of the input track lands on `main`. + +--- + +## Substrate missing (record, do not wait on it) + +- **No typed verify transaction.** Every probe went through the ygg-verify + stopgap, and one run queued behind 5 busy slots. This is Idunn's verify + campaign. +- **No machine-readable media-path map.** The ownership facts are spread across + `teardown-map.md` (with 10+ stale rows), a memory file (`media-path-ownership.md`) + and three repos. The staleness this pass found (B4, B9, L656) is the cost. +- **No synthetic media source anywhere on the path.** Every earlier + measurement needed Raven, a GPU and a game. Cut 2's seam is the first harness + that runs off Raven. +- **Idunn host-native targets cannot fetch pinned inputs.** + `external_inputs` are refused on host-native materialisation (`I host.rs:953-956`). + So Raven's FFmpeg development root is hand-provisioned and verified only by + `build.rs`'s version pin and the inventory's sha256. Every future Windows-host + native dependency hits this. The requirement belongs to Idunn: materialise a + sha-pinned archive on a host-native runner. +- **No C++ CultNet runtime.** The encoder's typed command channel needs a Rust + shell around the C++ core (6a). Every native child with a control channel + will pay this, and the alternative (hand-decoding MessagePack in C++) is the + Mimir receiver scar. The Rust-shell-over-C-ABI pattern (Ratatoskr's FFI, + `muninn-move-tracker`'s staticlib) is the house answer until a need justifies + a C++ runtime. + +## Appendix A: probe logs + +In this session's scratchpad: +- `donor-fec-tests.log` (9 pass); +- `muninn-media-tests.log` (78 pass); +- `rs-probe.log` and `rs-probe/` (the scratch crate, commit `656865b`); +- `ratatoskr-tests.log` (31 + 2 pass at `488b5b1`). + +Pass 2 ran no new builds. Its claims are source reads at the named SHAs. The +6a, H1 and H4 harnesses are the first executions of those designs. diff --git a/docs/streaming-deprecation.md b/docs/streaming-deprecation.md new file mode 100644 index 0000000..8f4085a --- /dev/null +++ b/docs/streaming-deprecation.md @@ -0,0 +1,37 @@ +# Streaming deprecation (Meta, 2026-11-06) + +Muninn's streaming role and the OBS media receiver are superseded in the streaming +space. Scope: screen and loopback-audio capture, the media sender, and the receiver at +github.com/GameCult/Ratatoskr (forge mirror `GameCult/Ratatoskr-receiver`; the forge repo +`GameCult/Ratatoskr` is an unrelated chat client and is not covered). Nothing has been +deleted. The lists below come from file names and docs, not from a consumer audit; +confirm each consumer before cutting. + +## What depends on the streaming role + +- Nothing in StreamPixels on main. StreamPixels `tools/showcheck` (PR #2) read Muninn's + activation log and the receiver's OBS log until it was rescoped on 2026-11-06 (a762f69) + to server, overlay and OBS only; the Muninn and Ratatoskr hops are gone from it and + survive only on its parked branch `kiko/showcheck-muninn-chain`. +- Docs here that describe it: `docs/muninn-media-streaming.md`, + `docs/realtime-robustness-cut.md`, and the receiver sections of `docs/teardown-map.md`. +- Operations: `scripts/activate-muninn-raven-*`, `scripts/health-*`, + `scripts/restart-*`, and `deployment/idunn` (the health and restart scripts also serve + the non-streaming daemon, so they stay). +- The receiver repo's README names Muninn in prose. + +## Removal candidates (streaming only; verify consumers first) + +- `crates/muninn-daemon/src/media_send.rs`, `media_send/tests.rs`, + `media_packetizer.rs`, and the media wiring in `main.rs`. +- Media-related records in `crates/muninn-contracts` (`records.rs`, `lib.rs`), if no + non-streaming consumer reads them. +- `scripts/activate-muninn-raven-av-srt.cmd`, `scripts/activate-muninn-raven-media.ps1`, + `scripts/wasapi-loopback-capture.ps1`. +- `docs/muninn-media-streaming.md` (move to history rather than delete if it is cited). + +## Keep + +Sensor serving, PS Move tracking (`muninn-move-tracker`, `muninn-psmoveapi-tracker`, +`native/`), and `sleipnir-daemon` input are outside this notice. Do not remove them under +it. `idunn_presence.rs` matched a media search term only; it is presence, not streaming. diff --git a/docs/teardown-map.md b/docs/teardown-map.md index 6890d45..b77d53a 100644 --- a/docs/teardown-map.md +++ b/docs/teardown-map.md @@ -1,6 +1,6 @@ -# Muninn Teardown Map (pre-rebuild) +# Muninn Teardown Map (history of the extraction) -Date: 2026-09-09. Working map for extracting Muninn from Odin into a dedicated repo. +Date: 2026-09-09. Working map for extracting Muninn from Odin into a dedicated repo. Muninn now lives in `GameCult/Muninn`; the body below was written at `Odin\crates\muninn-daemon` and is annotated in place where git has since contradicted it. Line counts at `e70db69`: `main.rs` 15,134 and `media_packetizer.rs` 2,633 under `crates/muninn-daemon/src/`. ## What Muninn is (operator, 2026-09-09) @@ -21,7 +21,7 @@ Independently confirmed in gamecult-ops `scripts/idunn/idunn-deployment-targets. - `src/media_packetizer.rs` 4,244 lines Sibling crates: `muninn-move-tracker` (308), `muninn-psmoveapi-tracker` (359). -CultLib pin: `c13b6ba0` (2026-09-05), 3 commits behind CultLib HEAD `d1a9edad`. +CultLib pin at the time of writing: `c13b6ba0` (2026-09-05), 3 commits behind CultLib HEAD `d1a9edad`. Live pin: `c2a9a6e` (`crates/muninn-daemon/Cargo.toml:18-20`). ## Authorities currently fused in main.rs @@ -47,7 +47,7 @@ Adding a sensor touches one file and zero core code. ## Schema ownership (decided) -19 `muninn.*` schemas, 38 declarations, currently in `odin-core/src/documents.rs`. +19 `muninn.*` schemas, 38 declarations, at the time of writing in `odin-core/src/documents.rs`. The four media schemas have since moved to CultLib as `gamecult.media_*`; the other `muninn.*` records are still imported from odin-core. Muninn's contracts owned by Odin = inversion. Move to CultLib, following `a539d4f` (Idunn/Odin authority contracts returned to CultLib) and `c13b6ba` (IdunnDaemonHealthTrustBindingRecord into cultnet-rs). @@ -62,7 +62,7 @@ obs_stream_catalog, quest_access, telemetry_surface, transport_profile. ## Coupling -Muninn -> odin-core: ONE import block, 20 symbols (main.rs). +Muninn -> odin-core: ONE import block, 20 symbols (main.rs) at the time of writing; 21 at `e70db69` (`main.rs:27-37`). odin-core / odin-daemon / sleipnir-daemon -> Muninn: NONE. Crate boundary cuts clean. @@ -436,7 +436,7 @@ exercising the path it claims to measure; `--metrics` stays in the script. ## Ratatoskr exists (2026-09-10) -https://github.com/GameCult/Ratatoskr — the receiving end, extracted from the +https://github.com/GameCult/Ratatoskr (forge mirror `GameCult/Ratatoskr-receiver`; the forge `GameCult/Ratatoskr` is the unrelated chat client) — the receiving end, extracted from the 6,515-line C++ plugin in `Mimir/native/obs_stem_source/`. Holds one rule: **it implements no transport, it consumes CultNet.** The plugin @@ -447,7 +447,7 @@ cultnet-rs and cultnet-ts but not the receiver. Working: subscription over `cultnet-rs`, drained and handed across a C ABI. 9 Rust tests, 14 C checks (the C side loads the cdylib dynamically and verifies -the header's claims, rather than assuming them). Pinned to CultLib `d1a9eda`. +the header's claims, rather than assuming them). Pinned to CultLib `d1a9eda` at the time of writing; now `c2a9a6e` (Ratatoskr `crates/ratatoskr-core/Cargo.toml:16-18`). ### The next blocking piece @@ -460,8 +460,9 @@ The receiver-side reassembly code that was kept in `media_packetizer.rs` as the seed for Ratatoskr moved there on 2026-09-10 (`Ratatoskr` 2618184, `crates/ratatoskr-core/src/video.rs`) and was cut here (705 lines: frame assembly, the assembly set, reassembly, expired-frame feedback, their tests). -Muninn now holds only the producer half: packetize, XOR stripe parity, and the -feedback *builder* its sender tests exercise. The contract's erasure code is +Muninn holds the producer half (packetize, XOR stripe parity, the feedback +*builder* its sender tests exercise) and still carries receiver residue: `AudioPacketBuffer` +and the whole-stream Annex B helpers in `media_packetizer.rs`, which only tests call. The contract's erasure code is XOR stripes, one recovered chunk per stripe; the C++ receiver's GF(256) block solver reads fields the v2 record does not carry and stayed in Mimir. @@ -608,22 +609,24 @@ Three repos where there was one crate, and a contract neither of them owns. | Repo | Role | State | |---|---|---| -| CultLib `main` `05e0925` | the contract | media records, wire envelope, validation, channel delivery | +| CultLib `main` `05e0925` at the time of writing (media contract unchanged since `c2a9a6e`) | the contract | media records, wire envelope, validation, channel delivery | | Muninn | producer | speaks the shared contract; blocked on one pin (below) | | Ratatoskr | consumer | decodes the envelope; builds clean, no conflicts | -### The one thing blocking a clean Muninn build +### The one thing blocking a clean Muninn build (history; resolved) + +Resolved 2026-09-11 (see the Raven section below): `Cargo.lock` is tracked (`70d267f`) and the pins are the build. The build resolves `odin-core` from Odin `3e96c6c`, which no Odin branch holds; only the tag `attic/claude-cultlib-pin-c2a9a6e` keeps it reachable. The text below is the state on 2026-09-10. `odin-core` pins CultLib `c13b6ba`; Muninn needs `05e0925`. Cargo resolves two `cultcache-rs` copies and `DatabaseEntry` from one is not `DatabaseEntry` from the other. -Muninn cannot resolve this alone: it uses 23 odin-core symbols, and while 16 are +Muninn cannot resolve this alone: it used 23 odin-core symbols (21 at `e70db69`), and while 16 are its own records that belong here (capture stream, command boundary, HID controller state, five Move records, OBS catalog, Quest access, telemetry -surface, transport profile), 7 are genuinely Odin's — `discover_provider_endpoints`, +surface, transport profile), 7 were genuinely Odin's — `discover_provider_endpoints`, `OdinDocuments`, `OdinEndpointQuery`, Eve advertisement and surface records, -`IdunnDaemonHealthRecord`. +`IdunnDaemonHealthRecord`. At `e70db69` four remain imported: `EveProviderAdvertisementRecord`, `EveSurfaceStateRecord`, `IdunnDaemonHealthRecord`, `OdinDocuments`. Muninn's two bodies were collapsed 2026-09-10 (Odin d41c744 dropped its workspace copy of the three crates and the actuator scripts). The Idunn @@ -653,10 +656,8 @@ one once the patch is gone. Muninn-specific `obs_stream_catalog` / `capture_stream_command` stay published beside them until nothing reads them. The old plugin's CLI shell-out and `.cc` snapshot are not ported. The connection direction was - inverted the same day (section above). **Not yet exercised live:** Raven - runs a pre-b679fc2 Muninn; the next Raven deploy ships this repository - (gamecult-ops rebound the targets 2026-09-10) and needs - `MUNINN_MEDIA_RUDP_ADVERTISE` set. + inverted the same day (section above). First live frames on `58e8663` (2026-09-10); exercised through 2026-09-11 on `bc43e1b` and later + (measurements below); the 2026-09-10 note that Raven ran a pre-b679fc2 Muninn is history. 3. **Opus.** Unblocked and measured at 16.8x. `-f aac` in the receiver becomes codec-driven; framing follows the `aac-adts-padded-v1` precedent (2-byte big-endian length prefix). @@ -664,8 +665,10 @@ one once the patch is gone. `feedback.rs`). The producer's repair cache and keyframe counter now have a live counterpart. `build_receiver_feedback` moved to CultLib (34c8ea7) and stopped implying a keyframe request from missing chunks (4160ab5): a repair - request is the alternative to one, and the sender turns every new keyframe - request into an IDR. + request is the alternative to one. The sender counts keyframe requests and logs them; + it does not force an IDR (`main.rs:3036-3048`). Recovery today is the fixed GOP: + every GOP keyframe is an IDR, at a GOP of `framerate/4` frames (`-forced-idr 1`, `-g`, + `-keyint_min`, `main.rs:10405-10410`); not every frame. ### Deliberate breaks, both recorded as passing tests @@ -698,8 +701,7 @@ by continuity in under 10 s. The catalog on Odin named the new endpoint the first time the restarted `serve` advertised. Still Raven-specific and unmanaged: the two activation scripts and -`health-muninn.ps1`, which still passes the retired `--idunn-rudp-health` -flags. That flag family (`IdunnRudpHealthOptions`, `run_daemon_health_publisher`, -`idunn.daemon_health` documents) has no consumer since the previous Idunn -generation was retired and is the next cut; nightwing and starfire's restart -scripts still require it, so it goes with them. +`health-muninn.ps1`. The retired `--idunn-rudp-health` flag family +(`IdunnRudpHealthOptions`, `run_daemon_health_publisher`, `idunn.daemon_health` +documents) had no consumer since the previous Idunn generation was retired; it +was deleted from `muninn`, its five host scripts and `muninn.md` in named cut 3. diff --git a/scripts/health-muninn.cmd b/scripts/health-muninn.cmd index 7811b7d..e2ddbe7 100644 --- a/scripts/health-muninn.cmd +++ b/scripts/health-muninn.cmd @@ -1,3 +1,3 @@ @echo off -echo health-muninn.cmd archived: Raven Muninn health is daemon-published over CultNet/RUDP as muninn.cultnet-rudp-remote-telemetry-health. Use health-muninn.ps1 only as an explicit witness inspection, not Idunn health truth. +echo health-muninn.cmd archived: Raven Muninn has no daemon-published health. Run health-muninn.ps1 as an explicit witness inspection (scheduled-task actions, serve process, store freshness); it is not Idunn health truth. exit /b 2 diff --git a/scripts/health-muninn.ps1 b/scripts/health-muninn.ps1 index f783148..407b89e 100644 --- a/scripts/health-muninn.ps1 +++ b/scripts/health-muninn.ps1 @@ -5,7 +5,6 @@ param( [string] $ActivateStorePath = "C:\Meta\Odin\state\muninn.activate.cc", [string] $LogRoot = "C:\Meta\Odin\logs\muninn", [int] $MaxStoreAgeSeconds = 180, - [string] $IdunnRudpHealth = $env:IDUNN_RUDP_HEALTH, [int] $ConnectTimeoutSeconds = 10, [string] $SshUser = "madman's lullaby", [string] $IdentityFile = "" @@ -13,10 +12,6 @@ param( $ErrorActionPreference = "Stop" -if ([string]::IsNullOrWhiteSpace($IdunnRudpHealth)) { - throw "Idunn RUDP health endpoint must be supplied by -IdunnRudpHealth or IDUNN_RUDP_HEALTH; no Starfire LAN default is allowed." -} - function Set-AsciiFile { param( [Parameter(Mandatory = $true)] [string] $Path, @@ -177,10 +172,7 @@ if (`$null -eq `$process) { } foreach (`$pattern in @( "--host raven", - "--activate-store $ActivateStorePath", - "--idunn-rudp-health $IdunnRudpHealth", - "--idunn-daemon muninn", - "--idunn-health-contract muninn.cultnet-rudp-remote-telemetry-health" + "--activate-store $ActivateStorePath" )) { if (`$process.CommandLine -notlike "*`$pattern*") { throw "Muninn serve process is missing expected command-line segment `${pattern}: `$(`$process.CommandLine)" diff --git a/scripts/health-nightwing-muninn.cmd b/scripts/health-nightwing-muninn.cmd index 6b6554b..eede45d 100644 --- a/scripts/health-nightwing-muninn.cmd +++ b/scripts/health-nightwing-muninn.cmd @@ -1,3 +1,3 @@ @echo off -echo health-nightwing-muninn.cmd archived: Nightwing Muninn health is daemon-published over CultNet/RUDP as muninn.cultnet-rudp-remote-telemetry-and-move-hid. Use health-nightwing-muninn.ps1 only as an explicit witness inspection, not Idunn health truth. +echo health-nightwing-muninn.cmd archived: Nightwing Muninn has no daemon-published health. Run health-nightwing-muninn.ps1 as an explicit witness inspection (serve process, store freshness, PID file); it is not Idunn health truth. exit /b 2 diff --git a/scripts/health-nightwing-muninn.ps1 b/scripts/health-nightwing-muninn.ps1 index ce2ce79..d6319cd 100644 --- a/scripts/health-nightwing-muninn.ps1 +++ b/scripts/health-nightwing-muninn.ps1 @@ -5,16 +5,11 @@ param( [string] $PidPath = "/home/metacrat/.local/state/gamecult/muninn/muninn.pid", [string[]] $MoveState = @(), [int] $IntervalSeconds = 15, - [int] $MaxStoreAgeSeconds = 180, - [string] $IdunnRudpHealth = $env:IDUNN_RUDP_HEALTH + [int] $MaxStoreAgeSeconds = 180 ) $ErrorActionPreference = "Stop" -if ([string]::IsNullOrWhiteSpace($IdunnRudpHealth)) { - throw "Idunn RUDP health endpoint must be supplied by -IdunnRudpHealth or IDUNN_RUDP_HEALTH; no WireGuard endpoint default is allowed." -} - function Set-AsciiFile { param( [Parameter(Mandatory = $true)] [string] $Path, @@ -76,16 +71,6 @@ if [ -z "`$process_line" ]; then echo 'Nightwing Muninn serve command line is unavailable' >&2 exit 1 fi -for pattern in \ - '--idunn-rudp-health $IdunnRudpHealth' \ - '--idunn-daemon nightwing-muninn' \ - '--idunn-health-contract muninn.cultnet-rudp-remote-telemetry-and-move-hid' -do - if ! printf '%s\n' "`$process_line" | grep -F -- "`$pattern" >/dev/null 2>&1; then - echo "Nightwing Muninn serve command line is missing `$pattern" >&2 - exit 1 - fi -done if [ ! -f '$StorePath' ]; then echo 'Muninn telemetry store is missing on Nightwing' >&2 exit 1 diff --git a/scripts/health-starfire-muninn.cmd b/scripts/health-starfire-muninn.cmd index 36d421c..db26de6 100644 --- a/scripts/health-starfire-muninn.cmd +++ b/scripts/health-starfire-muninn.cmd @@ -1,3 +1,3 @@ @echo off -echo health-starfire-muninn.cmd archived: Starfire Muninn health is daemon-published over CultNet/RUDP as muninn.cultnet-rudp-local-telemetry-and-quest-access. Use health-starfire-muninn.ps1 only as an explicit witness inspection, not Idunn health truth. +echo health-starfire-muninn.cmd archived: Starfire Muninn has no daemon-published health. Run health-starfire-muninn.ps1 as an explicit witness inspection (serve process, store freshness, PID file); it is not Idunn health truth. exit /b 2 diff --git a/scripts/health-starfire-muninn.ps1 b/scripts/health-starfire-muninn.ps1 index c331145..d5be3ec 100644 --- a/scripts/health-starfire-muninn.ps1 +++ b/scripts/health-starfire-muninn.ps1 @@ -3,16 +3,11 @@ param( [string] $StorePath = "C:\Meta\Odin\state\starfire.muninn.telemetry.cc", [string] $LogRoot = "C:\Meta\Odin\logs\starfire-muninn", [string[]] $MoveState = @(), - [int] $MaxStoreAgeSeconds = 180, - [string] $IdunnRudpHealth = $env:IDUNN_RUDP_HEALTH + [int] $MaxStoreAgeSeconds = 180 ) $ErrorActionPreference = "Stop" -if ([string]::IsNullOrWhiteSpace($IdunnRudpHealth)) { - throw "Idunn RUDP health endpoint must be supplied by -IdunnRudpHealth or IDUNN_RUDP_HEALTH; no Starfire LAN default is allowed." -} - if (-not (Test-Path -LiteralPath $MuninnExe)) { throw "Muninn executable not found at $MuninnExe" } @@ -28,15 +23,6 @@ $process = Get-CimInstance Win32_Process | if ($null -eq $process) { throw "Starfire Muninn serve process is not running with Quest access enabled" } -foreach ($pattern in @( - "--idunn-rudp-health $IdunnRudpHealth", - "--idunn-daemon starfire-muninn", - "--idunn-health-contract muninn.cultnet-rudp-local-telemetry-and-quest-access" -)) { - if ($process.CommandLine -notlike "*$pattern*") { - throw "Starfire Muninn serve process is missing expected command-line segment ${pattern}: $($process.CommandLine)" - } -} if (-not (Test-Path -LiteralPath $StorePath)) { throw "Starfire Muninn telemetry store is missing at $StorePath" } diff --git a/scripts/restart-nightwing-muninn.ps1 b/scripts/restart-nightwing-muninn.ps1 index 9f92fa4..58fa1b1 100644 --- a/scripts/restart-nightwing-muninn.ps1 +++ b/scripts/restart-nightwing-muninn.ps1 @@ -17,14 +17,10 @@ param( "nightwing-eye-1" = 100 }, [int] $IntervalSeconds = 15, - [string] $IdunnRudpHealth = $env:IDUNN_RUDP_HEALTH, - [string] $IdunnDaemon = "nightwing-muninn", - [string] $IdunnHealthContract = "muninn.cultnet-rudp-remote-telemetry-and-move-hid", [string] $OdinCultMeshUri = $(if ($env:ODIN_CULTMESH_URI) { $env:ODIN_CULTMESH_URI } else { "cultmesh://odin/rendezvous/provider-catalog" }), [string] $OdinCultMeshRudpEndpoint = $(if ($env:CULTMESH_URI_ODIN_RUDP) { $env:CULTMESH_URI_ODIN_RUDP } else { "10.77.0.2:17871" }), [string] $HidControllerRudpBind = "0.0.0.0:17888", [string] $HidControllerRudpAdvertise = $(if ($env:MUNINN_HID_CONTROLLER_RUDP_ADVERTISE) { $env:MUNINN_HID_CONTROLLER_RUDP_ADVERTISE } else { "10.77.0.3:17888" }), - [string] $CommandRudpBind = "0.0.0.0:17889", [string] $CommandRudpAdvertise = "10.77.0.3:17889" ) @@ -34,12 +30,6 @@ if ($env:IDUNN_ACTUATOR -ne "1" -or $env:IDUNN_COMMAND_AUTHORITY -ne "idunn-daem throw "restart-nightwing-muninn.ps1 is an Idunn actuator body. Redeploy by poking Idunn; direct service restart is not an owned path." } -if ([string]::IsNullOrWhiteSpace($IdunnRudpHealth)) { - throw "Idunn RUDP health endpoint must be supplied by -IdunnRudpHealth or IDUNN_RUDP_HEALTH; no Starfire LAN default is allowed." -} -if ($IdunnRudpHealth -match '^(127\.0\.0\.1|localhost):(\d+)$') { - $IdunnRudpHealth = "10.77.0.2:$($Matches[2])" -} if (-not [string]::IsNullOrWhiteSpace($HidControllerRudpBind) -and [string]::IsNullOrWhiteSpace($HidControllerRudpAdvertise)) { throw "HID controller RUDP advertise endpoint must be supplied by -HidControllerRudpAdvertise or MUNINN_HID_CONTROLLER_RUDP_ADVERTISE when HID RUDP bind is enabled; no Nightwing LAN default is allowed." } @@ -135,7 +125,7 @@ if (-not [string]::IsNullOrWhiteSpace($HidControllerRudpAdvertise)) { $hidControllerRudpSetLines += "set -- ""`$@"" --hid-controller-rudp-advertise $(Quote-ShSingle $HidControllerRudpAdvertise)" } $hidControllerRudpSetBlock = ($hidControllerRudpSetLines -join "`n") -$commandRudpSetBlock = "set -- ""`$@"" --command-rudp-bind $(Quote-ShSingle $CommandRudpBind) --command-rudp-advertise $(Quote-ShSingle $CommandRudpAdvertise)" +$commandRudpSetBlock = "set -- ""`$@"" --command-rudp-advertise $(Quote-ShSingle $CommandRudpAdvertise)" $remoteScript = @" set -eu mkdir -p '$LogRoot' @@ -162,10 +152,7 @@ set -- serve \ --host nightwing $moveRuntimeSetBlock set -- "`$@" \ - --interval-seconds '$IntervalSeconds' \ - --idunn-rudp-health '$IdunnRudpHealth' \ - --idunn-daemon '$IdunnDaemon' \ - --idunn-health-contract '$IdunnHealthContract' + --interval-seconds '$IntervalSeconds' $odinCultMeshUriSetBlock $hidControllerRudpSetBlock $commandRudpSetBlock @@ -179,10 +166,9 @@ muninn_pid="`$(cat '$LogRoot/muninn.pid')" kill -0 "`$muninn_pid" 2>/dev/null muninn_cmdline="`$(tr '\0' ' ' < "/proc/`$muninn_pid/cmdline")" if ! printf '%s\n' "`$muninn_cmdline" | grep -F -- '--host nightwing' >/dev/null 2>&1 || - ! printf '%s\n' "`$muninn_cmdline" | grep -F -- '--idunn-rudp-health $IdunnRudpHealth' >/dev/null 2>&1 || ! printf '%s\n' "`$muninn_cmdline" | grep -F -- '--move-marker-camera nightwing-eye-0=/dev/video2' >/dev/null 2>&1 || ! printf '%s\n' "`$muninn_cmdline" | grep -F -- '--move-marker-camera nightwing-eye-1=/dev/video3' >/dev/null 2>&1; then - echo 'Nightwing Muninn serve command line is missing Idunn health or dual-camera arguments' >&2 + echo 'Nightwing Muninn serve command line is missing dual-camera arguments' >&2 exit 1 fi "@ diff --git a/scripts/restart-starfire-muninn.ps1 b/scripts/restart-starfire-muninn.ps1 index 70b79f6..69af854 100644 --- a/scripts/restart-starfire-muninn.ps1 +++ b/scripts/restart-starfire-muninn.ps1 @@ -6,9 +6,6 @@ param( [string] $MoveBluetoothHost = "", [string[]] $MoveState = @(), [switch] $EnableUsbMoveState, - [string] $IdunnRudpHealth = $env:IDUNN_RUDP_HEALTH, - [string] $IdunnDaemon = "starfire-muninn", - [string] $IdunnHealthContract = "muninn.cultnet-rudp-local-telemetry-and-quest-access", [string] $OdinCultMeshUri = $(if ($env:ODIN_CULTMESH_URI) { $env:ODIN_CULTMESH_URI } else { "cultmesh://odin/rendezvous/provider-catalog" }), [string] $OdinCultMeshRudpEndpoint = $(if ($env:CULTMESH_URI_ODIN_RUDP) { $env:CULTMESH_URI_ODIN_RUDP } else { "127.0.0.1:17871" }), [string] $HidControllerRudpBind = "", @@ -29,9 +26,6 @@ if ($env:IDUNN_ACTUATOR -ne "1" -or $env:IDUNN_COMMAND_AUTHORITY -ne "idunn-daem if (-not (Test-Path -LiteralPath $MuninnExe)) { throw "Muninn executable not found at $MuninnExe" } -if ([string]::IsNullOrWhiteSpace($IdunnRudpHealth)) { - throw "Idunn RUDP health endpoint must be supplied by -IdunnRudpHealth or IDUNN_RUDP_HEALTH; no Starfire LAN default is allowed." -} if (-not [string]::IsNullOrWhiteSpace($HidControllerRudpBind) -and [string]::IsNullOrWhiteSpace($HidControllerRudpAdvertise)) { throw "HID controller RUDP advertise endpoint must be supplied by -HidControllerRudpAdvertise or MUNINN_HID_CONTROLLER_RUDP_ADVERTISE when HID RUDP bind is enabled; no Starfire LAN default is allowed." } @@ -63,10 +57,7 @@ $arguments = @( "--host", "starfire", "--interval-seconds", "15", "--quest-adb", - "--quest-serial", $QuestSerial, - "--idunn-rudp-health", $IdunnRudpHealth, - "--idunn-daemon", $IdunnDaemon, - "--idunn-health-contract", $IdunnHealthContract + "--quest-serial", $QuestSerial ) if (-not [string]::IsNullOrWhiteSpace($OdinCultMeshUri)) { $arguments += @("--odin-cultmesh-uri", $OdinCultMeshUri) @@ -160,15 +151,3 @@ if ($null -eq $processCheck) { if ($null -eq $processCheck) { throw "Starfire Muninn serve process is not running after restart" } -foreach ($pattern in @( - "--idunn-rudp-health", - $IdunnRudpHealth, - "--idunn-daemon", - $IdunnDaemon, - "--idunn-health-contract", - $IdunnHealthContract -)) { - if ($processCheck.CommandLine -notlike "*$pattern*") { - throw "Starfire Muninn serve command line is missing ${pattern}: $($processCheck.CommandLine)" - } -}