From 73551e6f47e36aba6d301a2091fbf8847b2fa116 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Thu, 16 Jul 2026 20:29:46 +0100 Subject: [PATCH] Harden Muninn and Sleipnir realtime delivery --- crates/muninn-daemon/src/main.rs | 330 +++++- crates/muninn-daemon/src/media_packetizer.rs | 76 +- crates/sleipnir-daemon/src/main.rs | 169 ++- docs/realtime-delivery-authority.md | 105 ++ vendor/CULTLIB_SNAPSHOT.md | 27 + vendor/cultcache-rs/README.md | 8 +- vendor/cultcache-rs/src/lib.rs | 214 +++- vendor/cultmesh-rs/src/lib.rs | 5 +- vendor/cultnet-rs/README.md | 231 +++- .../cultnet.shard-catalog-request.schema.json | 19 + ...cultnet.shard-catalog-response.schema.json | 47 + .../cultnet.transport-profile.schema.json | 19 + .../examples/cultnet_interop_peer.rs | 978 ++++++++++++--- vendor/cultnet-rs/src/contracts.rs | 186 ++- vendor/cultnet-rs/src/cultmesh.rs | 525 ++++++++ vendor/cultnet-rs/src/lib.rs | 6 + vendor/cultnet-rs/src/operation_service.rs | 60 + vendor/cultnet-rs/src/replication.rs | 574 +++++++++ vendor/cultnet-rs/src/rudp.rs | 519 ++++---- vendor/cultnet-rs/src/schema_discovery.rs | 14 + vendor/cultnet-rs/src/shard_catalog.rs | 134 +++ vendor/cultnet-rs/src/transport.rs | 108 +- vendor/cultnet-rs/tests/cultnet.rs | 1051 ++++++++++++++--- 23 files changed, 4650 insertions(+), 755 deletions(-) create mode 100644 docs/realtime-delivery-authority.md create mode 100644 vendor/CULTLIB_SNAPSHOT.md create mode 100644 vendor/cultnet-rs/contracts/cultnet.shard-catalog-request.schema.json create mode 100644 vendor/cultnet-rs/contracts/cultnet.shard-catalog-response.schema.json create mode 100644 vendor/cultnet-rs/src/cultmesh.rs create mode 100644 vendor/cultnet-rs/src/operation_service.rs create mode 100644 vendor/cultnet-rs/src/shard_catalog.rs diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index ac29ce7..e687544 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -80,7 +80,10 @@ const MUNINN_RUDP_MEDIA_MAX_FRAGMENT_BYTES: usize = MUNINN_RUDP_IPV4_UDP_PAYLOAD - MUNINN_RUDP_FIXED_HEADER_BYTES - crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL.len(); const MUNINN_RUDP_MEDIA_RESEND_DELAY_MS: u64 = 5; -const MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS: u64 = 2_000; +const MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS: u64 = 100; +const MUNINN_RUDP_MEDIA_PAYLOAD_CHANNEL_CAPACITY: usize = 512; +const MUNINN_RUDP_MEDIA_PENDING_AUDIO_CAPACITY: usize = 256; +const MUNINN_RUDP_MEDIA_PENDING_VIDEO_CAPACITY: usize = 512; 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; @@ -259,7 +262,7 @@ struct MuninnRudpMediaProfile { video_rc_lookahead: u8, sender_queue_deadline_ms: u64, sender_resend_delay_ms: u64, - sender_reliable_expire_after_ms: u64, + sender_delivery_deadline_ms: u64, sender_pace_every_payloads: usize, sender_pace_sleep_us: u64, receiver_assembly_deadline_ms: u64, @@ -687,7 +690,7 @@ fn run_provider_command_ingress( 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 { @@ -1946,7 +1949,10 @@ fn run_rudp_mux_once( )?; let mut last_stream_publish_at = Instant::now(); - let (payload_tx, payload_rx) = mpsc::channel::>(); + let (payload_tx, payload_rx) = + mpsc::sync_channel::>( + MUNINN_RUDP_MEDIA_PAYLOAD_CHANNEL_CAPACITY, + ); video_sender = if let Some(stdout) = video_ffmpeg_stdout { Some(video_rudp_payload_reader( payload_tx.clone(), @@ -2105,7 +2111,11 @@ fn run_rudp_mux_once( } let payloads_dropped = payloads_queue_expired + payloads_send_expired; if queued.kind == QueuedMuninnMediaKind::Video { - repair_cache.remember(&queued.payload)?; + repair_cache.remember( + &queued.payload, + Instant::now(), + Duration::from_millis(media_profile.sender_queue_deadline_ms), + )?; } poll_rudp_media_receiver_feedback( &mut video_transport, @@ -2254,8 +2264,18 @@ struct PendingMuninnMediaSendQueues { 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), + QueuedMuninnMediaKind::Audio => { + while self.audio.len() >= MUNINN_RUDP_MEDIA_PENDING_AUDIO_CAPACITY { + self.audio.pop_front(); + } + self.audio.push_back(payload); + } + QueuedMuninnMediaKind::Video => { + while self.video.len() >= MUNINN_RUDP_MEDIA_PENDING_VIDEO_CAPACITY { + self.video.pop_front(); + } + self.video.push_back(payload); + } } } @@ -2378,7 +2398,13 @@ impl MuninnRudpRepairBudget { struct RecentVideoChunkRepairCache { max_entries: usize, order: VecDeque, - entries: HashMap, + entries: HashMap, +} + +#[derive(Debug)] +struct CachedVideoRepair { + payload: MuninnMediaSendPayload, + expires_at: Instant, } impl RecentVideoChunkRepairCache { @@ -2390,16 +2416,25 @@ impl RecentVideoChunkRepairCache { } } - fn remember(&mut self, payload: &MuninnMediaSendPayload) -> Result<()> { + fn remember( + &mut self, + payload: &MuninnMediaSendPayload, + now: Instant, + lifetime: Duration, + ) -> Result<()> { let Some(key) = video_repair_cache_key_from_payload(payload)? else { return Ok(()); }; + let cached = CachedVideoRepair { + payload: payload.clone(), + expires_at: now + lifetime, + }; if self.entries.contains_key(&key) { - self.entries.insert(key, payload.clone()); + self.entries.insert(key, cached); return Ok(()); } self.order.push_back(key.clone()); - self.entries.insert(key, payload.clone()); + self.entries.insert(key, cached); while self.entries.len() > self.max_entries { let Some(expired) = self.order.pop_front() else { break; @@ -2412,10 +2447,17 @@ impl RecentVideoChunkRepairCache { fn repair_payloads_for_feedback( &self, feedback: &MuninnMediaReceiverFeedbackRecord, + now: Instant, ) -> Vec { feedback .missing_video_chunk_keys .iter() + .filter(|chunk_key| { + chunk_key + .split_once(':') + .and_then(|(frame_id, _)| frame_id.parse::().ok()) + .is_none_or(|frame_id| !feedback.late_frame_ids.contains(&frame_id)) + }) .filter_map(|chunk_key| { self.entries .get(&video_repair_cache_key( @@ -2423,7 +2465,8 @@ impl RecentVideoChunkRepairCache { &feedback.session_id, chunk_key, )) - .cloned() + .filter(|cached| cached.expires_at > now) + .map(|cached| cached.payload.clone()) }) .collect() } @@ -2448,7 +2491,7 @@ fn video_repair_cache_key_from_payload(payload: &MuninnMediaSendPayload) -> Resu } fn queue_muninn_media_payload( - tx: &mpsc::Sender>, + tx: &mpsc::SyncSender>, payload: MuninnMediaSendPayload, kind: QueuedMuninnMediaKind, ) -> Result<()> { @@ -2671,7 +2714,7 @@ fn record_rudp_media_receiver_feedback( return Ok(Vec::new()); }; - let repair_payloads = repair_cache.repair_payloads_for_feedback(&feedback); + let repair_payloads = repair_cache.repair_payloads_for_feedback(&feedback, Instant::now()); stats.feedback_records = stats.feedback_records.saturating_add(1); if feedback.requested_keyframe { stats.requested_keyframes = stats.requested_keyframes.saturating_add(1); @@ -2820,13 +2863,12 @@ fn muninn_media_rudp_options( endpoint: SocketAddr, media_profile: &MuninnRudpMediaProfile, connection_id: u32, - reliable_expire_after_ms: Option, + _reliable_expire_after_ms: Option, ) -> CultNetRudpSocketTransportOptions { let mut options = CultNetRudpSocketTransportOptions::client("muninn-media", socket, endpoint, 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_reliable_expire_after_ms = reliable_expire_after_ms; options } @@ -2834,14 +2876,12 @@ fn reliable_packets_expired( video_transport: &CultNetRudpSocketTransportConnection, audio_transport: &CultNetRudpSocketTransportConnection, ) -> u64 { - video_transport - .stats() - .reliable_packets_expired - .saturating_add(audio_transport.stats().reliable_packets_expired) + let _ = (video_transport, audio_transport); + 0 } fn video_rudp_payload_reader( - tx: mpsc::Sender>, + tx: mpsc::SyncSender>, mut reader: R, config: VideoAnnexBStreamSendConfig, ) -> thread::JoinHandle<()> @@ -2856,7 +2896,7 @@ where } fn audio_rudp_payload_reader( - tx: mpsc::Sender>, + tx: mpsc::SyncSender>, mut reader: R, config: AudioPcmStreamSendConfig, ) -> thread::JoinHandle<()> @@ -2871,7 +2911,7 @@ where } fn read_video_rudp_payloads( - tx: &mpsc::Sender>, + tx: &mpsc::SyncSender>, reader: &mut R, config: VideoAnnexBStreamSendConfig, ) -> Result<()> @@ -2899,7 +2939,7 @@ where } fn read_audio_rudp_payloads( - tx: &mpsc::Sender>, + tx: &mpsc::SyncSender>, reader: &mut R, config: AudioPcmStreamSendConfig, ) -> Result<()> @@ -3438,7 +3478,7 @@ fn publish_runtime_boundary_records( "video_rc_lookahead": media_profile.video_rc_lookahead, "sender_queue_deadline_ms": media_profile.sender_queue_deadline_ms, "sender_resend_delay_ms": media_profile.sender_resend_delay_ms, - "sender_reliable_expire_after_ms": media_profile.sender_reliable_expire_after_ms, + "sender_delivery_deadline_ms": media_profile.sender_delivery_deadline_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", @@ -5364,7 +5404,12 @@ struct ActiveHidControllerStream { struct ActiveHidControllerRudpSource { source: MoveStateSource, + epoch: u64, sequence: u64, + next_edge_sequence: u64, + pending_edges: VecDeque, + edge_buttons: Vec, + last_edge_send_at: Option, joystick_axes: [i16; 16], joystick_buttons: [bool; 32], latest_report: Option, @@ -5377,11 +5422,17 @@ struct ActiveHidControllerRudpSource { } fn active_hid_controller_rudp_source(source: MoveStateSource) -> ActiveHidControllerRudpSource { + let epoch = timestamp_ns().unwrap_or_default().max(0) as u64; ActiveHidControllerRudpSource { #[cfg(windows)] report_rx: start_windows_hid_report_reader_if_supported(&source.hidraw_path), source, + epoch, sequence: 0, + next_edge_sequence: 1, + pending_edges: VecDeque::new(), + edge_buttons: Vec::new(), + last_edge_send_at: None, joystick_axes: [0; 16], joystick_buttons: [false; 32], latest_report: None, @@ -5392,6 +5443,42 @@ fn active_hid_controller_rudp_source(source: MoveStateSource) -> ActiveHidContro } } +#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)] +struct HidButtonEdge { + epoch: u64, + device_id: String, + edge_sequence: u64, + button: String, + pressed: bool, +} + +#[derive(Clone, Debug, Serialize, Deserialize)] +struct HidLatestStateFrame { + epoch: u64, + state_sequence: u64, + record: MuninnHidControllerStateRecord, +} + +#[derive(Clone, Debug, Deserialize)] +struct HidEdgeAck { + epoch: u64, + device_id: String, + edge_sequence: u64, +} + +fn capture_button_edges(active: &mut ActiveHidControllerRudpSource, buttons: &[String]) { + let previous = active.edge_buttons.clone(); + for button in previous.iter().filter(|button| !buttons.contains(button)) { + active.pending_edges.push_back(HidButtonEdge { epoch: active.epoch.clone(), device_id: active.source.move_id.clone(), edge_sequence: active.next_edge_sequence, button: button.clone(), pressed: false }); + active.next_edge_sequence = active.next_edge_sequence.saturating_add(1); + } + for button in buttons.iter().filter(|button| !previous.contains(button)) { + active.pending_edges.push_back(HidButtonEdge { epoch: active.epoch.clone(), device_id: active.source.move_id.clone(), edge_sequence: active.next_edge_sequence, button: button.clone(), pressed: true }); + active.next_edge_sequence = active.next_edge_sequence.saturating_add(1); + } + active.edge_buttons = buttons.to_vec(); +} + fn sync_hid_controller_rudp_sources( active: &mut Vec, desired: Vec, @@ -5474,7 +5561,7 @@ fn run_hid_controller_rudp_ingress( max_payload_bytes: None, max_fragment_bytes: Some(HID_CONTROLLER_RUDP_MAX_FRAGMENT_BYTES), max_pending_reliable_packets: Some(256), - media_reliable_expire_after_ms: Some(25), + reconnect_policy: None, })?; let mut sources = live_move_state_sources(&options) .into_iter() @@ -5522,6 +5609,15 @@ fn run_hid_controller_rudp_ingress( } } } + Ok(Some(frame)) if frame.channel_id == "hid.edge.ack" => { + if let Ok(ack) = serde_json::from_slice::(&frame.payload) { + if let Some(source) = sources.iter_mut().find(|source| source.source.move_id == ack.device_id && source.epoch == ack.epoch) { + while source.pending_edges.front().is_some_and(|edge| edge.edge_sequence <= ack.edge_sequence) { + source.pending_edges.pop_front(); + } + } + } + } Ok(Some(_)) => {} Ok(None) => break, Err(error) => { @@ -5574,12 +5670,21 @@ fn run_hid_controller_rudp_ingress( continue; } if transport.connected() { - let payload = serde_json::to_vec(&sanitize_hid_controller_record(record.clone())) + let payload = serde_json::to_vec(&HidLatestStateFrame { epoch: source.epoch.clone(), state_sequence: record.sequence, record: sanitize_hid_controller_record(record.clone()) }) .context("encoding Muninn HID controller stream record")?; if let Err(error) = transport.send("latest", payload) { eprintln!("Muninn HID controller RUDP send warning: {error:#}"); break; } + if source.last_edge_send_at.is_none_or(|sent| sent.elapsed() >= Duration::from_millis(15)) { + if let Some(edge) = source.pending_edges.front() { + if let Err(error) = transport.send("hid.edge", serde_json::to_vec(edge)?) { + eprintln!("Muninn HID edge send warning: {error:#}"); + } else { + source.last_edge_send_at = Some(Instant::now()); + } + } + } sent_frames = sent_frames.saturating_add(1); last_sent_at = Some(Instant::now()); last_stale_log_at = None; @@ -5651,7 +5756,7 @@ fn read_hid_controller_state_for_stream( active: &mut ActiveHidControllerRudpSource, reader: &mut impl MoveControllerStateReader, ) -> Option { - let source = &active.source; + let source = active.source.clone(); if is_joystick_path(&source.hidraw_path) { let events = match reader.read_joystick_events(&source.hidraw_path) { Ok(events) => { @@ -5678,6 +5783,8 @@ fn read_hid_controller_state_for_stream( if let Some(button) = active.joystick_buttons.get_mut(event.number as usize) { *button = event.value != 0; } + let buttons = joystick_button_names(active.joystick_buttons); + capture_button_edges(active, &buttons); } 0x02 => { if let Some(axis) = active.joystick_axes.get_mut(event.number as usize) { @@ -5689,7 +5796,7 @@ fn read_hid_controller_state_for_stream( } let record = build_hid_controller_state_record_from_joystick( options, - source, + &source, active.sequence.saturating_add(1), active.joystick_axes, active.joystick_buttons, @@ -5703,14 +5810,20 @@ fn read_hid_controller_state_for_stream( if let Some(rx) = active.report_rx.as_ref() { let mut saw_report = false; let mut drained_reports = 0usize; + let mut reports = Vec::new(); for _ in 0..HID_CONTROLLER_RUDP_MAX_REPORT_DRAIN { let Ok(report) = rx.try_recv() else { break; }; - active.latest_report = Some(report); + reports.push(report); saw_report = true; drained_reports += 1; } + for report in reports { + let buttons = hid_controller_button_names(&active.source, &report.bytes); + capture_button_edges(active, &buttons); + active.latest_report = Some(report); + } if drained_reports == HID_CONTROLLER_RUDP_MAX_REPORT_DRAIN { eprintln!( "Muninn Windows HID reader drained {drained_reports} queued reports for {}; keeping latest", @@ -5726,7 +5839,7 @@ fn read_hid_controller_state_for_stream( let report = active.latest_report.as_ref()?; let record = build_hid_controller_state_record_from_report( options, - source, + &source, active.sequence.saturating_add(1), &report.bytes, report.source_timestamp_ns, @@ -5756,7 +5869,7 @@ fn read_hid_controller_state_for_stream( }; let record = build_hid_controller_state_record_from_report( options, - source, + &source, active.sequence.saturating_add(1), &report, timestamp_ns().ok()?, @@ -5790,7 +5903,7 @@ fn read_hid_controller_state_for_stream( }; let record = build_hid_controller_state_record_from_xinput_gamepad( options, - source, + &source, active.sequence.saturating_add(1), &gamepad, timestamp_ns().ok()?, @@ -5803,6 +5916,7 @@ fn emit_hid_controller_record_if_due( active: &mut ActiveHidControllerRudpSource, mut record: MuninnHidControllerStateRecord, ) -> Option { + capture_button_edges(active, &record.buttons); let axes_changed = active .last_emitted_axes .as_ref() @@ -6018,7 +6132,7 @@ fn create_hid_controller_stream(options: &Options) -> Result>(); + assert_eq!(edges.len(), 2); + assert_eq!((edges[0].button.as_str(), edges[0].pressed, edges[0].edge_sequence), ("a", true, 1)); + assert_eq!((edges[1].button.as_str(), edges[1].pressed, edges[1].edge_sequence), ("a", false, 2)); + assert_eq!(edges[0].epoch, edges[1].epoch); + } + #[test] fn active_move_state_sync_replaces_stale_hotplug_identity() { let mut active = active_move_state_sources(vec![MoveStateSource { diff --git a/crates/muninn-daemon/src/media_packetizer.rs b/crates/muninn-daemon/src/media_packetizer.rs index 3d6b364..c46e1d0 100644 --- a/crates/muninn-daemon/src/media_packetizer.rs +++ b/crates/muninn-daemon/src/media_packetizer.rs @@ -12,7 +12,10 @@ use odin_core::{ use serde::{Serialize, de::DeserializeOwned}; use std::collections::BTreeMap; -pub const MUNINN_MEDIA_RUDP_CHANNEL: &str = "media"; +// Deadline-bound audio/video must use the experimental CultNet realtime lane. +// The `media` lane is reliable without expiry and can accumulate corpses behind +// loss; application-level parity/repair and playout deadlines own recovery. +pub const MUNINN_MEDIA_RUDP_CHANNEL: &str = "realtime"; #[derive(Clone, Debug, PartialEq, Eq)] pub struct VideoAccessUnit { @@ -817,6 +820,7 @@ pub struct ExpiredVideoFrame { pub key: VideoFrameKey, pub deadline_ticks: i64, pub missing_video_chunk_keys: Vec, + pub decode_chain_invalidated: bool, } #[derive(Clone, Debug)] @@ -888,6 +892,13 @@ impl VideoFrameAssembly { .unwrap_or_default() } + pub fn invalidates_decode_chain(&self) -> bool { + self.chunks + .values() + .next() + .is_some_and(|chunk| chunk.keyframe || chunk.dependency_frame_id.is_some()) + } + pub fn reassemble(&self) -> Result { let chunks = self.chunks.values().cloned().collect::>(); reassemble_video_access_unit(&chunks) @@ -1014,6 +1025,7 @@ impl VideoFrameAssemblySet { key, deadline_ticks: assembly.deadline_ticks(), missing_video_chunk_keys: assembly.missing_video_chunk_keys(), + decode_chain_invalidated: assembly.invalidates_decode_chain(), }) }) .collect() @@ -1573,10 +1585,6 @@ pub fn build_receiver_feedback( late_frame_ids.sort_unstable(); late_frame_ids.dedup(); - let requested_keyframe = options.requested_keyframe - || !missing_frame_ids.is_empty() - || !missing_video_chunk_keys.is_empty(); - Ok(MuninnMediaReceiverFeedbackRecord { stream_id: options.stream_id.to_string(), session_id: options.session_id.to_string(), @@ -1584,7 +1592,7 @@ pub fn build_receiver_feedback( highest_decodable_frame_id: options.highest_decodable_frame_id, missing_frame_ids, late_frame_ids, - requested_keyframe, + requested_keyframe: options.requested_keyframe, jitter_us: options.jitter_us, decode_queue_us: options.decode_queue_us, observed_at: options.observed_at.to_string(), @@ -1602,6 +1610,7 @@ pub fn build_feedback_for_expired_video_frames( let mut late_frame_ids = Vec::with_capacity(expired.len()); let mut missing_video_chunk_keys = Vec::new(); + let mut decode_chain_invalidated = false; for frame in expired { if frame.key.stream_id != first.key.stream_id || frame.key.session_id != first.key.session_id @@ -1612,6 +1621,7 @@ pub fn build_feedback_for_expired_video_frames( } late_frame_ids.push(frame.key.frame_id); missing_video_chunk_keys.extend(frame.missing_video_chunk_keys.iter().cloned()); + decode_chain_invalidated |= frame.decode_chain_invalidated; } build_receiver_feedback(ReceiverFeedbackOptions { @@ -1622,7 +1632,7 @@ pub fn build_feedback_for_expired_video_frames( missing_frame_ids: Vec::new(), missing_video_chunk_keys, late_frame_ids, - requested_keyframe: true, + requested_keyframe: decode_chain_invalidated, jitter_us: options.jitter_us, decode_queue_us: options.decode_queue_us, observed_at: options.observed_at, @@ -3056,7 +3066,7 @@ mod tests { } #[test] - fn builds_receiver_feedback_with_sorted_unique_damage_lists() -> Result<()> { + fn recoverable_receiver_damage_does_not_request_keyframe() -> Result<()> { let feedback = build_receiver_feedback(ReceiverFeedbackOptions { stream_id: "muninn.raven.av.rudp", session_id: "session-1", @@ -3078,6 +3088,26 @@ mod tests { assert_eq!(feedback.missing_frame_ids, vec![42, 43]); assert_eq!(feedback.missing_video_chunk_keys, vec!["42:1", "43:2"]); assert_eq!(feedback.late_frame_ids, vec![38, 39]); + assert!(!feedback.requested_keyframe); + Ok(()) + } + + #[test] + fn explicit_decode_chain_invalidation_requests_keyframe() -> Result<()> { + let feedback = build_receiver_feedback(ReceiverFeedbackOptions { + stream_id: "muninn.raven.av.rudp", + session_id: "session-1", + receiver_id: "starfire.obs", + highest_decodable_frame_id: Some(40), + missing_frame_ids: vec![41], + missing_video_chunk_keys: Vec::new(), + late_frame_ids: vec![41], + requested_keyframe: true, + jitter_us: 700, + decode_queue_us: 2_000, + observed_at: "2026-06-18T00:00:00Z", + })?; + assert!(feedback.requested_keyframe); Ok(()) } @@ -3368,6 +3398,7 @@ mod tests { }, deadline_ticks: 28_800, missing_video_chunk_keys: vec![video_chunk_feedback_key(9, 1)], + decode_chain_invalidated: true, }, ExpiredVideoFrame { key: VideoFrameKey { @@ -3377,6 +3408,7 @@ mod tests { }, deadline_ticks: 31_800, missing_video_chunk_keys: vec![video_chunk_feedback_key(10, 1)], + decode_chain_invalidated: true, }, ]; @@ -3394,6 +3426,34 @@ mod tests { assert!(error.to_string().contains("one stream_id/session_id")); } + #[test] + fn expired_non_dependency_damage_does_not_request_keyframe() -> Result<()> { + let expired = vec![ExpiredVideoFrame { + key: VideoFrameKey { + stream_id: "muninn.raven.av.rudp".to_string(), + session_id: "session-1".to_string(), + frame_id: 9, + }, + deadline_ticks: 28_800, + missing_video_chunk_keys: vec![video_chunk_feedback_key(9, 1)], + decode_chain_invalidated: false, + }]; + + let feedback = build_feedback_for_expired_video_frames( + &expired, + ExpiredVideoFrameFeedbackOptions { + receiver_id: "starfire.obs", + jitter_us: 700, + decode_queue_us: 2_000, + observed_at: "2026-06-18T00:00:00Z", + }, + )? + .expect("expired damage should produce feedback"); + + assert!(!feedback.requested_keyframe); + Ok(()) + } + #[test] fn media_wire_round_trips_video_document() -> Result<()> { let access_unit = VideoAccessUnit { diff --git a/crates/sleipnir-daemon/src/main.rs b/crates/sleipnir-daemon/src/main.rs index 1f4189f..72a462e 100644 --- a/crates/sleipnir-daemon/src/main.rs +++ b/crates/sleipnir-daemon/src/main.rs @@ -12,7 +12,7 @@ use odin_core::{ IdunnDaemonHealthRecord, MUNINN_HID_CONTROLLER_STATE_SCHEMA, MuninnHidControllerStateRecord, OdinDocuments, OdinEndpointQuery, SleipnirInputMappingRecord, discover_provider_endpoints, }; -use std::collections::HashMap; +use std::collections::{BTreeMap, HashMap, HashSet}; use std::env; use std::fs; use std::net::{SocketAddr, ToSocketAddrs, UdpSocket}; @@ -62,6 +62,7 @@ struct ActiveRudpStream { last_frame_at: Option, last_stale_log_at: Option, last_subscription: Option, + received_edges: Vec, last_subscription_at: Option, } @@ -154,9 +155,79 @@ struct VirtualPadState { #[derive(Clone, Debug)] struct TimedHidRecord { record: MuninnHidControllerStateRecord, + epoch: u64, + state_sequence: u64, timing: HidRecordTiming, } +#[derive(Clone, Debug)] +struct HidLatestStateFrame { + epoch: u64, + state_sequence: u64, + record: MuninnHidControllerStateRecord, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +struct HidButtonEdge { + epoch: u64, + device_id: String, + edge_sequence: u64, + button: String, + pressed: bool, +} + +fn decode_latest_state_frame(payload: &[u8]) -> Option { + let value: serde_json::Value = serde_json::from_slice(payload).ok()?; + Some(HidLatestStateFrame { + epoch: value.get("epoch")?.as_u64()?, + state_sequence: value.get("state_sequence")?.as_u64()?, + record: serde_json::from_value(value.get("record")?.clone()).ok()?, + }) +} + +fn decode_button_edge(payload: &[u8]) -> Option { + let value: serde_json::Value = serde_json::from_slice(payload).ok()?; + Some(HidButtonEdge { + epoch: value.get("epoch")?.as_u64()?, + device_id: value.get("device_id")?.as_str()?.to_string(), + edge_sequence: value.get("edge_sequence")?.as_u64()?, + button: value.get("button")?.as_str()?.to_string(), + pressed: value.get("pressed")?.as_bool()?, + }) +} + +#[derive(Default)] +struct HidSemanticCursor { + epoch: u64, + state_sequence: u64, + edge_sequence: u64, + pending_edges: BTreeMap, + retired_epochs: HashSet, +} + +impl HidSemanticCursor { + fn accept_state(&mut self, epoch: u64, sequence: u64) -> bool { + if epoch == 0 && self.epoch != 0 { return false; } + if self.retired_epochs.contains(&epoch) || (epoch == self.epoch && sequence <= self.state_sequence) { return false; } + if epoch != self.epoch { + if self.epoch != 0 { self.retired_epochs.insert(self.epoch); } + self.epoch = epoch; self.state_sequence = 0; self.edge_sequence = 0; self.pending_edges.clear(); + } + self.state_sequence = sequence; + true + } + fn push_edge(&mut self, edge: HidButtonEdge) -> Vec { + if edge.epoch != self.epoch || edge.edge_sequence <= self.edge_sequence { return Vec::new(); } + self.pending_edges.entry(edge.edge_sequence).or_insert(edge); + let mut ready = Vec::new(); + while let Some(edge) = self.pending_edges.remove(&(self.edge_sequence + 1)) { + self.edge_sequence += 1; + ready.push(edge); + } + ready + } +} + #[derive(Clone, Debug)] struct HidRecordTiming { frame_received_at: Instant, @@ -344,7 +415,7 @@ fn main() -> Result<()> { 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 semantic_cursor = HidSemanticCursor::default(); 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); @@ -352,7 +423,6 @@ fn main() -> Result<()> { 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() @@ -387,11 +457,10 @@ fn main() -> Result<()> { 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(); + semantic_cursor = HidSemanticCursor::default(); } let mut last_applied_record: Option = None; if let Some(stream) = rudp_stream.as_mut() { @@ -400,7 +469,7 @@ fn main() -> Result<()> { backend.update(&VirtualPadState::default())?; output_is_neutral = true; last_output_frame_at = Some(Instant::now()); - last_output_source_timestamp_ns = None; + semantic_cursor = HidSemanticCursor::default(); if options.trace { eprintln!( "Sleipnir neutralized virtual pad before recreating stale Muninn HID RUDP connection for filter={:?}", @@ -431,6 +500,8 @@ fn main() -> Result<()> { )?; let records = receive_rudp_records(stream, options.trace)?; for timed_record in records { + let epoch = timed_record.epoch; + let state_sequence = timed_record.state_sequence; let record = timed_record.record; let timing = timed_record.timing; if record_matches_filter(&record, current_device_filter.as_deref()) { @@ -443,13 +514,7 @@ fn main() -> Result<()> { 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 { + if semantic_cursor.accept_state(epoch, state_sequence) || options.once { let state = map_record_to_virtual_pad(&record, &desired_mapping); let axis_classified_at = Instant::now(); let output_frame_at = Instant::now(); @@ -482,8 +547,6 @@ fn main() -> Result<()> { )); 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) => { @@ -516,6 +579,28 @@ fn main() -> Result<()> { } } } + let edges = std::mem::take(&mut stream.received_edges); + for edge in edges { + let edge_epoch = edge.epoch; + let edge_sequence = edge.edge_sequence; + let edge_device = edge.device_id.clone(); + for applied in semantic_cursor.push_edge(edge) { + let Some(record) = last_applied_record.as_mut().or(recent_applied_record.as_mut()) else { continue; }; + if applied.pressed { + if !record.buttons.contains(&applied.button) { record.buttons.push(applied.button.clone()); } + } else { + record.buttons.retain(|button| button != &applied.button); + } + let state = map_record_to_virtual_pad(record, &desired_mapping); + backend.update(&state)?; + output_is_neutral = state == VirtualPadState::default(); + last_output_frame_at = Some(Instant::now()); + } + if edge_epoch == semantic_cursor.epoch && edge_sequence <= semantic_cursor.edge_sequence { + let ack = serde_json::json!({"epoch": edge_epoch, "device_id": edge_device, "edge_sequence": semantic_cursor.edge_sequence}); + stream.transport.send("hid.edge.ack", serde_json::to_vec(&ack)?)?; + } + } if desired_mapping.enabled && !output_is_neutral && last_output_frame_at @@ -2226,7 +2311,7 @@ fn create_rudp_stream( 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), + reconnect_policy: None, })?; transport.connect(Vec::new())?; return Ok(Some(ActiveRudpStream { @@ -2238,6 +2323,7 @@ fn create_rudp_stream( last_stale_log_at: None, last_subscription: None, last_subscription_at: None, + received_edges: Vec::new(), })); } let Some(bind) = bind else { @@ -2266,7 +2352,7 @@ fn create_rudp_stream( 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), + reconnect_policy: None, })?, target: None, last_connect_attempt_at: None, @@ -2275,6 +2361,7 @@ fn create_rudp_stream( last_stale_log_at: None, last_subscription: None, last_subscription_at: None, + received_edges: Vec::new(), })) } @@ -2491,9 +2578,15 @@ fn receive_rudp_records(stream: &mut ActiveRudpStream, trace: bool) -> Result frame.record.clone(), + None => serde_json::from_slice(&frame.payload).context("decoding Sleipnir RUDP HID frame")?, + }; records.push(TimedHidRecord { - record: serde_json::from_slice(&frame.payload) - .context("decoding Sleipnir RUDP HID frame")?, + state_sequence: decoded.as_ref().map_or(record.sequence, |frame| frame.state_sequence), + epoch: decoded.as_ref().map_or(0, |frame| frame.epoch), + record, timing: HidRecordTiming { frame_received_at, frame_received_unix_ns, @@ -2501,6 +2594,12 @@ fn receive_rudp_records(stream: &mut ActiveRudpStream, trace: bool) -> Result { + empty_polls = 0; + let edge = decode_button_edge(&frame.payload) + .ok_or_else(|| anyhow!("decoding Sleipnir HID button edge"))?; + stream.received_edges.push(edge); + } Ok(Some(frame)) => { empty_polls = 0; if trace { @@ -2975,6 +3074,38 @@ mod tests { assert_eq!(records[1].axes[0], 0.0); } + fn edge(epoch: u64, sequence: u64, button: &str, pressed: bool) -> HidButtonEdge { + HidButtonEdge { epoch, device_id: "pad".into(), edge_sequence: sequence, button: button.into(), pressed } + } + + #[test] + fn ordered_edges_preserve_quick_tap_and_dedupe_reorder() { + let mut cursor = HidSemanticCursor::default(); + assert!(cursor.accept_state(7, 1)); + assert!(cursor.push_edge(edge(7, 2, "a", false)).is_empty()); + let ready = cursor.push_edge(edge(7, 1, "a", true)); + assert_eq!(ready.iter().map(|edge| (edge.pressed, edge.edge_sequence)).collect::>(), vec![(true, 1), (false, 2)]); + assert!(cursor.push_edge(edge(7, 1, "a", true)).is_empty()); + } + + #[test] + fn latest_state_wins_without_wall_clock_ordering() { + let mut cursor = HidSemanticCursor::default(); + assert!(cursor.accept_state(9, 4)); + assert!(!cursor.accept_state(9, 3)); + assert!(cursor.accept_state(9, 5)); // source wall clock may move backwards; it is irrelevant here. + } + + #[test] + fn epoch_reset_rejects_stale_edges() { + let mut cursor = HidSemanticCursor::default(); + assert!(cursor.accept_state(10, 8)); + assert!(cursor.accept_state(11, 1)); + assert!(cursor.push_edge(edge(10, 9, "a", true)).is_empty()); + assert_eq!(cursor.push_edge(edge(11, 1, "b", true)).len(), 1); + assert!(!cursor.accept_state(10, 99)); + } + #[test] fn coalesces_by_source_timestamp_not_arrival_order() { let mut newer_nav = record(vec![0.0, 1.0, -1.0], Vec::new(), 10); diff --git a/docs/realtime-delivery-authority.md b/docs/realtime-delivery-authority.md new file mode 100644 index 0000000..5eb16d3 --- /dev/null +++ b/docs/realtime-delivery-authority.md @@ -0,0 +1,105 @@ +# Realtime delivery authority + +This map governs Muninn media and Sleipnir input hardening. Transport is a +carrier. Signal semantics own what survives loss. + +## Sleipnir input + +- Owner: Muninn owns source-local sampling and classification. Sleipnir owns + mapping and the single local virtual-HID commit path. +- Inputs: physical reports, selected device/stream, mapping intent, connection + epoch, monotonic state sequence, ordered input edges, and application receipt. +- Outputs: replaceable latest state, replayable ordered edges, virtual-HID + commits, acknowledgement cursor, and bounded freshness telemetry. +- Derived state: wall-clock capture time is telemetry only. The latest full + snapshot reconciles held state; it does not prove that intervening edges were + delivered. +- Forbidden writers: generic retry order, CultCache telemetry, receiver batch + coalescing, and wall-clock comparison may not decide input freshness or edge + delivery. +- Shared paths: live input, remapping, reconnect, replay tests, and + neutralization use the same Sleipnir commit primitive. +- Cut line: a whole controller snapshot is no longer the sole owner of button + delivery. Replaceable state and non-replaceable edges have separate sequence + and acknowledgement semantics. +- Verification layer: observe virtual-HID transition timelines through loss, + duplication, reorder, stalls, clock rollback, and reconnect. + +## Muninn media + +- Owner: Muninn owns capture/encoder lifecycle, access-unit packetization, + sender queues, parity/repair material, and response to receiver feedback. +- Inputs: encoded video access units, encoded audio packets, media-clock PTS, + consumer-derived deadlines, and receiver damage/decode feedback. +- Outputs: deadline-bound video chunks/parity, deadline-bound audio continuity + packets, selective repairs, encoder recovery requests, and stage telemetry. +- Derived state: RUDP acknowledgements, repair counters, CultCache receipts, and + OBS lowering are evidence or carrier state. They do not extend usefulness. +- Forbidden writers: generic RUDP retry duration must not decide media lifetime; + a repair cache must not mint a new deadline; a missing but recoverable chunk + must not independently force an IDR; persistence and OBS must not own sync. +- Shared paths: live capture, test injection, repair, keyframe recovery, and + reconnect use the same frame/deadline policy. +- Cut line: remove unbounded payload queues and the two-second realtime default. + Expired frames, audio packets, parity, and repairs leave the machine together. +- Verification layer: observe decoded/presented timelines through controlled + loss, jitter, reorder, oversubscription, and reconnect—not merely transport + counters. + +## Transport substrate + +- Owner: CultNet RUDP owns connection/session mechanics, packetization, + retransmission, transport acknowledgement, fragment reassembly, and delivery + flags. It does not own application usefulness or application receipt. +- Inputs: semantic channel, connection epoch, payload, send deadline, and peer + packets. +- Outputs: delivered frames, bounded delivery failure, transport counters, and + liveness state. +- Derived state: pending packet maps, ACK windows, fragment buffers, and reorder + buffers are bounded transport internals. +- Forbidden writers: one global packet sequence must not let lost deadline + traffic block ordered edges; transport ACK must not impersonate Sleipnir + application receipt; reconnect must not silently continue an old epoch. +- Shared paths: input state, input edges, media, control, health, and schema + traffic use explicit semantic channels whose interference is tested. +- Cut line: do not wrap ambiguous delivery in another retry loop. Split or fix + the underlying sequence/ACK authority when cross-channel behavior violates a + signal contract. +- Verification layer: deterministic session tests plus socket impairment tests + for loss, ACK-window escape, sustained inbound load, buffer bounds, wrap, and + reconnect. + +## Delivery classes + +| Class | Supersession | Ordering | Recovery | Expiry | +|---|---|---|---|---| +| input latest state | newer `(epoch, state_sequence)` replaces older | per device | republish current state | tens of milliseconds | +| input edge | never until application-acknowledged or epoch fenced | per device/epoch | bounded replay from edge cursor | session/lease bounded | +| video access unit | whole frame and dependency chain | frame/dependency IDs | parity, selective repair, then keyframe | decode deadline | +| audio continuity | playout order | packet/media clock | small bounded FEC/reorder/concealment | playout deadline | +| control | none unless command contract says so | command sequence | reliable delivery plus application receipt | explicit command deadline | + +The machine is reliable when each class loses only what its contract permits. + +## Implemented reliability cut: 2026-07-16 + +- Odin's vendored Rust substrate is pinned to the experimental CultLib runtime + snapshot recorded in `vendor/CULTLIB_SNAPSHOT.md`. +- Muninn/Sleipnir HID traffic now carries a per-source epoch, monotonic latest + state sequence, pre-collapse ordered button edges, cumulative application + acknowledgement, replay until acknowledgement, duplicate/reorder handling, + and stale-epoch rejection. Wall time is telemetry only. +- Muninn audio/video payloads use CultNet's unreliable `realtime` lane. The + experimental `media` lane is reliable without expiry and therefore cannot own + deadline-bound A/V. +- The default LAN media deadline is 100 ms. Encoder-to-sender transport uses a + bounded synchronous channel; pending audio/video queues are bounded; repair + cache entries expire on the sender deadline; receiver-declared late frames + cannot be repaired. +- Recoverable missing video chunks remain repair/FEC damage. Only explicit or + dependency-derived decode-chain invalidation requests a keyframe. + +Still open: real encoder keyframe actuation, receiver-side production parity +reconstruction, bounded long-disconnect admission for unacknowledged HID edges, +audio FEC/concealment, adaptive bitrate/parity from receiver pressure, and a +socket impairment timeline harness. diff --git a/vendor/CULTLIB_SNAPSHOT.md b/vendor/CULTLIB_SNAPSHOT.md new file mode 100644 index 0000000..7c5b7d9 --- /dev/null +++ b/vendor/CULTLIB_SNAPSHOT.md @@ -0,0 +1,27 @@ +# CultLib experimental snapshot + +Odin's vendored Rust CultCache/CultNet body is synchronized from: + +- repository: `https://github.com/GameCult/CultLib.git` +- local runtime source: `E:\Projects\CultLib-dev-runtime` +- commit: `8965f3c0e0e0082b76e2001772bf1fe600f386f4` +- commit title: `Authenticate provider session ingress` +- containing experimental branches at synchronization time: + `origin/codex/cultmesh-reliability-control-plane` and + `origin/codex/cultmesh-mapped-content` + +This is the experimental CultMesh/CultNet body used by the live VoidBot runtime +and is ancestral to the CultLib Unity 1.0.15 package consumed by Aetheria. Odin +vendors `packages/cultcache-rs` and `packages/cultnet-rs` because the CultLib +repository is not a Cargo workspace at its root and Cargo cannot consume those +subdirectory crates as one portable git dependency. + +Do not patch the vendored transport as an Odin-private fork. Make transport +changes in CultLib's experimental branch, verify them there, then resynchronize +the two package trees and update this receipt. + +One local adapter remains in `cultcache-rs`: `put_raw_envelope` lets Odin's +runtime document registry admit a dynamically typed envelope after registration. +It does not alter persistence or transport semantics. Promote this narrow API to +CultLib before the next snapshot refresh so the vendored package can become an +exact copy. diff --git a/vendor/cultcache-rs/README.md b/vendor/cultcache-rs/README.md index b21c324..2d75d94 100644 --- a/vendor/cultcache-rs/README.md +++ b/vendor/cultcache-rs/README.md @@ -53,7 +53,7 @@ struct Settings { let mut cache = CultCache::new(); cache.register_entry_type::()?; -cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new("cache.cc")); +cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new("cache.msgpack")); cache.pull_all_backing_stores()?; cache.put("app", &Settings { @@ -136,7 +136,7 @@ pub struct PlayerData { let mut cache = CultCache::builder() .with_generated_entries(game_entries()) - .with_generic_store(SingleFileMessagePackBackingStore::new("cache.cc")) + .with_generic_store(SingleFileMessagePackBackingStore::new("cache.msgpack")) .build()?; cache.pull_all_backing_stores()?; @@ -185,14 +185,14 @@ without pretending Rust has runtime reflection hiding under the floorboards. Generic store: ```rust -cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new("cache.cc")); +cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new("cache.msgpack")); ``` Type-specific store: ```rust cache.add_backing_store( - SingleFileMessagePackBackingStore::new("players.cc"), + SingleFileMessagePackBackingStore::new("players.msgpack"), ["player"], ); ``` diff --git a/vendor/cultcache-rs/src/lib.rs b/vendor/cultcache-rs/src/lib.rs index 7e654b9..a2efe71 100644 --- a/vendor/cultcache-rs/src/lib.rs +++ b/vendor/cultcache-rs/src/lib.rs @@ -137,9 +137,10 @@ impl SingleFileMessagePackBackingStore { if bytes.is_empty() { return Ok(Vec::new()); } - decode_store_snapshot(&bytes) - .or_else(|_| rmp_serde::from_slice(&bytes)) - .with_context(|| format!("failed to decode MessagePack {}", self.path.display())) + decode_store_snapshot(&bytes).or_else(|_| { + rmp_serde::from_slice(&bytes) + .with_context(|| format!("failed to decode MessagePack {}", self.path.display())) + }) } fn write_all_unlocked(&self, entries: &[CultCacheEnvelope]) -> Result<()> { @@ -206,7 +207,7 @@ impl SingleFileMessagePackBackingStore { .path .file_name() .map(|value| value.to_os_string()) - .unwrap_or_else(|| "cultcache.cc".into()); + .unwrap_or_else(|| "cultcache.msgpack".into()); lock_name.push(".lock"); self.path.with_file_name(lock_name) } @@ -251,6 +252,7 @@ struct CultCacheStoreRegistration { pub struct CultCache { definitions: BTreeMap, + schema_name_definitions: BTreeMap, entries: BTreeMap, stores: Vec, } @@ -259,6 +261,7 @@ impl CultCache { pub fn new() -> Self { Self { definitions: BTreeMap::new(), + schema_name_definitions: BTreeMap::new(), entries: BTreeMap::new(), stores: Vec::new(), } @@ -278,7 +281,18 @@ impl CultCache { T::TYPE )); } + if let Some(existing_type) = self.schema_name_definitions.get(T::SCHEMA_NAME) + && existing_type != T::TYPE + { + return Err(anyhow!( + "CultCache schema name {:?} is already registered for type {:?}", + T::SCHEMA_NAME, + existing_type + )); + } self.definitions.insert(T::TYPE.to_string(), T::SCHEMA_NAME); + self.schema_name_definitions + .insert(T::SCHEMA_NAME.to_string(), T::TYPE.to_string()); Ok(()) } @@ -309,14 +323,20 @@ impl CultCache { pub fn pull_all_backing_stores(&mut self) -> Result<()> { self.entries.clear(); let known_types: BTreeSet = self.definitions.keys().cloned().collect(); + let schema_name_definitions = self.schema_name_definitions.clone(); for registration in &mut self.stores { - for entry in registration.store.pull_all()? { - if !known_types.contains(&entry.r#type) { + for mut entry in registration.store.pull_all()? { + let Some(canonical_type) = resolve_registered_type( + &known_types, + &schema_name_definitions, + &entry.r#type, + ) else { return Err(anyhow!( "No schema is registered for persisted entry type {:?}", entry.r#type )); - } + }; + entry.r#type = canonical_type; self.entries.insert(entry_id(&entry), entry); } } @@ -459,6 +479,9 @@ impl CultCache { Ok(parsed) } + /// Odin's dynamic CultMesh registry adapter. The experimental CultCache + /// surface is typed by default; this boundary admits an already-validated + /// envelope only after its runtime type has been registered. pub fn put_raw_envelope(&mut self, entry: CultCacheEnvelope) -> Result<()> { if !self.definitions.contains_key(&entry.r#type) { return Err(anyhow!( @@ -555,6 +578,7 @@ impl CultCache { .filter_map(|(index, registration)| registration.types.is_empty().then_some(index)) .collect() } + } impl Default for CultCache { @@ -571,28 +595,39 @@ fn entry_id_parts(r#type: &str, key: &str) -> String { format!("{type}::{key}", type = r#type) } +fn resolve_registered_type( + known_types: &BTreeSet, + schema_name_definitions: &BTreeMap, + persisted_type: &str, +) -> Option { + if known_types.contains(persisted_type) { + return Some(persisted_type.to_string()); + } + + schema_name_definitions.get(persisted_type).cloned() +} + fn now_utc_second() -> String { chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true) } fn encode_store_snapshot(entries: &[CultCacheEnvelope]) -> PersistedStoreSnapshot { - let mut schema_names = BTreeMap::::new(); + let mut schema_names = BTreeSet::::new(); for entry in entries { schema_names.insert( entry .schema_id .clone() .unwrap_or_else(|| entry.r#type.clone()), - entry.r#type.clone(), ); } let catalog = schema_names .into_iter() - .map(|(schema_id, document_type)| { + .map(|schema_id| { PersistedSchemaCatalogEntry( schema_id.clone(), - document_type, + schema_id.clone(), format!("{schema_id}.v1"), schema_id.clone(), format!( @@ -639,13 +674,25 @@ fn decode_store_snapshot(bytes: &[u8]) -> Result> { .2 .into_iter() .map(|record| { - let r#type = catalog.get(&record.1).cloned().ok_or_else(|| { - anyhow!( - "CultCache record {:?} references missing schema {:?}", - record.0, - record.1 - ) - })?; + let r#type = match catalog.get(&record.1) { + Some(schema_name) => schema_name.clone(), + None => { + let schema_version = infer_schema_version_from_payload(&record.3).ok_or_else(|| { + anyhow!( + "CultCache record {:?} references missing schema {:?}", + record.0, + record.1 + ) + })?; + infer_schema_name(&schema_version).ok_or_else(|| { + anyhow!( + "CultCache record {:?} references missing schema {:?}", + record.0, + record.1 + ) + })? + } + }; Ok(CultCacheEnvelope { key: record.0, r#type, @@ -657,6 +704,68 @@ fn decode_store_snapshot(bytes: &[u8]) -> Result> { .collect() } +fn infer_schema_version_from_payload(payload: &[u8]) -> Option { + let mut offset = 0usize; + read_array_header(payload, &mut offset)?; + read_string(payload, &mut offset) +} + +fn read_array_header(payload: &[u8], offset: &mut usize) -> Option { + let marker = *payload.get(*offset)?; + *offset += 1; + match marker { + 0x90..=0x9f => Some((marker & 0x0f) as u32), + 0xdc => { + let bytes = payload.get(*offset..(*offset + 2))?; + *offset += 2; + Some(u16::from_be_bytes([bytes[0], bytes[1]]) as u32) + } + 0xdd => { + let bytes = payload.get(*offset..(*offset + 4))?; + *offset += 4; + Some(u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]])) + } + _ => None, + } +} + +fn read_string(payload: &[u8], offset: &mut usize) -> Option { + let marker = *payload.get(*offset)?; + *offset += 1; + let length = match marker { + 0xa0..=0xbf => (marker & 0x1f) as usize, + 0xd9 => { + let length = *payload.get(*offset)? as usize; + *offset += 1; + length + } + 0xda => { + let bytes = payload.get(*offset..(*offset + 2))?; + *offset += 2; + u16::from_be_bytes([bytes[0], bytes[1]]) as usize + } + 0xdb => { + let bytes = payload.get(*offset..(*offset + 4))?; + *offset += 4; + u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]) as usize + } + _ => return None, + }; + + let bytes = payload.get(*offset..(*offset + length))?; + std::str::from_utf8(bytes).ok().map(str::to_string) +} + +fn infer_schema_name(schema_version: &str) -> Option { + let marker = schema_version.rfind(".v")?; + let version = schema_version.get((marker + 2)..)?; + if marker == 0 || version.is_empty() || !version.bytes().all(|value| value.is_ascii_digit()) { + return None; + } + + Some(schema_version[..marker].to_string()) +} + fn escape_json_string(value: &str) -> String { value.replace('\\', "\\\\").replace('"', "\\\"") } @@ -665,7 +774,7 @@ fn temporary_path_for(path: &Path) -> PathBuf { let mut file_name = path .file_name() .map(|value| value.to_os_string()) - .unwrap_or_else(|| "cultcache.cc".into()); + .unwrap_or_else(|| "cultcache.msgpack".into()); file_name.push(format!(".{}.tmp", uuid::Uuid::new_v4())); path.with_file_name(file_name) } @@ -693,12 +802,23 @@ mod tests { body: String, } + #[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] + #[cultcache(type = "runtime-policy", schema = "tests.schema_stamped_entry")] + struct SchemaStamped { + #[cultcache(key = 0)] + schema_version: String, + #[cultcache(key = 1)] + name: String, + #[cultcache(key = 2)] + value: String, + } + cultcache_registry!(TestEntries { Settings, Note }); #[test] fn familiar_cultcache_flow_persists_and_reloads_typed_documents() -> Result<()> { let temp = tempfile::tempdir()?; - let store_path = temp.path().join("cache.cc"); + let store_path = temp.path().join("cache.msgpack"); let settings = Settings { theme: "ash".to_string(), retries: 3, @@ -722,7 +842,7 @@ mod tests { #[test] fn entry_identity_is_polymorphic_by_type_and_key() -> Result<()> { let temp = tempfile::tempdir()?; - let store_path = temp.path().join("cache.cc"); + let store_path = temp.path().join("cache.msgpack"); let mut cache = CultCache::new(); cache.register_registry(TestEntries)?; cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&store_path)); @@ -751,8 +871,8 @@ mod tests { #[test] fn type_specific_store_routes_before_generic_store() -> Result<()> { let temp = tempfile::tempdir()?; - let generic_path = temp.path().join("generic.cc"); - let settings_path = temp.path().join("settings.cc"); + let generic_path = temp.path().join("generic.msgpack"); + let settings_path = temp.path().join("settings.msgpack"); let mut cache = CultCache::new(); cache.register_entry_type::()?; cache.register_entry_type::()?; @@ -787,7 +907,7 @@ mod tests { #[test] fn update_and_delete_follow_the_cache_api() -> Result<()> { let temp = tempfile::tempdir()?; - let store_path = temp.path().join("cache.cc"); + let store_path = temp.path().join("cache.msgpack"); let mut cache = CultCache::new(); cache.register_entry_type::()?; cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&store_path)); @@ -809,7 +929,7 @@ mod tests { #[test] fn pull_rejects_unregistered_persisted_entry_type() -> Result<()> { let temp = tempfile::tempdir()?; - let store_path = temp.path().join("cache.cc"); + let store_path = temp.path().join("cache.msgpack"); let mut store = SingleFileMessagePackBackingStore::new(&store_path); store.push(&CultCacheEnvelope { key: "unknown".to_string(), @@ -833,7 +953,7 @@ mod tests { #[test] fn payload_is_binary_messagepack_not_json_value() -> Result<()> { let temp = tempfile::tempdir()?; - let store_path = temp.path().join("cache.cc"); + let store_path = temp.path().join("cache.msgpack"); let mut cache = CultCache::new(); cache.register_entry_type::()?; cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&store_path)); @@ -855,7 +975,7 @@ mod tests { #[test] fn corrupted_payload_fails_during_typed_retrieval() -> Result<()> { let temp = tempfile::tempdir()?; - let store_path = temp.path().join("cache.cc"); + let store_path = temp.path().join("cache.msgpack"); let mut store = SingleFileMessagePackBackingStore::new(&store_path); store.push(&CultCacheEnvelope { key: "app".to_string(), @@ -881,8 +1001,8 @@ mod tests { #[test] fn put_envelope_reuses_existing_messagepack_payload() -> Result<()> { let temp = tempfile::tempdir()?; - let origin_store = temp.path().join("origin.cc"); - let target_store = temp.path().join("target.cc"); + let origin_store = temp.path().join("origin.msgpack"); + let target_store = temp.path().join("target.msgpack"); let mut origin = CultCache::new(); origin.register_entry_type::()?; @@ -916,4 +1036,40 @@ mod tests { ); Ok(()) } + + #[test] + fn messagepack_store_recovers_schema_stamped_records_missing_catalog_entries() -> Result<()> { + let temp = tempfile::tempdir()?; + let store_path = temp.path().join("missing-catalog.msgpack"); + let expected = SchemaStamped { + schema_version: "tests.schema_stamped_entry.v1".to_string(), + name: "schema-stamped".to_string(), + value: "still readable".to_string(), + }; + let snapshot = PersistedStoreSnapshot( + "cultcache.store.v1".to_string(), + Vec::new(), + vec![PersistedRecord( + "record-1".to_string(), + "sha256:stale-schema-id-from-cold-record".to_string(), + "2026-06-25T12:00:00Z".to_string(), + rmp_serde::to_vec(&expected)?, + )], + ); + fs::write(&store_path, rmp_serde::to_vec(&snapshot)?)?; + + let mut cache = CultCache::new(); + cache.register_entry_type::()?; + cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&store_path)); + cache.pull_all_backing_stores()?; + + assert_eq!(cache.get_required::("record-1")?, expected); + assert_eq!( + cache + .get_required_envelope::("record-1")? + .schema_id, + Some("sha256:stale-schema-id-from-cold-record".to_string()) + ); + Ok(()) + } } diff --git a/vendor/cultmesh-rs/src/lib.rs b/vendor/cultmesh-rs/src/lib.rs index 3217a28..08ad7c7 100644 --- a/vendor/cultmesh-rs/src/lib.rs +++ b/vendor/cultmesh-rs/src/lib.rs @@ -748,7 +748,7 @@ fn request_raw_snapshot_from_rudp_catalog( max_payload_bytes: None, max_fragment_bytes: Some(1200), max_pending_reliable_packets: None, - media_reliable_expire_after_ms: None, + reconnect_policy: None, }, )?; client.connect(Vec::new())?; @@ -844,7 +844,7 @@ fn publish_cultnet_message_to_rudp_catalog( max_payload_bytes: None, max_fragment_bytes: Some(1200), max_pending_reliable_packets: None, - media_reliable_expire_after_ms: None, + reconnect_policy: None, }, )?; client.connect(Vec::new())?; @@ -855,7 +855,6 @@ fn publish_cultnet_message_to_rudp_catalog( thread::sleep(options.poll_interval); } if !client.connected() { - client.assume_connected(); } let payload = encode_cultnet_message_to_vec(message, CultNetWireContract::CultNetSchemaV0)?; diff --git a/vendor/cultnet-rs/README.md b/vendor/cultnet-rs/README.md index 8324a5b..7ade81d 100644 --- a/vendor/cultnet-rs/README.md +++ b/vendor/cultnet-rs/README.md @@ -1,9 +1,9 @@ # CultNet RS `cultnet-rs` is the Rust sibling of `cultnet-ts`: typed MessagePack messages, -4-byte length-prefixed direct-pipe framing, stop-and-wait RUDP message delivery, -CultLib-shaped security helpers, and CultCache replication without making -callers paw through raw envelopes like we lost a bet. +4-byte length-prefixed direct-pipe framing, CultLib-shaped security helpers, and +CultCache replication without making callers paw through raw envelopes like we +lost a bet. The contract is intentionally boring: @@ -14,8 +14,6 @@ The contract is intentionally boring: - document put/delete/snapshot messages move typed CultCache entries. - raw document put/snapshot messages preserve canonical MessagePack payload bytes for bit-compatible neighbors. -- `cultnet.transport.rudp.v0` carries one CultNet message per acknowledged UDP - datagram with timeout/retry semantics. - hello messages advertise `supportedMutationContracts`, so callers discover which document types are read-only, which accept typed intents, which authority owns the mutation, and which receipt documents prove the outcome. @@ -42,24 +40,11 @@ The initial tests prove: - schema-versioned message round trips - legacy `gamecult.networking.v0` login mapping - schema discovery catalog responses with canonical JSON schema hashes +- shard catalog request/response filtering and response application - CultCache snapshot replication through registered typed documents - raw snapshot replication that preserves the original payload bytes +- raw snapshot replication into a local same-schema Rust alias type - document mutation contract advertisement through hello frames and registries -- acknowledged localhost UDP delivery through `cultnet.transport.rudp.v0` - -## RUDP Transport - -`cultnet.transport.rudp.v0` is the Rust crate's first non-TCP daemon transport. -It is intentionally small: one CultNet message becomes one UDP data packet, the -receiver sends an acknowledgement packet, and the sender retries until the ack -arrives or the retry budget is spent. - -This is a daemon health/control substrate, not a bulk stream transport. It does -not fragment oversized messages, multiplex streams, or promise congestion -control. Large snapshots should stay in CultCache/CultMesh storage and move by -document reference or a later chunking contract. The useful invariant is simple: -Rust runtimes can now move a typed CultNet message across UDP without reaching -for TCP as the hidden truth path. ## Schema Discovery @@ -69,14 +54,51 @@ surface: - core wire messages - legacy `gamecult.networking.v0` auth/sample payloads - schema catalog request/response messages +- shard catalog request/response messages - the canonical `ghostlight.agent-state` document payload schema -Use `builtin_schema_registry()` when you want the standard catalog, or register -your own closed-world schema set with `CultNetSchemaRegistry`. Discovery stays -explicit on purpose: peers advertise only the contracts they were compiled to -understand, the same way CultCache only consumes the document types you +Use `builtin_schema_registry()` or `CultMesh::create_builtin_schema_registry()` +when you want the standard catalog, or register your own closed-world schema set +with `CultNetSchemaRegistry` / `CultMesh::create_schema_registry()`. Discovery +stays explicit on purpose: peers advertise only the contracts they were compiled +to understand, the same way CultCache only consumes the document types you registered instead of pretending polymorphism is a public park. +## Shard Catalogs + +Rust now exposes the same shard topology vocabulary as the other runtimes +without claiming to be the full C# service body: + +```rust +use cultnet_rs::{CultMesh, CultNetMessage, CultNetShardDescriptor}; + +let mut catalog = CultMesh::create_shard_catalog(); +catalog.upsert(CultNetShardDescriptor { + shard_id: "notes-a".to_string(), + owner_runtime_id: "rust-primary".to_string(), + epoch: 3, + is_primary: Some(true), + schema_ids: vec!["note.v0".to_string()], + key_prefix: Some("note:".to_string()), + primary_endpoints: vec!["rudp://127.0.0.1:4100".to_string()], + replica_endpoints: vec![], + read_replica_endpoints: vec![], + region: None, + authority_lease_id: None, +})?; + +let response = catalog.create_catalog_response(&CultNetMessage::ShardCatalogRequest { + message_id: "discover-shards".to_string(), + schema_ids: Some(vec!["note.v0".to_string()]), + record_keys: Some(vec!["note:1".to_string()]), +})?; +``` + +`CultNetShardCatalog::apply_response(...)` imports remote +`cultnet.shard_catalog_response.v0` descriptors into the local catalog. The +catalog owns topology inspection only; shard-log serving, daemon policy, and +game-session authority remain separate responsibilities. + ## Local Fast Lane `cultnet-rs` now mirrors the raw replication seam from `cultnet-ts`: @@ -89,8 +111,169 @@ CultCache along with the typed envelope metadata. Combined with `CultCache::put_envelope::()`, that lets a bit-compatible neighbor ingest the document without re-encoding the payload first. +The receiving Rust type does not have to be the sender's concrete Rust type. If +the local registry binds a different `DatabaseEntry` to the same schema id, +`sync_raw_document_from_snapshot_response::(...)` hydrates one local +alias type directly: + +```rust +let mut target_registry = CultNetDocumentRegistry::new(); +target_registry.register(CultNetDocumentBinding::for_entry_with_schema_id::( + "aetheria.note.v1".to_string(), + "aetheria.note.v1".to_string(), +)); + +let note = target_registry.sync_raw_document_from_snapshot_response::( + &mut target_cache, + &snapshot_response, + "note:bridge", +)?; +``` + That still is not zero-copy in the religious sense. Frames allocate, bytes move, and the receiving cache still decodes once to keep typed reads and validation honest. The win is narrower and realer: identical payload bytes stop getting decoded into generic sludge and then encoded right back into the same bytes for no reason. + +## Reactive Documents + +For local state that should feel owned by the caller, Rust can wrap a registered +CultCache record as a managed reactive document: + +```rust +use std::sync::{Arc, Mutex}; +use cultnet_rs::{CultNetReactiveDocumentOptions, CultNetDocumentRegistry}; + +let cache = Arc::new(Mutex::new(target_cache)); +let note = registry.reactive_document::( + Arc::clone(&cache), + "note:bridge", + CultNetReactiveDocumentOptions::default(), +)?; + +{ + let current = note.current(); + current.lock().unwrap().body = "local prediction".to_string(); +} +``` + +The handle polls the serialized `current` value on the configured debounce +cadence and flushes changed state back through the typed cache. `update(...)`, +`set_current(...)`, `mark_dirty()`, and `flush()` are available when the caller +wants a more explicit Rust shape. + +When a canonical document put arrives while local state is dirty, +`apply_document_put_message(...)` or `apply_raw_document_put_message(...)` +records a `CultNetReactiveDocumentReconciliation`: the canonical value, the +predicted local value, and a delta that can be smoothed by the caller. CultCache +payloads serialize by numeric field slot, so Rust tuple-backed deltas use slot +keys such as `"0"` and `"1"` when field names are not present on the wire. + +## CultMesh Rust Facade + +Rust is still the low-level substrate runtime, not a clone of the C# game +server. It does now expose the small CultMesh entrypoint needed for practical +contact and authority ergonomics: + +```rust +use cultnet_rs::{ + CultMesh, CultMeshAuthorityLease, CultMeshPeerCard, CultMeshRudpClientOptions, + CultMeshRudpSocketOptions, CultNetMessage, CultNetSchemaKind, +}; +use chrono::{Duration, Utc}; + +let schemas = CultMesh::create_builtin_schema_registry()?; +let shared_contracts = schemas.list(&cultnet_rs::CultNetSchemaCatalogOptions { + include_schema_json: false, + schema_ids: None, + kinds: Some(vec![CultNetSchemaKind::SharedContract]), +}); + +let mut server = CultMesh::create_rudp_server( + "rust-server", + 0x1020_3040, + CultMeshRudpSocketOptions::default(), +)?; +let port = server.profile.transports[0].port.unwrap(); + +let peer = CultMeshPeerCard::new( + "rust-server", + "local", + [format!("rudp://127.0.0.1:{port}")], +) +.with_roles(["schema"]) +.with_authority_lease_id("lease:rust-server"); + +let now = Utc::now(); +let mut peers = CultMesh::create_peer_catalog(); +let mut leases = CultMesh::create_authority_lease_catalog(); +peers.upsert(peer.clone())?; +leases.upsert(CultMeshAuthorityLease { + lease_id: "lease:rust-server".to_string(), + verse_id: "local".to_string(), + peer_id: "rust-server".to_string(), + roles: vec!["schema".to_string()], + shard_ids: Vec::new(), + issuer_runtime_id: None, + valid_from: now - Duration::minutes(1), + expires_at: now + Duration::minutes(1), +})?; + +let mut client = CultMesh::connect_rudp_client_for_authorized_peer( + "rust-client", + 0x1020_3040, + &peers, + &leases, + "local", + "schema", + None, + now, + CultMeshRudpClientOptions { + socket_options: CultMeshRudpSocketOptions::default(), + connect_payload: b"join".to_vec(), + ..CultMeshRudpClientOptions::default() + }, +)?; +client.send_schema_message(&CultNetMessage::SchemaCatalogRequest { + message_id: "rust-schema-catalog".to_string(), + include_schema_json: Some(false), + schema_ids: None, + kinds: Some(vec![CultNetSchemaKind::DocumentPayload]), +})?; +``` + +`create_rudp_client...` remains available when the caller intentionally owns the +handshake and polling loop. `connect_rudp_client...` performs the client +handshake before returning the same schema-message-capable RUDP transport. + +For caller-owned reconnect loops, `CultNetRudpReconnectLoop` keeps transport +construction outside the library while sharing the portable retry controller: + +```rust +use cultnet_rs::{ + CultNetReconnectPolicyOptions, CultNetRudpReconnectLoop, create_reconnect_policy, +}; + +let policy = create_reconnect_policy(CultNetReconnectPolicyOptions::default()); +let mut reconnect = CultNetRudpReconnectLoop::new(policy, b"join".to_vec(), || { + CultMesh::create_rudp_client_for_peer( + "rust-client", + 0x1020_3040, + &peer, + CultMeshRudpSocketOptions::default(), + ) +}); + +reconnect.start()?; +let decision = reconnect.handle_closed(now_ms, 0); +if decision.is_some() { + reconnect.reconnect_if_due(now_ms)?; +} +``` + +`CultMesh::parse_rudp_endpoint(...)` handles advertised `rudp://host:port` +contact hints, and `CultMeshAuthorityLeaseCatalog` keeps trust separate from +discovery. A peer card can say where to dial; `peers.first_authorized(...)` and +`CultMesh::create_rudp_client_for_authorized_peer(...)` only use that contact +hint after a lease says the peer may own the requested role or shard. diff --git a/vendor/cultnet-rs/contracts/cultnet.shard-catalog-request.schema.json b/vendor/cultnet-rs/contracts/cultnet.shard-catalog-request.schema.json new file mode 100644 index 0000000..c91ee09 --- /dev/null +++ b/vendor/cultnet-rs/contracts/cultnet.shard-catalog-request.schema.json @@ -0,0 +1,19 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "cultnet.shard_catalog_request.v0", + "type": "object", + "required": ["schemaVersion", "messageId"], + "additionalProperties": false, + "properties": { + "schemaVersion": { "const": "cultnet.shard_catalog_request.v0" }, + "messageId": { "type": "string", "minLength": 1 }, + "schemaIds": { + "type": "array", + "items": { "type": "string", "minLength": 1 } + }, + "recordKeys": { + "type": "array", + "items": { "type": "string", "minLength": 1 } + } + } +} diff --git a/vendor/cultnet-rs/contracts/cultnet.shard-catalog-response.schema.json b/vendor/cultnet-rs/contracts/cultnet.shard-catalog-response.schema.json new file mode 100644 index 0000000..b266178 --- /dev/null +++ b/vendor/cultnet-rs/contracts/cultnet.shard-catalog-response.schema.json @@ -0,0 +1,47 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "cultnet.shard_catalog_response.v0", + "type": "object", + "required": ["schemaVersion", "messageId", "shards"], + "additionalProperties": false, + "properties": { + "schemaVersion": { "const": "cultnet.shard_catalog_response.v0" }, + "messageId": { "type": "string", "minLength": 1 }, + "shards": { + "type": "array", + "items": { "$ref": "#/$defs/shardDescriptor" } + } + }, + "$defs": { + "shardDescriptor": { + "type": "object", + "required": ["shardId", "ownerRuntimeId", "epoch"], + "additionalProperties": false, + "properties": { + "shardId": { "type": "string", "minLength": 1 }, + "ownerRuntimeId": { "type": "string", "minLength": 1 }, + "epoch": { "type": "integer", "minimum": 0 }, + "isPrimary": { "type": "boolean" }, + "schemaIds": { + "type": "array", + "items": { "type": "string", "minLength": 1 } + }, + "keyPrefix": { "type": "string", "minLength": 1 }, + "primaryEndpoints": { + "type": "array", + "items": { "type": "string", "minLength": 1 } + }, + "replicaEndpoints": { + "type": "array", + "items": { "type": "string", "minLength": 1 } + }, + "readReplicaEndpoints": { + "type": "array", + "items": { "type": "string", "minLength": 1 } + }, + "region": { "type": "string", "minLength": 1 }, + "authorityLeaseId": { "type": "string", "minLength": 1 } + } + } + } +} diff --git a/vendor/cultnet-rs/contracts/cultnet.transport-profile.schema.json b/vendor/cultnet-rs/contracts/cultnet.transport-profile.schema.json index cc237e7..90261c7 100644 --- a/vendor/cultnet-rs/contracts/cultnet.transport-profile.schema.json +++ b/vendor/cultnet-rs/contracts/cultnet.transport-profile.schema.json @@ -41,6 +41,25 @@ "type": "array", "items": { "type": "string", "minLength": 1 } }, + "reconnectPolicy": { + "type": "object", + "required": [ + "schemaVersion", + "policyId", + "baseDelayMs", + "maxDelayMs", + "maxJitterMs" + ], + "additionalProperties": false, + "properties": { + "schemaVersion": { "const": "cultnet.reconnect_policy.v0" }, + "policyId": { "type": "string", "minLength": 1 }, + "baseDelayMs": { "type": "integer", "minimum": 0 }, + "maxDelayMs": { "type": "integer", "minimum": 0 }, + "maxJitterMs": { "type": "integer", "minimum": 0 }, + "maxAttempts": { "type": "integer", "minimum": 1 } + } + }, "channels": { "type": "array", "items": { diff --git a/vendor/cultnet-rs/examples/cultnet_interop_peer.rs b/vendor/cultnet-rs/examples/cultnet_interop_peer.rs index 0a00c63..ab00c6c 100644 --- a/vendor/cultnet-rs/examples/cultnet_interop_peer.rs +++ b/vendor/cultnet-rs/examples/cultnet_interop_peer.rs @@ -11,20 +11,27 @@ use cultnet_rs::CultNetDocumentPutOptions; use cultnet_rs::CultNetDocumentRegistry; use cultnet_rs::CultNetMessage; use cultnet_rs::CultNetMutationAuthority; +use cultnet_rs::CultNetRudpPacketType; +use cultnet_rs::CultNetRudpSendOptions; +use cultnet_rs::CultNetRudpSession; +use cultnet_rs::CultNetRudpSessionOptions; +use cultnet_rs::CultNetRudpSocketTransportConnection; +use cultnet_rs::CultNetRudpSocketTransportOptions; use cultnet_rs::CultNetSchemaKind; use cultnet_rs::CultNetSchemaRegistration; use cultnet_rs::CultNetSchemaRegistry; -use cultnet_rs::CultNetTransportChannel; -use cultnet_rs::CultNetTransportDelivery; -use cultnet_rs::CultNetTransportDescriptor; -use cultnet_rs::CultNetTransportOrdering; use cultnet_rs::CultNetTransportProfile; -use cultnet_rs::CultNetTransportProtocol; use cultnet_rs::CultNetWireContract; +use cultnet_rs::RudpTransportProfileOptions; +use cultnet_rs::TcpFramedTransportConnection; +use cultnet_rs::TcpFramedTransportProfileOptions; use cultnet_rs::builtin_schema_registry; +use cultnet_rs::create_rudp_transport_profile; +use cultnet_rs::create_tcp_framed_transport_profile; use cultnet_rs::decode_cultnet_message_from_slice; +use cultnet_rs::decode_rudp_packet; use cultnet_rs::encode_cultnet_message_to_vec; -use cultnet_rs::encode_frame; +use cultnet_rs::encode_rudp_packet; use serde::Deserialize; use serde::Serialize; use socket2::Domain; @@ -33,8 +40,6 @@ use socket2::Socket; use socket2::Type; use std::collections::BTreeMap; use std::fs; -use std::io::Read; -use std::io::Write; use std::net::Ipv4Addr; use std::net::SocketAddr; use std::net::SocketAddrV4; @@ -45,6 +50,7 @@ use std::sync::Arc; use std::sync::Mutex; use std::thread; use std::time::Duration; +use std::time::Instant; const INTEROP_DOCUMENT_TYPE: &str = "cultnet.interop-note"; const INTEROP_SCHEMA_VERSION: &str = "cultnet.interop_note.v0"; @@ -61,6 +67,10 @@ const FIRE_RECEIPT_TYPE: &str = "cultnet.interop-fire-weapon-receipt"; const FIRE_RECEIPT_SCHEMA_ID: &str = "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-fire-weapon-receipt.schema.json"; const FIRE_RECEIPT_SCHEMA_VERSION: &str = "cultnet.interop_fire_weapon_receipt.v0"; const DISCOVERY_ANNOUNCE_SCHEMA_VERSION: &str = "cultnet.discovery_announce.v0"; +const RUDP_INTEROP_CONNECTION_ID: u32 = 0x43554C54; +const RUDP_INTEROP_MAX_FRAGMENT_BYTES: usize = 1024; +const RUDP_INTEROP_RESEND_DELAY_MS: u64 = 25; +const RUDP_INTEROP_READ_TIMEOUT: Duration = Duration::from_secs(15); #[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] #[cultcache(type = "cultnet.interop-note", schema = "CultNetInteropNote")] @@ -174,6 +184,8 @@ enum DiscoveryMessage { tcp_port: u16, wire_contract: String, supported_document_types: Vec, + #[serde(default, skip_serializing_if = "Option::is_none")] + transport_profiles: Option>, supports_schema_catalog: bool, }, } @@ -187,6 +199,7 @@ struct PeerConfig { bind_host: String, advertise_host: String, tcp_port: u16, + rudp_port: u16, discovery_port: u16, discovery_group: Ipv4Addr, schema_path: String, @@ -199,21 +212,34 @@ struct DialConfig { display_name: String, agent_id: String, target_host: String, - target_port: u16, + target_port: Option, + target_rudp_port: Option, schema_path: String, } +trait SchemaMessageSender { + fn send_schema_message(&mut self, message: &CultNetMessage) -> Result<()>; +} + +trait SchemaMessageTransport: SchemaMessageSender { + fn read_schema_message(&mut self) -> Result; +} + fn main() -> Result<()> { let mut args = std::env::args().skip(1); - let mode = args - .next() - .ok_or_else(|| anyhow!("expected mode: serve | probe | dial"))?; + let mode = args.next().ok_or_else(|| { + anyhow!("expected mode: serve | probe | dial | rudp-serve-once | rudp-dial-once | rudp-serve-message-once | rudp-dial-message-once") + })?; let options = parse_args(args.collect()); match mode.as_str() { "serve" => serve(parse_peer_config(&options)?)?, "probe" => probe(&options)?, "dial" => dial(parse_dial_config(&options)?)?, + "rudp-serve-once" => rudp_serve_once(&options)?, + "rudp-dial-once" => rudp_dial_once(&options)?, + "rudp-serve-message-once" => rudp_serve_message_once(&options)?, + "rudp-dial-message-once" => rudp_dial_message_once(&options)?, _ => return Err(anyhow!("unknown mode {mode}")), } @@ -244,7 +270,13 @@ fn serve(config: PeerConfig) -> Result<()> { let config = Arc::new(config); start_udp_discovery_server(config.clone())?; - start_tcp_server(config.clone(), cache, document_registry, schema_registry)?; + start_tcp_server( + config.clone(), + cache.clone(), + document_registry.clone(), + schema_registry.clone(), + )?; + start_rudp_server(config.clone(), cache, document_registry, schema_registry)?; print_json(&serde_json::json!({ "status": "ready", @@ -252,6 +284,7 @@ fn serve(config: PeerConfig) -> Result<()> { "runtimeId": config.runtime_id, "runtimeKind": config.runtime_kind, "tcpPort": config.tcp_port, + "rudpPort": config.rudp_port, "discoveryPort": config.discovery_port, "discoveryGroup": config.discovery_group.to_string(), }))?; @@ -296,6 +329,7 @@ fn probe(options: &BTreeMap) -> Result<()> { tcp_port, wire_contract, supported_document_types, + transport_profiles, supports_schema_catalog, }) = rmp_serde::from_slice::(&buffer[..len]) { @@ -313,6 +347,7 @@ fn probe(options: &BTreeMap) -> Result<()> { "tcpPort": tcp_port, "wireContract": wire_contract, "supportedDocumentTypes": supported_document_types, + "transportProfiles": transport_profiles, "supportsSchemaCatalog": supports_schema_catalog, }), ); @@ -351,51 +386,43 @@ fn dial(config: DialConfig) -> Result<()> { let mut document_registry = CultNetDocumentRegistry::new(); register_capability_bindings(&mut document_registry, &schema_registration.schema_id); - let mut stream = TcpStream::connect((config.target_host.as_str(), config.target_port)) - .with_context(|| { - format!( - "failed to connect to {}:{}", - config.target_host, config.target_port - ) - })?; + let transport_name = if config.target_rudp_port.is_some() { + "rudp" + } else { + "tcp" + }; + let mut transport = open_dial_transport(&config)?; - send_message( - &mut stream, - &CultNetMessage::Hello { - runtime_id: config.runtime_id.clone(), - runtime_kind: config.runtime_kind.clone(), - agent_id: Some(config.agent_id.clone()), - role: None, - display_name: Some(config.display_name.clone()), - supported_document_types: Some(vec![INTEROP_DOCUMENT_TYPE.to_string()]), - supported_mutation_contracts: Some(interaction_contracts()), - supported_message_versions: Some(vec![INTEROP_SCHEMA_VERSION.to_string()]), - transport_profiles: Some(tcp_framed_transport_profiles( - &config.runtime_id, - None, - None, - None, - )), - supports_schema_catalog: Some(true), - }, - )?; + transport.send_schema_message(&CultNetMessage::Hello { + runtime_id: config.runtime_id.clone(), + runtime_kind: config.runtime_kind.clone(), + agent_id: Some(config.agent_id.clone()), + role: None, + display_name: Some(config.display_name.clone()), + supported_document_types: Some(vec![INTEROP_DOCUMENT_TYPE.to_string()]), + supported_mutation_contracts: Some(interaction_contracts()), + supported_message_versions: Some(vec![INTEROP_SCHEMA_VERSION.to_string()]), + transport_profiles: Some(dial_transport_profiles(&config)), + supports_schema_catalog: Some(true), + })?; - let remote_hello = read_message(&mut stream)?; + let remote_hello = transport + .read_schema_message() + .context("waiting for remote hello")?; let remote_runtime_id = match &remote_hello { CultNetMessage::Hello { runtime_id, .. } => runtime_id.clone(), other => return Err(anyhow!("expected hello response, got {other:?}")), }; - send_message( - &mut stream, - &CultNetMessage::SchemaCatalogRequest { - message_id: format!("{}-catalog", config.runtime_id), - include_schema_json: Some(true), - schema_ids: None, - kinds: None, - }, - )?; - let catalog_response = read_message(&mut stream)?; + transport.send_schema_message(&CultNetMessage::SchemaCatalogRequest { + message_id: format!("{}-catalog", config.runtime_id), + include_schema_json: Some(true), + schema_ids: None, + kinds: None, + })?; + let catalog_response = transport + .read_schema_message() + .context("waiting for schema catalog response")?; let has_interop_schema = match &catalog_response { CultNetMessage::SchemaCatalogResponse { schemas, .. } => schemas.iter().any(|schema| { schema.schema_id == schema_registration.schema_id @@ -404,15 +431,14 @@ fn dial(config: DialConfig) -> Result<()> { other => return Err(anyhow!("expected catalog response, got {other:?}")), }; - send_message( - &mut stream, - &CultNetMessage::SnapshotRequest { - message_id: format!("{}-snapshot", config.runtime_id), - schema_ids: Some(vec![schema_registration.schema_id.clone()]), - record_keys: None, - }, - )?; - let snapshot_response = read_message(&mut stream)?; + transport.send_schema_message(&CultNetMessage::SnapshotRequest { + message_id: format!("{}-snapshot", config.runtime_id), + schema_ids: Some(vec![schema_registration.schema_id.clone()]), + record_keys: None, + })?; + let snapshot_response = transport + .read_schema_message() + .context("waiting for snapshot response")?; let applied = document_registry .apply_raw_snapshot_response::(&mut cache, &snapshot_response)?; let note = applied @@ -422,9 +448,10 @@ fn dial(config: DialConfig) -> Result<()> { print_json(&serde_json::json!({ "mode": "dial", + "transport": transport_name, "runtimeId": config.runtime_id, "targetHost": config.target_host, - "targetPort": config.target_port, + "targetPort": config.target_rudp_port.or(config.target_port), "remoteHello": { "schemaVersion": "cultnet.hello.v0", "runtimeId": remote_runtime_id, @@ -438,14 +465,289 @@ fn dial(config: DialConfig) -> Result<()> { "body": note.body, "tags": note.tags, }, - "mutatedNote": mutate_remote_note(&mut stream, &mut cache, &document_registry, &schema_registration.schema_id, &config.runtime_id, ¬e)?, - "fireReceipt": fire_remote_weapon(&mut stream, &mut cache, &document_registry, &config.runtime_id, &remote_runtime_id)?, + "mutatedNote": mutate_remote_note(&mut *transport, &mut cache, &document_registry, &schema_registration.schema_id, &config.runtime_id, ¬e)?, + "fireReceipt": fire_remote_weapon(&mut *transport, &mut cache, &document_registry, &config.runtime_id, &remote_runtime_id)?, }))?; Ok(()) } +fn rudp_serve_once(options: &BTreeMap) -> Result<()> { + let bind_host = options + .get("bind-host") + .cloned() + .unwrap_or_else(|| "127.0.0.1".to_string()); + let bind_port = options + .get("bind-port") + .map(|value| value.parse::()) + .transpose() + .with_context(|| "argument --bind-port must be a u16")? + .unwrap_or(0); + let expected_client_payload = options + .get("client-payload") + .map(|value| value.as_bytes().to_vec()) + .unwrap_or_else(|| b"ts-rust-client-state".to_vec()); + let server_payload = options + .get("server-payload") + .map(|value| value.as_bytes().to_vec()) + .unwrap_or_else(|| b"rust-server-state".to_vec()); + let server_extra_payload = options + .get("server-extra-payload") + .map(|value| value.as_bytes().to_vec()); + let disconnect_reason = options + .get("disconnect-reason") + .map(|value| value.as_bytes().to_vec()); + let max_fragment_bytes = options + .get("max-fragment-bytes") + .map(|value| value.parse::()) + .transpose() + .with_context(|| "argument --max-fragment-bytes must be a u32")?; + let socket = UdpSocket::bind((bind_host.as_str(), bind_port)) + .with_context(|| format!("failed to bind RUDP server on {bind_host}:{bind_port}"))?; + socket.set_read_timeout(Some(Duration::from_millis(20)))?; + let local_port = socket.local_addr()?.port(); + let mut transport_options = + CultNetRudpSocketTransportOptions::server("rust-rudp-interop", socket, 0x22446688); + transport_options.initial_sequence = 100; + transport_options.resend_delay_ms = 25; + transport_options.max_fragment_bytes = max_fragment_bytes; + let mut transport = CultNetRudpSocketTransportConnection::new(transport_options)?; + + print_json(&serde_json::json!({ + "status": "ready", + "port": local_port, + }))?; + + let deadline = Instant::now() + Duration::from_secs(5); + while Instant::now() < deadline { + if let Some(frame) = transport.receive_once()? { + if frame.channel_id != "schema" || frame.payload != expected_client_payload { + return Err(anyhow!( + "unexpected RUDP frame: channel={} payload={:?}", + frame.channel_id, + frame.payload + )); + } + transport.send("schema", server_payload.clone())?; + if let Some(extra_payload) = &server_extra_payload { + transport.send("schema", extra_payload.clone())?; + } + if let Some(reason) = &disconnect_reason { + transport.disconnect(reason.clone())?; + } + poll_rudp_after_send(&mut transport, Duration::from_millis(250))?; + print_json(&serde_json::json!({ "status": "ok" }))?; + return Ok(()); + } + transport.poll_resends()?; + thread::sleep(Duration::from_millis(5)); + } + + Err(anyhow!("timed out waiting for TypeScript RUDP frame")) +} + +fn rudp_dial_once(options: &BTreeMap) -> Result<()> { + let target_host = require_arg(options, "target-host")?; + let target_port = parse_u16_arg(options, "target-port")?; + let remote_addr: SocketAddr = format!("{target_host}:{target_port}") + .parse() + .with_context(|| { + format!("failed to parse RUDP remote endpoint {target_host}:{target_port}") + })?; + let socket = UdpSocket::bind(("127.0.0.1", 0))?; + socket.set_read_timeout(Some(Duration::from_millis(20)))?; + let mut transport_options = CultNetRudpSocketTransportOptions::client( + "rust-rudp-client-interop", + socket, + remote_addr, + 0x88664422, + ); + transport_options.resend_delay_ms = 25; + let mut transport = CultNetRudpSocketTransportConnection::new(transport_options)?; + transport.connect(b"rust-join".to_vec())?; + + let mut sent = false; + let deadline = Instant::now() + Duration::from_secs(5); + while Instant::now() < deadline { + if let Some(frame) = transport.receive_once()? { + if frame.channel_id != "schema" || frame.payload != b"ts-rust-server-state" { + return Err(anyhow!( + "unexpected RUDP frame: channel={} payload={:?}", + frame.channel_id, + frame.payload + )); + } + print_json(&serde_json::json!({ "status": "ok" }))?; + return Ok(()); + } + transport.poll_resends()?; + if transport.connected() && !sent { + transport.send("schema", b"rust-client-state".to_vec())?; + sent = true; + } + thread::sleep(Duration::from_millis(5)); + } + + Err(anyhow!("timed out waiting for TypeScript RUDP response")) +} + +fn rudp_serve_message_once(options: &BTreeMap) -> Result<()> { + let bind_host = options + .get("bind-host") + .cloned() + .unwrap_or_else(|| "127.0.0.1".to_string()); + let bind_port = options + .get("bind-port") + .map(|value| value.parse::()) + .transpose() + .with_context(|| "argument --bind-port must be a u16")? + .unwrap_or(0); + let socket = UdpSocket::bind((bind_host.as_str(), bind_port)).with_context(|| { + format!("failed to bind RUDP message server on {bind_host}:{bind_port}") + })?; + socket.set_read_timeout(Some(Duration::from_millis(20)))?; + let local_port = socket.local_addr()?.port(); + let mut transport_options = + CultNetRudpSocketTransportOptions::server("rust-rudp-message-interop", socket, 0x22446689); + transport_options.initial_sequence = 100; + transport_options.resend_delay_ms = 25; + let mut transport = CultNetRudpSocketTransportConnection::new(transport_options)?; + + print_json(&serde_json::json!({ + "status": "ready", + "port": local_port, + }))?; + + let deadline = Instant::now() + Duration::from_secs(5); + while Instant::now() < deadline { + if let Some(frame) = transport.receive_once()? { + if frame.channel_id != "schema" { + return Err(anyhow!("unexpected RUDP channel: {}", frame.channel_id)); + } + let message = decode_cultnet_message_from_slice( + &frame.payload, + CultNetWireContract::CultNetSchemaV0, + )?; + let CultNetMessage::SchemaCatalogRequest { .. } = message else { + return Err(anyhow!("unexpected schema message: {message:?}")); + }; + let response = CultNetMessage::Hello { + runtime_id: "rust-rudp-message-interop".to_string(), + runtime_kind: "rust".to_string(), + agent_id: None, + role: None, + display_name: Some("Rust RUDP Message Interop".to_string()), + supported_document_types: Some(vec![]), + supported_mutation_contracts: Some(vec![]), + supported_message_versions: Some(vec![ + "cultnet.hello.v0".to_string(), + "cultnet.schema_catalog_request.v0".to_string(), + ]), + transport_profiles: Some(vec![create_rudp_transport_profile( + "rust-rudp-message-interop", + RudpTransportProfileOptions { + host: Some("127.0.0.1".to_string()), + port: Some(local_port), + ..RudpTransportProfileOptions::default() + }, + )]), + supports_schema_catalog: Some(true), + }; + transport.send( + "schema", + encode_cultnet_message_to_vec(&response, CultNetWireContract::CultNetSchemaV0)?, + )?; + poll_rudp_after_send(&mut transport, Duration::from_millis(250))?; + print_json(&serde_json::json!({ "status": "ok" }))?; + return Ok(()); + } + transport.poll_resends()?; + thread::sleep(Duration::from_millis(5)); + } + + Err(anyhow!( + "timed out waiting for TypeScript RUDP schema-v0 message" + )) +} + +fn rudp_dial_message_once(options: &BTreeMap) -> Result<()> { + let target_host = require_arg(options, "target-host")?; + let target_port = parse_u16_arg(options, "target-port")?; + let remote_addr: SocketAddr = format!("{target_host}:{target_port}") + .parse() + .with_context(|| { + format!("failed to parse RUDP remote endpoint {target_host}:{target_port}") + })?; + let socket = UdpSocket::bind(("127.0.0.1", 0))?; + socket.set_read_timeout(Some(Duration::from_millis(20)))?; + let mut transport_options = CultNetRudpSocketTransportOptions::client( + "rust-rudp-message-client-interop", + socket, + remote_addr, + 0x88664423, + ); + transport_options.resend_delay_ms = 25; + let mut transport = CultNetRudpSocketTransportConnection::new(transport_options)?; + transport.connect(b"rust-message-join".to_vec())?; + + let request = CultNetMessage::SchemaCatalogRequest { + message_id: "rust-ts-schema-message".to_string(), + include_schema_json: Some(false), + schema_ids: Some(vec![]), + kinds: Some(vec![CultNetSchemaKind::WireMessage]), + }; + + let mut sent = false; + let deadline = Instant::now() + Duration::from_secs(5); + while Instant::now() < deadline { + if let Some(frame) = transport.receive_once()? { + if frame.channel_id != "schema" { + return Err(anyhow!("unexpected RUDP channel: {}", frame.channel_id)); + } + let message = decode_cultnet_message_from_slice( + &frame.payload, + CultNetWireContract::CultNetSchemaV0, + )?; + match message { + CultNetMessage::Hello { runtime_id, .. } + if runtime_id == "ts-rust-rudp-message-server" => + { + print_json(&serde_json::json!({ "status": "ok" }))?; + return Ok(()); + } + other => return Err(anyhow!("unexpected schema message: {other:?}")), + } + } + transport.poll_resends()?; + if transport.connected() && !sent { + transport.send( + "schema", + encode_cultnet_message_to_vec(&request, CultNetWireContract::CultNetSchemaV0)?, + )?; + sent = true; + } + thread::sleep(Duration::from_millis(5)); + } + + Err(anyhow!( + "timed out waiting for TypeScript RUDP schema-v0 response" + )) +} + +fn poll_rudp_after_send( + transport: &mut CultNetRudpSocketTransportConnection, + duration: Duration, +) -> Result<()> { + let deadline = Instant::now() + duration; + while Instant::now() < deadline { + let _ = transport.receive_once()?; + transport.poll_resends()?; + thread::sleep(Duration::from_millis(5)); + } + Ok(()) +} + fn mutate_remote_note( - stream: &mut TcpStream, + transport: &mut dyn SchemaMessageTransport, cache: &mut CultCache, document_registry: &CultNetDocumentRegistry, note_schema_id: &str, @@ -465,12 +767,16 @@ fn mutate_remote_note( &intent, CultNetDocumentPutOptions::default(), )?; - send_message(stream, &message)?; + transport.send_schema_message(&message)?; - let receipt_message = read_message(stream)?; + let receipt_message = transport + .read_schema_message() + .context("waiting for mutation receipt")?; let _receipt = document_registry .apply_raw_document_put_message::(cache, &receipt_message)?; - let mutated_message = read_message(stream)?; + let mutated_message = transport + .read_schema_message() + .context("waiting for mutated note")?; let mutated = document_registry .apply_raw_document_put_message::(cache, &mutated_message)?; if mutated_message_schema_id(&mutated_message) != Some(note_schema_id) { @@ -487,7 +793,7 @@ fn mutate_remote_note( } fn fire_remote_weapon( - stream: &mut TcpStream, + transport: &mut dyn SchemaMessageTransport, cache: &mut CultCache, document_registry: &CultNetDocumentRegistry, runtime_id: &str, @@ -505,8 +811,10 @@ fn fire_remote_weapon( &command, CultNetDocumentPutOptions::default(), )?; - send_message(stream, &message)?; - let receipt_message = read_message(stream)?; + transport.send_schema_message(&message)?; + let receipt_message = transport + .read_schema_message() + .context("waiting for fire receipt")?; let receipt = document_registry .apply_raw_document_put_message::(cache, &receipt_message)?; Ok(serde_json::json!({ @@ -545,6 +853,12 @@ fn start_udp_discovery_server(config: Arc) -> Result<()> { tcp_port: config.tcp_port, wire_contract: "cultnet.schema.v0".to_string(), supported_document_types: vec![INTEROP_DOCUMENT_TYPE.to_string()], + transport_profiles: Some(interop_transport_profiles( + &config.runtime_id, + &config.advertise_host, + config.tcp_port, + config.rudp_port, + )), supports_schema_catalog: true, }; if let Ok(payload) = rmp_serde::to_vec_named(&announce) { @@ -600,81 +914,216 @@ fn start_tcp_server( Ok(()) } -fn handle_connection( - mut stream: TcpStream, +fn start_rudp_server( config: Arc, cache: Arc>, document_registry: Arc, schema_registry: Arc, ) -> Result<()> { + let socket = + UdpSocket::bind((config.bind_host.as_str(), config.rudp_port)).with_context(|| { + format!( + "failed to bind RUDP listener on {}:{}", + config.bind_host, config.rudp_port + ) + })?; + socket.set_read_timeout(Some(Duration::from_millis(20)))?; + + thread::spawn(move || { + if let Err(error) = + run_rudp_server(socket, config, cache, document_registry, schema_registry) + { + eprintln!("{error:#}"); + } + }); + + Ok(()) +} + +struct RudpPeerSession { + session: CultNetRudpSession, +} + +fn run_rudp_server( + socket: UdpSocket, + config: Arc, + cache: Arc>, + document_registry: Arc, + schema_registry: Arc, +) -> Result<()> { + let mut peers = BTreeMap::::new(); + let mut buffer = vec![0_u8; 65_535]; loop { - let message = match read_message(&mut stream) { + match socket.recv_from(&mut buffer) { + Ok((len, remote_addr)) => { + let packet = match decode_rudp_packet(&buffer[..len]) { + Ok(packet) if packet.connection_id == RUDP_INTEROP_CONNECTION_ID => packet, + Ok(_) => continue, + Err(error) => { + eprintln!("{error:#}"); + continue; + } + }; + let peer = peers.entry(remote_addr).or_insert_with(|| RudpPeerSession { + session: CultNetRudpSession::new(CultNetRudpSessionOptions { + connection_id: RUDP_INTEROP_CONNECTION_ID, + initial_sequence: 100, + resend_delay_ms: RUDP_INTEROP_RESEND_DELAY_MS, + max_pending_reliable_packets: None, + }), + }); + if packet.packet_type == CultNetRudpPacketType::Connect { + let accept = peer.session.accept_connect( + &packet, + rudp_now_ms(), + b"cultnet-interop-rudp".to_vec(), + )?; + send_rudp_packet(&socket, remote_addr, &accept)?; + continue; + } + + let result = peer.session.receive(&packet, rudp_now_ms())?; + if let Some(reply) = result.reply { + send_rudp_packet(&socket, remote_addr, &reply)?; + } + if packet.packet_type == CultNetRudpPacketType::Data { + let ack = peer.session.create_ack(); + send_rudp_packet(&socket, remote_addr, &ack)?; + } + for frame in result.delivered { + if frame.channel_id != "schema" { + continue; + } + let message = decode_cultnet_message_from_slice( + &frame.payload, + CultNetWireContract::CultNetSchemaV0, + )?; + let mut transport = RudpSessionSender { + socket: &socket, + remote_addr, + session: &mut peer.session, + }; + handle_server_message( + &mut transport, + message, + &config, + &cache, + &document_registry, + &schema_registry, + )?; + } + } + Err(error) + if error.kind() == std::io::ErrorKind::WouldBlock + || error.kind() == std::io::ErrorKind::TimedOut + || error.kind() == std::io::ErrorKind::ConnectionReset => + { + let now = rudp_now_ms(); + for (remote_addr, peer) in peers.iter_mut() { + for packet in peer.session.due_resends(now) { + send_rudp_packet(&socket, *remote_addr, &packet)?; + } + } + } + Err(error) => return Err(error.into()), + } + } +} + +fn handle_connection( + stream: TcpStream, + config: Arc, + cache: Arc>, + document_registry: Arc, + schema_registry: Arc, +) -> Result<()> { + let mut transport = TcpFramedTransportConnection::new( + stream, + tcp_transport_profile(&config.runtime_id, &config.advertise_host, config.tcp_port), + ); + loop { + let message = match transport.read_schema_message() { Ok(message) => message, Err(error) if is_eof_like(&error) => break, Err(error) => return Err(error), }; - match message { - CultNetMessage::Hello { .. } => { - send_message( - &mut stream, - &CultNetMessage::Hello { - runtime_id: config.runtime_id.clone(), - runtime_kind: config.runtime_kind.clone(), - agent_id: Some(config.agent_id.clone()), - role: None, - display_name: Some(config.display_name.clone()), - supported_document_types: Some(vec![INTEROP_DOCUMENT_TYPE.to_string()]), - supported_mutation_contracts: Some(interaction_contracts()), - supported_message_versions: Some(vec![INTEROP_SCHEMA_VERSION.to_string()]), - transport_profiles: Some(tcp_framed_transport_profiles( - &config.runtime_id, - Some(&config.advertise_host), - Some(config.tcp_port), - Some(config.discovery_group), - )), - supports_schema_catalog: Some(true), - }, - )?; - } - request @ CultNetMessage::SchemaCatalogRequest { .. } => { - let response = schema_registry.create_catalog_response(&request)?; - send_message(&mut stream, &response)?; - } - CultNetMessage::SnapshotRequest { - message_id, - schema_ids, - record_keys, - } => { - let mut response = document_registry.create_raw_snapshot_response( - &cache.lock().expect("cache poisoned"), - message_id, - schema_ids.as_deref(), - record_keys.as_deref(), - )?; - if let CultNetMessage::SnapshotResponseRaw { documents, .. } = &mut response { - for document in documents.iter_mut() { - document.source_runtime_id = Some(config.runtime_id.clone()); - document.source_agent_id = Some(config.agent_id.clone()); - document.source_role = Some("peer".to_string()); - document.tags = - Some(vec!["interop".to_string(), config.runtime_id.clone()]); - } - } - send_message(&mut stream, &response)?; - } - message @ CultNetMessage::DocumentPutRaw { .. } => { - handle_raw_put(&mut stream, &config, &cache, &document_registry, &message)?; - } - _ => {} - } + handle_server_message( + &mut transport, + message, + &config, + &cache, + &document_registry, + &schema_registry, + )?; } Ok(()) } +fn handle_server_message( + transport: &mut dyn SchemaMessageSender, + message: CultNetMessage, + config: &PeerConfig, + cache: &Arc>, + document_registry: &CultNetDocumentRegistry, + schema_registry: &CultNetSchemaRegistry, +) -> Result<()> { + match message { + CultNetMessage::Hello { .. } => { + transport.send_schema_message(&CultNetMessage::Hello { + runtime_id: config.runtime_id.clone(), + runtime_kind: config.runtime_kind.clone(), + agent_id: Some(config.agent_id.clone()), + role: None, + display_name: Some(config.display_name.clone()), + supported_document_types: Some(vec![INTEROP_DOCUMENT_TYPE.to_string()]), + supported_mutation_contracts: Some(interaction_contracts()), + supported_message_versions: Some(vec![INTEROP_SCHEMA_VERSION.to_string()]), + transport_profiles: Some(interop_transport_profiles( + &config.runtime_id, + &config.advertise_host, + config.tcp_port, + config.rudp_port, + )), + supports_schema_catalog: Some(true), + })?; + } + request @ CultNetMessage::SchemaCatalogRequest { .. } => { + let response = schema_registry.create_catalog_response(&request)?; + transport.send_schema_message(&response)?; + } + CultNetMessage::SnapshotRequest { + message_id, + schema_ids, + record_keys, + } => { + let mut response = document_registry.create_raw_snapshot_response( + &cache.lock().expect("cache poisoned"), + message_id, + schema_ids.as_deref(), + record_keys.as_deref(), + )?; + if let CultNetMessage::SnapshotResponseRaw { documents, .. } = &mut response { + for document in documents.iter_mut() { + document.source_runtime_id = Some(config.runtime_id.clone()); + document.source_agent_id = Some(config.agent_id.clone()); + document.source_role = Some("peer".to_string()); + document.tags = Some(vec!["interop".to_string(), config.runtime_id.clone()]); + } + } + transport.send_schema_message(&response)?; + } + message @ CultNetMessage::DocumentPutRaw { .. } => { + handle_raw_put(transport, config, cache, document_registry, &message)?; + } + _ => {} + } + Ok(()) +} + fn handle_raw_put( - stream: &mut TcpStream, + transport: &mut dyn SchemaMessageSender, config: &PeerConfig, cache: &Arc>, document_registry: &CultNetDocumentRegistry, @@ -712,8 +1161,8 @@ fn handle_raw_put( ¬e, options, )?; - send_message(stream, &receipt_message)?; - send_message(stream, ¬e_message)?; + transport.send_schema_message(&receipt_message)?; + transport.send_schema_message(¬e_message)?; } else if document.schema_id == FIRE_COMMAND_SCHEMA_ID { let mut cache = cache.lock().expect("cache poisoned"); let command = document_registry @@ -733,7 +1182,7 @@ fn handle_raw_put( &receipt, response_options(config, "side-effect"), )?; - send_message(stream, &receipt_message)?; + transport.send_schema_message(&receipt_message)?; } Ok(()) } @@ -832,45 +1281,103 @@ fn interaction_contracts() -> Vec { }] } -fn tcp_framed_transport_profiles( +fn tcp_transport_profile(runtime_id: &str, host: &str, port: u16) -> CultNetTransportProfile { + create_tcp_framed_transport_profile( + runtime_id, + TcpFramedTransportProfileOptions { + transport_id: Some("interop-tcp".to_string()), + host: Some(host.to_string()), + port: Some(port), + ..TcpFramedTransportProfileOptions::default() + }, + ) +} + +fn rudp_transport_profile(runtime_id: &str, host: &str, port: u16) -> CultNetTransportProfile { + create_rudp_transport_profile( + runtime_id, + RudpTransportProfileOptions { + transport_id: Some("interop-rudp".to_string()), + host: Some(host.to_string()), + port: Some(port), + max_fragment_bytes: Some(RUDP_INTEROP_MAX_FRAGMENT_BYTES as u32), + ..RudpTransportProfileOptions::default() + }, + ) +} + +fn interop_transport_profiles( runtime_id: &str, - host: Option<&str>, - port: Option, - discovery_group: Option, + host: &str, + tcp_port: u16, + rudp_port: u16, ) -> Vec { - vec![CultNetTransportProfile { - schema_version: "cultnet.transport_profile.v0".to_string(), - runtime_id: runtime_id.to_string(), - transports: vec![CultNetTransportDescriptor { - transport_id: "interop-tcp-framed".to_string(), - protocol: CultNetTransportProtocol::TcpFramed, - host: host.map(ToString::to_string), - port, - path: None, - discovery_group: discovery_group.map(|group| group.to_string()), - wire_contracts: Some(vec!["cultnet.schema.v0".to_string()]), - channels: vec![ - CultNetTransportChannel { - channel_id: "schema".to_string(), - delivery: CultNetTransportDelivery::Reliable, - ordering: CultNetTransportOrdering::Ordered, - max_payload_bytes: None, - max_fragment_bytes: None, - max_pending_reliable_packets: None, - reliable_expire_after_ms: None, - }, - CultNetTransportChannel { - channel_id: "state".to_string(), - delivery: CultNetTransportDelivery::Reliable, - ordering: CultNetTransportOrdering::Ordered, - max_payload_bytes: None, - max_fragment_bytes: None, - max_pending_reliable_packets: None, - reliable_expire_after_ms: None, - }, - ], - }], - }] + vec![ + tcp_transport_profile(runtime_id, host, tcp_port), + rudp_transport_profile(runtime_id, host, rudp_port), + ] +} + +fn dial_transport_profiles(config: &DialConfig) -> Vec { + let mut profiles = Vec::new(); + if let Some(target_port) = config.target_port { + profiles.push(tcp_transport_profile( + &config.runtime_id, + &config.target_host, + target_port, + )); + } + if let Some(target_rudp_port) = config.target_rudp_port { + profiles.push(rudp_transport_profile( + &config.runtime_id, + &config.target_host, + target_rudp_port, + )); + } + profiles +} + +fn open_dial_transport(config: &DialConfig) -> Result> { + if let Some(target_rudp_port) = config.target_rudp_port { + let remote_addr: SocketAddr = format!("{}:{}", config.target_host, target_rudp_port) + .parse() + .with_context(|| { + format!( + "failed to parse RUDP remote endpoint {}:{}", + config.target_host, target_rudp_port + ) + })?; + let socket = UdpSocket::bind(("127.0.0.1", 0))?; + socket.set_read_timeout(Some(Duration::from_millis(20)))?; + let mut options = CultNetRudpSocketTransportOptions::client( + format!("{}-interop-rudp-dial", config.runtime_id), + socket, + remote_addr, + RUDP_INTEROP_CONNECTION_ID, + ); + options.transport_id = Some("interop-rudp".to_string()); + options.resend_delay_ms = RUDP_INTEROP_RESEND_DELAY_MS; + options.max_fragment_bytes = Some(RUDP_INTEROP_MAX_FRAGMENT_BYTES as u32); + let mut transport = CultNetRudpSocketTransportConnection::new(options)?; + transport.connect(b"cultnet-interop-rudp".to_vec())?; + wait_for_rudp_connected(&mut transport, Duration::from_secs(5))?; + return Ok(Box::new(transport)); + } + + let target_port = config + .target_port + .ok_or_else(|| anyhow!("dial requires --target-port or --target-rudp-port"))?; + let stream = + TcpStream::connect((config.target_host.as_str(), target_port)).with_context(|| { + format!( + "failed to connect to {}:{}", + config.target_host, target_port + ) + })?; + Ok(Box::new(TcpFramedTransportConnection::new( + stream, + tcp_transport_profile(&config.runtime_id, &config.target_host, target_port), + ))) } fn response_options(config: &PeerConfig, tag: &str) -> CultNetDocumentPutOptions { @@ -907,29 +1414,108 @@ fn build_note(runtime_id: &str, display_name: &str) -> CultNetInteropNote { } } -fn send_message(stream: &mut TcpStream, message: &CultNetMessage) -> Result<()> { - let payload = encode_cultnet_message_to_vec(message, CultNetWireContract::CultNetSchemaV0)?; - let frame = encode_frame(&payload)?; - stream.write_all(&frame)?; - stream.flush()?; - Ok(()) -} - -fn read_message(stream: &mut TcpStream) -> Result { - let mut header = [0_u8; 4]; - stream.read_exact(&mut header)?; - let payload_len = u32::from_be_bytes(header) as usize; - let mut payload = vec![0_u8; payload_len]; - stream.read_exact(&mut payload)?; - decode_cultnet_message_from_slice(&payload, CultNetWireContract::CultNetSchemaV0) -} - fn is_eof_like(error: &anyhow::Error) -> bool { error .downcast_ref::() .is_some_and(|io| io.kind() == std::io::ErrorKind::UnexpectedEof) } +impl SchemaMessageSender for TcpFramedTransportConnection { + fn send_schema_message(&mut self, message: &CultNetMessage) -> Result<()> { + let payload = encode_cultnet_message_to_vec(message, CultNetWireContract::CultNetSchemaV0)?; + self.send("schema", &payload) + } +} + +impl SchemaMessageTransport for TcpFramedTransportConnection { + fn read_schema_message(&mut self) -> Result { + let frame = self.receive()?; + decode_cultnet_message_from_slice(&frame.payload, CultNetWireContract::CultNetSchemaV0) + } +} + +impl SchemaMessageSender for CultNetRudpSocketTransportConnection { + fn send_schema_message(&mut self, message: &CultNetMessage) -> Result<()> { + CultNetRudpSocketTransportConnection::send_schema_message(self, message) + } +} + +impl SchemaMessageTransport for CultNetRudpSocketTransportConnection { + fn read_schema_message(&mut self) -> Result { + let deadline = Instant::now() + RUDP_INTEROP_READ_TIMEOUT; + while Instant::now() < deadline { + if let Some(message) = self.receive_schema_message_once()? { + return Ok(message); + } + self.poll_resends()?; + thread::sleep(Duration::from_millis(5)); + } + Err(anyhow!("timed out waiting for RUDP schema message")) + } +} + +struct RudpSessionSender<'a> { + socket: &'a UdpSocket, + remote_addr: SocketAddr, + session: &'a mut CultNetRudpSession, +} + +impl SchemaMessageSender for RudpSessionSender<'_> { + fn send_schema_message(&mut self, message: &CultNetMessage) -> Result<()> { + let payload = encode_cultnet_message_to_vec(message, CultNetWireContract::CultNetSchemaV0)?; + let packets = self.session.send_many( + "schema", + payload, + CultNetRudpSendOptions { + reliable: true, + ordered: true, + sequenced: false, + now_ms: rudp_now_ms(), + }, + Some(RUDP_INTEROP_MAX_FRAGMENT_BYTES), + )?; + for packet in packets { + send_rudp_packet(self.socket, self.remote_addr, &packet)?; + } + Ok(()) + } +} + +fn send_rudp_packet( + socket: &UdpSocket, + remote_addr: SocketAddr, + packet: &cultnet_rs::CultNetRudpPacket, +) -> Result<()> { + socket.send_to(&encode_rudp_packet(packet)?, remote_addr)?; + Ok(()) +} + +fn wait_for_rudp_connected( + transport: &mut CultNetRudpSocketTransportConnection, + timeout: Duration, +) -> Result<()> { + let deadline = Instant::now() + timeout; + while Instant::now() < deadline { + if transport.connected() { + return Ok(()); + } + let _ = transport.receive_once()?; + transport.poll_resends()?; + thread::sleep(Duration::from_millis(5)); + } + Err(anyhow!("timed out waiting for RUDP connect")) +} + +fn rudp_now_ms() -> u64 { + use std::time::SystemTime; + use std::time::UNIX_EPOCH; + + SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_millis() as u64 +} + fn create_discovery_socket(port: u16, _join_group: bool) -> Result { let socket = Socket::new(Domain::IPV4, Type::DGRAM, Some(Protocol::UDP))?; socket.set_reuse_address(true)?; @@ -942,6 +1528,7 @@ fn create_discovery_socket(port: u16, _join_group: bool) -> Result { } fn parse_peer_config(options: &BTreeMap) -> Result { + let tcp_port = parse_u16_arg(options, "tcp-port")?; Ok(PeerConfig { runtime_id: require_arg(options, "runtime-id")?.to_string(), runtime_kind: require_arg(options, "runtime-kind")?.to_string(), @@ -952,7 +1539,13 @@ fn parse_peer_config(options: &BTreeMap) -> Result { .cloned() .unwrap_or_else(|| "127.0.0.1".to_string()), advertise_host: require_arg(options, "advertise-host")?.to_string(), - tcp_port: parse_u16_arg(options, "tcp-port")?, + tcp_port, + rudp_port: options + .get("rudp-port") + .map(|value| value.parse::()) + .transpose() + .with_context(|| "argument --rudp-port must be a u16")? + .unwrap_or(tcp_port), discovery_port: parse_u16_arg(options, "discovery-port")?, discovery_group: parse_ipv4_arg(options, "discovery-group")?, schema_path: require_arg(options, "schema-path")?.to_string(), @@ -966,7 +1559,16 @@ fn parse_dial_config(options: &BTreeMap) -> Result { display_name: require_arg(options, "display-name")?.to_string(), agent_id: require_arg(options, "agent-id")?.to_string(), target_host: require_arg(options, "target-host")?.to_string(), - target_port: parse_u16_arg(options, "target-port")?, + target_port: options + .get("target-port") + .map(|value| value.parse::()) + .transpose() + .with_context(|| "argument --target-port must be a u16")?, + target_rudp_port: options + .get("target-rudp-port") + .map(|value| value.parse::()) + .transpose() + .with_context(|| "argument --target-rudp-port must be a u16")?, schema_path: require_arg(options, "schema-path")?.to_string(), }) } @@ -1017,7 +1619,7 @@ fn parse_ipv4_arg(options: &BTreeMap, name: &str) -> Result std::path::PathBuf { - std::env::temp_dir().join(format!("cultnet-rs-interop-{runtime_id}.cc")) + std::env::temp_dir().join(format!("cultnet-rs-interop-{runtime_id}.msgpack")) } fn print_json(value: &serde_json::Value) -> Result<()> { diff --git a/vendor/cultnet-rs/src/contracts.rs b/vendor/cultnet-rs/src/contracts.rs index 460764d..e637883 100644 --- a/vendor/cultnet-rs/src/contracts.rs +++ b/vendor/cultnet-rs/src/contracts.rs @@ -104,9 +104,23 @@ pub struct CultNetTransportDescriptor { pub discovery_group: Option, #[serde(default, skip_serializing_if = "Option::is_none")] pub wire_contracts: Option>, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub reconnect_policy: Option, pub channels: Vec, } +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct CultNetReconnectPolicy { + pub schema_version: String, + pub policy_id: String, + pub base_delay_ms: u64, + pub max_delay_ms: u64, + pub max_jitter_ms: u64, + #[serde(skip_serializing_if = "Option::is_none")] + pub max_attempts: Option, +} + #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum CultNetTransportProtocol { @@ -128,8 +142,6 @@ pub struct CultNetTransportChannel { pub max_fragment_bytes: Option, #[serde(default, skip_serializing_if = "Option::is_none")] pub max_pending_reliable_packets: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub reliable_expire_after_ms: Option, } #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] @@ -183,6 +195,53 @@ pub struct CultNetSchemaDescriptor { pub schema_json: Option, } +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct CultNetShardDescriptor { + pub shard_id: String, + pub owner_runtime_id: String, + pub epoch: u64, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub is_primary: Option, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub schema_ids: Vec, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub key_prefix: Option, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub primary_endpoints: Vec, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub replica_endpoints: Vec, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub read_replica_endpoints: Vec, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub region: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub authority_lease_id: Option, +} + +impl CultNetShardDescriptor { + pub fn serves(&self, schema_id: Option<&str>, record_key: Option<&str>) -> bool { + if let Some(schema_id) = schema_id + && !self.schema_ids.is_empty() + && !self + .schema_ids + .iter() + .any(|candidate| candidate == schema_id) + { + return false; + } + + if let Some(record_key) = record_key + && let Some(prefix) = self.key_prefix.as_deref() + && !record_key.starts_with(prefix) + { + return false; + } + + true + } +} + #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(tag = "schemaVersion")] pub enum CultNetMessage { @@ -282,6 +341,52 @@ pub enum CultNetMessage { message_id: String, schemas: Vec, }, + #[serde(rename = "cultnet.shard_catalog_request.v0", rename_all = "camelCase")] + ShardCatalogRequest { + message_id: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + schema_ids: Option>, + #[serde(default, skip_serializing_if = "Option::is_none")] + record_keys: Option>, + }, + #[serde(rename = "cultnet.shard_catalog_response.v0", rename_all = "camelCase")] + ShardCatalogResponse { + message_id: String, + shards: Vec, + }, + #[serde(rename = "cultnet.operation_request.v0", rename_all = "camelCase")] + OperationRequest { + message_id: String, + service_id: String, + operation: String, + payload_schema: String, + #[serde(default = "messagepack_base64_encoding")] + payload_encoding: String, + payload: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + source_runtime_id: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + target_runtime_id: Option, + }, + #[serde(rename = "cultnet.operation_response.v0", rename_all = "camelCase")] + OperationResponse { + message_id: String, + service_id: String, + operation: String, + status: String, + payload_schema: String, + #[serde(default = "messagepack_base64_encoding")] + payload_encoding: String, + payload: String, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + diagnostics: Vec, + #[serde(default, skip_serializing_if = "Option::is_none")] + source_runtime_id: Option, + }, +} + +fn messagepack_base64_encoding() -> String { + "messagepack-base64".to_string() } pub fn parse_cultnet_message( @@ -473,6 +578,60 @@ fn validate_message(message: &CultNetMessage) -> Result<()> { validate_schema_descriptor(schema)?; } } + CultNetMessage::ShardCatalogRequest { + message_id, + schema_ids, + record_keys, + } => { + require_non_empty(message_id, "messageId")?; + require_optional_string_vec(schema_ids.as_deref(), "schemaIds")?; + require_optional_string_vec(record_keys.as_deref(), "recordKeys")?; + } + CultNetMessage::ShardCatalogResponse { message_id, shards } => { + require_non_empty(message_id, "messageId")?; + for shard in shards { + validate_shard_descriptor(shard)?; + } + } + CultNetMessage::OperationRequest { + message_id, + service_id, + operation, + payload_schema, + payload_encoding, + payload, + source_runtime_id, + target_runtime_id, + } => { + require_non_empty(message_id, "messageId")?; + require_non_empty(service_id, "serviceId")?; + require_non_empty(operation, "operation")?; + require_non_empty(payload_schema, "payloadSchema")?; + require_exact(payload_encoding, "messagepack-base64", "payloadEncoding")?; + require_non_empty(payload, "payload")?; + require_optional_non_empty(source_runtime_id.as_deref(), "sourceRuntimeId")?; + require_optional_non_empty(target_runtime_id.as_deref(), "targetRuntimeId")?; + } + CultNetMessage::OperationResponse { + message_id, + service_id, + operation, + status, + payload_schema, + payload_encoding, + payload, + diagnostics: _, + source_runtime_id, + } => { + require_non_empty(message_id, "messageId")?; + require_non_empty(service_id, "serviceId")?; + require_non_empty(operation, "operation")?; + require_non_empty(status, "status")?; + require_non_empty(payload_schema, "payloadSchema")?; + require_exact(payload_encoding, "messagepack-base64", "payloadEncoding")?; + require_non_empty(payload, "payload")?; + require_optional_non_empty(source_runtime_id.as_deref(), "sourceRuntimeId")?; + } } Ok(()) } @@ -545,6 +704,22 @@ fn validate_schema_descriptor(schema: &CultNetSchemaDescriptor) -> Result<()> { Ok(()) } +fn validate_shard_descriptor(shard: &CultNetShardDescriptor) -> Result<()> { + require_non_empty(&shard.shard_id, "shardId")?; + require_non_empty(&shard.owner_runtime_id, "ownerRuntimeId")?; + require_optional_string_vec(Some(shard.schema_ids.as_slice()), "schemaIds")?; + require_optional_non_empty(shard.key_prefix.as_deref(), "keyPrefix")?; + require_optional_string_vec(Some(shard.primary_endpoints.as_slice()), "primaryEndpoints")?; + require_optional_string_vec(Some(shard.replica_endpoints.as_slice()), "replicaEndpoints")?; + require_optional_string_vec( + Some(shard.read_replica_endpoints.as_slice()), + "readReplicaEndpoints", + )?; + require_optional_non_empty(shard.region.as_deref(), "region")?; + require_optional_non_empty(shard.authority_lease_id.as_deref(), "authorityLeaseId")?; + Ok(()) +} + fn require_non_empty(value: &str, field: &str) -> Result<()> { if value.trim().is_empty() { return Err(anyhow!("CultNet field {field} must be non-empty")); @@ -552,6 +727,13 @@ fn require_non_empty(value: &str, field: &str) -> Result<()> { Ok(()) } +fn require_exact(value: &str, expected: &str, field: &str) -> Result<()> { + if value != expected { + return Err(anyhow!("{field} must be {expected}")); + } + Ok(()) +} + fn require_optional_non_empty(value: Option<&str>, field: &str) -> Result<()> { if let Some(value) = value { require_non_empty(value, field)?; diff --git a/vendor/cultnet-rs/src/cultmesh.rs b/vendor/cultnet-rs/src/cultmesh.rs new file mode 100644 index 0000000..20d2123 --- /dev/null +++ b/vendor/cultnet-rs/src/cultmesh.rs @@ -0,0 +1,525 @@ +use anyhow::Result; +use anyhow::anyhow; +use chrono::DateTime; +use chrono::Utc; +use std::collections::BTreeMap; +use std::net::SocketAddr; +use std::net::ToSocketAddrs; +use std::net::UdpSocket; +use std::thread; +use std::time::Duration; +use std::time::Instant; + +use crate::CultNetRudpSocketMode; +use crate::CultNetRudpSocketTransportConnection; +use crate::CultNetRudpSocketTransportOptions; +use crate::CultNetSchemaRegistry; +use crate::CultNetShardCatalog; +use crate::builtin_schema_registry; + +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct CultMeshPeerCard { + pub peer_id: String, + pub verse_id: String, + pub endpoints: Vec, + pub roles: Vec, + pub shard_ids: Vec, + pub authority_lease_id: Option, +} + +impl CultMeshPeerCard { + pub fn new( + peer_id: impl Into, + verse_id: impl Into, + endpoints: impl IntoIterator>, + ) -> Self { + Self { + peer_id: peer_id.into(), + verse_id: verse_id.into(), + endpoints: endpoints.into_iter().map(Into::into).collect(), + roles: Vec::new(), + shard_ids: Vec::new(), + authority_lease_id: None, + } + } + + pub fn with_roles(mut self, roles: impl IntoIterator>) -> Self { + self.roles = roles.into_iter().map(Into::into).collect(); + self + } + + pub fn with_shard_ids( + mut self, + shard_ids: impl IntoIterator>, + ) -> Self { + self.shard_ids = shard_ids.into_iter().map(Into::into).collect(); + self + } + + pub fn with_authority_lease_id(mut self, authority_lease_id: impl Into) -> Self { + self.authority_lease_id = Some(authority_lease_id.into()); + self + } + + pub fn rudp_endpoint(&self) -> Result { + let endpoint = self + .endpoints + .iter() + .find(|endpoint| endpoint.to_ascii_lowercase().starts_with("rudp://")) + .ok_or_else(|| anyhow!("Peer {} does not advertise a RUDP endpoint", self.peer_id))?; + CultMesh::parse_rudp_endpoint(endpoint) + } +} + +#[derive(Clone, Debug, Default)] +pub struct CultMeshPeerCatalog { + peers: BTreeMap, +} + +impl CultMeshPeerCatalog { + pub fn new() -> Self { + Self::default() + } + + pub fn upsert(&mut self, peer: CultMeshPeerCard) -> Result<()> { + require_non_empty(&peer.peer_id, "peer.peer_id")?; + require_non_empty(&peer.verse_id, "peer.verse_id")?; + self.peers.insert(peer.peer_id.clone(), peer); + Ok(()) + } + + pub fn get(&self, peer_id: &str) -> Option<&CultMeshPeerCard> { + self.peers.get(peer_id) + } + + pub fn peers(&self) -> Vec { + self.peers.values().cloned().collect() + } + + pub fn find(&self, verse_id: &str, role: Option<&str>) -> Vec { + self.peers + .values() + .filter(|peer| { + peer.verse_id == verse_id + && role.is_none_or(|role| peer.roles.iter().any(|value| value == role)) + }) + .cloned() + .collect() + } + + pub fn find_authorized( + &self, + verse_id: &str, + role: &str, + leases: &CultMeshAuthorityLeaseCatalog, + shard_id: Option<&str>, + at: DateTime, + ) -> Vec { + self.find(verse_id, Some(role)) + .into_iter() + .filter(|peer| leases.is_authorized(peer, role, shard_id, at)) + .collect() + } + + pub fn first_authorized( + &self, + verse_id: &str, + role: &str, + leases: &CultMeshAuthorityLeaseCatalog, + shard_id: Option<&str>, + at: DateTime, + ) -> Option { + self.find_authorized(verse_id, role, leases, shard_id, at) + .into_iter() + .next() + } +} + +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct CultMeshAuthorityLease { + pub lease_id: String, + pub verse_id: String, + pub peer_id: String, + pub roles: Vec, + pub shard_ids: Vec, + pub issuer_runtime_id: Option, + pub valid_from: DateTime, + pub expires_at: DateTime, +} + +impl CultMeshAuthorityLease { + pub fn covers( + &self, + peer: &CultMeshPeerCard, + role: &str, + shard_id: Option<&str>, + at: DateTime, + ) -> bool { + at >= self.valid_from + && at < self.expires_at + && self.verse_id == peer.verse_id + && self.peer_id == peer.peer_id + && self.roles.iter().any(|value| value == role) + && peer.roles.iter().any(|value| value == role) + && shard_id.is_none_or(|shard_id| { + self.shard_ids.is_empty() || self.shard_ids.iter().any(|value| value == shard_id) + }) + } +} + +#[derive(Clone, Debug, Default)] +pub struct CultMeshAuthorityLeaseCatalog { + leases: BTreeMap, +} + +impl CultMeshAuthorityLeaseCatalog { + pub fn new() -> Self { + Self::default() + } + + pub fn upsert(&mut self, lease: CultMeshAuthorityLease) -> Result<()> { + require_non_empty(&lease.lease_id, "lease.lease_id")?; + require_non_empty(&lease.verse_id, "lease.verse_id")?; + require_non_empty(&lease.peer_id, "lease.peer_id")?; + if lease.expires_at <= lease.valid_from { + return Err(anyhow!( + "CultMesh authority lease expiry must be after valid_from" + )); + } + self.leases.insert(lease.lease_id.clone(), lease); + Ok(()) + } + + pub fn get(&self, lease_id: &str) -> Option<&CultMeshAuthorityLease> { + self.leases.get(lease_id) + } + + pub fn leases(&self) -> Vec { + self.leases.values().cloned().collect() + } + + pub fn is_authorized( + &self, + peer: &CultMeshPeerCard, + role: &str, + shard_id: Option<&str>, + at: DateTime, + ) -> bool { + let Some(lease_id) = peer.authority_lease_id.as_deref() else { + return false; + }; + self.leases + .get(lease_id) + .is_some_and(|lease| lease.covers(peer, role, shard_id, at)) + } +} + +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct CultNetRudpEndpoint { + pub host: String, + pub port: u16, +} + +impl CultNetRudpEndpoint { + pub fn uri(&self) -> String { + if self.host.contains(':') && !self.host.starts_with('[') { + format!("rudp://[{}]:{}", self.host, self.port) + } else { + format!("rudp://{}:{}", self.host, self.port) + } + } + + pub fn socket_addr(&self) -> Result { + format!("{}:{}", socket_host(&self.host), self.port) + .to_socket_addrs() + .map_err(|error| anyhow!("Invalid RUDP socket endpoint {}: {error}", self.uri()))? + .next() + .ok_or_else(|| anyhow!("RUDP socket endpoint {} did not resolve", self.uri())) + } +} + +#[derive(Clone, Debug)] +pub struct CultMeshRudpSocketOptions { + pub bind_host: String, + pub bind_port: u16, + pub read_timeout: Option, + pub initial_sequence: u32, + pub resend_delay_ms: u64, + pub max_payload_bytes: Option, + pub max_fragment_bytes: Option, + pub max_pending_reliable_packets: Option, +} + +impl Default for CultMeshRudpSocketOptions { + fn default() -> Self { + Self { + bind_host: "127.0.0.1".to_string(), + bind_port: 0, + read_timeout: Some(Duration::from_millis(20)), + initial_sequence: 1, + resend_delay_ms: 250, + max_payload_bytes: None, + max_fragment_bytes: None, + max_pending_reliable_packets: None, + } + } +} + +#[derive(Clone, Debug)] +pub struct CultMeshRudpClientOptions { + pub socket_options: CultMeshRudpSocketOptions, + pub connect_payload: Vec, + pub connect_timeout: Duration, + pub poll_interval: Duration, +} + +impl Default for CultMeshRudpClientOptions { + fn default() -> Self { + Self { + socket_options: CultMeshRudpSocketOptions::default(), + connect_payload: Vec::new(), + connect_timeout: Duration::from_secs(1), + poll_interval: Duration::from_millis(5), + } + } +} + +pub struct CultMesh; + +impl CultMesh { + pub fn create_schema_registry() -> CultNetSchemaRegistry { + CultNetSchemaRegistry::new() + } + + pub fn create_builtin_schema_registry() -> Result { + builtin_schema_registry() + } + + pub fn create_shard_catalog() -> CultNetShardCatalog { + CultNetShardCatalog::new() + } + + pub fn create_peer_catalog() -> CultMeshPeerCatalog { + CultMeshPeerCatalog::new() + } + + pub fn create_authority_lease_catalog() -> CultMeshAuthorityLeaseCatalog { + CultMeshAuthorityLeaseCatalog::new() + } + + pub fn parse_rudp_endpoint(endpoint: &str) -> Result { + cultnet_rudp_endpoint(endpoint) + } + + pub fn create_rudp_server( + runtime_id: impl Into, + connection_id: u32, + options: CultMeshRudpSocketOptions, + ) -> Result { + let socket = bind_rudp_socket(&options)?; + CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { + runtime_id: runtime_id.into(), + socket, + mode: CultNetRudpSocketMode::Server, + remote_addr: None, + connection_id, + initial_sequence: options.initial_sequence, + resend_delay_ms: options.resend_delay_ms, + transport_id: None, + max_payload_bytes: options.max_payload_bytes, + max_fragment_bytes: options.max_fragment_bytes, + max_pending_reliable_packets: options.max_pending_reliable_packets, + reconnect_policy: None, + }) + } + + pub fn create_rudp_client( + runtime_id: impl Into, + connection_id: u32, + endpoint: &CultNetRudpEndpoint, + options: CultMeshRudpSocketOptions, + ) -> Result { + let socket = bind_rudp_socket(&options)?; + CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { + runtime_id: runtime_id.into(), + socket, + mode: CultNetRudpSocketMode::Client, + remote_addr: Some(endpoint.socket_addr()?), + connection_id, + initial_sequence: options.initial_sequence, + resend_delay_ms: options.resend_delay_ms, + transport_id: None, + max_payload_bytes: options.max_payload_bytes, + max_fragment_bytes: options.max_fragment_bytes, + max_pending_reliable_packets: options.max_pending_reliable_packets, + reconnect_policy: None, + }) + } + + pub fn create_rudp_client_for_endpoint( + runtime_id: impl Into, + connection_id: u32, + endpoint: &str, + options: CultMeshRudpSocketOptions, + ) -> Result { + let endpoint = Self::parse_rudp_endpoint(endpoint)?; + Self::create_rudp_client(runtime_id, connection_id, &endpoint, options) + } + + pub fn create_rudp_client_for_peer( + runtime_id: impl Into, + connection_id: u32, + peer: &CultMeshPeerCard, + options: CultMeshRudpSocketOptions, + ) -> Result { + let endpoint = peer.rudp_endpoint()?; + Self::create_rudp_client(runtime_id, connection_id, &endpoint, options) + } + + pub fn create_rudp_client_for_authorized_peer( + runtime_id: impl Into, + connection_id: u32, + peers: &CultMeshPeerCatalog, + leases: &CultMeshAuthorityLeaseCatalog, + verse_id: &str, + role: &str, + shard_id: Option<&str>, + at: DateTime, + options: CultMeshRudpSocketOptions, + ) -> Result { + let peer = peers + .first_authorized(verse_id, role, leases, shard_id, at) + .ok_or_else(|| { + anyhow!("No authorized RUDP peer for role {role} in Verse {verse_id}") + })?; + Self::create_rudp_client_for_peer(runtime_id, connection_id, &peer, options) + } + + pub fn connect_rudp_client( + runtime_id: impl Into, + connection_id: u32, + endpoint: &CultNetRudpEndpoint, + options: CultMeshRudpClientOptions, + ) -> Result { + let runtime_id = runtime_id.into(); + let mut client = Self::create_rudp_client( + runtime_id.clone(), + connection_id, + endpoint, + options.socket_options, + )?; + client.connect(options.connect_payload)?; + let deadline = Instant::now() + options.connect_timeout; + while Instant::now() < deadline { + let _ = client.receive_once()?; + client.poll_resends()?; + if client.connected() { + return Ok(client); + } + thread::sleep(options.poll_interval); + } + if client.connected() { + return Ok(client); + } + Err(anyhow!( + "Timed out waiting for RUDP client {runtime_id} to connect" + )) + } + + pub fn connect_rudp_client_for_endpoint( + runtime_id: impl Into, + connection_id: u32, + endpoint: &str, + options: CultMeshRudpClientOptions, + ) -> Result { + let endpoint = Self::parse_rudp_endpoint(endpoint)?; + Self::connect_rudp_client(runtime_id, connection_id, &endpoint, options) + } + + pub fn connect_rudp_client_for_peer( + runtime_id: impl Into, + connection_id: u32, + peer: &CultMeshPeerCard, + options: CultMeshRudpClientOptions, + ) -> Result { + let endpoint = peer.rudp_endpoint()?; + Self::connect_rudp_client(runtime_id, connection_id, &endpoint, options) + } + + pub fn connect_rudp_client_for_authorized_peer( + runtime_id: impl Into, + connection_id: u32, + peers: &CultMeshPeerCatalog, + leases: &CultMeshAuthorityLeaseCatalog, + verse_id: &str, + role: &str, + shard_id: Option<&str>, + at: DateTime, + options: CultMeshRudpClientOptions, + ) -> Result { + let peer = peers + .first_authorized(verse_id, role, leases, shard_id, at) + .ok_or_else(|| { + anyhow!("No authorized RUDP peer for role {role} in Verse {verse_id}") + })?; + Self::connect_rudp_client_for_peer(runtime_id, connection_id, &peer, options) + } +} + +pub fn cultnet_rudp_endpoint(endpoint: &str) -> Result { + let scheme = "rudp://"; + if endpoint.len() < scheme.len() || !endpoint[..scheme.len()].eq_ignore_ascii_case(scheme) { + return Err(anyhow!("RUDP endpoint must use the rudp scheme")); + } + let rest = &endpoint[scheme.len()..]; + let (host, port_text) = if let Some(rest) = rest.strip_prefix('[') { + let (host, port_rest) = rest + .split_once(']') + .ok_or_else(|| anyhow!("RUDP IPv6 endpoint must close the host bracket"))?; + let port_text = port_rest + .strip_prefix(':') + .ok_or_else(|| anyhow!("RUDP endpoint must include a valid port"))?; + (host.to_string(), port_text) + } else { + let (host, port_text) = rest + .rsplit_once(':') + .ok_or_else(|| anyhow!("RUDP endpoint must include a host and port"))?; + if host.contains(':') { + return Err(anyhow!("RUDP IPv6 endpoint host must be bracketed")); + } + (host.to_string(), port_text) + }; + require_non_empty(&host, "rudp host")?; + let port = port_text + .parse::() + .map_err(|error| anyhow!("RUDP endpoint must include a valid port: {error}"))?; + if port == 0 { + return Err(anyhow!("RUDP endpoint port must be greater than zero")); + } + Ok(CultNetRudpEndpoint { host, port }) +} + +fn bind_rudp_socket(options: &CultMeshRudpSocketOptions) -> Result { + let socket = UdpSocket::bind(format!( + "{}:{}", + socket_host(&options.bind_host), + options.bind_port + ))?; + socket.set_read_timeout(options.read_timeout)?; + Ok(socket) +} + +fn socket_host(host: &str) -> String { + if host.contains(':') && !host.starts_with('[') { + format!("[{host}]") + } else { + host.to_string() + } +} + +fn require_non_empty(value: &str, field: &str) -> Result<()> { + if value.trim().is_empty() { + return Err(anyhow!("CultMesh {field} must not be empty")); + } + Ok(()) +} diff --git a/vendor/cultnet-rs/src/lib.rs b/vendor/cultnet-rs/src/lib.rs index bc804d3..0b9fbb5 100644 --- a/vendor/cultnet-rs/src/lib.rs +++ b/vendor/cultnet-rs/src/lib.rs @@ -1,15 +1,21 @@ mod contracts; +mod cultmesh; mod framing; +mod operation_service; mod replication; mod rudp; mod schema_discovery; mod security; +mod shard_catalog; mod transport; pub use contracts::*; +pub use cultmesh::*; pub use framing::*; +pub use operation_service::*; pub use replication::*; pub use rudp::*; pub use schema_discovery::*; pub use security::*; +pub use shard_catalog::*; pub use transport::*; diff --git a/vendor/cultnet-rs/src/operation_service.rs b/vendor/cultnet-rs/src/operation_service.rs new file mode 100644 index 0000000..84d60cf --- /dev/null +++ b/vendor/cultnet-rs/src/operation_service.rs @@ -0,0 +1,60 @@ +use std::net::UdpSocket; +use std::time::Duration; + +use anyhow::{Result, anyhow}; + +use crate::{ + CultNetMessage, CultNetRudpSocketTransportConnection, CultNetRudpSocketTransportOptions, +}; + +pub const CULTNET_OPERATION_CONNECTION_ID: u32 = 0x4355_4c54; + +pub struct CultNetOperationServer { + transport: CultNetRudpSocketTransportConnection, + endpoint: String, +} + +impl CultNetOperationServer { + pub fn bind(runtime_id: impl Into, host: &str, port: u16) -> Result { + let socket = UdpSocket::bind((host, port))?; + socket.set_read_timeout(Some(Duration::from_millis(25)))?; + let address = socket.local_addr()?; + let mut options = CultNetRudpSocketTransportOptions::server( + runtime_id, + socket, + CULTNET_OPERATION_CONNECTION_ID, + ); + options.max_fragment_bytes = Some(2048); + Ok(Self { + transport: CultNetRudpSocketTransportConnection::new(options)?, + endpoint: format!("rudp://{}:{}", address.ip(), address.port()), + }) + } + + pub fn endpoint(&self) -> &str { + &self.endpoint + } + + pub fn serve_once( + &mut self, + mut handler: impl FnMut(CultNetMessage) -> Result, + ) -> Result { + let Some(request) = self.transport.receive_schema_message_once()? else { + self.transport.poll_resends()?; + return Ok(false); + }; + if !matches!(request, CultNetMessage::OperationRequest { .. }) { + return Err(anyhow!( + "CultNet operation service received a non-operation message" + )); + } + let response = handler(request)?; + if !matches!(response, CultNetMessage::OperationResponse { .. }) { + return Err(anyhow!( + "CultNet operation handler returned a non-operation response" + )); + } + self.transport.send_schema_message(&response)?; + Ok(true) + } +} diff --git a/vendor/cultnet-rs/src/replication.rs b/vendor/cultnet-rs/src/replication.rs index 492cf31..d02a141 100644 --- a/vendor/cultnet-rs/src/replication.rs +++ b/vendor/cultnet-rs/src/replication.rs @@ -9,6 +9,13 @@ use serde::de::DeserializeOwned; use serde_json::Value; use std::collections::BTreeMap; use std::collections::BTreeSet; +use std::sync::Arc; +use std::sync::Mutex; +use std::sync::atomic::AtomicBool; +use std::sync::atomic::Ordering; +use std::thread; +use std::thread::JoinHandle; +use std::time::Duration; use crate::CultNetDocumentMutationContract; use crate::CultNetDocumentRecord; @@ -67,6 +74,56 @@ pub struct CultNetDocumentRegistry { bindings_by_schema_id: BTreeMap, } +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct CultNetReactiveDocumentOptions { + pub flush_delay: Duration, + pub detect_local_changes: bool, + pub replace_dirty_current_on_canonical_snapshot: bool, +} + +impl Default for CultNetReactiveDocumentOptions { + fn default() -> Self { + Self { + flush_delay: Duration::from_millis(16), + detect_local_changes: true, + replace_dirty_current_on_canonical_snapshot: false, + } + } +} + +#[derive(Clone, Debug, PartialEq)] +pub struct CultNetReactiveDocumentReconciliation { + pub canonical: T, + pub predicted: T, + pub delta: BTreeMap, + pub version: u64, + pub received_at: String, +} + +struct CultNetReactiveDocumentState { + dirty: bool, + flushing: bool, + flush_queued: bool, + last_clean_payload: Vec, + reconciliation: Option>, + reconciliation_version: u64, + last_error: Option, +} + +pub struct CultNetReactiveDocument +where + T: DatabaseEntry + Serialize + DeserializeOwned, +{ + registry: CultNetDocumentRegistry, + cache: Arc>, + record_key: String, + current: Arc>, + state: Arc>>, + options: CultNetReactiveDocumentOptions, + disposed: Arc, + detect_worker: Option>, +} + impl CultNetDocumentRegistry { pub fn new() -> Self { Self::default() @@ -352,6 +409,40 @@ impl CultNetDocumentRegistry { Ok(applied) } + pub fn sync_document_from_snapshot_response( + &self, + cache: &mut CultCache, + response: &CultNetMessage, + record_key: &str, + ) -> Result + where + T: DatabaseEntry + Serialize + DeserializeOwned, + { + let CultNetMessage::SnapshotResponse { documents, .. } = response else { + return Err(anyhow!("expected cultnet.snapshot_response.v0")); + }; + let binding = self.require_binding(T::TYPE)?; + let document = documents + .iter() + .find(|document| { + document.schema_id == binding.schema_id && document.record_key == record_key + }) + .ok_or_else(|| { + anyhow!( + "No CultNet snapshot document for schema {:?} and record key {:?}", + binding.schema_id, + record_key + ) + })?; + self.apply_document_put_message::( + cache, + &CultNetMessage::DocumentPut { + message_id: "snapshot-sync".to_string(), + document: document.clone(), + }, + ) + } + pub fn apply_raw_snapshot_response( &self, cache: &mut CultCache, @@ -380,6 +471,52 @@ impl CultNetDocumentRegistry { Ok(applied) } + pub fn sync_raw_document_from_snapshot_response( + &self, + cache: &mut CultCache, + response: &CultNetMessage, + record_key: &str, + ) -> Result + where + T: DatabaseEntry + Serialize + DeserializeOwned, + { + let CultNetMessage::SnapshotResponseRaw { documents, .. } = response else { + return Err(anyhow!("expected cultnet.snapshot_response_raw.v0")); + }; + let binding = self.require_binding(T::TYPE)?; + let document = documents + .iter() + .find(|document| { + document.schema_id == binding.schema_id && document.record_key == record_key + }) + .ok_or_else(|| { + anyhow!( + "No raw CultNet snapshot document for schema {:?} and record key {:?}", + binding.schema_id, + record_key + ) + })?; + self.apply_raw_document_put_message::( + cache, + &CultNetMessage::DocumentPutRaw { + message_id: "snapshot-sync-raw".to_string(), + document: document.clone(), + }, + ) + } + + pub fn reactive_document( + &self, + cache: Arc>, + record_key: impl Into, + options: CultNetReactiveDocumentOptions, + ) -> Result> + where + T: DatabaseEntry + Serialize + DeserializeOwned, + { + CultNetReactiveDocument::new(self.clone(), cache, record_key, options) + } + fn document_record_from_envelope( &self, envelope: &CultCacheEnvelope, @@ -428,6 +565,443 @@ impl CultNetDocumentRegistry { } } +impl CultNetReactiveDocument +where + T: DatabaseEntry + Serialize + DeserializeOwned, +{ + pub fn new( + registry: CultNetDocumentRegistry, + cache: Arc>, + record_key: impl Into, + options: CultNetReactiveDocumentOptions, + ) -> Result { + let record_key = record_key.into(); + if record_key.trim().is_empty() { + return Err(anyhow!("record_key must be non-empty")); + } + registry.require_binding(T::TYPE)?; + let current = { + let cache = cache + .lock() + .map_err(|_| anyhow!("CultCache mutex poisoned"))?; + cache.get_required::(&record_key)? + }; + let last_clean_payload = serialize_typed(¤t)?; + let current = Arc::new(Mutex::new(current)); + let state = Arc::new(Mutex::new(CultNetReactiveDocumentState { + dirty: false, + flushing: false, + flush_queued: false, + last_clean_payload, + reconciliation: None, + reconciliation_version: 0, + last_error: None, + })); + let disposed = Arc::new(AtomicBool::new(false)); + let detect_worker = if options.detect_local_changes { + Some(start_reactive_detection_worker::( + Arc::clone(&cache), + Arc::clone(¤t), + Arc::clone(&state), + Arc::clone(&disposed), + options.flush_delay, + record_key.clone(), + )) + } else { + None + }; + Ok(Self { + registry, + cache, + record_key, + current, + state, + options, + disposed, + detect_worker, + }) + } + + pub fn current(&self) -> Arc> { + Arc::clone(&self.current) + } + + pub fn record_key(&self) -> &str { + &self.record_key + } + + pub fn is_dirty(&self) -> bool { + self.state.lock().map(|state| state.dirty).unwrap_or(false) + } + + pub fn reconciliation(&self) -> Option> { + self.state + .lock() + .ok() + .and_then(|state| state.reconciliation.clone()) + } + + pub fn last_error(&self) -> Option { + self.state + .lock() + .ok() + .and_then(|state| state.last_error.clone()) + } + + pub fn update(&self, update: impl FnOnce(&mut T)) -> Result { + let predicted = { + let mut current = self + .current + .lock() + .map_err(|_| anyhow!("reactive document mutex poisoned"))?; + update(&mut current); + current.clone() + }; + { + let mut state = self + .state + .lock() + .map_err(|_| anyhow!("reactive document state mutex poisoned"))?; + state.dirty = true; + } + if self.options.flush_delay.is_zero() { + self.flush()?; + } + Ok(predicted) + } + + pub fn set_current(&self, value: T) -> Result { + { + let mut current = self + .current + .lock() + .map_err(|_| anyhow!("reactive document mutex poisoned"))?; + *current = value.clone(); + } + { + let mut state = self + .state + .lock() + .map_err(|_| anyhow!("reactive document state mutex poisoned"))?; + state.dirty = true; + } + if self.options.flush_delay.is_zero() { + self.flush()?; + } + Ok(value) + } + + pub fn mark_dirty(&self) -> Result<()> { + let mut state = self + .state + .lock() + .map_err(|_| anyhow!("reactive document state mutex poisoned"))?; + state.dirty = true; + Ok(()) + } + + pub fn refresh(&self) -> Result { + let canonical = { + let cache = self + .cache + .lock() + .map_err(|_| anyhow!("CultCache mutex poisoned"))?; + cache.get_required::(&self.record_key)? + }; + { + let mut current = self + .current + .lock() + .map_err(|_| anyhow!("reactive document mutex poisoned"))?; + *current = canonical.clone(); + } + { + let mut state = self + .state + .lock() + .map_err(|_| anyhow!("reactive document state mutex poisoned"))?; + state.last_clean_payload = serialize_typed(&canonical)?; + state.dirty = false; + state.flush_queued = false; + state.reconciliation = None; + } + Ok(canonical) + } + + pub fn flush(&self) -> Result<()> { + flush_reactive_document::(&self.cache, &self.current, &self.state, &self.record_key) + } + + pub fn apply_document_put_message(&self, message: &CultNetMessage) -> Result { + let canonical = { + let mut cache = self + .cache + .lock() + .map_err(|_| anyhow!("CultCache mutex poisoned"))?; + self.registry + .apply_document_put_message::(&mut cache, message)? + }; + self.apply_canonical_value(canonical) + } + + pub fn apply_raw_document_put_message(&self, message: &CultNetMessage) -> Result { + let canonical = { + let mut cache = self + .cache + .lock() + .map_err(|_| anyhow!("CultCache mutex poisoned"))?; + self.registry + .apply_raw_document_put_message::(&mut cache, message)? + }; + self.apply_canonical_value(canonical) + } + + pub fn clear_reconciliation(&self) -> Result<()> { + let mut state = self + .state + .lock() + .map_err(|_| anyhow!("reactive document state mutex poisoned"))?; + state.reconciliation = None; + Ok(()) + } + + fn apply_canonical_value(&self, canonical: T) -> Result { + let predicted = self + .current + .lock() + .map_err(|_| anyhow!("reactive document mutex poisoned"))? + .clone(); + let mut state = self + .state + .lock() + .map_err(|_| anyhow!("reactive document state mutex poisoned"))?; + if state.dirty || state.flushing { + let delta = create_reconciliation_delta(&predicted, &canonical)?; + if delta.is_empty() { + state.reconciliation = None; + } else { + state.reconciliation_version += 1; + state.reconciliation = Some(CultNetReactiveDocumentReconciliation { + canonical: canonical.clone(), + predicted, + delta, + version: state.reconciliation_version, + received_at: now_utc_second(), + }); + } + if !self.options.replace_dirty_current_on_canonical_snapshot { + return Ok(canonical); + } + } + drop(state); + { + let mut current = self + .current + .lock() + .map_err(|_| anyhow!("reactive document mutex poisoned"))?; + *current = canonical.clone(); + } + let mut state = self + .state + .lock() + .map_err(|_| anyhow!("reactive document state mutex poisoned"))?; + state.last_clean_payload = serialize_typed(&canonical)?; + state.reconciliation = None; + Ok(canonical) + } +} + +impl Drop for CultNetReactiveDocument +where + T: DatabaseEntry + Serialize + DeserializeOwned, +{ + fn drop(&mut self) { + self.disposed.store(true, Ordering::SeqCst); + let _ = self.detect_worker.take(); + } +} + +fn start_reactive_detection_worker( + cache: Arc>, + current: Arc>, + state: Arc>>, + disposed: Arc, + flush_delay: Duration, + record_key: String, +) -> JoinHandle<()> +where + T: DatabaseEntry + Serialize + DeserializeOwned, +{ + thread::spawn(move || { + let delay = if flush_delay.is_zero() { + Duration::from_millis(1) + } else { + flush_delay + }; + while !disposed.load(Ordering::SeqCst) { + thread::sleep(delay); + match detect_reactive_document_change::(¤t, &state).and_then(|dirty| { + if dirty { + flush_reactive_document::(&cache, ¤t, &state, &record_key)?; + } + Ok(()) + }) { + Ok(()) => {} + Err(error) => { + if let Ok(mut state) = state.lock() { + state.last_error = Some(error.to_string()); + } + } + } + } + }) +} + +fn detect_reactive_document_change( + current: &Arc>, + state: &Arc>>, +) -> Result +where + T: DatabaseEntry + Serialize + DeserializeOwned, +{ + let payload = { + let current = current + .lock() + .map_err(|_| anyhow!("reactive document mutex poisoned"))?; + serialize_typed(&*current)? + }; + let mut state = state + .lock() + .map_err(|_| anyhow!("reactive document state mutex poisoned"))?; + if !state.dirty && !state.flushing && payload != state.last_clean_payload { + state.dirty = true; + } + Ok(state.dirty && !state.flushing) +} + +fn flush_reactive_document( + cache: &Arc>, + current: &Arc>, + state: &Arc>>, + record_key: &str, +) -> Result<()> +where + T: DatabaseEntry + Serialize + DeserializeOwned, +{ + let predicted = { + let mut state_guard = state + .lock() + .map_err(|_| anyhow!("reactive document state mutex poisoned"))?; + if !state_guard.dirty { + drop(state_guard); + if !detect_reactive_document_change::(current, state)? { + return Ok(()); + } + state_guard = state + .lock() + .map_err(|_| anyhow!("reactive document state mutex poisoned"))?; + } + if state_guard.flushing { + state_guard.flush_queued = true; + return Ok(()); + } + state_guard.flushing = true; + state_guard.dirty = false; + current + .lock() + .map_err(|_| anyhow!("reactive document mutex poisoned"))? + .clone() + }; + let payload = serialize_typed(&predicted)?; + { + let mut cache = cache + .lock() + .map_err(|_| anyhow!("CultCache mutex poisoned"))?; + cache.put::(record_key.to_string(), &predicted)?; + } + let should_flush_again = { + let mut state = state + .lock() + .map_err(|_| anyhow!("reactive document state mutex poisoned"))?; + state.flushing = false; + state.last_clean_payload = payload; + state.last_error = None; + state.reconciliation = None; + let changed_after_flush = { + let current = current + .lock() + .map_err(|_| anyhow!("reactive document mutex poisoned"))?; + serialize_typed(&*current)? != state.last_clean_payload + }; + if changed_after_flush { + state.dirty = true; + } + let should_flush_again = state.flush_queued || state.dirty; + state.flush_queued = false; + should_flush_again + }; + if should_flush_again { + flush_reactive_document::(cache, current, state, record_key)?; + } + Ok(()) +} + +fn serialize_typed(value: &T) -> Result> +where + T: Serialize, +{ + Ok(rmp_serde::to_vec(value)?) +} + +fn create_reconciliation_delta(predicted: &T, canonical: &T) -> Result> +where + T: Serialize, +{ + let predicted = serde_json::to_value(predicted)?; + let canonical = serde_json::to_value(canonical)?; + let mut delta = BTreeMap::new(); + match (predicted, canonical) { + (Value::Object(predicted), Value::Object(canonical)) => { + for (key, predicted_value) in predicted { + let canonical_value = canonical.get(&key).cloned().unwrap_or(Value::Null); + if predicted_value == canonical_value { + continue; + } + delta.insert( + key, + numeric_delta(&predicted_value, &canonical_value).unwrap_or(predicted_value), + ); + } + } + (Value::Array(predicted), Value::Array(canonical)) => { + for (index, predicted_value) in predicted.into_iter().enumerate() { + let canonical_value = canonical.get(index).cloned().unwrap_or(Value::Null); + if predicted_value == canonical_value { + continue; + } + delta.insert( + index.to_string(), + numeric_delta(&predicted_value, &canonical_value).unwrap_or(predicted_value), + ); + } + } + (predicted, canonical) if predicted != canonical => { + delta.insert( + "value".to_string(), + numeric_delta(&predicted, &canonical).unwrap_or(predicted), + ); + } + _ => {} + } + Ok(delta) +} + +fn numeric_delta(predicted: &Value, canonical: &Value) -> Option { + let predicted = predicted.as_f64()?; + let canonical = canonical.as_f64()?; + serde_json::Number::from_f64(predicted - canonical).map(Value::Number) +} + fn round_trip_typed(value: &T) -> Result where T: Serialize + DeserializeOwned, diff --git a/vendor/cultnet-rs/src/rudp.rs b/vendor/cultnet-rs/src/rudp.rs index 87d8da2..8b47f9e 100644 --- a/vendor/cultnet-rs/src/rudp.rs +++ b/vendor/cultnet-rs/src/rudp.rs @@ -6,11 +6,13 @@ use std::collections::VecDeque; use std::io::ErrorKind; use std::net::SocketAddr; use std::net::UdpSocket; -use std::thread; -use std::time::Duration; use std::time::SystemTime; use std::time::UNIX_EPOCH; +use crate::CultNetMessage; +use crate::CultNetReconnectController; +use crate::CultNetReconnectDecision; +use crate::CultNetReconnectPolicy; use crate::CultNetTransportChannel; use crate::CultNetTransportDelivery; use crate::CultNetTransportDescriptor; @@ -19,11 +21,14 @@ use crate::CultNetTransportOrdering; use crate::CultNetTransportProfile; use crate::CultNetTransportProtocol; use crate::CultNetTransportStats; +use crate::CultNetWireContract; +use crate::create_reconnect_policy; +use crate::decode_cultnet_message_from_slice; +use crate::encode_cultnet_message_to_vec; const RUDP_MAGIC: [u8; 4] = [0x43, 0x4e, 0x52, 0x30]; const RUDP_VERSION: u8 = 0; const RUDP_FIXED_HEADER_BYTES: usize = 36; -const DEFAULT_MEDIA_RELIABLE_EXPIRE_AFTER_MS: u64 = 75; #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum CultNetRudpPacketType { @@ -95,14 +100,12 @@ pub struct CultNetRudpSendOptions { pub ordered: bool, pub sequenced: bool, pub now_ms: u64, - pub reliable_expire_after_ms: Option, } #[derive(Clone, Debug, PartialEq, Eq)] struct PendingReliablePacket { packet: CultNetRudpPacket, last_sent_at_ms: u64, - expires_at_ms: Option, } #[derive(Clone, Debug, PartialEq, Eq)] @@ -124,6 +127,7 @@ pub struct CultNetRudpSession { connection_id: u32, resend_delay_ms: u64, max_pending_reliable_packets: Option, + initial_sequence: u32, next_sequence: u32, next_fragment_id: u16, connected: bool, @@ -134,8 +138,6 @@ pub struct CultNetRudpSession { ordered_next_sequence_by_channel: BTreeMap, ordered_buffers: BTreeMap>, fragment_buffers: BTreeMap<(String, u16), FragmentBuffer>, - highest_delivered_sequenced_by_channel: BTreeMap, - reliable_packets_expired: u64, } impl CultNetRudpSession { @@ -144,6 +146,7 @@ impl CultNetRudpSession { connection_id: options.connection_id, resend_delay_ms: options.resend_delay_ms, max_pending_reliable_packets: options.max_pending_reliable_packets, + initial_sequence: options.initial_sequence, next_sequence: options.initial_sequence, next_fragment_id: 1, connected: false, @@ -154,8 +157,6 @@ impl CultNetRudpSession { ordered_next_sequence_by_channel: BTreeMap::new(), ordered_buffers: BTreeMap::new(), fragment_buffers: BTreeMap::new(), - highest_delivered_sequenced_by_channel: BTreeMap::new(), - reliable_packets_expired: 0, } } @@ -171,23 +172,6 @@ impl CultNetRudpSession { self.connected } - pub fn reset_peer_state(&mut self) { - self.connected = false; - self.last_received_at_ms = None; - self.highest_received_sequence = None; - self.received_sequences.clear(); - self.pending_reliable.clear(); - self.ordered_next_sequence_by_channel.clear(); - self.ordered_buffers.clear(); - self.fragment_buffers.clear(); - self.highest_delivered_sequenced_by_channel.clear(); - } - - pub fn assume_connected(&mut self, now_ms: u64) { - self.connected = true; - self.last_received_at_ms = Some(now_ms); - } - pub fn pending_reliable_sequences(&self) -> Vec { self.pending_reliable.keys().copied().collect() } @@ -196,8 +180,17 @@ impl CultNetRudpSession { self.last_received_at_ms } - pub fn reliable_packets_expired(&self) -> u64 { - self.reliable_packets_expired + pub fn reset_peer_state(&mut self) { + self.next_sequence = self.initial_sequence; + self.next_fragment_id = 1; + self.connected = false; + self.last_received_at_ms = None; + self.highest_received_sequence = None; + self.received_sequences.clear(); + self.pending_reliable.clear(); + self.ordered_next_sequence_by_channel.clear(); + self.ordered_buffers.clear(); + self.fragment_buffers.clear(); } pub fn create_connect(&mut self, now_ms: u64, payload: Vec) -> Result { @@ -210,16 +203,7 @@ impl CultNetRudpSession { true, false, ); - self.track_reliable( - &CultNetRudpSendOptions { - reliable: true, - ordered: true, - sequenced: false, - now_ms, - reliable_expire_after_ms: None, - }, - packet.clone(), - ); + self.track_reliable(packet.clone(), now_ms); Ok(packet) } @@ -237,12 +221,8 @@ impl CultNetRudpSession { )); } - let was_connected = self.connected; - if !was_connected { - self.ensure_reliable_capacity(1)?; - } + self.ensure_reliable_capacity(1)?; self.remember_received(packet.sequence); - self.last_received_at_ms = Some(now_ms); self.connected = true; let response = self.create_packet( CultNetRudpPacketType::Accept, @@ -252,18 +232,7 @@ impl CultNetRudpSession { true, false, ); - if !was_connected { - self.track_reliable( - &CultNetRudpSendOptions { - reliable: true, - ordered: true, - sequenced: false, - now_ms, - reliable_expire_after_ms: None, - }, - response.clone(), - ); - } + self.track_reliable(response.clone(), now_ms); Ok(response) } @@ -291,7 +260,6 @@ impl CultNetRudpSession { "Cannot send RUDP data before the session is connected" )); } - self.purge_expired_reliable(options.now_ms); if let Some(max_fragment_bytes) = max_fragment_bytes { if max_fragment_bytes == 0 { @@ -320,7 +288,7 @@ impl CultNetRudpSession { fragment_count as u16, ); if packet.reliable { - self.track_reliable(&options, packet.clone()); + self.track_reliable(packet.clone(), options.now_ms); } packets.push(packet); } @@ -338,7 +306,7 @@ impl CultNetRudpSession { options.sequenced, ); if packet.reliable { - self.track_reliable(&options, packet.clone()); + self.track_reliable(packet.clone(), options.now_ms); } Ok(vec![packet]) } @@ -391,7 +359,9 @@ impl CultNetRudpSession { if packet.packet_type == CultNetRudpPacketType::Ack || packet.packet_type == CultNetRudpPacketType::Pong { - self.remember_received(packet.sequence); + if packet.packet_type == CultNetRudpPacketType::Pong { + self.remember_received(packet.sequence); + } return Ok(CultNetRudpReceiveResult { delivered: Vec::new(), reply: None, @@ -453,23 +423,6 @@ impl CultNetRudpSession { disconnect_reason: Vec::new(), }); }; - if packet.sequenced && !ordered { - let highest = self - .highest_delivered_sequenced_by_channel - .entry(frame.channel_id.clone()) - .or_insert(frame.sequence); - if frame.sequence < *highest { - return Ok(CultNetRudpReceiveResult { - delivered: Vec::new(), - reply: None, - pong: false, - pong_payload: Vec::new(), - disconnected: false, - disconnect_reason: Vec::new(), - }); - } - *highest = frame.sequence; - } let delivered = if ordered { self.deliver_ordered(frame, next_sequence, expected_sequence_if_uninitialized) } else { @@ -486,14 +439,22 @@ impl CultNetRudpSession { } pub fn create_ack(&mut self) -> CultNetRudpPacket { - self.create_packet( - CultNetRudpPacketType::Ack, - "control", - Vec::new(), - false, - false, - false, - ) + let (ack, ack_mask) = self.ack_state(); + CultNetRudpPacket { + packet_type: CultNetRudpPacketType::Ack, + connection_id: self.connection_id, + sequence: 0, + ack, + ack_mask, + channel_id: "control".to_string(), + reliable: false, + ordered: false, + sequenced: false, + fragment_id: 0, + fragment_index: 0, + fragment_count: 0, + payload: Vec::new(), + } } pub fn create_ping(&mut self, payload: Vec) -> CultNetRudpPacket { @@ -534,7 +495,6 @@ impl CultNetRudpSession { } pub fn due_resends(&mut self, now_ms: u64) -> Vec { - self.purge_expired_reliable(now_ms); let mut due = Vec::new(); for pending in self.pending_reliable.values_mut() { if now_ms.saturating_sub(pending.last_sent_at_ms) >= self.resend_delay_ms { @@ -604,16 +564,12 @@ impl CultNetRudpSession { } } - fn track_reliable(&mut self, options: &CultNetRudpSendOptions, packet: CultNetRudpPacket) { - let expires_at_ms = options - .reliable_expire_after_ms - .map(|ttl| options.now_ms.saturating_add(ttl)); + fn track_reliable(&mut self, packet: CultNetRudpPacket, now_ms: u64) { self.pending_reliable.insert( packet.sequence, PendingReliablePacket { packet, - last_sent_at_ms: options.now_ms, - expires_at_ms, + last_sent_at_ms: now_ms, }, ); } @@ -630,16 +586,6 @@ impl CultNetRudpSession { Ok(()) } - fn purge_expired_reliable(&mut self, now_ms: u64) { - let before = self.pending_reliable.len(); - self.pending_reliable.retain(|_, pending| { - pending - .expires_at_ms - .map_or(true, |expires_at_ms| now_ms <= expires_at_ms) - }); - self.reliable_packets_expired += (before - self.pending_reliable.len()) as u64; - } - fn apply_acknowledgements(&mut self, packet: &CultNetRudpPacket) { self.pending_reliable.remove(&packet.ack); for bit in 0..32 { @@ -755,7 +701,7 @@ impl CultNetRudpSession { expected_sequence_if_uninitialized: u32, ) -> Vec { let channel_id = frame.channel_id.clone(); - let next = if let Some(next) = self + let mut next = if let Some(next) = self .ordered_next_sequence_by_channel .get(&channel_id) .copied() @@ -769,6 +715,18 @@ impl CultNetRudpSession { expected_sequence_if_uninitialized.min(frame.sequence) }; + while frame.sequence > next + && self.received_sequences.contains(&next) + && !self + .ordered_buffers + .get(&channel_id) + .is_some_and(|buffer| buffer.contains_key(&next)) + { + next = next.saturating_add(1); + self.ordered_next_sequence_by_channel + .insert(channel_id.clone(), next); + } + if frame.sequence < next { return Vec::new(); } @@ -810,10 +768,31 @@ impl CultNetRudpSession { delivered.push(pending.frame); self.ordered_next_sequence_by_channel .insert(channel_id.to_string(), pending.next_sequence); + self.skip_received_non_channel_sequences(channel_id); } delivered } + fn skip_received_non_channel_sequences(&mut self, channel_id: &str) { + let Some(mut next) = self + .ordered_next_sequence_by_channel + .get(channel_id) + .copied() + else { + return; + }; + while self.received_sequences.contains(&next) + && !self + .ordered_buffers + .get(channel_id) + .is_some_and(|buffer| buffer.contains_key(&next)) + { + next = next.saturating_add(1); + self.ordered_next_sequence_by_channel + .insert(channel_id.to_string(), next); + } + } + fn allocate_fragment_id(&mut self) -> u16 { let fragment_id = self.next_fragment_id; self.next_fragment_id = self.next_fragment_id.saturating_add(1); @@ -853,7 +832,7 @@ pub struct CultNetRudpSocketTransportOptions { pub max_payload_bytes: Option, pub max_fragment_bytes: Option, pub max_pending_reliable_packets: Option, - pub media_reliable_expire_after_ms: Option, + pub reconnect_policy: Option, } impl CultNetRudpSocketTransportOptions { @@ -875,7 +854,7 @@ impl CultNetRudpSocketTransportOptions { max_payload_bytes: None, max_fragment_bytes: None, max_pending_reliable_packets: None, - media_reliable_expire_after_ms: Some(DEFAULT_MEDIA_RELIABLE_EXPIRE_AFTER_MS), + reconnect_policy: None, } } @@ -892,7 +871,7 @@ impl CultNetRudpSocketTransportOptions { max_payload_bytes: None, max_fragment_bytes: None, max_pending_reliable_packets: None, - media_reliable_expire_after_ms: Some(DEFAULT_MEDIA_RELIABLE_EXPIRE_AFTER_MS), + reconnect_policy: None, } } } @@ -903,7 +882,6 @@ pub struct CultNetRudpSocketTransportConnection { mode: CultNetRudpSocketMode, remote_addr: Option, pub profile: CultNetTransportProfile, - transport_id: Option, stats: CultNetTransportStats, delivered_frames: VecDeque, max_fragment_bytes: Option, @@ -914,7 +892,6 @@ pub struct CultNetRudpSocketTransportConnection { impl CultNetRudpSocketTransportConnection { pub fn new(options: CultNetRudpSocketTransportOptions) -> Result { let local_addr = options.socket.local_addr()?; - let transport_id = options.transport_id.clone(); let profile = create_rudp_transport_profile( options.runtime_id, RudpTransportProfileOptions { @@ -924,7 +901,7 @@ impl CultNetRudpSocketTransportConnection { max_payload_bytes: options.max_payload_bytes, max_fragment_bytes: options.max_fragment_bytes, max_pending_reliable_packets: options.max_pending_reliable_packets, - media_reliable_expire_after_ms: options.media_reliable_expire_after_ms, + reconnect_policy: options.reconnect_policy, }, ); let max_pending_reliable_packets = options @@ -941,7 +918,6 @@ impl CultNetRudpSocketTransportConnection { mode: options.mode, remote_addr: options.remote_addr, profile, - transport_id, stats: CultNetTransportStats::default(), delivered_frames: VecDeque::new(), max_fragment_bytes: options.max_fragment_bytes.map(|value| value as usize), @@ -954,14 +930,8 @@ impl CultNetRudpSocketTransportConnection { self.session.connected() } - pub fn assume_connected(&mut self) { - self.session.assume_connected(now_ms()); - } - pub fn stats(&self) -> CultNetTransportStats { - let mut stats = self.stats.clone(); - stats.reliable_packets_expired = self.session.reliable_packets_expired(); - stats + self.stats.clone() } pub fn disconnect_reason(&self) -> Option<&[u8]> { @@ -983,21 +953,38 @@ impl CultNetRudpSocketTransportConnection { } pub fn send(&mut self, channel_id: &str, payload: Vec) -> Result<()> { - let options = self.channel_send_options(channel_id, now_ms()); + let options = channel_send_options(channel_id, now_ms()); let packets = self.session .send_many(channel_id, payload, options, self.max_fragment_bytes)?; - let fragmented = packets.len() > 1; - for (index, packet) in packets.iter().enumerate() { - self.send_packet(packet)?; - if fragmented && (index + 1) % 16 == 0 { - thread::sleep(Duration::from_millis(1)); - } + for packet in packets { + self.send_packet(&packet)?; } self.stats.frames_sent += 1; Ok(()) } + pub fn send_schema_message(&mut self, message: &CultNetMessage) -> Result<()> { + let payload = encode_cultnet_message_to_vec(message, CultNetWireContract::CultNetSchemaV0)?; + self.send("schema", payload) + } + + pub fn receive_schema_message_once(&mut self) -> Result> { + let Some(frame) = self.receive_once()? else { + return Ok(None); + }; + if frame.channel_id != "schema" { + return Err(anyhow!( + "Expected RUDP schema frame, received channel {}", + frame.channel_id + )); + } + Ok(Some(decode_cultnet_message_from_slice( + &frame.payload, + CultNetWireContract::CultNetSchemaV0, + )?)) + } + pub fn disconnect(&mut self, reason: Vec) -> Result<()> { let packet = self.session.create_disconnect(reason); self.send_packet(&packet) @@ -1012,42 +999,8 @@ impl CultNetRudpSocketTransportConnection { self.session.check_timeout(now_ms(), timeout_ms) } - fn channel_send_options(&self, channel_id: &str, now_ms: u64) -> CultNetRudpSendOptions { - match channel_id { - "schema" => CultNetRudpSendOptions { - reliable: true, - ordered: true, - sequenced: false, - now_ms, - reliable_expire_after_ms: None, - }, - "latest" => CultNetRudpSendOptions { - reliable: false, - ordered: false, - sequenced: true, - now_ms, - reliable_expire_after_ms: None, - }, - "media" => CultNetRudpSendOptions { - reliable: false, - ordered: false, - sequenced: false, - now_ms, - reliable_expire_after_ms: None, - }, - _ => CultNetRudpSendOptions { - reliable: false, - ordered: false, - sequenced: false, - now_ms, - reliable_expire_after_ms: None, - }, - } - } - pub fn receive_once(&mut self) -> Result> { if let Some(frame) = self.delivered_frames.pop_front() { - self.session.assume_connected(now_ms()); return Ok(Some(frame)); } @@ -1064,42 +1017,7 @@ impl CultNetRudpSocketTransportConnection { wire.truncate(received); self.stats.bytes_received += received as u64; - let packet = match decode_rudp_packet(&wire) { - Ok(packet) => packet, - Err(error) => { - if std::env::var_os("CULTNET_RUDP_TRACE").is_some() - && self.transport_id.as_deref() == Some("muninn-provider-command-rudp") - { - eprintln!("RUDP muninn-provider-command-rudp rejected {} bytes from {remote_addr}: {error:#}", wire.len()); - } - return Ok(None); - } - }; - let trace_transport = std::env::var_os("CULTNET_RUDP_TRACE").is_some() - && self - .transport_id - .as_deref() - .is_some_and(|id| { - id == "sleipnir-hid-rudp" - || id == "muninn-hid-controller-rudp" - || id == "muninn-provider-command-rudp" - }); - if trace_transport { - eprintln!( - "RUDP {} recv {:?} channel={} seq={} ack={} reliable={} ordered={} sequenced={} bytes={} from {}", - self.transport_id.as_deref().unwrap_or("unknown"), - packet.packet_type, - packet.channel_id, - packet.sequence, - packet.ack, - packet.reliable, - packet.ordered, - packet.sequenced, - packet.payload.len(), - remote_addr - ); - } - + let packet = decode_rudp_packet(&wire)?; if let Some(expected) = self.remote_addr { if expected != remote_addr { if self.mode == CultNetRudpSocketMode::Server @@ -1155,11 +1073,8 @@ impl CultNetRudpSocketTransportConnection { } pub fn poll_resends(&mut self) -> Result<()> { - for (index, packet) in self.session.due_resends(now_ms()).into_iter().enumerate() { + for packet in self.session.due_resends(now_ms()) { self.send_packet(&packet)?; - if (index + 1) % 16 == 0 { - thread::sleep(Duration::from_millis(1)); - } } Ok(()) } @@ -1171,33 +1086,104 @@ impl CultNetRudpSocketTransportConnection { )); }; let wire = encode_rudp_packet(packet)?; - let trace_transport = std::env::var_os("CULTNET_RUDP_TRACE").is_some() - && self - .transport_id - .as_deref() - .is_some_and(|id| id == "sleipnir-hid-rudp" || id == "muninn-hid-controller-rudp"); - if trace_transport { - eprintln!( - "RUDP {} send {:?} channel={} seq={} ack={} reliable={} ordered={} sequenced={} payload={} wire={} to {}", - self.transport_id.as_deref().unwrap_or("unknown"), - packet.packet_type, - packet.channel_id, - packet.sequence, - packet.ack, - packet.reliable, - packet.ordered, - packet.sequenced, - packet.payload.len(), - wire.len(), - remote_addr - ); - } let sent = self.socket.send_to(&wire, remote_addr)?; self.stats.bytes_sent += sent as u64; Ok(()) } } +pub struct CultNetRudpReconnectLoop +where + F: FnMut() -> Result, +{ + pub reconnect_controller: CultNetReconnectController, + create_transport: F, + connect_payload: Vec, + transport: Option, + stopped: bool, +} + +impl CultNetRudpReconnectLoop +where + F: FnMut() -> Result, +{ + pub fn new( + reconnect_policy: CultNetReconnectPolicy, + connect_payload: Vec, + create_transport: F, + ) -> Self { + Self { + reconnect_controller: CultNetReconnectController::new(reconnect_policy), + create_transport, + connect_payload, + transport: None, + stopped: true, + } + } + + pub fn with_default_policy(connect_payload: Vec, create_transport: F) -> Self { + Self::new( + create_reconnect_policy(Default::default()), + connect_payload, + create_transport, + ) + } + + pub fn transport(&self) -> Option<&CultNetRudpSocketTransportConnection> { + self.transport.as_ref() + } + + pub fn transport_mut(&mut self) -> Option<&mut CultNetRudpSocketTransportConnection> { + self.transport.as_mut() + } + + pub fn start(&mut self) -> Result<&mut CultNetRudpSocketTransportConnection> { + self.stopped = false; + self.reconnect_controller.reset(); + self.open_transport() + } + + pub fn stop(&mut self) { + self.stopped = true; + self.transport = None; + self.reconnect_controller.reset(); + } + + pub fn mark_connected(&mut self) { + self.reconnect_controller.reset(); + } + + pub fn handle_closed( + &mut self, + now_ms: u64, + jitter_ms: u64, + ) -> Option { + self.transport = None; + if self.stopped { + return None; + } + Some(self.reconnect_controller.record_failure(now_ms, jitter_ms)) + } + + pub fn reconnect_if_due(&mut self, now_ms: u64) -> Result { + if self.stopped || !self.reconnect_controller.can_attempt(now_ms) { + return Ok(false); + } + self.open_transport()?; + Ok(true) + } + + fn open_transport(&mut self) -> Result<&mut CultNetRudpSocketTransportConnection> { + let mut transport = (self.create_transport)()?; + transport.connect(self.connect_payload.clone())?; + self.transport = Some(transport); + Ok(self + .transport + .as_mut() + .expect("RUDP reconnect loop opened a transport")) + } +} + #[derive(Clone, Debug, Default)] pub struct RudpTransportProfileOptions { pub transport_id: Option, @@ -1206,7 +1192,7 @@ pub struct RudpTransportProfileOptions { pub max_payload_bytes: Option, pub max_fragment_bytes: Option, pub max_pending_reliable_packets: Option, - pub media_reliable_expire_after_ms: Option, + pub reconnect_policy: Option, } pub fn create_rudp_transport_profile( @@ -1224,6 +1210,11 @@ pub fn create_rudp_transport_profile( path: None, discovery_group: None, wire_contracts: Some(vec!["cultnet.schema.v0".to_string()]), + reconnect_policy: Some( + options + .reconnect_policy + .unwrap_or_else(|| create_reconnect_policy(Default::default())), + ), channels: vec![ CultNetTransportChannel { channel_id: "schema".to_string(), @@ -1232,7 +1223,6 @@ pub fn create_rudp_transport_profile( max_payload_bytes: options.max_payload_bytes, max_fragment_bytes: options.max_fragment_bytes, max_pending_reliable_packets: options.max_pending_reliable_packets, - reliable_expire_after_ms: None, }, CultNetTransportChannel { channel_id: "latest".to_string(), @@ -1241,7 +1231,6 @@ pub fn create_rudp_transport_profile( max_payload_bytes: options.max_payload_bytes, max_fragment_bytes: options.max_fragment_bytes, max_pending_reliable_packets: options.max_pending_reliable_packets, - reliable_expire_after_ms: None, }, CultNetTransportChannel { channel_id: "realtime".to_string(), @@ -1250,16 +1239,14 @@ pub fn create_rudp_transport_profile( max_payload_bytes: options.max_payload_bytes, max_fragment_bytes: options.max_fragment_bytes, max_pending_reliable_packets: options.max_pending_reliable_packets, - reliable_expire_after_ms: None, }, CultNetTransportChannel { channel_id: "media".to_string(), - delivery: CultNetTransportDelivery::Unreliable, + delivery: CultNetTransportDelivery::Reliable, ordering: CultNetTransportOrdering::Unordered, max_payload_bytes: options.max_payload_bytes, max_fragment_bytes: options.max_fragment_bytes, max_pending_reliable_packets: options.max_pending_reliable_packets, - reliable_expire_after_ms: None, }, ], }], @@ -1368,6 +1355,35 @@ fn packet_type_to_code(packet_type: CultNetRudpPacketType) -> u8 { } } +fn channel_send_options(channel_id: &str, now_ms: u64) -> CultNetRudpSendOptions { + match channel_id { + "schema" => CultNetRudpSendOptions { + reliable: true, + ordered: true, + sequenced: false, + now_ms, + }, + "latest" => CultNetRudpSendOptions { + reliable: false, + ordered: false, + sequenced: true, + now_ms, + }, + "media" => CultNetRudpSendOptions { + reliable: true, + ordered: false, + sequenced: false, + now_ms, + }, + _ => CultNetRudpSendOptions { + reliable: false, + ordered: false, + sequenced: false, + now_ms, + }, + } +} + fn now_ms() -> u64 { SystemTime::now() .duration_since(UNIX_EPOCH) @@ -1387,58 +1403,3 @@ fn packet_type_from_code(code: u8) -> Result { _ => Err(anyhow!("Unsupported CultNet RUDP packet type {code}")), } } - -#[cfg(test)] -mod tests { - use super::*; - - fn connected_session(initial_sequence: u32) -> CultNetRudpSession { - let mut session = CultNetRudpSession::new(CultNetRudpSessionOptions { - connection_id: 0xCAFE_BABE, - initial_sequence, - resend_delay_ms: 5, - max_pending_reliable_packets: Some(64), - }); - session.assume_connected(1); - session - } - - #[test] - fn sequenced_unordered_channel_drops_older_late_frames() { - let mut sender = connected_session(1); - let mut receiver = connected_session(1); - let first = sender - .send( - "latest", - b"first".to_vec(), - CultNetRudpSendOptions { - reliable: false, - ordered: false, - sequenced: true, - now_ms: 1, - reliable_expire_after_ms: None, - }, - ) - .unwrap(); - let second = sender - .send( - "latest", - b"second".to_vec(), - CultNetRudpSendOptions { - reliable: false, - ordered: false, - sequenced: true, - now_ms: 2, - reliable_expire_after_ms: None, - }, - ) - .unwrap(); - - let delivered_second = receiver.receive(&second, 2).unwrap().delivered; - let delivered_first = receiver.receive(&first, 3).unwrap().delivered; - - assert_eq!(delivered_second.len(), 1); - assert_eq!(delivered_second[0].payload, b"second"); - assert!(delivered_first.is_empty()); - } -} diff --git a/vendor/cultnet-rs/src/schema_discovery.rs b/vendor/cultnet-rs/src/schema_discovery.rs index 2cc1420..272323b 100644 --- a/vendor/cultnet-rs/src/schema_discovery.rs +++ b/vendor/cultnet-rs/src/schema_discovery.rs @@ -353,6 +353,20 @@ pub fn builtin_schema_registry() -> Result { Some("cultnet.schema_catalog_response.v0"), None, )?, + schema_registration( + include_str!("../contracts/cultnet.shard-catalog-request.schema.json"), + CultNetSchemaKind::WireMessage, + vec![CultNetWireContract::CultNetSchemaV0], + Some("cultnet.shard_catalog_request.v0"), + None, + )?, + schema_registration( + include_str!("../contracts/cultnet.shard-catalog-response.schema.json"), + CultNetSchemaKind::WireMessage, + vec![CultNetWireContract::CultNetSchemaV0], + Some("cultnet.shard_catalog_response.v0"), + None, + )?, schema_registration( include_str!("../contracts/ghostlight.agent-state.schema.json"), CultNetSchemaKind::DocumentPayload, diff --git a/vendor/cultnet-rs/src/shard_catalog.rs b/vendor/cultnet-rs/src/shard_catalog.rs new file mode 100644 index 0000000..a112246 --- /dev/null +++ b/vendor/cultnet-rs/src/shard_catalog.rs @@ -0,0 +1,134 @@ +use anyhow::Result; +use anyhow::anyhow; +use std::collections::BTreeMap; +use std::collections::BTreeSet; + +use crate::CultNetMessage; +use crate::CultNetShardDescriptor; + +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct CultNetShardCatalogOptions { + pub schema_ids: Option>, + pub record_keys: Option>, +} + +#[derive(Clone, Debug, Default)] +pub struct CultNetShardCatalog { + shards: BTreeMap, +} + +impl CultNetShardCatalog { + pub fn new() -> Self { + Self::default() + } + + pub fn upsert(&mut self, descriptor: CultNetShardDescriptor) -> Result<()> { + validate_descriptor(&descriptor)?; + self.shards.insert(descriptor.shard_id.clone(), descriptor); + Ok(()) + } + + pub fn get(&self, shard_id: &str) -> Option<&CultNetShardDescriptor> { + self.shards.get(shard_id) + } + + pub fn list(&self, options: &CultNetShardCatalogOptions) -> Vec { + let schema_ids = options + .schema_ids + .as_ref() + .map(|values| values.iter().cloned().collect::>()); + let record_keys = options + .record_keys + .as_ref() + .map(|values| values.iter().cloned().collect::>()); + + self.shards + .values() + .filter(|shard| { + let schema_match = schema_ids.as_ref().is_none_or(|requested| { + requested + .iter() + .any(|schema_id| shard.serves(Some(schema_id), None)) + }); + let key_match = record_keys.as_ref().is_none_or(|requested| { + requested + .iter() + .any(|record_key| shard.serves(None, Some(record_key))) + }); + schema_match && key_match + }) + .cloned() + .collect() + } + + pub fn create_catalog_response(&self, request: &CultNetMessage) -> Result { + let CultNetMessage::ShardCatalogRequest { + message_id, + schema_ids, + record_keys, + } = request + else { + return Err(anyhow!( + "expected cultnet.shard_catalog_request.v0 for shard discovery" + )); + }; + + Ok(CultNetMessage::ShardCatalogResponse { + message_id: message_id.clone(), + shards: self.list(&CultNetShardCatalogOptions { + schema_ids: schema_ids.clone(), + record_keys: record_keys.clone(), + }), + }) + } + + pub fn apply_response( + &mut self, + response: &CultNetMessage, + ) -> Result> { + let CultNetMessage::ShardCatalogResponse { shards, .. } = response else { + return Err(anyhow!( + "expected cultnet.shard_catalog_response.v0 for shard discovery" + )); + }; + + let mut applied = Vec::with_capacity(shards.len()); + for shard in shards { + self.upsert(shard.clone())?; + applied.push(shard.clone()); + } + Ok(applied) + } +} + +fn validate_descriptor(descriptor: &CultNetShardDescriptor) -> Result<()> { + if descriptor.shard_id.trim().is_empty() { + return Err(anyhow!("shard_id must be non-empty")); + } + if descriptor.owner_runtime_id.trim().is_empty() { + return Err(anyhow!("owner_runtime_id must be non-empty")); + } + for schema_id in &descriptor.schema_ids { + if schema_id.trim().is_empty() { + return Err(anyhow!("schema_ids must not contain empty values")); + } + } + if descriptor + .key_prefix + .as_deref() + .is_some_and(|value| value.trim().is_empty()) + { + return Err(anyhow!("key_prefix must be non-empty when present")); + } + for endpoint in descriptor + .primary_endpoints + .iter() + .chain(descriptor.replica_endpoints.iter()) + .chain(descriptor.read_replica_endpoints.iter()) + { + if endpoint.trim().is_empty() { + return Err(anyhow!("shard endpoints must not contain empty values")); + } + } + Ok(()) +} diff --git a/vendor/cultnet-rs/src/transport.rs b/vendor/cultnet-rs/src/transport.rs index 55e0097..d7aad26 100644 --- a/vendor/cultnet-rs/src/transport.rs +++ b/vendor/cultnet-rs/src/transport.rs @@ -1,10 +1,9 @@ use anyhow::Result; use anyhow::anyhow; -use serde::Deserialize; -use serde::Serialize; use std::io::Read; use std::io::Write; +use crate::CultNetReconnectPolicy; use crate::CultNetTransportChannel; use crate::CultNetTransportDelivery; use crate::CultNetTransportDescriptor; @@ -20,7 +19,6 @@ pub struct CultNetTransportStats { pub bytes_sent: u64, pub frames_received: u64, pub frames_sent: u64, - pub reliable_packets_expired: u64, } #[derive(Clone, Debug, PartialEq, Eq)] @@ -29,18 +27,6 @@ pub struct CultNetTransportFrame { pub payload: Vec, } -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct CultNetReconnectPolicy { - pub schema_version: String, - pub policy_id: String, - pub base_delay_ms: u64, - pub max_delay_ms: u64, - pub max_jitter_ms: u64, - #[serde(skip_serializing_if = "Option::is_none")] - pub max_attempts: Option, -} - #[derive(Clone, Debug)] pub struct CultNetReconnectPolicyOptions { pub policy_id: String, @@ -91,6 +77,96 @@ pub fn compute_reconnect_delay_ms( capped_base_delay + jitter_ms.min(policy.max_jitter_ms) } +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct CultNetReconnectDecision { + pub attempt: u32, + pub should_retry: bool, + pub delay_ms: u64, + pub next_attempt_at_ms: Option, + pub exhausted: bool, +} + +#[derive(Clone, Debug)] +pub struct CultNetReconnectController { + pub policy: CultNetReconnectPolicy, + attempt: u32, + next_attempt_at_ms: Option, + exhausted: bool, +} + +impl Default for CultNetReconnectController { + fn default() -> Self { + Self::new(create_reconnect_policy(Default::default())) + } +} + +impl CultNetReconnectController { + pub fn new(policy: CultNetReconnectPolicy) -> Self { + Self { + policy, + attempt: 0, + next_attempt_at_ms: None, + exhausted: false, + } + } + + pub fn attempt(&self) -> u32 { + self.attempt + } + + pub fn next_attempt_at_ms(&self) -> Option { + self.next_attempt_at_ms + } + + pub fn exhausted(&self) -> bool { + self.exhausted + } + + pub fn reset(&mut self) { + self.attempt = 0; + self.next_attempt_at_ms = None; + self.exhausted = false; + } + + pub fn can_attempt(&self, now_ms: u64) -> bool { + !self.exhausted + && self + .next_attempt_at_ms + .is_none_or(|next_attempt_at_ms| now_ms >= next_attempt_at_ms) + } + + pub fn record_failure(&mut self, now_ms: u64, jitter_ms: u64) -> CultNetReconnectDecision { + let next_attempt = self.attempt.saturating_add(1); + if self + .policy + .max_attempts + .is_some_and(|max_attempts| next_attempt > max_attempts) + { + self.exhausted = true; + self.next_attempt_at_ms = None; + return CultNetReconnectDecision { + attempt: self.attempt, + should_retry: false, + delay_ms: 0, + next_attempt_at_ms: None, + exhausted: true, + }; + } + + self.attempt = next_attempt; + let delay_ms = compute_reconnect_delay_ms(&self.policy, self.attempt, jitter_ms); + let next_attempt_at_ms = now_ms.saturating_add(delay_ms); + self.next_attempt_at_ms = Some(next_attempt_at_ms); + CultNetReconnectDecision { + attempt: self.attempt, + should_retry: true, + delay_ms, + next_attempt_at_ms: Some(next_attempt_at_ms), + exhausted: false, + } + } +} + #[derive(Clone, Debug, Default)] pub struct TcpFramedTransportProfileOptions { pub transport_id: Option, @@ -117,6 +193,7 @@ pub fn create_tcp_framed_transport_profile( path: None, discovery_group: None, wire_contracts: Some(vec!["cultnet.schema.v0".to_string()]), + reconnect_policy: None, channels: vec![CultNetTransportChannel { channel_id: "schema".to_string(), delivery: CultNetTransportDelivery::Reliable, @@ -124,7 +201,6 @@ pub fn create_tcp_framed_transport_profile( max_payload_bytes: options.max_payload_bytes, max_fragment_bytes: options.max_fragment_bytes, max_pending_reliable_packets: None, - reliable_expire_after_ms: None, }], }], } diff --git a/vendor/cultnet-rs/tests/cultnet.rs b/vendor/cultnet-rs/tests/cultnet.rs index a650e28..6511fdb 100644 --- a/vendor/cultnet-rs/tests/cultnet.rs +++ b/vendor/cultnet-rs/tests/cultnet.rs @@ -1,8 +1,14 @@ use anyhow::Result; use chrono::Duration; +use chrono::Utc; use cultcache_rs::CultCache; use cultcache_rs::DatabaseEntry; use cultcache_rs::SingleFileMessagePackBackingStore; +use cultnet_rs::CultMesh; +use cultnet_rs::CultMeshAuthorityLease; +use cultnet_rs::CultMeshPeerCard; +use cultnet_rs::CultMeshRudpClientOptions; +use cultnet_rs::CultMeshRudpSocketOptions; use cultnet_rs::CultNetClientSecurityOptions; use cultnet_rs::CultNetDocumentBinding; use cultnet_rs::CultNetDocumentMutationContract; @@ -11,8 +17,12 @@ use cultnet_rs::CultNetDocumentPutOptions; use cultnet_rs::CultNetDocumentRegistry; use cultnet_rs::CultNetMessage; use cultnet_rs::CultNetMutationAuthority; +use cultnet_rs::CultNetReactiveDocumentOptions; +use cultnet_rs::CultNetReconnectController; +use cultnet_rs::CultNetReconnectPolicyOptions; use cultnet_rs::CultNetRudpPacket; use cultnet_rs::CultNetRudpPacketType; +use cultnet_rs::CultNetRudpReconnectLoop; use cultnet_rs::CultNetRudpSendOptions; use cultnet_rs::CultNetRudpSession; use cultnet_rs::CultNetRudpSessionOptions; @@ -20,9 +30,12 @@ use cultnet_rs::CultNetRudpSocketMode; use cultnet_rs::CultNetRudpSocketTransportConnection; use cultnet_rs::CultNetRudpSocketTransportOptions; use cultnet_rs::CultNetSchemaKind; +use cultnet_rs::CultNetSchemaRegistration; use cultnet_rs::CultNetSchemaRegistry; use cultnet_rs::CultNetSecret; use cultnet_rs::CultNetServerSecurityOptions; +use cultnet_rs::CultNetShardCatalog; +use cultnet_rs::CultNetShardDescriptor; use cultnet_rs::CultNetTransportChannel; use cultnet_rs::CultNetTransportDelivery; use cultnet_rs::CultNetTransportDescriptor; @@ -35,6 +48,8 @@ use cultnet_rs::LengthPrefixedMessageFramer; use cultnet_rs::TcpFramedTransportConnection; use cultnet_rs::TcpFramedTransportProfileOptions; use cultnet_rs::builtin_schema_registry; +use cultnet_rs::compute_reconnect_delay_ms; +use cultnet_rs::create_reconnect_policy; use cultnet_rs::create_rudp_transport_profile; use cultnet_rs::create_tcp_framed_transport_profile; use cultnet_rs::decode_cultnet_message_from_slice; @@ -44,7 +59,11 @@ use cultnet_rs::encode_cultnet_message_to_vec; use cultnet_rs::encode_frame; use cultnet_rs::encode_rudp_packet; use pretty_assertions::assert_eq; +use std::cell::RefCell; use std::net::UdpSocket; +use std::rc::Rc; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::{Arc, Mutex}; use std::thread; use std::time::Duration as StdDuration; @@ -85,6 +104,38 @@ fn receive_rudp_frame( anyhow::bail!("RUDP socket frame was not delivered") } +fn receive_rudp_schema_message( + transport: &mut CultNetRudpSocketTransportConnection, +) -> Result { + for _ in 0..20 { + if let Some(message) = transport.receive_schema_message_once()? { + return Ok(message); + } + thread::sleep(StdDuration::from_millis(5)); + } + anyhow::bail!("RUDP schema message was not delivered") +} + +fn pump_rudp_server_until_connected( + server: Arc>, + done: Arc, +) -> thread::JoinHandle> { + thread::spawn(move || { + while !done.load(Ordering::SeqCst) { + { + let mut server = server.lock().expect("RUDP server mutex poisoned"); + let _ = server.receive_once()?; + server.poll_resends()?; + if server.connected() { + return Ok(()); + } + } + thread::sleep(StdDuration::from_millis(5)); + } + Ok(()) + }) +} + #[derive(Clone, Debug, PartialEq, DatabaseEntry)] #[cultcache( type = "ghostlight.agent-state", @@ -99,6 +150,44 @@ struct GhostlightAgentStateFixture { display_name: String, } +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "ghostlight.agent-state.ui", + schema = "GhostlightAgentStateUiFixture" +)] +struct GhostlightAgentStateUiFixture { + #[cultcache(key = 0)] + schema_version: String, + #[cultcache(key = 1)] + agent_id: String, + #[cultcache(key = 2)] + display_name: String, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "ghostlight.reactive-note", + schema = "GhostlightReactiveNoteFixture" +)] +struct GhostlightReactiveNoteFixture { + #[cultcache(key = 0)] + body: String, + #[cultcache(key = 1)] + revision: i32, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "ghostlight.reactive-note.ui", + schema = "GhostlightReactiveNoteUiFixture" +)] +struct GhostlightReactiveNoteUiFixture { + #[cultcache(key = 0)] + body: String, + #[cultcache(key = 1)] + revision: i32, +} + #[test] fn security_helpers_round_trip_encrypted_strings_and_validate_sessions() -> Result<()> { let server_security = CultNetServerSecurityOptions::development(); @@ -158,6 +247,7 @@ fn cultnet_schema_messages_round_trip_through_messagepack_frames() -> Result<()> path: None, discovery_group: None, wire_contracts: Some(vec!["cultnet.schema.v0".to_string()]), + reconnect_policy: None, channels: vec![CultNetTransportChannel { channel_id: "schema".to_string(), delivery: CultNetTransportDelivery::Reliable, @@ -165,7 +255,6 @@ fn cultnet_schema_messages_round_trip_through_messagepack_frames() -> Result<()> max_payload_bytes: None, max_fragment_bytes: None, max_pending_reliable_packets: None, - reliable_expire_after_ms: None, }], }], }]), @@ -272,7 +361,7 @@ fn rudp_transport_profile_advertises_state_and_realtime_channels() { max_payload_bytes: Some(1200), max_fragment_bytes: Some(1000), max_pending_reliable_packets: Some(64), - media_reliable_expire_after_ms: Some(75), + reconnect_policy: None, }, ); @@ -280,6 +369,20 @@ fn rudp_transport_profile_advertises_state_and_realtime_channels() { profile.transports[0].protocol, CultNetTransportProtocol::Rudp ); + assert_eq!( + profile.transports[0] + .reconnect_policy + .as_ref() + .map(|policy| policy.schema_version.as_str()), + Some("cultnet.reconnect_policy.v0") + ); + assert_eq!( + profile.transports[0] + .reconnect_policy + .as_ref() + .map(|policy| policy.base_delay_ms), + Some(1_000) + ); let channels = profile.transports[0] .channels .iter() @@ -289,7 +392,6 @@ fn rudp_transport_profile_advertises_state_and_realtime_channels() { channel.delivery, channel.ordering, channel.max_pending_reliable_packets, - channel.reliable_expire_after_ms, ) }) .collect::>(); @@ -300,34 +402,142 @@ fn rudp_transport_profile_advertises_state_and_realtime_channels() { "schema", CultNetTransportDelivery::Reliable, CultNetTransportOrdering::Ordered, - Some(64), - None + Some(64) ), ( "latest", CultNetTransportDelivery::Unreliable, CultNetTransportOrdering::Sequenced, - Some(64), - None + Some(64) ), ( "realtime", CultNetTransportDelivery::Unreliable, CultNetTransportOrdering::Unordered, - Some(64), - None + Some(64) ), ( "media", CultNetTransportDelivery::Reliable, CultNetTransportOrdering::Unordered, - Some(64), - Some(75) + Some(64) ), ] ); } +#[test] +fn reconnect_policy_exposes_portable_delay_contract() { + let policy = create_reconnect_policy(CultNetReconnectPolicyOptions { + policy_id: "rudp-default".to_string(), + max_attempts: Some(8), + ..CultNetReconnectPolicyOptions::default() + }); + + assert_eq!(policy.schema_version, "cultnet.reconnect_policy.v0"); + assert_eq!(policy.policy_id, "rudp-default"); + assert_eq!(policy.max_attempts, Some(8)); + assert_eq!(compute_reconnect_delay_ms(&policy, 1, 0), 1_000); + assert_eq!(compute_reconnect_delay_ms(&policy, 3, 17), 4_017); + assert_eq!(compute_reconnect_delay_ms(&policy, 9, 999), 30_250); + assert_eq!(compute_reconnect_delay_ms(&policy, 0, 0), 1_000); +} + +#[test] +fn reconnect_controller_schedules_attempts_and_reset() { + let policy = create_reconnect_policy(CultNetReconnectPolicyOptions { + max_attempts: Some(2), + ..CultNetReconnectPolicyOptions::default() + }); + let mut controller = CultNetReconnectController::new(policy); + + let first = controller.record_failure(10_000, 0); + assert_eq!(first.attempt, 1); + assert!(first.should_retry); + assert_eq!(first.delay_ms, 1_000); + assert_eq!(first.next_attempt_at_ms, Some(11_000)); + assert!(!first.exhausted); + assert!(!controller.can_attempt(10_999)); + assert!(controller.can_attempt(11_000)); + + let second = controller.record_failure(11_000, 17); + assert_eq!(second.attempt, 2); + assert_eq!(second.delay_ms, 2_017); + assert_eq!(second.next_attempt_at_ms, Some(13_017)); + assert!(second.should_retry); + + let exhausted = controller.record_failure(13_017, 0); + assert_eq!(exhausted.attempt, 2); + assert!(!exhausted.should_retry); + assert_eq!(exhausted.delay_ms, 0); + assert_eq!(exhausted.next_attempt_at_ms, None); + assert!(exhausted.exhausted); + assert!(!controller.can_attempt(99_000)); + + controller.reset(); + assert_eq!(controller.attempt(), 0); + assert_eq!(controller.next_attempt_at_ms(), None); + assert!(!controller.exhausted()); + assert!(controller.can_attempt(99_000)); +} + +#[test] +fn rudp_reconnect_loop_consumes_shared_controller() -> Result<()> { + let server_socket = bind_udp_socket()?; + let remote_addr = server_socket.local_addr()?; + let opened_local_addrs = Rc::new(RefCell::new(Vec::new())); + let opened_for_factory = Rc::clone(&opened_local_addrs); + let connection_id = 0x2233_4455; + let policy = create_reconnect_policy(CultNetReconnectPolicyOptions { + max_attempts: Some(2), + ..CultNetReconnectPolicyOptions::default() + }); + + let mut loop_ = CultNetRudpReconnectLoop::new(policy, b"join".to_vec(), move || { + let socket = bind_udp_socket()?; + opened_for_factory.borrow_mut().push(socket.local_addr()?); + CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions::client( + "rust-rudp-reconnect", + socket, + remote_addr, + connection_id, + )) + }); + + { + let first = loop_.start()?; + assert!(first.stats().bytes_sent > 0); + } + assert!(loop_.transport().is_some()); + assert_eq!(opened_local_addrs.borrow().len(), 1); + + let decision = loop_.handle_closed(10_000, 17).expect("retry decision"); + assert_eq!(decision.attempt, 1); + assert!(decision.should_retry); + assert_eq!(decision.delay_ms, 1_017); + assert_eq!(decision.next_attempt_at_ms, Some(11_017)); + assert_eq!(loop_.reconnect_controller.attempt(), 1); + assert_eq!( + loop_.reconnect_controller.next_attempt_at_ms(), + Some(11_017) + ); + + assert!(!loop_.reconnect_if_due(11_016)?); + assert_eq!(opened_local_addrs.borrow().len(), 1); + assert!(loop_.reconnect_if_due(11_017)?); + assert_eq!(opened_local_addrs.borrow().len(), 2); + assert!(loop_.transport().is_some()); + + loop_.mark_connected(); + assert_eq!(loop_.reconnect_controller.attempt(), 0); + + loop_.stop(); + assert!(loop_.transport().is_none()); + assert_eq!(loop_.reconnect_controller.attempt(), 0); + + Ok(()) +} + #[test] fn rudp_session_handshake_acks_reliable_connect_and_accept_packets() -> Result<()> { let mut client = CultNetRudpSession::new(CultNetRudpSessionOptions { @@ -513,74 +723,6 @@ fn rudp_session_schedules_reliable_resends_until_acked() -> Result<()> { Ok(()) } -#[test] -fn rudp_session_expires_bounded_reliable_media_resends() -> Result<()> { - let mut session = CultNetRudpSession::new(CultNetRudpSessionOptions { - connection_id: 100, - initial_sequence: 1, - resend_delay_ms: 20, - media_reliable_expire_after_ms: Some(50), - max_pending_reliable_packets: Some(1), - }); - session.receive( - &CultNetRudpPacket { - packet_type: CultNetRudpPacketType::Accept, - connection_id: 100, - sequence: 50, - ack: 0, - ack_mask: 0, - channel_id: "control".to_string(), - reliable: false, - ordered: false, - sequenced: false, - fragment_id: 0, - fragment_index: 0, - fragment_count: 0, - payload: Vec::new(), - }, - 0, - )?; - let sent = session.send( - "media", - b"frame-chunk".to_vec(), - CultNetRudpSendOptions { - reliable: true, - ordered: false, - now_ms: 10, - reliable_expire_after_ms: Some(50), - ..CultNetRudpSendOptions::default() - }, - )?; - - assert_eq!(session.pending_reliable_sequences(), vec![sent.sequence]); - assert!(session.due_resends(25).is_empty()); - assert_eq!( - session - .due_resends(35) - .iter() - .map(|packet| packet.sequence) - .collect::>(), - vec![sent.sequence] - ); - assert!(session.due_resends(61).is_empty()); - assert!(session.pending_reliable_sequences().is_empty()); - assert_eq!(session.reliable_packets_expired(), 1); - - session.send( - "media", - b"fresh-frame-chunk".to_vec(), - CultNetRudpSendOptions { - reliable: true, - ordered: false, - now_ms: 62, - reliable_expire_after_ms: Some(50), - ..CultNetRudpSendOptions::default() - }, - )?; - assert_eq!(session.reliable_packets_expired(), 1); - Ok(()) -} - #[test] fn rudp_session_pings_and_detects_receive_timeout() -> Result<()> { let mut client = CultNetRudpSession::new(CultNetRudpSessionOptions { @@ -793,6 +935,88 @@ fn rudp_session_suppresses_duplicates_and_delivers_reliable_ordered_payloads_in_ Ok(()) } +#[test] +fn rudp_session_skips_control_packets_while_ordering_schema_payloads() -> Result<()> { + let mut sender = CultNetRudpSession::new(CultNetRudpSessionOptions { + connection_id: 124, + initial_sequence: 1, + ..CultNetRudpSessionOptions::default() + }); + let mut receiver = CultNetRudpSession::new(CultNetRudpSessionOptions { + connection_id: 124, + initial_sequence: 100, + ..CultNetRudpSessionOptions::default() + }); + sender.receive( + &CultNetRudpPacket { + packet_type: CultNetRudpPacketType::Accept, + connection_id: 124, + sequence: 90, + ack: 0, + ack_mask: 0, + channel_id: "control".to_string(), + reliable: false, + ordered: false, + sequenced: false, + fragment_id: 0, + fragment_index: 0, + fragment_count: 0, + payload: Vec::new(), + }, + 0, + )?; + receiver.receive( + &CultNetRudpPacket { + packet_type: CultNetRudpPacketType::Accept, + connection_id: 124, + sequence: 91, + ack: 0, + ack_mask: 0, + channel_id: "control".to_string(), + reliable: false, + ordered: false, + sequenced: false, + fragment_id: 0, + fragment_index: 0, + fragment_count: 0, + payload: Vec::new(), + }, + 0, + )?; + + let options = CultNetRudpSendOptions { + reliable: true, + ordered: true, + ..CultNetRudpSendOptions::default() + }; + let first = sender.send("schema", b"first".to_vec(), options.clone())?; + let control = sender.create_ack(); + let second = sender.send("schema", b"second".to_vec(), options)?; + assert_eq!(control.sequence, 0); + assert_eq!(second.sequence, first.sequence + 1); + + assert_eq!( + receiver + .receive(&first, 0)? + .delivered + .iter() + .map(|frame| String::from_utf8(frame.payload.clone()).unwrap()) + .collect::>(), + vec!["first"] + ); + assert!(receiver.receive(&control, 0)?.delivered.is_empty()); + assert_eq!( + receiver + .receive(&second, 0)? + .delivered + .iter() + .map(|frame| String::from_utf8(frame.payload.clone()).unwrap()) + .collect::>(), + vec!["second"] + ); + Ok(()) +} + #[test] fn rudp_session_fragments_and_reassembles_reliable_ordered_payloads() -> Result<()> { let mut sender = CultNetRudpSession::new(CultNetRudpSessionOptions { @@ -903,7 +1127,7 @@ fn rudp_socket_transport_handshakes_and_carries_reliable_ordered_schema_frames() max_payload_bytes: None, max_fragment_bytes: None, max_pending_reliable_packets: None, - media_reliable_expire_after_ms: Some(75), + reconnect_policy: None, })?; let mut client = CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { @@ -918,7 +1142,7 @@ fn rudp_socket_transport_handshakes_and_carries_reliable_ordered_schema_frames() max_payload_bytes: None, max_fragment_bytes: None, max_pending_reliable_packets: None, - media_reliable_expire_after_ms: Some(75), + reconnect_policy: None, })?; client.connect(b"join".to_vec())?; @@ -935,65 +1159,45 @@ fn rudp_socket_transport_handshakes_and_carries_reliable_ordered_schema_frames() let client_frame = receive_rudp_frame(&mut client)?; assert_eq!(client_frame.channel_id, "schema"); assert_eq!(client_frame.payload, b"server-state"); + + client.send_schema_message(&CultNetMessage::Hello { + runtime_id: "rust-rudp-client".to_string(), + runtime_kind: "rust-worker".to_string(), + agent_id: None, + role: Some("schema".to_string()), + display_name: None, + supported_document_types: None, + supported_mutation_contracts: None, + supported_message_versions: None, + transport_profiles: Some(vec![client.profile.clone()]), + supports_schema_catalog: Some(true), + })?; + let message = receive_rudp_schema_message(&mut server)?; + let CultNetMessage::Hello { + runtime_id, + transport_profiles, + supports_schema_catalog, + .. + } = message + else { + anyhow::bail!("RUDP schema message did not decode as hello"); + }; + assert_eq!(runtime_id, "rust-rudp-client"); + assert_eq!(supports_schema_catalog, Some(true)); + assert_eq!( + transport_profiles.expect("hello advertises transport")[0].transports[0].protocol, + CultNetTransportProtocol::Rudp + ); assert_eq!( server.profile.transports[0].protocol, CultNetTransportProtocol::Rudp ); - assert_eq!(client.stats().frames_sent, 1); - assert_eq!(server.stats().frames_received, 1); + assert_eq!(client.stats().frames_sent, 2); + assert_eq!(server.stats().frames_received, 2); Ok(()) } -#[test] -fn rudp_socket_transport_reports_expired_reliable_media_packets() -> Result<()> { - let server_socket = bind_udp_socket()?; - let client_socket = bind_udp_socket()?; - let server_addr = server_socket.local_addr()?; - let connection_id = 0x1020_3042; - let mut server = - CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { - runtime_id: "rust-rudp-media-expiry-server".to_string(), - socket: server_socket, - mode: CultNetRudpSocketMode::Server, - remote_addr: None, - connection_id, - initial_sequence: 100, - resend_delay_ms: 5, - transport_id: None, - max_payload_bytes: None, - max_fragment_bytes: None, - max_pending_reliable_packets: None, - media_reliable_expire_after_ms: Some(25), - })?; - let mut client = - CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { - runtime_id: "rust-rudp-media-expiry-client".to_string(), - socket: client_socket, - mode: CultNetRudpSocketMode::Client, - remote_addr: Some(server_addr), - connection_id, - initial_sequence: 1, - resend_delay_ms: 5, - transport_id: None, - max_payload_bytes: None, - max_fragment_bytes: None, - max_pending_reliable_packets: None, - media_reliable_expire_after_ms: Some(25), - })?; - - client.connect(b"join".to_vec())?; - pump_rudp_handshake(&mut client, &mut server)?; - client.send("media", b"late-frame".to_vec())?; - assert_eq!(client.stats().reliable_packets_expired, 0); - - thread::sleep(StdDuration::from_millis(40)); - client.poll_resends()?; - - assert_eq!(client.stats().reliable_packets_expired, 1); - Ok(()) -} - #[test] fn rudp_socket_transport_carries_fragmented_reliable_ordered_schema_frames() -> Result<()> { let server_socket = bind_udp_socket()?; @@ -1013,7 +1217,7 @@ fn rudp_socket_transport_carries_fragmented_reliable_ordered_schema_frames() -> max_payload_bytes: None, max_fragment_bytes: Some(8), max_pending_reliable_packets: None, - media_reliable_expire_after_ms: Some(75), + reconnect_policy: None, })?; let mut client = CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { @@ -1028,7 +1232,7 @@ fn rudp_socket_transport_carries_fragmented_reliable_ordered_schema_frames() -> max_payload_bytes: None, max_fragment_bytes: Some(8), max_pending_reliable_packets: None, - media_reliable_expire_after_ms: Some(75), + reconnect_policy: None, })?; client.connect(b"join".to_vec())?; @@ -1044,6 +1248,292 @@ fn rudp_socket_transport_carries_fragmented_reliable_ordered_schema_frames() -> Ok(()) } +#[test] +fn cultmesh_facade_creates_rudp_client_from_peer_endpoint() -> Result<()> { + let connection_id = 0x2030_4050; + let options = CultMeshRudpSocketOptions { + resend_delay_ms: 25, + max_fragment_bytes: Some(8), + max_pending_reliable_packets: Some(16), + ..CultMeshRudpSocketOptions::default() + }; + let mut server = + CultMesh::create_rudp_server("rust-cultmesh-server", connection_id, options.clone())?; + let server_port = server.profile.transports[0] + .port + .expect("RUDP server profile advertises its local port"); + let endpoint = CultMesh::parse_rudp_endpoint(&format!("rudp://127.0.0.1:{server_port}"))?; + assert_eq!(endpoint.host, "127.0.0.1"); + assert_eq!(endpoint.port, server_port); + assert_eq!( + CultMesh::parse_rudp_endpoint("RuDp://localhost:4100")?.host, + "localhost" + ); + assert_eq!( + CultMesh::parse_rudp_endpoint("rudp://[::1]:4100")?.uri(), + "rudp://[::1]:4100" + ); + + let peer = CultMeshPeerCard::new("rust-cultmesh-server", "local", [endpoint.uri()]) + .with_roles(["schema"]) + .with_authority_lease_id("lease:rust-cultmesh-server"); + let mut peers = CultMesh::create_peer_catalog(); + peers.upsert(peer.clone())?; + assert_eq!(peers.find("local", Some("schema")), vec![peer.clone()]); + let now = Utc::now(); + let mut leases = CultMesh::create_authority_lease_catalog(); + assert!( + CultMesh::create_rudp_client_for_authorized_peer( + "rust-cultmesh-client", + connection_id, + &peers, + &leases, + "local", + "schema", + None, + now, + options.clone(), + ) + .is_err() + ); + leases.upsert(CultMeshAuthorityLease { + lease_id: "lease:rust-cultmesh-server".to_string(), + verse_id: "local".to_string(), + peer_id: "rust-cultmesh-server".to_string(), + roles: vec!["schema".to_string()], + shard_ids: Vec::new(), + issuer_runtime_id: Some("odin".to_string()), + valid_from: now - Duration::minutes(1), + expires_at: now + Duration::minutes(1), + })?; + + let mut client = CultMesh::create_rudp_client_for_authorized_peer( + "rust-cultmesh-client", + connection_id, + &peers, + &leases, + "local", + "schema", + None, + now, + options, + )?; + client.connect(b"join".to_vec())?; + pump_rudp_handshake(&mut client, &mut server)?; + + client.send("schema", b"client-state".to_vec())?; + let server_frame = receive_rudp_frame(&mut server)?; + assert_eq!(server_frame.channel_id, "schema"); + assert_eq!(server_frame.payload, b"client-state"); + Ok(()) +} + +#[test] +fn cultmesh_facade_connects_authorized_rudp_client_for_schema_messages() -> Result<()> { + let connection_id = 0x2030_4051; + let options = CultMeshRudpSocketOptions { + resend_delay_ms: 25, + max_fragment_bytes: Some(1024), + max_pending_reliable_packets: Some(16), + ..CultMeshRudpSocketOptions::default() + }; + let server = Arc::new(Mutex::new(CultMesh::create_rudp_server( + "rust-cultmesh-connected-server", + connection_id, + options.clone(), + )?)); + let server_port = server + .lock() + .expect("RUDP server mutex poisoned") + .profile + .transports[0] + .port + .expect("RUDP server profile advertises its local port"); + let endpoint = CultMesh::parse_rudp_endpoint(&format!("rudp://127.0.0.1:{server_port}"))?; + let peer = CultMeshPeerCard::new("rust-cultmesh-connected-server", "local", [endpoint.uri()]) + .with_roles(["schema"]) + .with_authority_lease_id("lease:rust-cultmesh-connected-server"); + let mut peers = CultMesh::create_peer_catalog(); + peers.upsert(peer)?; + let now = Utc::now(); + let mut leases = CultMesh::create_authority_lease_catalog(); + leases.upsert(CultMeshAuthorityLease { + lease_id: "lease:rust-cultmesh-connected-server".to_string(), + verse_id: "local".to_string(), + peer_id: "rust-cultmesh-connected-server".to_string(), + roles: vec!["schema".to_string()], + shard_ids: Vec::new(), + issuer_runtime_id: Some("odin".to_string()), + valid_from: now - Duration::minutes(1), + expires_at: now + Duration::minutes(1), + })?; + + let done = Arc::new(AtomicBool::new(false)); + let pump = pump_rudp_server_until_connected(server.clone(), done.clone()); + let mut client = CultMesh::connect_rudp_client_for_authorized_peer( + "rust-cultmesh-connected-client", + connection_id, + &peers, + &leases, + "local", + "schema", + None, + now, + CultMeshRudpClientOptions { + socket_options: options, + connect_payload: b"join".to_vec(), + connect_timeout: StdDuration::from_secs(1), + poll_interval: StdDuration::from_millis(5), + }, + )?; + done.store(true, Ordering::SeqCst); + pump.join() + .map_err(|_| anyhow::anyhow!("RUDP server pump panicked"))??; + + assert!(client.connected()); + assert!( + server + .lock() + .expect("RUDP server mutex poisoned") + .connected() + ); + client.send_schema_message(&CultNetMessage::SchemaCatalogRequest { + message_id: "rust-cultmesh-rudp-schema-catalog".to_string(), + include_schema_json: Some(true), + schema_ids: None, + kinds: Some(vec![CultNetSchemaKind::DocumentPayload]), + })?; + let request = { + let mut server = server.lock().expect("RUDP server mutex poisoned"); + receive_rudp_schema_message(&mut server)? + }; + let CultNetMessage::SchemaCatalogRequest { + message_id, kinds, .. + } = request + else { + anyhow::bail!("RUDP schema message did not decode as schema catalog request"); + }; + assert_eq!(message_id, "rust-cultmesh-rudp-schema-catalog"); + assert_eq!(kinds, Some(vec![CultNetSchemaKind::DocumentPayload])); + assert_eq!( + client.profile.transports[0].protocol, + CultNetTransportProtocol::Rudp + ); + Ok(()) +} + +#[test] +fn cultmesh_facade_exposes_schema_registry_and_shard_catalog_owners() -> Result<()> { + let mut schemas = CultMesh::create_schema_registry(); + schemas.register(CultNetSchemaRegistration { + schema_id: "rust.cultmesh.note.v1".to_string(), + kind: CultNetSchemaKind::DocumentPayload, + wire_contracts: vec![CultNetWireContract::CultNetSchemaV0], + schema_version: Some("rust.cultmesh.note.v1".to_string()), + document_type: Some("rust.cultmesh.note".to_string()), + title: Some("Rust CultMesh Note".to_string()), + schema_json: Some( + r#"{"$id":"rust.cultmesh.note.v1","type":"object","properties":{"body":{"type":"string"}}}"# + .to_string(), + ), + })?; + assert_eq!( + schemas + .get("rust.cultmesh.note.v1", false) + .expect("registered schema is discoverable") + .document_type + .as_deref(), + Some("rust.cultmesh.note") + ); + + let builtins = CultMesh::create_builtin_schema_registry()?; + let shared_contracts = builtins.list(&cultnet_rs::CultNetSchemaCatalogOptions { + include_schema_json: false, + schema_ids: None, + kinds: Some(vec![CultNetSchemaKind::SharedContract]), + }); + assert!(shared_contracts.iter().any(|schema| { + schema.schema_id + == "https://github.com/GameCult/cultnet-ts/contracts/cultnet.transport-profile.schema.json" + && schema.schema_version.as_deref() == Some("cultnet.transport_profile.v0") + })); + + let mut shards = CultMesh::create_shard_catalog(); + shards.upsert(CultNetShardDescriptor { + shard_id: "rust-notes-a".to_string(), + owner_runtime_id: "rust-cultmesh".to_string(), + epoch: 7, + is_primary: Some(true), + schema_ids: vec!["rust.cultmesh.note.v1".to_string()], + key_prefix: Some("note:".to_string()), + primary_endpoints: vec!["rudp://127.0.0.1:4100".to_string()], + replica_endpoints: Vec::new(), + read_replica_endpoints: Vec::new(), + region: None, + authority_lease_id: Some("lease:rust-notes-a".to_string()), + })?; + let matching = shards.list(&cultnet_rs::CultNetShardCatalogOptions { + schema_ids: Some(vec!["rust.cultmesh.note.v1".to_string()]), + record_keys: Some(vec!["note:1".to_string()]), + }); + assert_eq!(matching.len(), 1); + assert_eq!(matching[0].shard_id, "rust-notes-a"); + assert!(shards.get("rust-notes-a").is_some()); + Ok(()) +} + +#[test] +fn cultmesh_authority_leases_gate_peer_contact_hints() -> Result<()> { + let now = Utc::now(); + let peer = CultMeshPeerCard::new("rust-peer", "public", ["rudp://127.0.0.1:4100"]) + .with_roles(["shard-primary"]) + .with_authority_lease_id("lease:rust-peer"); + let mut leases = CultMesh::create_authority_lease_catalog(); + let mut peers = CultMesh::create_peer_catalog(); + peers.upsert(peer.clone())?; + + assert!(!leases.is_authorized(&peer, "shard-primary", Some("players"), now)); + assert!( + peers + .find_authorized("public", "shard-primary", &leases, Some("players"), now) + .is_empty() + ); + leases.upsert(CultMeshAuthorityLease { + lease_id: "lease:rust-peer".to_string(), + verse_id: "public".to_string(), + peer_id: "rust-peer".to_string(), + roles: vec!["shard-primary".to_string()], + shard_ids: vec!["players".to_string()], + issuer_runtime_id: Some("odin".to_string()), + valid_from: now - Duration::minutes(1), + expires_at: now + Duration::minutes(1), + })?; + + assert!(leases.is_authorized(&peer, "shard-primary", Some("players"), now)); + assert_eq!( + peers.find_authorized("public", "shard-primary", &leases, Some("players"), now), + vec![peer.clone()] + ); + assert_eq!( + peers.first_authorized("public", "shard-primary", &leases, Some("players"), now), + Some(peer.clone()) + ); + assert!(!leases.is_authorized(&peer, "schema", Some("players"), now)); + assert!( + peers + .first_authorized("public", "schema", &leases, Some("players"), now) + .is_none() + ); + assert!(!leases.is_authorized(&peer, "shard-primary", Some("inventory"), now)); + assert!(!leases.is_authorized( + &peer, + "shard-primary", + Some("players"), + now + Duration::minutes(1) + )); + Ok(()) +} + #[test] fn legacy_gamecult_networking_contract_round_trips_login_union() -> Result<()> { let message = CultNetMessage::Login { @@ -1167,7 +1657,13 @@ fn document_registry_replicates_typed_cultcache_state() -> Result<()> { target.pull_all_backing_stores()?; let applied = registry.apply_snapshot_response::(&mut target, &snapshot)?; + let synced = registry.sync_document_from_snapshot_response::( + &mut target, + &snapshot, + "epiphany.persona", + )?; assert_eq!(applied, vec![payload.clone()]); + assert_eq!(synced, payload); assert_eq!( target.get_required::("epiphany.persona")?, payload @@ -1233,6 +1729,213 @@ fn raw_snapshot_replication_preserves_messagepack_payload_bytes() -> Result<()> Ok(()) } +#[test] +fn raw_snapshot_replication_hydrates_same_schema_rust_aliases() -> Result<()> { + let temp = tempfile::tempdir()?; + let origin_store = temp.path().join("origin-alias.msgpack"); + let target_store = temp.path().join("target-alias.msgpack"); + let canonical = GhostlightAgentStateFixture { + schema_version: "ghostlight.agent_state.v0".to_string(), + agent_id: "epiphany.persona".to_string(), + display_name: "Persona".to_string(), + }; + + let mut origin_registry = CultNetDocumentRegistry::new(); + origin_registry.register(CultNetDocumentBinding::for_entry_with_schema_id::< + GhostlightAgentStateFixture, + >( + "ghostlight.agent_state.v0".to_string(), + "ghostlight.agent_state.v0".to_string(), + )); + let mut origin = CultCache::new(); + origin.register_entry_type::()?; + origin.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&origin_store)); + origin.pull_all_backing_stores()?; + origin.put("epiphany.persona", &canonical)?; + let raw_snapshot = origin_registry.create_raw_snapshot_response( + &origin, + "raw-snapshot-alias", + Some(&["ghostlight.agent_state.v0".to_string()]), + Some(&["epiphany.persona".to_string()]), + )?; + + let mut alias_registry = CultNetDocumentRegistry::new(); + alias_registry.register(CultNetDocumentBinding::for_entry_with_schema_id::< + GhostlightAgentStateUiFixture, + >( + "ghostlight.agent_state.v0".to_string(), + "ghostlight.agent_state.v0".to_string(), + )); + let mut target = CultCache::new(); + target.register_entry_type::()?; + target.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&target_store)); + target.pull_all_backing_stores()?; + + let applied = alias_registry + .sync_raw_document_from_snapshot_response::( + &mut target, + &raw_snapshot, + "epiphany.persona", + )?; + + assert_eq!( + applied, + GhostlightAgentStateUiFixture { + schema_version: "ghostlight.agent_state.v0".to_string(), + agent_id: "epiphany.persona".to_string(), + display_name: "Persona".to_string(), + } + ); + assert_eq!( + target.get_required::("epiphany.persona")?, + applied + ); + Ok(()) +} + +#[test] +fn reactive_document_coalesces_direct_same_schema_alias_member_writes() -> Result<()> { + let temp = tempfile::tempdir()?; + let target_store = temp.path().join("target-reactive-alias.msgpack"); + let mut registry = CultNetDocumentRegistry::new(); + registry.register(CultNetDocumentBinding::for_entry_with_schema_id::< + GhostlightReactiveNoteUiFixture, + >( + "ghostlight.reactive_note.v0".to_string(), + "ghostlight.reactive_note.v0".to_string(), + )); + let cache = Arc::new(Mutex::new(CultCache::new())); + { + let mut cache = cache.lock().expect("cache mutex"); + cache.register_entry_type::()?; + cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&target_store)); + cache.pull_all_backing_stores()?; + cache.put( + "note:reactive", + &GhostlightReactiveNoteUiFixture { + body: "initial".to_string(), + revision: 1, + }, + )?; + } + + let reactive = registry.reactive_document::( + Arc::clone(&cache), + "note:reactive", + CultNetReactiveDocumentOptions { + flush_delay: StdDuration::from_millis(5), + ..CultNetReactiveDocumentOptions::default() + }, + )?; + { + let current = reactive.current(); + let mut current = current.lock().expect("reactive current mutex"); + current.body = "first-local-edit".to_string(); + current.body = "second-local-edit".to_string(); + current.revision = 2; + } + + for _ in 0..30 { + let body = cache + .lock() + .expect("cache mutex") + .get_required::("note:reactive")? + .body; + if body == "second-local-edit" { + break; + } + thread::sleep(StdDuration::from_millis(5)); + } + + let stored = cache + .lock() + .expect("cache mutex") + .get_required::("note:reactive")?; + assert_eq!(stored.body, "second-local-edit"); + assert_eq!(stored.revision, 2); + assert!(!reactive.is_dirty()); + assert!(reactive.last_error().is_none()); + Ok(()) +} + +#[test] +fn reactive_document_tracks_canonical_reconciliation_delta() -> Result<()> { + let temp = tempfile::tempdir()?; + let target_store = temp.path().join("target-reactive-reconcile.msgpack"); + let mut registry = CultNetDocumentRegistry::new(); + registry.register(CultNetDocumentBinding::for_entry_with_schema_id::< + GhostlightReactiveNoteFixture, + >( + "ghostlight.reactive_note.v0".to_string(), + "ghostlight.reactive_note.v0".to_string(), + )); + let cache = Arc::new(Mutex::new(CultCache::new())); + { + let mut cache = cache.lock().expect("cache mutex"); + cache.register_entry_type::()?; + cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&target_store)); + cache.pull_all_backing_stores()?; + cache.put( + "note:reconcile", + &GhostlightReactiveNoteFixture { + body: "initial".to_string(), + revision: 1, + }, + )?; + } + + let reactive = registry.reactive_document::( + Arc::clone(&cache), + "note:reconcile", + CultNetReactiveDocumentOptions { + flush_delay: StdDuration::from_secs(60), + detect_local_changes: false, + ..CultNetReactiveDocumentOptions::default() + }, + )?; + reactive.update(|note| { + note.body = "local-prediction".to_string(); + note.revision = 2; + })?; + let authoritative = registry.create_document_put_message( + "put-authoritative", + "note:reconcile", + &GhostlightReactiveNoteFixture { + body: "authoritative".to_string(), + revision: 7, + }, + CultNetDocumentPutOptions::default(), + )?; + + reactive.apply_document_put_message(&authoritative)?; + + let current = reactive.current(); + let current = current.lock().expect("reactive current mutex").clone(); + assert_eq!(current.body, "local-prediction"); + let reconciliation = reactive + .reconciliation() + .expect("dirty canonical apply records reconciliation"); + assert_eq!(reconciliation.canonical.body, "authoritative"); + assert_eq!(reconciliation.predicted.body, "local-prediction"); + assert_eq!( + reconciliation.delta.get("0"), + Some(&serde_json::json!("local-prediction")) + ); + assert_eq!( + reconciliation.delta.get("1"), + Some(&serde_json::json!(-5.0)) + ); + + reactive.flush()?; + let stored = cache + .lock() + .expect("cache mutex") + .get_required::("note:reconcile")?; + assert_eq!(stored.body, "local-prediction"); + assert!(reactive.reconciliation().is_none()); + Ok(()) +} + #[test] fn client_security_keeps_the_connection_key_visible_without_exposing_cipher_logic() -> Result<()> { let options = CultNetClientSecurityOptions::development(); @@ -1286,6 +1989,86 @@ fn builtin_schema_registry_advertises_canonical_ghostlight_schema_without_inline Ok(()) } +#[test] +fn builtin_schema_registry_advertises_shard_catalog_wire_messages() -> Result<()> { + let registry = builtin_schema_registry()?; + let response = registry.create_catalog_response(&CultNetMessage::SchemaCatalogRequest { + message_id: "catalog-shards".to_string(), + include_schema_json: None, + schema_ids: None, + kinds: Some(vec![CultNetSchemaKind::WireMessage]), + })?; + + let CultNetMessage::SchemaCatalogResponse { schemas, .. } = response else { + panic!("expected catalog response"); + }; + + assert!(schemas.iter().any(|schema| { + schema.schema_version.as_deref() == Some("cultnet.shard_catalog_request.v0") + })); + assert!(schemas.iter().any(|schema| { + schema.schema_version.as_deref() == Some("cultnet.shard_catalog_response.v0") + })); + Ok(()) +} + +#[test] +fn shard_catalog_filters_descriptors_and_applies_remote_responses() -> Result<()> { + let mut catalog = CultNetShardCatalog::new(); + catalog.upsert(CultNetShardDescriptor { + shard_id: "notes-a".to_string(), + owner_runtime_id: "rust-primary".to_string(), + epoch: 3, + is_primary: Some(true), + schema_ids: vec!["note.v0".to_string()], + key_prefix: Some("note:".to_string()), + primary_endpoints: vec!["rudp://127.0.0.1:4100".to_string()], + replica_endpoints: vec![], + read_replica_endpoints: vec![], + region: Some("local".to_string()), + authority_lease_id: Some("lease:notes-a".to_string()), + })?; + catalog.upsert(CultNetShardDescriptor { + shard_id: "players-a".to_string(), + owner_runtime_id: "rust-primary".to_string(), + epoch: 1, + is_primary: Some(false), + schema_ids: vec!["player.v0".to_string()], + key_prefix: Some("player:".to_string()), + primary_endpoints: vec!["cultnet://127.0.0.1:3075".to_string()], + replica_endpoints: vec![], + read_replica_endpoints: vec![], + region: None, + authority_lease_id: None, + })?; + + let response = catalog.create_catalog_response(&CultNetMessage::ShardCatalogRequest { + message_id: "shards".to_string(), + schema_ids: Some(vec!["note.v0".to_string()]), + record_keys: Some(vec!["note:1".to_string()]), + })?; + + let CultNetMessage::ShardCatalogResponse { message_id, shards } = &response else { + panic!("expected shard catalog response"); + }; + assert_eq!(message_id, "shards"); + assert_eq!(shards.len(), 1); + assert_eq!(shards[0].shard_id, "notes-a"); + + let bytes = encode_cultnet_message_to_vec(&response, CultNetWireContract::CultNetSchemaV0)?; + let decoded = decode_cultnet_message_from_slice(&bytes, CultNetWireContract::CultNetSchemaV0)?; + assert_eq!(decoded, response); + + let mut applied = CultNetShardCatalog::new(); + let applied_shards = applied.apply_response(&decoded)?; + assert_eq!(applied_shards.len(), 1); + assert!(applied.get("notes-a").is_some_and(|shard| { + shard.serves(Some("note.v0"), Some("note:2")) + && !shard.serves(Some("note.v0"), Some("player:2")) + })); + Ok(()) +} + #[test] fn schema_discovery_round_trips_over_legacy_gamecult_contract_when_inline_schemas_are_requested() -> Result<()> {