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}