Expand description
astrs-node-api — the AstRS node API (blueprint §9.1).
The flagship user-facing surface: everything a robotics node needs to join a dataflow, read its inputs and publish its outputs, and nothing it does not.
use astrs_node_api::prelude::*;
fn main() -> Result<(), NodeError> {
let (mut node, mut events) = Node::init_from_env()?;
let mut echo = node.raw_output("echo")?;
while let Some(event) = events.recv() {
match event {
Event::Input { id, data, meta } if id == "frames" => {
echo.send_bytes(data.to_vec(), meta.follow())?;
}
Event::Stop(_) => break,
_ => {}
}
}
Ok(())
}§The surface, in one table
| Area | Entry points |
|---|---|
| Init | Node::init_from_env, Node::builder, Node::init_from_node_id, Node::init_testing |
| Events | EventStream::recv, EventStream::recv_async, Iterator, Stream, EventStream::merge_external |
| Sending | Output::send, RawOutput::send_bytes, RawOutput::send_batch, RawOutput::send_array, RawOutput::allocate (and RawOutput::send_arrow under arrow-interop) |
| Patterns | Node::service_request, Node::service_response, Node::goal, Node::goal_status, Node::stream_chunk |
| Logging | Node::log_error … Node::log_trace, Node::log_with_fields |
| Introspection | Node::id, Node::dataflow_id, Node::descriptor, Node::is_restart, Node::restart_count, Node::hlc_now |
| Extensions | Node::ext_store, Node::ext_load, Node::ext_drop |
§How the pieces fit
Node ──────────────► SessionHandle ──► writer task ──► framed UDS/TCP ──► daemon
│ ▲ │
│ output::<T>() │ NodeRequest │ NodeEvent
▼ │ ▼
Output<T> ── threshold ──►│ reader task ──► EventMux
│ (§6.2) │ │ (queue policy)
└── SHM Producer ────────┘ ▼
(after RouteUpgrade, §6.3) EventStream ──► your loopEvery layer is testable without a daemon: Node::init_testing spins an
in-process testing::MockDaemon speaking the real §7.3 wire
protocol over a tokio::io::duplex pair, so a node’s whole lifecycle —
register, subscribe, inputs, patterns, stop — is a unit test.
§Zero copy, both ways
§6.3’s slow-start handshake is wired at both ends, and a node writes no code for either:
| End | What arrives | What this crate does |
|---|---|---|
| producer | NodeEvent::RouteUpgrade | opens a shared-memory producer; RawOutput::allocate hands back the ring slot itself (session::routes) |
| consumer | NodeEvent::InputRouteUpgrade | attaches the segment and reads samples in place, so Event::Input’s payload is Payload::is_zero_copy (session::inputs) |
Both directions fall back the same way: a downgrade, a dead producer or a
stale generation puts the route back on the reliable daemon path, and the
node’s event loop does not notice. Node::route_planes and
Node::input_planes report where each end currently is; a message’s
Payload::slot says where in the ring it came from, which is what turns
“zero copy” into something a test can check.
Payload::zero_copy stays public for a node that brokers a segment
itself — a recorder replaying into a ring, an embedder outside the
daemon’s graph — but nothing in a normal pipeline needs it any more.
§Features
| Feature | Default | What it adds |
|---|---|---|
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. |
Re-exports§
pub use error::NodeError;pub use error::Result;pub use events::Event;pub use events::EventStream;pub use events::Stream;pub use message::FromPayload;pub use node::Node;pub use node::NodeBuilder;pub use output::Output;pub use output::OutputSample;pub use output::RawOutput;pub use patterns::ActionOutcome;pub use patterns::GoalId;pub use patterns::GoalTracker;pub use patterns::RequestId;pub use patterns::ServiceRequest;pub use patterns::ServiceResponse;pub use patterns::StreamAssembler;pub use patterns::StreamWriter;pub use payload::Payload;pub use payload::PayloadKind;pub use payload::SlotLocation;pub use signal::Signal;pub use signal::WaitOutcome;pub use testing::MockDaemon;pub use testing::TestHarness;
Modules§
- env
- The environment surface a node reads at start-up (blueprint §24.2).
- error
NodeError— every way a node can fail, named.- events
EventandEventStream— what a node’s loop reads (blueprint §9.1).- message
- The
stdURN message types (blueprint §9.2, §24.3). - node
Node— the flagship surface of blueprint §9.1.- orphan
- The orphan guard (blueprint §4.2).
- output
- Publishing:
RawOutput,Output<T>andOutputSample(blueprint §9.1, §6.2, §6.3). - patterns
- Services, actions and streams (blueprint §9.4).
- payload
Payload— the bytes of one input, decoded only if the node looks.- prelude
- Everything a node’s
mainneeds, in one import. - runtime
NodeRuntime— the async runtime a node’s session lives on.- session
- The daemon session: one connection, two tasks, one shared state (blueprint §7.3).
- signal
Signal— one wakeup that both a blocking thread and an async task can wait on.- testing
- The testing harness (blueprint §9.1’s
init_testing).
Structs§
- Tensor
View - The read-only views
Payload::viewdecodes into (blueprint §9.1’slet img: ImageView = data.view()?;).
Enums§
- Image
View - The read-only views
Payload::viewdecodes into (blueprint §9.1’slet img: ImageView = data.view()?;).
Traits§
- Astrs
Message - A Rust type that maps onto a single-column AstRS payload (blueprint §6.1, §9.2).