Harden Muninn and Sleipnir realtime delivery

This commit is contained in:
Meta Vens 2026-07-16 20:29:46 +01:00
commit 73551e6f47
23 changed files with 4646 additions and 751 deletions

View file

@ -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::<Result<QueuedMuninnMediaSendPayload>>();
let (payload_tx, payload_rx) =
mpsc::sync_channel::<Result<QueuedMuninnMediaSendPayload>>(
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<String>,
entries: HashMap<String, MuninnMediaSendPayload>,
entries: HashMap<String, CachedVideoRepair>,
}
#[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<MuninnMediaSendPayload> {
feedback
.missing_video_chunk_keys
.iter()
.filter(|chunk_key| {
chunk_key
.split_once(':')
.and_then(|(frame_id, _)| frame_id.parse::<u64>().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<Result<QueuedMuninnMediaSendPayload>>,
tx: &mpsc::SyncSender<Result<QueuedMuninnMediaSendPayload>>,
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<u64>,
_reliable_expire_after_ms: Option<u64>,
) -> 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<R>(
tx: mpsc::Sender<Result<QueuedMuninnMediaSendPayload>>,
tx: mpsc::SyncSender<Result<QueuedMuninnMediaSendPayload>>,
mut reader: R,
config: VideoAnnexBStreamSendConfig,
) -> thread::JoinHandle<()>
@ -2856,7 +2896,7 @@ where
}
fn audio_rudp_payload_reader<R>(
tx: mpsc::Sender<Result<QueuedMuninnMediaSendPayload>>,
tx: mpsc::SyncSender<Result<QueuedMuninnMediaSendPayload>>,
mut reader: R,
config: AudioPcmStreamSendConfig,
) -> thread::JoinHandle<()>
@ -2871,7 +2911,7 @@ where
}
fn read_video_rudp_payloads<R>(
tx: &mpsc::Sender<Result<QueuedMuninnMediaSendPayload>>,
tx: &mpsc::SyncSender<Result<QueuedMuninnMediaSendPayload>>,
reader: &mut R,
config: VideoAnnexBStreamSendConfig,
) -> Result<()>
@ -2899,7 +2939,7 @@ where
}
fn read_audio_rudp_payloads<R>(
tx: &mpsc::Sender<Result<QueuedMuninnMediaSendPayload>>,
tx: &mpsc::SyncSender<Result<QueuedMuninnMediaSendPayload>>,
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<HidButtonEdge>,
edge_buttons: Vec<String>,
last_edge_send_at: Option<Instant>,
joystick_axes: [i16; 16],
joystick_buttons: [bool; 32],
latest_report: Option<LatestHidReport>,
@ -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<ActiveHidControllerRudpSource>,
desired: Vec<MoveStateSource>,
@ -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::<HidEdgeAck>(&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<MuninnHidControllerStateRecord> {
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<MuninnHidControllerStateRecord> {
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<Option<ActiveHidCon
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,
})?;
Ok(Some(ActiveHidControllerStream {
target,
@ -9591,7 +9705,7 @@ fn muninn_rudp_media_profile_for_bitrate_and_latency(
video_rc_lookahead: 0,
sender_queue_deadline_ms: latency_budget_ms,
sender_resend_delay_ms: MUNINN_RUDP_MEDIA_RESEND_DELAY_MS,
sender_reliable_expire_after_ms: latency_budget_ms,
sender_delivery_deadline_ms: latency_budget_ms,
sender_pace_every_payloads: MUNINN_RUDP_MEDIA_SEND_PACE_EVERY_PAYLOADS,
sender_pace_sleep_us: MUNINN_RUDP_MEDIA_SEND_PACE_SLEEP_US,
receiver_assembly_deadline_ms: latency_budget_ms,
@ -11525,7 +11639,7 @@ mod tests {
options.max_fragment_bytes,
Some(MUNINN_RUDP_MEDIA_MAX_FRAGMENT_BYTES as u32)
);
assert_eq!(options.media_reliable_expire_after_ms, None);
assert_eq!(options.reconnect_policy, None);
let transport = CultNetRudpSocketTransportConnection::new(options).unwrap();
let channels = transport
.profile
@ -11536,17 +11650,18 @@ mod tests {
.iter();
let media_channel = channels
.clone()
.find(|channel| channel.channel_id == "media")
.find(|channel| {
channel.channel_id == crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL
})
.unwrap();
assert_eq!(
media_channel.delivery,
cultnet_rs::CultNetTransportDelivery::Unreliable
);
assert_eq!(media_channel.reliable_expire_after_ms, None);
}
#[test]
fn rudp_audio_transport_uses_separate_reliable_media_connection() {
fn rudp_audio_transport_uses_separate_realtime_connection() {
let socket = UdpSocket::bind("127.0.0.1:0").unwrap();
let endpoint: SocketAddr = "127.0.0.1:5204".parse().unwrap();
let profile = muninn_rudp_media_profile();
@ -11560,10 +11675,7 @@ mod tests {
);
assert_eq!(options.connection_id, MUNINN_AUDIO_RUDP_CONNECTION_ID);
assert_eq!(
options.media_reliable_expire_after_ms,
Some(MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS)
);
assert_eq!(options.reconnect_policy, None);
}
#[test]
@ -11646,6 +11758,41 @@ mod tests {
assert!(pending.is_empty());
}
#[test]
fn rudp_media_pending_queues_are_structurally_bounded() {
let queued_at = Instant::now();
let mut pending = PendingMuninnMediaSendQueues::default();
for index in 0..(MUNINN_RUDP_MEDIA_PENDING_AUDIO_CAPACITY + 32) {
pending.push(QueuedMuninnMediaSendPayload {
payload: MuninnMediaSendPayload {
channel_id: crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL,
payload: vec![(index % 251) as u8],
},
queued_at,
kind: QueuedMuninnMediaKind::Audio,
});
}
for index in 0..(MUNINN_RUDP_MEDIA_PENDING_VIDEO_CAPACITY + 32) {
pending.push(QueuedMuninnMediaSendPayload {
payload: MuninnMediaSendPayload {
channel_id: crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL,
payload: vec![(index % 251) as u8],
},
queued_at,
kind: QueuedMuninnMediaKind::Video,
});
}
assert_eq!(
pending.audio_len(),
MUNINN_RUDP_MEDIA_PENDING_AUDIO_CAPACITY
);
assert_eq!(
pending.video_len(),
MUNINN_RUDP_MEDIA_PENDING_VIDEO_CAPACITY
);
}
#[test]
fn rudp_latency_budget_owns_sender_and_record_deadlines() {
let options = Options::parse(
@ -11669,7 +11816,7 @@ mod tests {
let profile = muninn_rudp_media_profile_for_options(&options);
assert_eq!(profile.sender_queue_deadline_ms, 2000);
assert_eq!(profile.sender_reliable_expire_after_ms, 2000);
assert_eq!(profile.sender_delivery_deadline_ms, 2000);
assert_eq!(
profile.sender_pace_every_payloads,
MUNINN_RUDP_MEDIA_SEND_PACE_EVERY_PAYLOADS
@ -11848,7 +11995,7 @@ mod tests {
highest_decodable_frame_id: Some(41),
missing_frame_ids: Vec::new(),
missing_video_chunk_keys: vec!["42:3".to_string(), "42:4".to_string()],
late_frame_ids: vec![42],
late_frame_ids: Vec::new(),
requested_keyframe: true,
jitter_us: 500,
decode_queue_us: 2_000,
@ -11858,12 +12005,82 @@ mod tests {
.unwrap();
let mut cache = RecentVideoChunkRepairCache::new(16);
cache.remember(&payload).unwrap();
let repairs = cache.repair_payloads_for_feedback(&feedback);
let now = Instant::now();
cache
.remember(&payload, now, Duration::from_millis(100))
.unwrap();
let repairs = cache.repair_payloads_for_feedback(&feedback, now);
assert_eq!(repairs, vec![payload]);
}
#[test]
fn repair_cache_refuses_expired_and_receiver_late_chunks() {
let video = odin_core::MuninnMediaVideoAccessUnitRecord {
stream_id: "muninn.raven.av.rudp".to_string(),
session_id: "raven:session:video".to_string(),
frame_id: 42,
codec: "h264".to_string(),
pts_ticks: 126_000,
duration_ticks: 3_000,
timebase_num: 1,
timebase_den: 90_000,
keyframe: false,
dependency_frame_id: Some(41),
deadline_ticks: 127_800,
chunk_index: 3,
chunk_count: 5,
payload: vec![1, 2, 3, 4],
};
let payload = MuninnMediaSendPayload {
channel_id: crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL,
payload: crate::media_packetizer::encode_media_wire_record(
&crate::media_packetizer::MuninnMediaWireRecord::Video(video),
"unix:1000",
"muninn-test",
"repair-cache-expiry-test",
)
.unwrap(),
};
let feedback = |late_frame_ids| {
crate::media_packetizer::build_receiver_feedback(
crate::media_packetizer::ReceiverFeedbackOptions {
stream_id: "muninn.raven.av.rudp",
session_id: "raven:session:video",
receiver_id: "starfire.obs",
highest_decodable_frame_id: Some(41),
missing_frame_ids: Vec::new(),
missing_video_chunk_keys: vec!["42:3".to_string()],
late_frame_ids,
requested_keyframe: false,
jitter_us: 500,
decode_queue_us: 2_000,
observed_at: "unix:1000",
},
)
.unwrap()
};
let now = Instant::now();
let mut cache = RecentVideoChunkRepairCache::new(16);
cache
.remember(&payload, now, Duration::from_millis(100))
.unwrap();
assert!(
cache
.repair_payloads_for_feedback(&feedback(vec![42]), now)
.is_empty()
);
assert!(
cache
.repair_payloads_for_feedback(
&feedback(Vec::new()),
now + Duration::from_millis(101),
)
.is_empty()
);
}
#[test]
fn idle_surface_advertises_affordances_without_active_streams() {
let options = Options::parse([].into_iter()).unwrap();
@ -12001,7 +12218,7 @@ mod tests {
max_payload_bytes: None,
max_fragment_bytes: Some(1200),
max_pending_reliable_packets: Some(64),
media_reliable_expire_after_ms: None,
reconnect_policy: None,
},
)
.unwrap();
@ -13047,7 +13264,7 @@ Device 00:07:04:A8:00:D0 (public)
);
assert_eq!(
media_profile
.get("sender_reliable_expire_after_ms")
.get("sender_delivery_deadline_ms")
.and_then(|value| value.as_u64()),
Some(MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS)
);
@ -13549,6 +13766,21 @@ Device 00:07:04:A8:00:D0 (public)
assert_eq!(record.buttons, vec!["up", "a", "b", "x", "y"]);
}
#[test]
fn hid_edge_capture_preserves_quick_tap_before_state_collapse() {
let mut active = active_hid_controller_rudp_source(MoveStateSource {
move_id: "pad".to_string(),
hidraw_path: "xinput://0".to_string(),
});
capture_button_edges(&mut active, &["a".to_string()]);
capture_button_edges(&mut active, &[]);
let edges = active.pending_edges.into_iter().collect::<Vec<_>>();
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 {

View file

@ -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<String>,
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<VideoAccessUnit> {
let chunks = self.chunks.values().cloned().collect::<Vec<_>>();
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 {

View file

@ -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<Instant>,
last_stale_log_at: Option<Instant>,
last_subscription: Option<HidControllerRudpSubscription>,
received_edges: Vec<HidButtonEdge>,
last_subscription_at: Option<Instant>,
}
@ -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<HidLatestStateFrame> {
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<HidButtonEdge> {
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<u64, HidButtonEdge>,
retired_epochs: HashSet<u64>,
}
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<HidButtonEdge> {
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::<String, u64>::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<SleipnirInputLatencySnapshot> = None;
let mut output_is_neutral = true;
let mut last_output_frame_at: Option<Instant> = None;
let mut last_output_source_timestamp_ns: Option<i64> = 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<MuninnHidControllerStateRecord> = 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<Ve
frame.payload.len()
);
}
let decoded = decode_latest_state_frame(&frame.payload);
let record = match decoded.as_ref() {
Some(frame) => 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<Ve
},
});
}
Ok(Some(frame)) if frame.channel_id == "hid.edge" => {
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<_>>(), 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);

View file

@ -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.

27
vendor/CULTLIB_SNAPSHOT.md vendored Normal file
View file

@ -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.

View file

@ -53,7 +53,7 @@ struct Settings {
let mut cache = CultCache::new();
cache.register_entry_type::<Settings>()?;
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"],
);
```

View file

@ -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<String, &'static str>,
schema_name_definitions: BTreeMap<String, String>,
entries: BTreeMap<String, CultCacheEnvelope>,
stores: Vec<CultCacheStoreRegistration>,
}
@ -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<String> = 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<String>,
schema_name_definitions: &BTreeMap<String, String>,
persisted_type: &str,
) -> Option<String> {
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::<String, String>::new();
let mut schema_names = BTreeSet::<String>::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<Vec<CultCacheEnvelope>> {
.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<Vec<CultCacheEnvelope>> {
.collect()
}
fn infer_schema_version_from_payload(payload: &[u8]) -> Option<String> {
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<u32> {
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<String> {
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<String> {
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::<Settings>()?;
cache.register_entry_type::<Note>()?;
@ -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::<Settings>()?;
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::<Settings>()?;
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::<Settings>()?;
@ -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::<SchemaStamped>()?;
cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&store_path));
cache.pull_all_backing_stores()?;
assert_eq!(cache.get_required::<SchemaStamped>("record-1")?, expected);
assert_eq!(
cache
.get_required_envelope::<SchemaStamped>("record-1")?
.schema_id,
Some("sha256:stale-schema-id-from-cold-record".to_string())
);
Ok(())
}
}

View file

@ -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)?;

View file

@ -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::<T>()`, 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::<LocalAlias>(...)` hydrates one local
alias type directly:
```rust
let mut target_registry = CultNetDocumentRegistry::new();
target_registry.register(CultNetDocumentBinding::for_entry_with_schema_id::<UiNote>(
"aetheria.note.v1".to_string(),
"aetheria.note.v1".to_string(),
));
let note = target_registry.sync_raw_document_from_snapshot_response::<UiNote>(
&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::<UiNote>(
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.

View file

@ -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 }
}
}
}

View file

@ -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 }
}
}
}
}

View file

@ -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": {

File diff suppressed because it is too large Load diff

View file

@ -104,9 +104,23 @@ pub struct CultNetTransportDescriptor {
pub discovery_group: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub wire_contracts: Option<Vec<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub reconnect_policy: Option<CultNetReconnectPolicy>,
pub channels: Vec<CultNetTransportChannel>,
}
#[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<u32>,
}
#[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<u32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_pending_reliable_packets: Option<u32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub reliable_expire_after_ms: Option<u64>,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
@ -183,6 +195,53 @@ pub struct CultNetSchemaDescriptor {
pub schema_json: Option<String>,
}
#[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<bool>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub schema_ids: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub key_prefix: Option<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub primary_endpoints: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub replica_endpoints: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub read_replica_endpoints: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub region: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub authority_lease_id: Option<String>,
}
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<CultNetSchemaDescriptor>,
},
#[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<Vec<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
record_keys: Option<Vec<String>>,
},
#[serde(rename = "cultnet.shard_catalog_response.v0", rename_all = "camelCase")]
ShardCatalogResponse {
message_id: String,
shards: Vec<CultNetShardDescriptor>,
},
#[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<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
target_runtime_id: Option<String>,
},
#[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<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
source_runtime_id: Option<String>,
},
}
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)?;

525
vendor/cultnet-rs/src/cultmesh.rs vendored Normal file
View file

@ -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<String>,
pub roles: Vec<String>,
pub shard_ids: Vec<String>,
pub authority_lease_id: Option<String>,
}
impl CultMeshPeerCard {
pub fn new(
peer_id: impl Into<String>,
verse_id: impl Into<String>,
endpoints: impl IntoIterator<Item = impl Into<String>>,
) -> 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<Item = impl Into<String>>) -> Self {
self.roles = roles.into_iter().map(Into::into).collect();
self
}
pub fn with_shard_ids(
mut self,
shard_ids: impl IntoIterator<Item = impl Into<String>>,
) -> 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<String>) -> Self {
self.authority_lease_id = Some(authority_lease_id.into());
self
}
pub fn rudp_endpoint(&self) -> Result<CultNetRudpEndpoint> {
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<String, CultMeshPeerCard>,
}
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<CultMeshPeerCard> {
self.peers.values().cloned().collect()
}
pub fn find(&self, verse_id: &str, role: Option<&str>) -> Vec<CultMeshPeerCard> {
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<Utc>,
) -> Vec<CultMeshPeerCard> {
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<Utc>,
) -> Option<CultMeshPeerCard> {
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<String>,
pub shard_ids: Vec<String>,
pub issuer_runtime_id: Option<String>,
pub valid_from: DateTime<Utc>,
pub expires_at: DateTime<Utc>,
}
impl CultMeshAuthorityLease {
pub fn covers(
&self,
peer: &CultMeshPeerCard,
role: &str,
shard_id: Option<&str>,
at: DateTime<Utc>,
) -> 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<String, CultMeshAuthorityLease>,
}
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<CultMeshAuthorityLease> {
self.leases.values().cloned().collect()
}
pub fn is_authorized(
&self,
peer: &CultMeshPeerCard,
role: &str,
shard_id: Option<&str>,
at: DateTime<Utc>,
) -> 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<SocketAddr> {
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<Duration>,
pub initial_sequence: u32,
pub resend_delay_ms: u64,
pub max_payload_bytes: Option<u32>,
pub max_fragment_bytes: Option<u32>,
pub max_pending_reliable_packets: Option<u32>,
}
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<u8>,
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<CultNetSchemaRegistry> {
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<CultNetRudpEndpoint> {
cultnet_rudp_endpoint(endpoint)
}
pub fn create_rudp_server(
runtime_id: impl Into<String>,
connection_id: u32,
options: CultMeshRudpSocketOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
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<String>,
connection_id: u32,
endpoint: &CultNetRudpEndpoint,
options: CultMeshRudpSocketOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
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<String>,
connection_id: u32,
endpoint: &str,
options: CultMeshRudpSocketOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
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<String>,
connection_id: u32,
peer: &CultMeshPeerCard,
options: CultMeshRudpSocketOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
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<String>,
connection_id: u32,
peers: &CultMeshPeerCatalog,
leases: &CultMeshAuthorityLeaseCatalog,
verse_id: &str,
role: &str,
shard_id: Option<&str>,
at: DateTime<Utc>,
options: CultMeshRudpSocketOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
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<String>,
connection_id: u32,
endpoint: &CultNetRudpEndpoint,
options: CultMeshRudpClientOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
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<String>,
connection_id: u32,
endpoint: &str,
options: CultMeshRudpClientOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
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<String>,
connection_id: u32,
peer: &CultMeshPeerCard,
options: CultMeshRudpClientOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
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<String>,
connection_id: u32,
peers: &CultMeshPeerCatalog,
leases: &CultMeshAuthorityLeaseCatalog,
verse_id: &str,
role: &str,
shard_id: Option<&str>,
at: DateTime<Utc>,
options: CultMeshRudpClientOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
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<CultNetRudpEndpoint> {
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::<u16>()
.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<UdpSocket> {
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(())
}

View file

@ -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::*;

View file

@ -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<String>, host: &str, port: u16) -> Result<Self> {
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<CultNetMessage>,
) -> Result<bool> {
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)
}
}

View file

@ -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<String, CultNetDocumentBinding>,
}
#[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<T> {
pub canonical: T,
pub predicted: T,
pub delta: BTreeMap<String, Value>,
pub version: u64,
pub received_at: String,
}
struct CultNetReactiveDocumentState<T> {
dirty: bool,
flushing: bool,
flush_queued: bool,
last_clean_payload: Vec<u8>,
reconciliation: Option<CultNetReactiveDocumentReconciliation<T>>,
reconciliation_version: u64,
last_error: Option<String>,
}
pub struct CultNetReactiveDocument<T>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
registry: CultNetDocumentRegistry,
cache: Arc<Mutex<CultCache>>,
record_key: String,
current: Arc<Mutex<T>>,
state: Arc<Mutex<CultNetReactiveDocumentState<T>>>,
options: CultNetReactiveDocumentOptions,
disposed: Arc<AtomicBool>,
detect_worker: Option<JoinHandle<()>>,
}
impl CultNetDocumentRegistry {
pub fn new() -> Self {
Self::default()
@ -352,6 +409,40 @@ impl CultNetDocumentRegistry {
Ok(applied)
}
pub fn sync_document_from_snapshot_response<T>(
&self,
cache: &mut CultCache,
response: &CultNetMessage,
record_key: &str,
) -> Result<T>
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::<T>(
cache,
&CultNetMessage::DocumentPut {
message_id: "snapshot-sync".to_string(),
document: document.clone(),
},
)
}
pub fn apply_raw_snapshot_response<T>(
&self,
cache: &mut CultCache,
@ -380,6 +471,52 @@ impl CultNetDocumentRegistry {
Ok(applied)
}
pub fn sync_raw_document_from_snapshot_response<T>(
&self,
cache: &mut CultCache,
response: &CultNetMessage,
record_key: &str,
) -> Result<T>
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::<T>(
cache,
&CultNetMessage::DocumentPutRaw {
message_id: "snapshot-sync-raw".to_string(),
document: document.clone(),
},
)
}
pub fn reactive_document<T>(
&self,
cache: Arc<Mutex<CultCache>>,
record_key: impl Into<String>,
options: CultNetReactiveDocumentOptions,
) -> Result<CultNetReactiveDocument<T>>
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<T> CultNetReactiveDocument<T>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
pub fn new(
registry: CultNetDocumentRegistry,
cache: Arc<Mutex<CultCache>>,
record_key: impl Into<String>,
options: CultNetReactiveDocumentOptions,
) -> Result<Self> {
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::<T>(&record_key)?
};
let last_clean_payload = serialize_typed(&current)?;
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::<T>(
Arc::clone(&cache),
Arc::clone(&current),
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<Mutex<T>> {
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<CultNetReactiveDocumentReconciliation<T>> {
self.state
.lock()
.ok()
.and_then(|state| state.reconciliation.clone())
}
pub fn last_error(&self) -> Option<String> {
self.state
.lock()
.ok()
.and_then(|state| state.last_error.clone())
}
pub fn update(&self, update: impl FnOnce(&mut T)) -> Result<T> {
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<T> {
{
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<T> {
let canonical = {
let cache = self
.cache
.lock()
.map_err(|_| anyhow!("CultCache mutex poisoned"))?;
cache.get_required::<T>(&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::<T>(&self.cache, &self.current, &self.state, &self.record_key)
}
pub fn apply_document_put_message(&self, message: &CultNetMessage) -> Result<T> {
let canonical = {
let mut cache = self
.cache
.lock()
.map_err(|_| anyhow!("CultCache mutex poisoned"))?;
self.registry
.apply_document_put_message::<T>(&mut cache, message)?
};
self.apply_canonical_value(canonical)
}
pub fn apply_raw_document_put_message(&self, message: &CultNetMessage) -> Result<T> {
let canonical = {
let mut cache = self
.cache
.lock()
.map_err(|_| anyhow!("CultCache mutex poisoned"))?;
self.registry
.apply_raw_document_put_message::<T>(&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<T> {
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<T> Drop for CultNetReactiveDocument<T>
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<T>(
cache: Arc<Mutex<CultCache>>,
current: Arc<Mutex<T>>,
state: Arc<Mutex<CultNetReactiveDocumentState<T>>>,
disposed: Arc<AtomicBool>,
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>(&current, &state).and_then(|dirty| {
if dirty {
flush_reactive_document::<T>(&cache, &current, &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<T>(
current: &Arc<Mutex<T>>,
state: &Arc<Mutex<CultNetReactiveDocumentState<T>>>,
) -> Result<bool>
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<T>(
cache: &Arc<Mutex<CultCache>>,
current: &Arc<Mutex<T>>,
state: &Arc<Mutex<CultNetReactiveDocumentState<T>>>,
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::<T>(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::<T>(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::<T>(cache, current, state, record_key)?;
}
Ok(())
}
fn serialize_typed<T>(value: &T) -> Result<Vec<u8>>
where
T: Serialize,
{
Ok(rmp_serde::to_vec(value)?)
}
fn create_reconciliation_delta<T>(predicted: &T, canonical: &T) -> Result<BTreeMap<String, Value>>
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<Value> {
let predicted = predicted.as_f64()?;
let canonical = canonical.as_f64()?;
serde_json::Number::from_f64(predicted - canonical).map(Value::Number)
}
fn round_trip_typed<T>(value: &T) -> Result<T>
where
T: Serialize + DeserializeOwned,

View file

@ -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<u64>,
}
#[derive(Clone, Debug, PartialEq, Eq)]
struct PendingReliablePacket {
packet: CultNetRudpPacket,
last_sent_at_ms: u64,
expires_at_ms: Option<u64>,
}
#[derive(Clone, Debug, PartialEq, Eq)]
@ -124,6 +127,7 @@ pub struct CultNetRudpSession {
connection_id: u32,
resend_delay_ms: u64,
max_pending_reliable_packets: Option<usize>,
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<String, u32>,
ordered_buffers: BTreeMap<String, BTreeMap<u32, PendingOrderedFrame>>,
fragment_buffers: BTreeMap<(String, u16), FragmentBuffer>,
highest_delivered_sequenced_by_channel: BTreeMap<String, u32>,
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<u32> {
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<u8>) -> Result<CultNetRudpPacket> {
@ -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<u8>) -> CultNetRudpPacket {
@ -534,7 +495,6 @@ impl CultNetRudpSession {
}
pub fn due_resends(&mut self, now_ms: u64) -> Vec<CultNetRudpPacket> {
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<CultNetRudpDeliveredFrame> {
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<u32>,
pub max_fragment_bytes: Option<u32>,
pub max_pending_reliable_packets: Option<u32>,
pub media_reliable_expire_after_ms: Option<u64>,
pub reconnect_policy: Option<CultNetReconnectPolicy>,
}
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<SocketAddr>,
pub profile: CultNetTransportProfile,
transport_id: Option<String>,
stats: CultNetTransportStats,
delivered_frames: VecDeque<CultNetTransportFrame>,
max_fragment_bytes: Option<usize>,
@ -914,7 +892,6 @@ pub struct CultNetRudpSocketTransportConnection {
impl CultNetRudpSocketTransportConnection {
pub fn new(options: CultNetRudpSocketTransportOptions) -> Result<Self> {
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<u8>) -> 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<Option<CultNetMessage>> {
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<u8>) -> 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<Option<CultNetTransportFrame>> {
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<F>
where
F: FnMut() -> Result<CultNetRudpSocketTransportConnection>,
{
pub reconnect_controller: CultNetReconnectController,
create_transport: F,
connect_payload: Vec<u8>,
transport: Option<CultNetRudpSocketTransportConnection>,
stopped: bool,
}
impl<F> CultNetRudpReconnectLoop<F>
where
F: FnMut() -> Result<CultNetRudpSocketTransportConnection>,
{
pub fn new(
reconnect_policy: CultNetReconnectPolicy,
connect_payload: Vec<u8>,
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<u8>, 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<CultNetReconnectDecision> {
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<bool> {
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<String>,
@ -1206,7 +1192,7 @@ pub struct RudpTransportProfileOptions {
pub max_payload_bytes: Option<u32>,
pub max_fragment_bytes: Option<u32>,
pub max_pending_reliable_packets: Option<u32>,
pub media_reliable_expire_after_ms: Option<u64>,
pub reconnect_policy: Option<CultNetReconnectPolicy>,
}
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<CultNetRudpPacketType> {
_ => 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());
}
}

View file

@ -353,6 +353,20 @@ pub fn builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
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,

134
vendor/cultnet-rs/src/shard_catalog.rs vendored Normal file
View file

@ -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<Vec<String>>,
pub record_keys: Option<Vec<String>>,
}
#[derive(Clone, Debug, Default)]
pub struct CultNetShardCatalog {
shards: BTreeMap<String, CultNetShardDescriptor>,
}
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<CultNetShardDescriptor> {
let schema_ids = options
.schema_ids
.as_ref()
.map(|values| values.iter().cloned().collect::<BTreeSet<_>>());
let record_keys = options
.record_keys
.as_ref()
.map(|values| values.iter().cloned().collect::<BTreeSet<_>>());
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<CultNetMessage> {
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<Vec<CultNetShardDescriptor>> {
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(())
}

View file

@ -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<u8>,
}
#[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<u32>,
}
#[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<u64>,
pub exhausted: bool,
}
#[derive(Clone, Debug)]
pub struct CultNetReconnectController {
pub policy: CultNetReconnectPolicy,
attempt: u32,
next_attempt_at_ms: Option<u64>,
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<u64> {
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<String>,
@ -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,
}],
}],
}

File diff suppressed because it is too large Load diff