Skip to main content

Crate astrs_node_api

Crate astrs_node_api 

Source
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

§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 loop

Every 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:

EndWhat arrivesWhat this crate does
producerNodeEvent::RouteUpgradeopens a shared-memory producer; RawOutput::allocate hands back the ring slot itself (session::routes)
consumerNodeEvent::InputRouteUpgradeattaches 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

FeatureDefaultWhat it adds
arrow-interopnoRawOutput::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
Event and EventStream — what a node’s loop reads (blueprint §9.1).
message
The std URN 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> and OutputSample (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 main needs, 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§

TensorView
The read-only views Payload::view decodes into (blueprint §9.1’s let img: ImageView = data.view()?;).

Enums§

ImageView
The read-only views Payload::view decodes into (blueprint §9.1’s let img: ImageView = data.view()?;).

Traits§

AstrsMessage
A Rust type that maps onto a single-column AstRS payload (blueprint §6.1, §9.2).