1pub mod connect;
34pub mod inputs;
35pub mod pump;
36pub mod routes;
37
38use std::collections::HashMap;
39use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
40use std::sync::{Arc, Mutex, MutexGuard};
41use std::time::{Duration, Instant};
42
43use astrs_time::{HlcClock, HlcTimestamp};
44use astrs_wire::common::stream::LogFrame;
45use astrs_wire::{
46 DataId, DataflowId, ExtensionKey, FrameLimits, LogRecord, NodeId, NodeRequest, NodeSpawnSpec,
47 SessionId, SubscriptionId,
48};
49use tokio::sync::{mpsc, oneshot};
50
51use crate::error::{NodeError, Result};
52use crate::events::EventSource;
53use crate::runtime::NodeRuntime;
54
55pub use connect::{LinkDuplex, LinkReader, LinkWriter, NodeLink};
56pub use inputs::{InputPlaneStats, InputRouteTable, MAX_CONSECUTIVE_LAGS, RECV_SLICE};
57pub use routes::{RoutePlane, RouteSlot, RouteTable, RouteUpdate};
58
59pub const OUTGOING_CAPACITY: usize = 256;
64
65pub const DEFAULT_REPLY_TIMEOUT: Duration = Duration::from_secs(5);
67
68pub type ExtReply = oneshot::Sender<Option<Vec<u8>>>;
70
71type ExtWaiters = HashMap<String, Vec<ExtReply>>;
73
74#[derive(Debug)]
76pub enum Outgoing {
77 Request(Box<NodeRequest>),
79 Log(Box<LogFrame>),
81 Shutdown,
88}
89
90impl Outgoing {
91 #[must_use]
93 pub fn request(request: NodeRequest) -> Self {
94 Self::Request(Box::new(request))
95 }
96
97 #[must_use]
99 pub fn log(subscription: SubscriptionId, record: LogRecord) -> Self {
100 Self::Log(Box::new(LogFrame::new(subscription, record)))
101 }
102}
103
104#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
106#[non_exhaustive]
107pub struct SessionStats {
108 pub requests_sent: u64,
110 pub events_received: u64,
112 pub sends_inline: u64,
114 pub sends_zero_copy: u64,
116 pub shm_fallbacks: u64,
119 pub logs_sent: u64,
121}
122
123pub struct SessionShared {
125 pub dataflow: DataflowId,
127 pub node: NodeId,
129 pub generation: u64,
131 pub session: SessionId,
133 pub spec: Arc<NodeSpawnSpec>,
135 outgoing: mpsc::Sender<Outgoing>,
137 pub source: Arc<EventSource>,
139 hlc: Mutex<HlcClock>,
141 closed: AtomicBool,
143 ext_waiters: Mutex<ExtWaiters>,
145 pub routes: RouteTable,
147 pub inputs: InputRouteTable,
150 pub zero_copy_threshold: u64,
152 pub shm_broker: Option<std::path::PathBuf>,
159 pub limits: FrameLimits,
161 pub runtime: NodeRuntime,
163 pub log_subscription: SubscriptionId,
165 log_seq: AtomicU64,
167 requests_sent: AtomicU64,
169 events_received: AtomicU64,
170 sends_inline: AtomicU64,
171 sends_zero_copy: AtomicU64,
172 shm_fallbacks: AtomicU64,
173 logs_sent: AtomicU64,
174}
175
176impl core::fmt::Debug for SessionShared {
177 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
178 f.debug_struct("SessionShared")
179 .field("dataflow", &self.dataflow)
180 .field("node", &self.node)
181 .field("generation", &self.generation)
182 .field("session", &self.session)
183 .field("closed", &self.is_closed())
184 .field("stats", &self.stats())
185 .finish_non_exhaustive()
186 }
187}
188
189impl SessionShared {
190 #[must_use]
192 pub fn new(
193 spec: Arc<NodeSpawnSpec>,
194 session: SessionId,
195 outgoing: mpsc::Sender<Outgoing>,
196 source: Arc<EventSource>,
197 runtime: NodeRuntime,
198 zero_copy_threshold: u64,
199 limits: FrameLimits,
200 ) -> Self {
201 Self {
202 dataflow: spec.dataflow,
203 node: spec.node.clone(),
204 generation: spec.generation,
205 session,
206 spec,
207 outgoing,
208 source,
209 hlc: Mutex::new(HlcClock::system()),
210 closed: AtomicBool::new(false),
211 ext_waiters: Mutex::new(HashMap::new()),
212 routes: RouteTable::new(),
213 inputs: InputRouteTable::new(),
214 zero_copy_threshold,
215 shm_broker: None,
216 limits,
217 runtime,
218 log_subscription: SubscriptionId::new(0),
219 log_seq: AtomicU64::new(0),
220 requests_sent: AtomicU64::new(0),
221 events_received: AtomicU64::new(0),
222 sends_inline: AtomicU64::new(0),
223 sends_zero_copy: AtomicU64::new(0),
224 shm_fallbacks: AtomicU64::new(0),
225 logs_sent: AtomicU64::new(0),
226 }
227 }
228
229 #[must_use]
235 pub fn with_shm_broker(mut self, path: Option<std::path::PathBuf>) -> Self {
236 self.shm_broker = path;
237 self
238 }
239
240 #[must_use]
242 pub fn is_closed(&self) -> bool {
243 self.closed.load(Ordering::Acquire)
244 }
245
246 pub fn request_drain(&self) -> Result<()> {
253 self.try_send(Outgoing::Shutdown)
254 }
255
256 pub fn close(&self) {
258 self.closed.store(true, Ordering::Release);
259 self.source.close();
260 self.inputs.close();
265 let waiters = std::mem::take(&mut *lock(&self.ext_waiters));
268 for (_key, senders) in waiters {
269 for sender in senders {
270 let _ = sender.send(None);
271 }
272 }
273 }
274
275 #[must_use]
277 pub fn hlc_now(&self) -> HlcTimestamp {
278 lock(&self.hlc).now()
279 }
280
281 pub fn observe_remote(&self, remote: HlcTimestamp) -> bool {
289 lock(&self.hlc).update_with(remote).is_ok()
290 }
291
292 #[must_use]
294 pub fn stats(&self) -> SessionStats {
295 SessionStats {
296 requests_sent: self.requests_sent.load(Ordering::Relaxed),
297 events_received: self.events_received.load(Ordering::Relaxed),
298 sends_inline: self.sends_inline.load(Ordering::Relaxed),
299 sends_zero_copy: self.sends_zero_copy.load(Ordering::Relaxed),
300 shm_fallbacks: self.shm_fallbacks.load(Ordering::Relaxed),
301 logs_sent: self.logs_sent.load(Ordering::Relaxed),
302 }
303 }
304
305 pub fn count_inline_send(&self) {
307 self.sends_inline.fetch_add(1, Ordering::Relaxed);
308 }
309
310 pub fn count_zero_copy_send(&self) {
312 self.sends_zero_copy.fetch_add(1, Ordering::Relaxed);
313 }
314
315 pub fn count_shm_fallback(&self) {
318 self.shm_fallbacks.fetch_add(1, Ordering::Relaxed);
319 }
320
321 pub fn count_event(&self) {
323 self.events_received.fetch_add(1, Ordering::Relaxed);
324 }
325
326 pub fn next_log_seq(&self) -> u64 {
328 self.log_seq.fetch_add(1, Ordering::Relaxed)
329 }
330
331 pub fn try_send(&self, message: Outgoing) -> Result<()> {
338 if self.is_closed() {
339 return Err(NodeError::DaemonGone);
340 }
341 let is_log = matches!(message, Outgoing::Log(_));
342 match self.outgoing.try_send(message) {
343 Ok(()) => {
344 self.count_outgoing(is_log);
345 Ok(())
346 }
347 Err(mpsc::error::TrySendError::Full(_)) => Err(NodeError::Backpressure {
348 depth: OUTGOING_CAPACITY,
349 }),
350 Err(mpsc::error::TrySendError::Closed(_)) => Err(NodeError::DaemonGone),
351 }
352 }
353
354 pub async fn send_async(&self, message: Outgoing) -> Result<()> {
360 if self.is_closed() {
361 return Err(NodeError::DaemonGone);
362 }
363 let is_log = matches!(message, Outgoing::Log(_));
364 self.outgoing
365 .send(message)
366 .await
367 .map_err(|_| NodeError::DaemonGone)?;
368 self.count_outgoing(is_log);
369 Ok(())
370 }
371
372 pub fn send_blocking(&self, message: Outgoing) -> Result<()> {
383 if self.is_closed() {
384 return Err(NodeError::DaemonGone);
385 }
386 let is_log = matches!(message, Outgoing::Log(_));
387 let pending = match self.outgoing.try_send(message) {
388 Ok(()) => {
389 self.count_outgoing(is_log);
390 return Ok(());
391 }
392 Err(mpsc::error::TrySendError::Full(message)) => message,
393 Err(mpsc::error::TrySendError::Closed(_)) => return Err(NodeError::DaemonGone),
394 };
395 let sender = self.outgoing.clone();
396 self.runtime
397 .block_on("Node::send", "Node::send_async", async move {
398 sender.send(pending).await
399 })?
400 .map_err(|_| NodeError::DaemonGone)?;
401 self.count_outgoing(is_log);
402 Ok(())
403 }
404
405 pub fn send_request(&self, request: NodeRequest) -> Result<()> {
419 let is_publish = matches!(request, NodeRequest::SendMessage { .. });
420 self.send_blocking(Outgoing::request(request))?;
421 if is_publish {
422 self.source.finish_deadlines(Instant::now());
423 }
424 Ok(())
425 }
426
427 pub async fn send_request_async(&self, request: NodeRequest) -> Result<()> {
437 let is_publish = matches!(request, NodeRequest::SendMessage { .. });
438 self.send_async(Outgoing::request(request)).await?;
439 if is_publish {
440 self.source.finish_deadlines(Instant::now());
441 }
442 Ok(())
443 }
444
445 fn count_outgoing(&self, is_log: bool) {
447 if is_log {
448 self.logs_sent.fetch_add(1, Ordering::Relaxed);
449 } else {
450 self.requests_sent.fetch_add(1, Ordering::Relaxed);
451 }
452 }
453
454 #[must_use]
456 pub fn watch_extension(&self, key: &ExtensionKey) -> oneshot::Receiver<Option<Vec<u8>>> {
457 let (sender, receiver) = oneshot::channel();
458 lock(&self.ext_waiters)
459 .entry(key.to_string())
460 .or_default()
461 .push(sender);
462 receiver
463 }
464
465 pub fn resolve_extension(&self, key: &ExtensionKey, value: Option<Vec<u8>>) -> bool {
470 let mut waiters = lock(&self.ext_waiters);
471 let Some(senders) = waiters.get_mut(&key.to_string()) else {
472 return false;
473 };
474 if senders.is_empty() {
475 return false;
476 }
477 let sender = senders.remove(0);
478 if senders.is_empty() {
479 let _ = waiters.remove(&key.to_string());
480 }
481 drop(waiters);
482 sender.send(value).is_ok()
483 }
484
485 #[must_use]
487 pub fn pending_extensions(&self) -> usize {
488 lock(&self.ext_waiters).values().map(Vec::len).sum()
489 }
490
491 #[must_use]
493 pub fn input_source(&self, input: &DataId) -> Option<astrs_wire::PortRef> {
494 self.spec.input(input).map(|spec| spec.source.clone())
495 }
496
497 #[must_use]
499 pub fn declares_output(&self, output: &DataId) -> bool {
500 self.spec.output(output).is_some()
501 }
502}
503
504fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
509 mutex
510 .lock()
511 .unwrap_or_else(std::sync::PoisonError::into_inner)
512}
513
514#[cfg(test)]
515mod tests {
516 #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
517
518 use super::*;
519 use astrs_wire::{LogLevel, NodeSource};
520
521 fn spec() -> Arc<NodeSpawnSpec> {
522 Arc::new(NodeSpawnSpec::new(
523 DataflowId::from_u128(1),
524 NodeId::new("camera").unwrap(),
525 2,
526 NodeSource::Dynamic,
527 ))
528 }
529
530 fn shared() -> (Arc<SessionShared>, mpsc::Receiver<Outgoing>) {
531 let (sender, receiver) = mpsc::channel(OUTGOING_CAPACITY);
532 let shared = Arc::new(SessionShared::new(
533 spec(),
534 SessionId::from_u128(7),
535 sender,
536 Arc::new(EventSource::new()),
537 NodeRuntime::acquire().unwrap(),
538 4096,
539 FrameLimits::uds(),
540 ));
541 (shared, receiver)
542 }
543
544 #[test]
545 fn requests_queue_and_are_counted() {
546 let (shared, mut receiver) = shared();
547 shared
548 .send_request(NodeRequest::EventStreamDropped)
549 .unwrap();
550 assert_eq!(shared.stats().requests_sent, 1);
551 let queued = receiver.try_recv().unwrap();
552 assert!(matches!(queued, Outgoing::Request(_)));
553 }
554
555 #[test]
556 fn a_full_channel_reports_backpressure_rather_than_growing() {
557 let (shared, _receiver) = shared();
560 let mut sent = 0;
561 loop {
562 match shared.try_send(Outgoing::request(NodeRequest::EventStreamDropped)) {
563 Ok(()) => sent += 1,
564 Err(NodeError::Backpressure { depth }) => {
565 assert_eq!(depth, OUTGOING_CAPACITY);
566 break;
567 }
568 Err(error) => panic!("unexpected {error}"),
569 }
570 assert!(sent <= OUTGOING_CAPACITY + 1, "the channel is unbounded");
571 }
572 assert_eq!(sent, OUTGOING_CAPACITY);
573 }
574
575 #[test]
576 fn a_blocking_send_waits_for_room_rather_than_dropping_the_message() {
577 let (shared, mut receiver) = shared();
578 for _ in 0..OUTGOING_CAPACITY {
579 shared
580 .try_send(Outgoing::request(NodeRequest::EventStreamDropped))
581 .unwrap();
582 }
583 let drainer = std::thread::spawn(move || {
585 std::thread::sleep(Duration::from_millis(20));
586 let mut drained = 0;
587 while receiver.blocking_recv().is_some() {
588 drained += 1;
589 if drained == OUTGOING_CAPACITY + 1 {
590 break;
591 }
592 }
593 drained
594 });
595 shared
596 .send_request(NodeRequest::EventStreamDropped)
597 .unwrap();
598 drop(shared);
599 assert!(drainer.join().unwrap() >= 1);
600 }
601
602 #[test]
603 fn a_closed_session_refuses_further_requests() {
604 let (shared, _receiver) = shared();
605 shared.close();
606 assert!(shared.is_closed());
607 assert!(matches!(
608 shared.send_request(NodeRequest::EventStreamDropped),
609 Err(NodeError::DaemonGone)
610 ));
611 assert!(shared.source.is_closed());
612 }
613
614 #[test]
615 fn extension_waiters_are_matched_by_key() {
616 let (shared, _receiver) = shared();
617 let key = ExtensionKey::user("calibration").unwrap();
618 let receiver = shared.watch_extension(&key);
619 assert_eq!(shared.pending_extensions(), 1);
620
621 assert!(shared.resolve_extension(&key, Some(vec![1, 2, 3])));
622 assert_eq!(shared.pending_extensions(), 0);
623 assert_eq!(receiver.blocking_recv().unwrap(), Some(vec![1, 2, 3]));
624
625 assert!(!shared.resolve_extension(&key, Some(vec![9])));
627 }
628
629 #[test]
630 fn closing_releases_extension_waiters() {
631 let (shared, _receiver) = shared();
632 let key = ExtensionKey::user("calibration").unwrap();
633 let receiver = shared.watch_extension(&key);
634 shared.close();
635 assert_eq!(receiver.blocking_recv().unwrap(), None);
636 assert_eq!(shared.pending_extensions(), 0);
637 }
638
639 #[test]
640 fn the_clock_advances_and_absorbs_remote_readings() {
641 let (shared, _receiver) = shared();
642 let first = shared.hlc_now();
643 let second = shared.hlc_now();
644 assert!(second >= first);
645 assert!(shared.observe_remote(second));
646 }
647
648 #[test]
649 fn log_frames_are_counted_separately() {
650 let (shared, mut receiver) = shared();
651 let record = LogRecord::new(shared.hlc_now(), LogLevel::Info, "hello");
652 shared
653 .try_send(Outgoing::log(shared.log_subscription, record))
654 .unwrap();
655 assert!(matches!(receiver.try_recv().unwrap(), Outgoing::Log(_)));
656 assert_eq!(shared.stats().logs_sent, 1);
657 assert_eq!(shared.stats().requests_sent, 0, "logs are not requests");
658 }
659
660 #[test]
661 fn counters_track_the_two_send_planes() {
662 let (shared, _receiver) = shared();
663 shared.count_inline_send();
664 shared.count_zero_copy_send();
665 shared.count_zero_copy_send();
666 shared.count_shm_fallback();
667 shared.count_event();
668 let stats = shared.stats();
669 assert_eq!(stats.sends_inline, 1);
670 assert_eq!(stats.sends_zero_copy, 2);
671 assert_eq!(stats.shm_fallbacks, 1);
672 assert_eq!(stats.events_received, 1);
673 }
674
675 #[test]
676 fn the_specification_answers_wiring_questions() {
677 let (shared, _receiver) = shared();
678 assert!(!shared.declares_output(&DataId::new("image").unwrap()));
679 assert!(
680 shared
681 .input_source(&DataId::new("frames").unwrap())
682 .is_none()
683 );
684 assert_eq!(shared.generation, 2);
685 assert!(format!("{shared:?}").contains("camera"));
686 }
687
688 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
689 async fn the_async_sender_waits_for_room() {
690 let (shared, mut receiver) = shared();
691 shared
692 .send_async(Outgoing::request(NodeRequest::EventStreamDropped))
693 .await
694 .unwrap();
695 assert!(receiver.recv().await.is_some());
696 }
697}