diff --git a/Cargo.lock b/Cargo.lock index 70a0f01..27c00d7 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -479,19 +479,6 @@ 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" @@ -501,7 +488,6 @@ dependencies = [ "cultmesh-rs", "cultnet-rs", "libc", - "muninn-contracts", "muninn-move-tracker", "muninn-psmoveapi-tracker", "odin-core", @@ -805,21 +791,6 @@ 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" @@ -907,15 +878,6 @@ 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 b9d770a..a6c8188 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,10 +1,8 @@ [workspace] members = [ - "crates/muninn-contracts", "crates/muninn-daemon", "crates/muninn-move-tracker", "crates/muninn-psmoveapi-tracker", - "crates/sleipnir-daemon", ] resolver = "3" @@ -12,11 +10,3 @@ 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 c894b34..f1bad58 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,5 @@ # 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 @@ -20,11 +11,6 @@ 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 deleted file mode 100644 index 8b674b5..0000000 --- a/crates/muninn-contracts/Cargo.toml +++ /dev/null @@ -1,21 +0,0 @@ -[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 deleted file mode 100644 index e111ae5..0000000 --- a/crates/muninn-contracts/src/lib.rs +++ /dev/null @@ -1,526 +0,0 @@ -//! 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 deleted file mode 100644 index 7742843..0000000 --- a/crates/muninn-contracts/src/records.rs +++ /dev/null @@ -1,508 +0,0 @@ -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 c77d6c5..ac34344 100644 --- a/crates/muninn-daemon/Cargo.toml +++ b/crates/muninn-daemon/Cargo.toml @@ -15,14 +15,13 @@ path = "src/main.rs" [dependencies] anyhow = "1" -cultcache-rs = { workspace = true } -cultmesh-rs = { workspace = true } -cultnet-rs = { workspace = true } +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" } 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 = { workspace = true } +odin-core = { git = "https://github.com/GameCult/Odin.git", rev = "3e96c6c85ca8b89b1bc7b01c1b7744f43111be99" } 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 0a031d6..cba71f0 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -1,11 +1,10 @@ mod idunn_presence; mod media_packetizer; -mod media_send; -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 crate::media_packetizer::{ + AudioPcmStreamSendConfig, AudioPcmStreamSendState, GameCultMediaWireRecord, + MuninnMediaSendPayload, VideoAnnexBStreamSendConfig, VideoAnnexBStreamSendState, + decode_media_wire_record, }; use anyhow::{Context, Result, anyhow}; use cultmesh_rs::{ @@ -13,30 +12,32 @@ use cultmesh_rs::{ CultMeshSharedMemoryFrameRing, CultMeshStreamBodyTransport, CultMeshStreamCatalog, CultMeshStreamClock, CultMeshStreamDescriptor, CultMeshStreamKind, }; +use cultnet_rs::GameCultMediaReceiverFeedbackRecord; use cultnet_rs::{ - CultNetRudpServerHub, CultNetRudpServerHubOptions, CultNetRudpSocketTransportConnection, - CultNetRudpSocketTransportOptions, - GAMECULT_MEDIA_STREAM_ADVERTISEMENT_SCHEMA, + CultNetMessage, CultNetRawDocumentRecord, CultNetRawPayloadEncoding, CultNetRudpServerEvent, + CultNetRudpServerHub, CultNetRudpServerHubOptions, CultNetRudpServerSessionContext, + CultNetRudpSocketTransportConnection, CultNetRudpSocketTransportOptions, CultNetTransportFrame, + CultNetWireContract, GAMECULT_MEDIA_STREAM_ADVERTISEMENT_SCHEMA, GAMECULT_MEDIA_STREAM_REQUEST_SCHEMA, GAMECULT_RUNTIME_PRESENCE_HEALTH_SCHEMA, GameCultMediaStreamAdvertisementRecord, GameCultMediaStreamRequestRecord, - GameCultRuntimePresenceHealthRecord, - media_stream_request_key, validate_media_stream_request, + GameCultRuntimePresenceHealthRecord, decode_cultnet_message_from_slice, + encode_cultnet_message_to_vec, media_stream_request_key, validate_media_stream_request, }; -use muninn_contracts::{ +#[cfg(feature = "psmoveapi-tracker")] +use odin_core::MuninnMoveTrackerHealthRecord; +use odin_core::{ + EveProviderAdvertisementRecord, EveSurfaceStateRecord, IdunnDaemonHealthRecord, MUNINN_MOVE_HUE_PROGRAM_SCHEMA, MUNINN_OBS_STREAM_CATALOG_SCHEMA, MuninnCaptureStreamCommandRecord, MuninnCaptureStreamRecord, MuninnCommandBoundaryCompatRecord, MuninnHidControllerStateRecord, MuninnMoveControllerStateRecord, MuninnMoveEvidenceTransportHealthRecord, MuninnMoveHueProgramRecord, MuninnMoveIdentityRecord, MuninnMoveLightCommandRecord, MuninnMoveMarkerCandidateRecord, MuninnObsStreamCatalogRecord, - MuninnQuestAccessRecord, MuninnRecords, MuninnTelemetrySurfaceRecord, - MuninnTransportProfileCompatRecord, + MuninnQuestAccessRecord, MuninnTelemetrySurfaceRecord, MuninnTransportProfileCompatRecord, + OdinDocuments, }; -#[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}; +use std::collections::{HashMap, HashSet, VecDeque}; use std::env; use std::fs; #[cfg(feature = "psmoveapi-tracker")] @@ -51,9 +52,8 @@ 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,8 +69,10 @@ 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; @@ -88,14 +90,25 @@ 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 latency budget anyway; 30 ms costs nothing it can feel. +/// the assembly deadline anyway; 30 ms costs nothing it can feel. const MUNINN_RUDP_MEDIA_RESEND_DELAY_MS: u64 = 30; -/// 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_ASSEMBLY_DEADLINE_MS: u64 = 2_000; 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; @@ -211,10 +224,12 @@ 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, } @@ -260,7 +275,12 @@ 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, } @@ -270,6 +290,13 @@ 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, @@ -394,6 +421,7 @@ 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)); @@ -430,6 +458,7 @@ 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(); @@ -599,10 +628,29 @@ 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>> { @@ -712,6 +760,135 @@ 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"]; @@ -1311,9 +1488,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_DEFAULT_LATENCY_BUDGET_MS as u32 + MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS as u32 } else { - clamp_latency_budget_ms(command.rudp_latency_budget_ms) + command.rudp_latency_budget_ms } } @@ -1650,14 +1827,7 @@ 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) @@ -2238,8 +2408,7 @@ fn run_rudp_mux_once( let mut audio_sender = None; let result = (|| -> Result { let media_profile = muninn_rudp_media_profile_for_options(options); - let policy = MediaSendPolicy::from_request(options.rudp_latency_budget_ms); - let hub = open_media_rudp_hub(options, &media_profile, &policy)?; + let mut hub = open_media_rudp_hub(options, &media_profile)?; publish_stream( node, options, @@ -2255,10 +2424,10 @@ fn run_rudp_mux_once( )?; let mut last_stream_publish_at = Instant::now(); - let (intake_tx, intake_rx) = media_intake_channel(); + let (payload_tx, payload_rx) = mpsc::channel::>(); video_sender = if let Some(stdout) = video_ffmpeg_stdout { - Some(spawn_video_group_reader( - intake_tx.clone(), + Some(video_rudp_payload_reader( + payload_tx.clone(), stdout, VideoAnnexBStreamSendConfig { stream_id: options.stream_id.clone(), @@ -2269,20 +2438,19 @@ fn run_rudp_mux_once( frame_duration_ticks: video_frame_duration_ticks(options)?, timebase_num: 1, timebase_den: 90_000, - deadline_delay_ticks: policy.video_deadline_delay_ticks(), + deadline_delay_ticks: rudp_media_deadline_delay_ticks(&media_profile), 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(spawn_audio_group_reader( - intake_tx.clone(), + Some(audio_rudp_payload_reader( + payload_tx.clone(), stdout, AudioPcmStreamSendConfig { stream_id: options.stream_id.clone(), @@ -2293,7 +2461,7 @@ fn run_rudp_mux_once( packet_duration_ticks: 480, timebase_num: 1, timebase_den: options.audio_sample_rate, - deadline_delay_ticks: policy.audio_deadline_delay_ticks(options.audio_sample_rate), + deadline_delay_ticks: rudp_audio_deadline_delay_ticks(options, &media_profile), channels: options.audio_channels, bytes_per_sample: 4, max_pending_bytes: 480usize @@ -2303,39 +2471,193 @@ fn run_rudp_mux_once( source_runtime_id: options.host_id.clone(), source_role: "muninn.rudp.audio".to_string(), }, - policy.clone(), )) } else { None }; - drop(intake_tx); + drop(payload_tx); - let mut core = MediaSendCore::new(hub, &policy); + 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; loop { - core.intake(&intake_rx, Duration::from_millis(5))?; - if core.send_next(Instant::now())? { - core.service_control(Instant::now())?; - } else if core.finished() { + 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; break Ok(RudpMuxRestart { - detail: format!("encoder stdout ended; {}", core.progress_detail()), + 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 + ) + ), delay: default_rudp_mux_restart_delay(restart_count), }); - } else { - core.service_control(Instant::now())?; } - 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, - )?; + + { + 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, + )?; + } } })(); @@ -2363,17 +2685,506 @@ 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!( @@ -2386,11 +3197,7 @@ 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, - policy, - ))?; + let hub = CultNetRudpServerHub::new(muninn_media_rudp_hub_options(socket, media_profile))?; eprintln!( "Muninn media RUDP listening at {} for receivers dialling connection {:#x}.", hub.local_addr()?, @@ -2412,21 +3219,110 @@ 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 request's latency budget. +/// past the receiver's assembly deadline. 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(policy.latency_budget_ms()); + options.media_reliable_expire_after_ms = Some(media_profile.receiver_assembly_deadline_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")); @@ -2434,6 +3330,32 @@ 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, @@ -2493,6 +3415,155 @@ 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(()) } @@ -2535,18 +3606,43 @@ fn publish_runtime_boundary_records( .as_ref() .map(|command| json!([command])) .unwrap_or_else(|| json!([])); - let current_transport = "daemon-owned-cultcache-telemetry-store"; - let transport_state = "cultcache-provider-store-only"; + 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 hid_controller_endpoint = options.hid_controller_rudp_bind.map(|bind| { options .hid_controller_rudp_advertise .clone() .unwrap_or_else(|| bind.to_string()) }); - let provider_routes = vec![json!({ + let mut 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| { @@ -2658,6 +3754,18 @@ 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", @@ -2705,7 +3813,7 @@ fn publish_runtime_boundary_records( "target_transport": CULTNET_RUDP_PROTOCOL_ID, "current_transport": current_transport, "state": transport_state, - "health_contract": serde_json::Value::Null, + "health_contract": options.idunn_rudp_health.as_ref().map(|idunn| idunn.health_contract.clone()), "provider_advertisement_schema": "gamecult.eve.provider_advertisement.v1", "command_boundary_schema": "muninn.command_boundary.v1", "telemetry_surface_schema": "muninn.telemetry_surface.v1", @@ -2730,8 +3838,10 @@ 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, - "latency_budget_ms": options.rudp_latency_budget_ms, + "sender_reliable_expire_after_ms": media_profile.sender_reliable_expire_after_ms, + "receiver_assembly_deadline_ms": media_profile.receiver_assembly_deadline_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" @@ -2767,6 +3877,12 @@ 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 @@ -2837,6 +3953,9 @@ 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(), @@ -8241,9 +9360,31 @@ fn quest_access_status(options: Options) -> Result<()> { } fn health_check(options: &Options) -> Result<()> { - let detail = evaluate_health(options)?; - println!("{detail}"); - Ok(()) + 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), + } } fn evaluate_health(options: &Options) -> Result { @@ -8295,6 +9436,22 @@ 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) @@ -8305,6 +9462,104 @@ 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)); @@ -8999,12 +10254,24 @@ fn muninn_rudp_media_profile() -> MuninnRudpMediaProfile { } fn muninn_rudp_media_profile_for_options(options: &Options) -> MuninnRudpMediaProfile { - muninn_rudp_media_profile_for_bitrate(options.rudp_video_bitrate_kbps) + muninn_rudp_media_profile_for_bitrate_and_latency( + options.rudp_video_bitrate_kbps, + options.rudp_latency_budget_ms, + ) } -/// 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", @@ -9016,7 +10283,12 @@ fn muninn_rudp_media_profile_for_bitrate(video_bitrate_kbps: u32) -> MuninnRudpM 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, } } @@ -9217,21 +10489,15 @@ fn ensure_state_dirs(options: &Options) -> Result<()> { Ok(()) } -/// 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. +/// 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. #[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::()?; @@ -9240,7 +10506,6 @@ 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, @@ -9299,7 +10564,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_DEFAULT_LATENCY_BUDGET_MS as u32, + rudp_latency_budget_ms: MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS as u32, width: 1920, height: 1080, framerate: 30, @@ -9351,15 +10616,20 @@ 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, @@ -9437,7 +10707,7 @@ impl Options { "--rudp-latency-budget-ms must be greater than zero" )); } - options.rudp_latency_budget_ms = clamp_latency_budget_ms(latency_budget); + options.rudp_latency_budget_ms = latency_budget; } "--width" => options.width = take_value(&mut args, "--width")?.parse()?, "--height" => options.height = take_value(&mut args, "--height")?.parse()?, @@ -9596,6 +10866,19 @@ 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!( @@ -9624,10 +10907,11 @@ impl Options { Some(take_value(&mut args, "--hid-controller-rudp-advertise")?) } "--command-rudp-bind" => { - 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)" - )); + options.command_rudp_bind = Some( + take_value(&mut args, "--command-rudp-bind")? + .parse() + .context("--command-rudp-bind must be a socket address")?, + ) } "--command-rudp-advertise" => { options.command_rudp_advertise = @@ -9782,11 +11066,32 @@ 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) } } @@ -9804,6 +11109,14 @@ 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) @@ -9872,7 +11185,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 ] [--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." + "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." } fn parse_move_state_source(value: &str) -> Result { @@ -9895,7 +11208,6 @@ 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 { @@ -10341,20 +11653,39 @@ mod tests { } #[test] - 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}" - ); - } + 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")); } #[test] @@ -10442,6 +11773,67 @@ 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( @@ -10952,40 +12344,33 @@ 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 = 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(), + 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", }, &access_unit, - ); + ) + .unwrap(); assert_eq!(payloads.len(), 1); assert!( @@ -11007,24 +12392,27 @@ mod tests { access_unit.extend_from_slice(&[0, 0, 0, 1, 0x65]); access_unit.resize(MUNINN_RUDP_MEDIA_PACKET_BYTES * 64, 0x80); - 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(), + 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", }, &access_unit, - ); + ) + .unwrap(); assert!(payloads.len() > 1); let largest = payloads @@ -11042,8 +12430,7 @@ 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 policy = MediaSendPolicy::from_request(137); - let options = muninn_media_rudp_hub_options(socket, &profile, &policy); + let options = muninn_media_rudp_hub_options(socket, &profile); 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); @@ -11070,7 +12457,7 @@ mod tests { ); assert_eq!( channel("audio").reliable_expire_after_ms, - Some(policy.latency_budget_ms()), + Some(profile.receiver_assembly_deadline_ms), "audio older than the receiver's deadline is not worth a retransmit" ); } @@ -11105,8 +12492,59 @@ mod tests { assert_eq!(args.last().map(String::as_str), Some("pipe:1")); } - fn options_with_latency_budget(budget_ms: &str) -> Options { - Options::parse( + #[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( [ "activate", "--media-transport", @@ -11118,121 +12556,210 @@ mod tests { "--audio-sample-rate", "48000", "--rudp-latency-budget-ms", - budget_ms, + "2000", ] .into_iter() .map(String::from), ) - .unwrap() - } + .unwrap(); + let profile = muninn_rudp_media_profile_for_options(&options); - #[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_queue_deadline_ms, 2000); + assert_eq!(profile.sender_reliable_expire_after_ms, 2000); assert_eq!( - rudp_endpoint_for_options(&options_with_latency_budget("137")), + 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), "cultmesh://odin/media/muninn-raven-av#muninn.raven.av.rudp" ); } #[test] - 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 advertisement = media_stream_advertisement(&advertised, false).unwrap(); - assert_eq!(advertisement.default_latency_budget_ms, 250); + 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), + }; - 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); + 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 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)); + 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, + }; - // 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), + 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", + }, ) .unwrap(); - assert_eq!(options.rudp_latency_budget_ms, 2_000); + 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); - // Advertised. - let advertisement = media_stream_advertisement(&options, false).unwrap(); - assert_eq!(advertisement.default_latency_budget_ms, 2_000); + let repairs = + record_rudp_media_receiver_feedback(&frame, &mut stats, &repair_cache).unwrap(); - // 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) - ); + 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_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", + }) + .unwrap(); + + let mut cache = RecentVideoChunkRepairCache::new(16); + cache.remember(&payload).unwrap(); + let repairs = cache.repair_payloads_for_feedback(&feedback); + + assert_eq!(repairs, vec![payload]); } #[test] @@ -11248,6 +12775,42 @@ 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!( @@ -11287,6 +12850,115 @@ 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(); @@ -12211,64 +13883,6 @@ 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 = @@ -12284,6 +13898,12 @@ 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), @@ -12316,13 +13936,6 @@ 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") @@ -12413,20 +14026,10 @@ Device 00:07:04:A8:00:D0 (public) ); assert_eq!( media_profile - .get("latency_budget_ms") + .get("sender_reliable_expire_after_ms") .and_then(|value| value.as_u64()), - Some(MUNINN_RUDP_MEDIA_DEFAULT_LATENCY_BUDGET_MS) + Some(MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_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") @@ -12473,6 +14076,8 @@ 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", ] @@ -12491,6 +14096,21 @@ 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") @@ -12701,8 +14321,7 @@ Device 00:07:04:A8:00:D0 (public) hidraw_path: "windows-psmove://current".to_string(), }]; - publish_move_identity_records(&mut node, &options, ¤t).unwrap(); - prune_stale_move_identity_records(&mut node, &options, ¤t).unwrap(); + reconcile_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 3462d05..25449b9 100644 --- a/crates/muninn-daemon/src/media_packetizer.rs +++ b/crates/muninn-daemon/src/media_packetizer.rs @@ -1,8 +1,12 @@ use anyhow::{Context, Result, anyhow}; use cultnet_rs::{ - GameCultMediaAudioPacketRecord, GameCultMediaVideoAccessUnitRecord, - GameCultMediaVideoParityShardRecord, + CultNetMessage, CultNetWireContract, GAMECULT_MEDIA_AUDIO_PACKET_SCHEMA, + GameCultMediaAudioPacketRecord, + GameCultMediaReceiverFeedbackRecord, GameCultMediaVideoAccessUnitRecord, + GameCultMediaVideoParityShardRecord, decode_cultnet_message_from_slice, + encode_cultnet_message_to_vec, }; +use serde::{Serialize, de::DeserializeOwned}; use std::collections::BTreeMap; /// Re-exported so this module stays the one place Muninn's media code imports @@ -155,6 +159,26 @@ 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, @@ -190,6 +214,7 @@ pub struct AudioPacketWireOptions<'a> { pub source_role: &'a str, } + pub struct AudioPcmStreamSendConfig { pub stream_id: String, pub session_id: String, @@ -207,26 +232,23 @@ 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 { @@ -269,43 +291,26 @@ impl VideoAnnexBStreamSendState { next_pts_ticks: config.first_pts_ticks, config, pending: Vec::new(), - dropped_access_units: 0, - discarding_tail: false, }) } - /// 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> { + 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 { - self.pending.clear(); - if !self.discarding_tail { - self.dropped_access_units += 1; - self.advance_frame_clock()?; - self.discarding_tail = true; - } + return Err(anyhow!( + "Annex B stream sender pending buffer exceeded {} bytes without a complete frame", + self.config.max_pending_bytes + )); } - Ok(groups) + self.emit_available(stored_at, false) } - 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() } @@ -318,23 +323,10 @@ 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()); } @@ -358,7 +350,7 @@ impl VideoAnnexBStreamSendState { return Ok(Vec::new()); } - let mut groups = Vec::with_capacity(emit_count); + let mut send_payloads = Vec::new(); let mut emitted_bytes = 0_usize; for access_unit in access_units.iter().take(emit_count) { emitted_bytes = emitted_bytes @@ -384,7 +376,7 @@ impl VideoAnnexBStreamSendState { access_unit, )?; let wire_records = video_wire_records_with_parity(&records)?; - groups.push(wire_payloads_to_media_send(encode_media_wire_records( + send_payloads.extend(wire_payloads_to_media_send(encode_media_wire_records( &wire_records, stored_at, &self.config.source_runtime_id, @@ -394,49 +386,7 @@ impl VideoAnnexBStreamSendState { } self.pending.drain(..emitted_bytes); - 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) + Ok(send_payloads) } fn advance_frame_clock(&mut self) -> Result<()> { @@ -452,6 +402,8 @@ impl VideoAnnexBStreamSendState { } } + + pub struct AudioPcmStreamSendState { config: AudioPcmStreamSendConfig, pending: Vec, @@ -600,6 +552,9 @@ impl AudioPcmStreamSendState { } } + + + pub fn packetize_video_access_unit( options: VideoFramePacketizeOptions<'_>, access_unit: &VideoAccessUnit, @@ -769,19 +724,86 @@ pub fn build_video_parity_shards( } fn video_wire_records_with_parity( - frame_records: &[GameCultMediaVideoAccessUnitRecord], + records: &[GameCultMediaVideoAccessUnitRecord], ) -> Result> { - 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)); + 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; } 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], @@ -822,6 +844,145 @@ 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. @@ -853,6 +1014,27 @@ 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], @@ -894,6 +1076,27 @@ 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"), @@ -903,6 +1106,8 @@ fn normalized_video_codec(codec: &str) -> Option<&'static str> { } } + + fn annex_b_nal_units<'a>( input: &'a [u8], codec_name: &str, @@ -1087,11 +1292,7 @@ impl<'a> BitReader<'a> { #[cfg(test)] mod tests { use super::*; - 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, - }; + use cultnet_rs::{ReceiverFeedbackOptions, VideoChunkKey, build_receiver_feedback}; fn start_code() -> [u8; 4] { [0, 0, 0, 1] @@ -1329,6 +1530,101 @@ 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 { @@ -1503,6 +1799,123 @@ 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 { @@ -1576,6 +1989,129 @@ 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(), @@ -1594,109 +2130,6 @@ 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<()> { @@ -1717,10 +2150,9 @@ 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].len(), 1); - assert_eq!(second_push[0][0].channel_id, MUNINN_MEDIA_RUDP_CHANNEL); + assert_eq!(second_push[0].channel_id, MUNINN_MEDIA_RUDP_CHANNEL); let GameCultMediaWireRecord::Video(first) = - decode_media_wire_record(&second_push[0][0].payload)? + decode_media_wire_record(&second_push[0].payload)? else { panic!("expected video media record"); }; @@ -1733,8 +2165,7 @@ mod tests { let tail = sender.finish("2026-06-18T00:00:00Z")?; assert_eq!(tail.len(), 1); - assert_eq!(tail[0].len(), 1); - let GameCultMediaWireRecord::Video(second) = decode_media_wire_record(&tail[0][0].payload)? + let GameCultMediaWireRecord::Video(second) = decode_media_wire_record(&tail[0].payload)? else { panic!("expected video media record"); }; @@ -1763,207 +2194,27 @@ 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 an_overflow_drop_consumes_its_frame_id_and_discards_the_leftover_slices() -> Result<()> { + fn annex_b_stream_send_state_rejects_unbounded_pending_bytes() -> Result<()> { let mut config = stream_send_config(); - config.max_pending_bytes = 16; - config.max_payload_bytes = 64; + config.max_pending_bytes = 4; 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() - }; - // 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"); + let error = sender + .push("2026-06-18T00:00:00Z", &[0x47, 0x40, 0x00, 0x10, 0x00]) + .unwrap_err(); - // 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!( + error + .to_string() + .contains("pending buffer exceeded 4 bytes") ); - 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<()> { @@ -2213,6 +2464,43 @@ 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 deleted file mode 100644 index 08ff860..0000000 --- a/crates/muninn-daemon/src/media_send.rs +++ /dev/null @@ -1,1085 +0,0 @@ -//! 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 deleted file mode 100644 index 873afd2..0000000 --- a/crates/muninn-daemon/src/media_send/tests.rs +++ /dev/null @@ -1,1523 +0,0 @@ -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 deleted file mode 100644 index 860d9e0..0000000 Binary files a/crates/muninn-daemon/testdata/clip.h264 and /dev/null differ diff --git a/crates/muninn-daemon/testdata/clip.h264.provenance.txt b/crates/muninn-daemon/testdata/clip.h264.provenance.txt deleted file mode 100644 index 3c0029b..0000000 --- a/crates/muninn-daemon/testdata/clip.h264.provenance.txt +++ /dev/null @@ -1,7 +0,0 @@ -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 deleted file mode 100644 index 09e4533..0000000 --- a/crates/sleipnir-daemon/Cargo.toml +++ /dev/null @@ -1,23 +0,0 @@ -[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 deleted file mode 100644 index 43675ce..0000000 --- a/crates/sleipnir-daemon/src/main.rs +++ /dev/null @@ -1,3112 +0,0 @@ -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 e5689c6..d3105ff 100644 --- a/docs/muninn-media-streaming.md +++ b/docs/muninn-media-streaming.md @@ -237,10 +237,9 @@ a temporary PCM/AAC compatibility bridge. Recommended first LAN profile: - Profile id: `muninn.rudp.low_latency_h264_lan.v1`. -- Video: H.264 NVENC, `p5` (`main.rs:9504`), ultra-low-latency tune, CBR high enough that LAN +- Video: H.264 NVENC, `p1`, ultra-low-latency tune, CBR high enough that LAN bandwidth is not the constraint, no B-frames, no lookahead, short GOP or - intra-refresh, keyframe actuation on feedback pressure (not built: keyframe requests are only - counted and logged today; Cut 6 builds it). + intra-refresh, periodic IDR/keyframe on feedback pressure. - 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. @@ -248,7 +247,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 `848` bytes (`main.rs:81`). That leaves headroom +- Packet size: default typed media chunks are `480` bytes. 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` @@ -256,9 +255,8 @@ 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 `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. +- Resend cadence: sender RUDP media resends are scheduled every `5` ms while + the packet is still inside the `75` ms reliable-expiry budget. - 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 b262640..6b7df20 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 +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 --health --store C:\Meta\Odin\state\muninn.telemetry.cc ``` @@ -97,7 +97,10 @@ 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`. +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`. 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 @@ -189,7 +192,11 @@ 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. -`--health` reads the telemetry store and reports; it publishes nothing. +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. 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. @@ -228,6 +235,10 @@ 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 @@ -237,12 +248,10 @@ 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. - -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. +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. 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 deleted file mode 100644 index 04ba0d6..0000000 --- a/docs/realtime-robustness-cut.md +++ /dev/null @@ -1,2145 +0,0 @@ -# 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 deleted file mode 100644 index 8f4085a..0000000 --- a/docs/streaming-deprecation.md +++ /dev/null @@ -1,37 +0,0 @@ -# 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 b77d53a..6890d45 100644 --- a/docs/teardown-map.md +++ b/docs/teardown-map.md @@ -1,6 +1,6 @@ -# Muninn Teardown Map (history of the extraction) +# Muninn Teardown Map (pre-rebuild) -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/`. +Date: 2026-09-09. Working map for extracting Muninn from Odin into a dedicated repo. ## 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 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`). +CultLib pin: `c13b6ba0` (2026-09-05), 3 commits behind CultLib HEAD `d1a9edad`. ## 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, 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. +19 `muninn.*` schemas, 38 declarations, currently in `odin-core/src/documents.rs`. 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) at the time of writing; 21 at `e70db69` (`main.rs:27-37`). +Muninn -> odin-core: ONE import block, 20 symbols (main.rs). 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 (forge mirror `GameCult/Ratatoskr-receiver`; the forge `GameCult/Ratatoskr` is the unrelated chat client) — the receiving end, extracted from the +https://github.com/GameCult/Ratatoskr — 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` at the time of writing; now `c2a9a6e` (Ratatoskr `crates/ratatoskr-core/Cargo.toml:16-18`). +the header's claims, rather than assuming them). Pinned to CultLib `d1a9eda`. ### The next blocking piece @@ -460,9 +460,8 @@ 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 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 +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 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. @@ -609,24 +608,22 @@ Three repos where there was one crate, and a contract neither of them owns. | Repo | Role | State | |---|---|---| -| CultLib `main` `05e0925` at the time of writing (media contract unchanged since `c2a9a6e`) | the contract | media records, wire envelope, validation, channel delivery | +| CultLib `main` `05e0925` | 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 (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. +### The one thing blocking a clean Muninn build `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 used 23 odin-core symbols (21 at `e70db69`), and while 16 are +Muninn cannot resolve this alone: it uses 23 odin-core symbols, 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 were genuinely Odin's — `discover_provider_endpoints`, +surface, transport profile), 7 are genuinely Odin's — `discover_provider_endpoints`, `OdinDocuments`, `OdinEndpointQuery`, Eve advertisement and surface records, -`IdunnDaemonHealthRecord`. At `e70db69` four remain imported: `EveProviderAdvertisementRecord`, `EveSurfaceStateRecord`, `IdunnDaemonHealthRecord`, `OdinDocuments`. +`IdunnDaemonHealthRecord`. 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 @@ -656,8 +653,10 @@ 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). 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. + 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. 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). @@ -665,10 +664,8 @@ 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. 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. + request is the alternative to one, and the sender turns every new keyframe + request into an IDR. ### Deliberate breaks, both recorded as passing tests @@ -701,7 +698,8 @@ 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`. 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. +`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. diff --git a/scripts/health-muninn.cmd b/scripts/health-muninn.cmd index e2ddbe7..7811b7d 100644 --- a/scripts/health-muninn.cmd +++ b/scripts/health-muninn.cmd @@ -1,3 +1,3 @@ @echo off -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. +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. exit /b 2 diff --git a/scripts/health-muninn.ps1 b/scripts/health-muninn.ps1 index 407b89e..f783148 100644 --- a/scripts/health-muninn.ps1 +++ b/scripts/health-muninn.ps1 @@ -5,6 +5,7 @@ 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 = "" @@ -12,6 +13,10 @@ 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, @@ -172,7 +177,10 @@ if (`$null -eq `$process) { } foreach (`$pattern in @( "--host raven", - "--activate-store $ActivateStorePath" + "--activate-store $ActivateStorePath", + "--idunn-rudp-health $IdunnRudpHealth", + "--idunn-daemon muninn", + "--idunn-health-contract muninn.cultnet-rudp-remote-telemetry-health" )) { 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 eede45d..6b6554b 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 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. +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. exit /b 2 diff --git a/scripts/health-nightwing-muninn.ps1 b/scripts/health-nightwing-muninn.ps1 index d6319cd..ce2ce79 100644 --- a/scripts/health-nightwing-muninn.ps1 +++ b/scripts/health-nightwing-muninn.ps1 @@ -5,11 +5,16 @@ param( [string] $PidPath = "/home/metacrat/.local/state/gamecult/muninn/muninn.pid", [string[]] $MoveState = @(), [int] $IntervalSeconds = 15, - [int] $MaxStoreAgeSeconds = 180 + [int] $MaxStoreAgeSeconds = 180, + [string] $IdunnRudpHealth = $env:IDUNN_RUDP_HEALTH ) $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, @@ -71,6 +76,16 @@ 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 db26de6..36d421c 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 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. +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. exit /b 2 diff --git a/scripts/health-starfire-muninn.ps1 b/scripts/health-starfire-muninn.ps1 index d5be3ec..c331145 100644 --- a/scripts/health-starfire-muninn.ps1 +++ b/scripts/health-starfire-muninn.ps1 @@ -3,11 +3,16 @@ param( [string] $StorePath = "C:\Meta\Odin\state\starfire.muninn.telemetry.cc", [string] $LogRoot = "C:\Meta\Odin\logs\starfire-muninn", [string[]] $MoveState = @(), - [int] $MaxStoreAgeSeconds = 180 + [int] $MaxStoreAgeSeconds = 180, + [string] $IdunnRudpHealth = $env:IDUNN_RUDP_HEALTH ) $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" } @@ -23,6 +28,15 @@ $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 58fa1b1..9f92fa4 100644 --- a/scripts/restart-nightwing-muninn.ps1 +++ b/scripts/restart-nightwing-muninn.ps1 @@ -17,10 +17,14 @@ 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" ) @@ -30,6 +34,12 @@ 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." } @@ -125,7 +135,7 @@ if (-not [string]::IsNullOrWhiteSpace($HidControllerRudpAdvertise)) { $hidControllerRudpSetLines += "set -- ""`$@"" --hid-controller-rudp-advertise $(Quote-ShSingle $HidControllerRudpAdvertise)" } $hidControllerRudpSetBlock = ($hidControllerRudpSetLines -join "`n") -$commandRudpSetBlock = "set -- ""`$@"" --command-rudp-advertise $(Quote-ShSingle $CommandRudpAdvertise)" +$commandRudpSetBlock = "set -- ""`$@"" --command-rudp-bind $(Quote-ShSingle $CommandRudpBind) --command-rudp-advertise $(Quote-ShSingle $CommandRudpAdvertise)" $remoteScript = @" set -eu mkdir -p '$LogRoot' @@ -152,7 +162,10 @@ set -- serve \ --host nightwing $moveRuntimeSetBlock set -- "`$@" \ - --interval-seconds '$IntervalSeconds' + --interval-seconds '$IntervalSeconds' \ + --idunn-rudp-health '$IdunnRudpHealth' \ + --idunn-daemon '$IdunnDaemon' \ + --idunn-health-contract '$IdunnHealthContract' $odinCultMeshUriSetBlock $hidControllerRudpSetBlock $commandRudpSetBlock @@ -166,9 +179,10 @@ 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 dual-camera arguments' >&2 + echo 'Nightwing Muninn serve command line is missing Idunn health or dual-camera arguments' >&2 exit 1 fi "@ diff --git a/scripts/restart-starfire-muninn.ps1 b/scripts/restart-starfire-muninn.ps1 index 69af854..70b79f6 100644 --- a/scripts/restart-starfire-muninn.ps1 +++ b/scripts/restart-starfire-muninn.ps1 @@ -6,6 +6,9 @@ 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 = "", @@ -26,6 +29,9 @@ 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." } @@ -57,7 +63,10 @@ $arguments = @( "--host", "starfire", "--interval-seconds", "15", "--quest-adb", - "--quest-serial", $QuestSerial + "--quest-serial", $QuestSerial, + "--idunn-rudp-health", $IdunnRudpHealth, + "--idunn-daemon", $IdunnDaemon, + "--idunn-health-contract", $IdunnHealthContract ) if (-not [string]::IsNullOrWhiteSpace($OdinCultMeshUri)) { $arguments += @("--odin-cultmesh-uri", $OdinCultMeshUri) @@ -151,3 +160,15 @@ 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)" + } +}