Skip to main content

astrs_node_api/
lib.rs

1//! **astrs-node-api** — the AstRS node API (blueprint §9.1).
2//!
3//! The flagship user-facing surface: everything a robotics node needs to join
4//! a dataflow, read its inputs and publish its outputs, and nothing it does
5//! not.
6//!
7//! ```no_run
8//! use astrs_node_api::prelude::*;
9//!
10//! fn main() -> Result<(), NodeError> {
11//!     let (mut node, mut events) = Node::init_from_env()?;
12//!     let mut echo = node.raw_output("echo")?;
13//!
14//!     while let Some(event) = events.recv() {
15//!         match event {
16//!             Event::Input { id, data, meta } if id == "frames" => {
17//!                 echo.send_bytes(data.to_vec(), meta.follow())?;
18//!             }
19//!             Event::Stop(_) => break,
20//!             _ => {}
21//!         }
22//!     }
23//!     Ok(())
24//! }
25//! ```
26//!
27//! # The surface, in one table
28//!
29//! | Area | Entry points |
30//! |---|---|
31//! | Init | [`Node::init_from_env`], [`Node::builder`], [`Node::init_from_node_id`], [`Node::init_testing`] |
32//! | Events | [`EventStream::recv`], [`EventStream::recv_async`], `Iterator`, [`Stream`], [`EventStream::merge_external`] |
33//! | Sending | [`Output::send`], [`RawOutput::send_bytes`], [`RawOutput::send_batch`], [`RawOutput::send_array`], [`RawOutput::allocate`] (and [`RawOutput::send_arrow`] under `arrow-interop`) |
34//! | Patterns | [`Node::service_request`], [`Node::service_response`], [`Node::goal`], [`Node::goal_status`], [`Node::stream_chunk`] |
35//! | Logging | [`Node::log_error`] … [`Node::log_trace`], [`Node::log_with_fields`] |
36//! | Introspection | [`Node::id`], [`Node::dataflow_id`], [`Node::descriptor`], [`Node::is_restart`], [`Node::restart_count`], [`Node::hlc_now`] |
37//! | Extensions | [`Node::ext_store`], [`Node::ext_load`], [`Node::ext_drop`] |
38//!
39//! # How the pieces fit
40//!
41//! ```text
42//!   Node ──────────────► SessionHandle ──► writer task ──► framed UDS/TCP ──► daemon
43//!    │                        ▲                                    │
44//!    │ output::<T>()          │ NodeRequest                        │ NodeEvent
45//!    ▼                        │                                    ▼
46//!   Output<T> ── threshold ──►│                            reader task ──► EventMux
47//!    │            (§6.2)      │                                    │      (queue policy)
48//!    └── SHM Producer ────────┘                                    ▼
49//!         (after RouteUpgrade, §6.3)                        EventStream ──► your loop
50//! ```
51//!
52//! Every layer is testable without a daemon: [`Node::init_testing`] spins an
53//! in-process [`testing::MockDaemon`] speaking the real §7.3 wire
54//! protocol over a `tokio::io::duplex` pair, so a node's whole lifecycle —
55//! register, subscribe, inputs, patterns, stop — is a unit test.
56//!
57//! # Zero copy, both ways
58//!
59//! §6.3's slow-start handshake is wired at **both** ends, and a node writes no
60//! code for either:
61//!
62//! | End | What arrives | What this crate does |
63//! |---|---|---|
64//! | producer | `NodeEvent::RouteUpgrade` | opens a shared-memory producer; [`RawOutput::allocate`] hands back the ring slot itself ([`session::routes`]) |
65//! | consumer | `NodeEvent::InputRouteUpgrade` | attaches the segment and reads samples in place, so `Event::Input`'s payload is [`Payload::is_zero_copy`] ([`session::inputs`]) |
66//!
67//! Both directions fall back the same way: a downgrade, a dead producer or a
68//! stale generation puts the route back on the reliable daemon path, and the
69//! node's event loop does not notice. [`Node::route_planes`] and
70//! [`Node::input_planes`] report where each end currently is; a message's
71//! [`Payload::slot`] says where in the ring it came from, which is what turns
72//! "zero copy" into something a test can check.
73//!
74//! [`Payload::zero_copy`] stays public for a node that brokers a segment
75//! itself — a recorder replaying into a ring, an embedder outside the
76//! daemon's graph — but nothing in a normal pipeline needs it any more.
77//!
78//! # Features
79//!
80//! | Feature | Default | What it adds |
81//! |---|---|---|
82//! | `arrow-interop` | no | [`RawOutput::send_arrow`] / [`Output::send_arrow`] — publishing arrow-rs values through `astrs-data`'s bridge (blueprint §6.1, §9.1). See [`output::arrow`]. |
83
84#![cfg_attr(docsrs, feature(doc_cfg))]
85
86pub mod env;
87pub mod error;
88pub mod events;
89pub mod message;
90pub mod node;
91pub mod orphan;
92pub mod output;
93pub mod patterns;
94pub mod payload;
95pub mod runtime;
96pub mod session;
97pub mod signal;
98pub mod testing;
99
100pub use error::{NodeError, Result};
101pub use events::{Event, EventStream, Stream};
102pub use message::{AstrsMessage, FromPayload};
103pub use node::{Node, NodeBuilder};
104pub use output::{Output, OutputSample, RawOutput};
105pub use patterns::{
106    ActionOutcome, GoalId, GoalTracker, RequestId, ServiceRequest, ServiceResponse,
107    StreamAssembler, StreamWriter,
108};
109pub use payload::{Payload, PayloadKind, SlotLocation};
110pub use signal::{Signal, WaitOutcome};
111pub use testing::{MockDaemon, TestHarness};
112
113/// The read-only views [`Payload::view`] decodes into (blueprint §9.1's
114/// `let img: ImageView = data.view()?;`).
115///
116/// They belong to `astrs-data` — a view is a checked window over columns
117/// somebody else built, and the layout rules it checks are that crate's — but
118/// the line that *names* them is a node's event loop, so a node reaches them
119/// here rather than through a second crate. [`ImageView`] has a
120/// [`FromPayload`] implementation (see [`message::media`]); [`TensorView`] is
121/// the general n-dimensional form the same module builds on.
122pub use astrs_data::tensor::{ImageView, TensorView};
123
124/// Everything a node's `main` needs, in one import.
125///
126/// ```no_run
127/// use astrs_node_api::prelude::*;
128///
129/// fn main() -> Result<(), NodeError> {
130///     let (mut node, mut events) = Node::init_from_env()?;
131///     while let Some(event) = events.recv() {
132///         if event.is_stop() {
133///             break;
134///         }
135///     }
136///     let _ = &mut node;
137///     Ok(())
138/// }
139/// ```
140pub mod prelude {
141    pub use crate::env::TypeCheckMode;
142    pub use crate::error::{NodeError, Result};
143    pub use crate::events::{Event, EventStream, Stream};
144    pub use crate::message::{AstrsMessage, FromPayload};
145    pub use crate::node::{Node, NodeBuilder};
146    /// The error `send_arrow` reports, for an application that names it in a
147    /// signature rather than only `?`-ing it.
148    #[cfg(feature = "arrow-interop")]
149    #[cfg_attr(docsrs, doc(cfg(feature = "arrow-interop")))]
150    pub use crate::output::{ArrowSendError, ArrowSendResult};
151    pub use crate::output::{Output, OutputSample, RawOutput};
152    pub use crate::patterns::{
153        ActionOutcome, GoalId, GoalTracker, RequestId, ServiceRequest, ServiceResponse,
154        StreamAssembler, StreamWriter,
155    };
156    pub use crate::payload::{Payload, PayloadKind, SlotLocation};
157    /// The zero-copy views §9.1's flagship loop names on its very first line
158    /// inside the match arm (`let img: ImageView = data.view()?;`). Without
159    /// them here that line needs a second `use` naming `astrs-data`, which is
160    /// exactly the shape the facade exists to avoid.
161    pub use astrs_data::tensor::{ImageView, TensorView};
162    pub use astrs_wire::{DataId, DataflowId, GoalStatus, Metadata, NodeId, PortRef, StopCause};
163}