pub mod builder;
pub mod extension;
pub mod init;
pub mod logging;
use std::collections::BTreeSet;
use std::sync::Arc;
use std::time::Duration;
use astrs_data::AstrsMessage;
use astrs_time::HlcTimestamp;
use astrs_wire::{
DataId, DataflowId, NodeId, NodeRequest, NodeSpawnSpec, PortRef, SessionId, StopCause,
};
use astrs_scheduler::QueueSnapshot;
use crate::env::TypeCheckMode;
use crate::error::{NodeError, Result};
use crate::events::EventStream;
use crate::events::source::StreamStats;
use crate::orphan::OrphanGuard;
use crate::output::{Output, RawOutput};
use crate::session::pump::SessionTasks;
use crate::session::{SessionShared, SessionStats};
const SHUTDOWN_DRAIN: Duration = Duration::from_secs(5);
pub use builder::NodeBuilder;
pub use init::Registration;
pub struct Node {
shared: Arc<SessionShared>,
tasks: Option<SessionTasks>,
type_check: TypeCheckMode,
orphan: Option<OrphanGuard>,
opened: BTreeSet<DataId>,
}
impl core::fmt::Debug for Node {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.debug_struct("Node")
.field("id", &self.shared.node)
.field("dataflow", &self.shared.dataflow)
.field("generation", &self.shared.generation)
.field("type_check", &self.type_check)
.field("orphan_guard", &self.orphan.is_some())
.finish_non_exhaustive()
}
}
impl Node {
#[must_use]
pub fn from_registration(
registration: Registration,
type_check: TypeCheckMode,
orphan: Option<OrphanGuard>,
) -> (Self, EventStream) {
let Registration {
shared,
events,
tasks,
spec: _,
} = registration;
(
Self {
shared,
tasks: Some(tasks),
type_check,
orphan,
opened: BTreeSet::new(),
},
events,
)
}
pub fn init_from_env() -> Result<(Self, EventStream)> {
NodeBuilder::from_env()?.connect()
}
#[must_use]
pub fn builder() -> NodeBuilder {
NodeBuilder::new()
}
pub fn init_from_node_id(node_id: impl AsRef<str>) -> Result<(Self, EventStream)> {
NodeBuilder::new().node_id(node_id)?.dynamic(true).connect()
}
pub fn init_testing() -> Result<crate::testing::TestHarness> {
crate::testing::TestHarness::start()
}
pub fn output<T: AstrsMessage>(&mut self, output: impl AsRef<str>) -> Result<Output<T>> {
let id = DataId::new(output.as_ref())?;
self.check_declared_type(&id, T::URN)?;
Ok(Output::new(self.claim_output(id)?))
}
pub fn raw_output(&mut self, output: impl AsRef<str>) -> Result<RawOutput> {
let id = DataId::new(output.as_ref())?;
self.claim_output(id)
}
#[must_use]
pub fn input_source(&self, input: impl AsRef<str>) -> Option<PortRef> {
let id = DataId::new(input.as_ref()).ok()?;
self.shared.input_source(&id)
}
pub fn request_events(&self, max_batch: u32, timeout: Option<Duration>) -> Result<()> {
self.shared.send_request(NodeRequest::NextEvent {
timeout: timeout.map(astrs_wire::DurationMs::from_duration),
max_batch: max_batch.max(1),
})
}
pub fn request_next_event(&self) -> Result<()> {
self.request_events(astrs_wire::DEFAULT_EVENT_BATCH, None)
}
pub fn close_outputs(&mut self) -> Result<()> {
self.shared.send_request(NodeRequest::CloseOutputs {
outputs: Vec::new(),
})
}
#[must_use]
pub fn id(&self) -> &NodeId {
&self.shared.node
}
#[must_use]
pub fn dataflow_id(&self) -> DataflowId {
self.shared.dataflow
}
#[must_use]
pub fn session_id(&self) -> SessionId {
self.shared.session
}
#[must_use]
pub fn descriptor(&self) -> &NodeSpawnSpec {
&self.shared.spec
}
#[must_use]
pub fn is_restart(&self) -> bool {
self.shared.generation > 0
}
#[must_use]
pub fn restart_count(&self) -> u64 {
self.shared.generation
}
#[must_use]
pub fn generation(&self) -> u64 {
self.shared.generation
}
#[must_use]
pub fn hlc_now(&self) -> HlcTimestamp {
self.shared.hlc_now()
}
#[must_use]
pub fn metadata(&self) -> astrs_wire::Metadata {
astrs_wire::Metadata::new(self.hlc_now())
}
#[must_use]
pub const fn type_check(&self) -> TypeCheckMode {
self.type_check
}
#[must_use]
pub fn stats(&self) -> SessionStats {
self.shared.stats()
}
#[must_use]
pub fn input_ids(&self) -> Vec<DataId> {
self.shared.source.input_ids()
}
#[must_use]
pub fn queue_snapshot(&self, input: impl AsRef<str>) -> Option<QueueSnapshot> {
let id = DataId::new(input.as_ref()).ok()?;
self.shared.source.queue_snapshot(&id)
}
#[must_use]
pub fn queue_snapshots(&self) -> Vec<(DataId, QueueSnapshot)> {
self.shared
.source
.input_ids()
.into_iter()
.filter_map(|id| {
self.shared
.source
.queue_snapshot(&id)
.map(|snapshot| (id, snapshot))
})
.collect()
}
#[must_use]
pub fn stream_stats(&self) -> StreamStats {
self.shared.source.stats()
}
#[must_use]
pub fn route_planes(&self) -> Vec<(DataId, crate::session::RoutePlane)> {
self.shared.routes.planes()
}
#[must_use]
pub fn input_planes(&self) -> Vec<(DataId, crate::session::RoutePlane)> {
self.shared.inputs.planes()
}
#[must_use]
pub fn input_plane(&self, input: impl AsRef<str>) -> crate::session::RoutePlane {
match DataId::new(input.as_ref()) {
Ok(id) => self.shared.inputs.plane(&id),
Err(_) => crate::session::RoutePlane::Daemon,
}
}
#[must_use]
pub fn input_plane_stats(&self) -> crate::session::InputPlaneStats {
self.shared.inputs.stats()
}
#[must_use]
pub fn input_segment(&self, input: impl AsRef<str>) -> Option<astrs_wire::ShmSegmentSpec> {
let id = DataId::new(input.as_ref()).ok()?;
self.shared.inputs.segment(&id)
}
#[must_use]
pub fn is_orphaned(&self) -> bool {
self.orphan.as_ref().is_some_and(OrphanGuard::has_fired)
}
#[must_use]
pub fn is_closed(&self) -> bool {
self.shared.is_closed()
}
#[must_use]
pub fn session(&self) -> &Arc<SessionShared> {
&self.shared
}
pub fn shutdown(&mut self) -> Result<()> {
if self.shared.is_closed() {
return Ok(());
}
let result = self.close_outputs();
let _ = self.shared.request_drain();
self.shared.close();
result
}
pub async fn join(&mut self) {
if let Some(tasks) = self.tasks.take() {
tasks.join().await;
}
}
pub async fn flush_outputs(&mut self) {
let Some(tasks) = self.tasks.take() else {
return;
};
let _ = tokio::time::timeout(SHUTDOWN_DRAIN, tasks.writer).await;
}
fn drain_writer(&mut self) {
let Some(tasks) = self.tasks.take() else {
return;
};
if !self.shared.runtime.can_block() {
return;
}
let runtime = self.shared.runtime.clone();
let _ = runtime.block_on("Node::drop", "Node::join", async move {
let _ = tokio::time::timeout(SHUTDOWN_DRAIN, tasks.writer).await;
});
}
#[must_use]
pub fn stop_cause_of(error: &NodeError) -> Option<StopCause> {
error.stop_cause()
}
fn claim_output(&mut self, id: DataId) -> Result<RawOutput> {
if !self.shared.spec.outputs.is_empty() && !self.shared.declares_output(&id) {
return Err(NodeError::UnknownOutput { output: id });
}
if !self.opened.insert(id.clone()) {
return Err(NodeError::UnknownOutput { output: id });
}
Ok(RawOutput::new(Arc::clone(&self.shared), id))
}
fn check_declared_type(&self, id: &DataId, requested: &str) -> Result<()> {
if !self.type_check.is_enabled() {
return Ok(());
}
let Some(declared) = self
.shared
.spec
.output(id)
.and_then(|spec| spec.type_urn.as_ref())
else {
return Ok(());
};
if declared.base() == requested || declared.as_str() == requested {
return Ok(());
}
let mismatch = NodeError::TypeMismatch {
port: id.clone(),
declared: declared.as_str().to_owned(),
requested: requested.to_owned(),
};
if self.type_check.is_fatal() {
return Err(mismatch);
}
tracing::warn!(
node = %self.shared.node,
port = %id,
declared = %declared,
requested = requested,
"port type mismatch (ASTRS_TYPE_CHECK=warn)"
);
Ok(())
}
pub(crate) const fn reply_timeout() -> Duration {
crate::session::DEFAULT_REPLY_TIMEOUT
}
}
impl Drop for Node {
fn drop(&mut self) {
let _ = self.shutdown();
self.drain_writer();
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use crate::message::Vector3;
use crate::testing::TestHarness;
#[test]
fn introspection_reports_what_the_daemon_assigned() {
let harness = TestHarness::start().unwrap();
let node = &harness.node;
assert_eq!(node.id().as_str(), TestHarness::DEFAULT_NODE);
assert_eq!(node.dataflow_id(), harness.daemon.dataflow());
assert!(!node.is_restart());
assert_eq!(node.restart_count(), 0);
assert_eq!(node.generation(), 0);
assert!(!node.is_orphaned());
assert!(!node.is_closed());
assert_eq!(node.type_check(), TypeCheckMode::Warn);
assert!(node.hlc_now() <= node.hlc_now());
assert!(format!("{node:?}").contains(TestHarness::DEFAULT_NODE));
}
#[test]
fn an_output_handle_is_handed_out_once() {
let mut harness = TestHarness::start().unwrap();
let first = harness.node.raw_output("out");
assert!(first.is_ok());
let second = harness.node.raw_output("out");
assert!(matches!(second, Err(NodeError::UnknownOutput { .. })));
}
#[test]
fn a_typed_handle_carries_its_urn() {
let mut harness = TestHarness::start().unwrap();
let output = harness
.node
.output::<Vector3>(TestHarness::DEFAULT_OUTPUT)
.unwrap();
assert_eq!(output.type_urn(), "std/geometry/v1/Vector3");
}
#[test]
fn shutdown_is_idempotent_and_closes_the_session() {
let mut harness = TestHarness::start().unwrap();
harness.node.shutdown().unwrap();
assert!(harness.node.is_closed());
harness.node.shutdown().unwrap();
}
#[test]
fn a_node_can_read_its_own_queue_counters() {
let mut harness = TestHarness::start().unwrap();
assert_eq!(
harness.node.input_ids(),
vec![astrs_wire::DataId::new(TestHarness::DEFAULT_INPUT).unwrap()]
);
let snapshot = harness
.node
.queue_snapshot(TestHarness::DEFAULT_INPUT)
.expect("the queue");
assert_eq!(snapshot.depth, 0);
assert_eq!(snapshot.capacity, astrs_wire::DEFAULT_QUEUE_SIZE);
assert!(harness.node.queue_snapshot("absent").is_none());
assert_eq!(harness.node.queue_snapshots().len(), 1);
assert_eq!(harness.node.stream_stats().delivered, 0);
harness.feed(vec![1]).unwrap();
let event = harness.next_event().unwrap();
assert!(event.is_input());
assert_eq!(harness.node.stream_stats().delivered, 1);
}
#[test]
fn the_reply_timeout_is_the_session_default() {
assert_eq!(Node::reply_timeout(), crate::session::DEFAULT_REPLY_TIMEOUT);
assert_eq!(
Node::stop_cause_of(&NodeError::Stopped),
Some(StopCause::Requested)
);
}
}