Skip to main content

astrs_node_api/node/
builder.rs

1//! [`NodeBuilder`] — the constructor for everything `init_from_env` does not
2//! cover (blueprint §9.1).
3//!
4//! Three shapes of node reach a daemon, and the builder is the one path all
5//! three take:
6//!
7//! | Shape | How it is built |
8//! |---|---|
9//! | Spawned | [`NodeBuilder::from_env`] reads `ASTRS_NODE_CONFIG` (§24.2) |
10//! | Dynamic | [`NodeBuilder::node_id`] + `dynamic(true)`, endpoints from the environment (§8.3) |
11//! | Overridden | Either of the above, plus explicit `daemon`/`auth`/`dataflow` |
12//!
13//! # Defaults
14//!
15//! Everything the builder does not set comes from §24.2: the Unix socket under
16//! `$XDG_RUNTIME_DIR/astrs` first, then TCP loopback on 7408; the 4 KiB
17//! zero-copy threshold; `ASTRS_TYPE_CHECK=warn`; and the orphan guard only
18//! when `ASTRS_RUN_PARENT_PID` names a supervisor.
19
20use std::time::Duration;
21
22use astrs_wire::{
23    AuthToken, DataId, DataflowId, NodeConfig, NodeHandshake, NodeId, NodeSource, NodeSpawnSpec,
24};
25
26use crate::env::{self, TypeCheckMode};
27use crate::error::{NodeError, Result};
28use crate::events::EventStream;
29use crate::node::{Node, init};
30use crate::orphan::{DEFAULT_POLL_INTERVAL, OrphanGuard};
31use crate::runtime::NodeRuntime;
32use crate::session::connect;
33
34/// The environment variable carrying the cluster token in hex (§16).
35///
36/// Not in the §24.2 table, because a *spawned* node gets its token inside the
37/// `ASTRS_NODE_CONFIG` blob. A dynamic node has no blob, so it needs some way
38/// to present one; this is that way, and it is read only when the builder was
39/// given no token of its own.
40pub const ENV_AUTH_TOKEN: &str = "ASTRS_AUTH_TOKEN";
41
42/// How long the dial and greeting are allowed to take.
43pub const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
44
45/// Builds a [`Node`].
46#[derive(Debug, Clone, Default)]
47pub struct NodeBuilder {
48    /// The blob a spawned node was handed.
49    config: Option<Box<NodeConfig>>,
50    /// An explicit node id.
51    node_id: Option<NodeId>,
52    /// An explicit dataflow id.
53    dataflow: Option<DataflowId>,
54    /// Endpoints to dial, overriding the configuration's.
55    endpoints: Vec<String>,
56    /// The cluster token.
57    auth: Option<AuthToken>,
58    /// Whether this node attaches itself (§8.3).
59    dynamic: bool,
60    /// The inputs a dynamic node declares.
61    inputs: Vec<DataId>,
62    /// The outputs a dynamic node declares.
63    outputs: Vec<DataId>,
64    /// The inputs to subscribe to; empty means all.
65    subscribe: Vec<DataId>,
66    /// An explicit type-check mode, overriding the environment.
67    type_check: Option<TypeCheckMode>,
68    /// An explicit zero-copy threshold, overriding the configuration.
69    zero_copy_threshold: Option<u64>,
70    /// The supervisor to watch, overriding `ASTRS_RUN_PARENT_PID`.
71    parent_pid: Option<u32>,
72    /// Whether to start the orphan guard at all.
73    orphan_guard: bool,
74    /// How long the dial and greeting may take.
75    connect_timeout: Duration,
76    /// A label for the greeting, shown in `astrs list`.
77    label: Option<String>,
78}
79
80impl NodeBuilder {
81    /// An empty builder.
82    #[must_use]
83    pub fn new() -> Self {
84        Self {
85            orphan_guard: true,
86            connect_timeout: DEFAULT_CONNECT_TIMEOUT,
87            ..Self::default()
88        }
89    }
90
91    /// A builder seeded from `ASTRS_NODE_CONFIG` (§24.2).
92    ///
93    /// # Errors
94    ///
95    /// [`NodeError::MissingEnv`] when the variable is unset, and
96    /// [`NodeError::Config`] when it does not decode.
97    pub fn from_env() -> Result<Self> {
98        let value =
99            std::env::var(astrs_wire::ENV_NODE_CONFIG).map_err(|_| NodeError::MissingEnv {
100                name: astrs_wire::ENV_NODE_CONFIG,
101            })?;
102        Self::from_env_value(&value)
103    }
104
105    /// A builder seeded from an explicit blob.
106    ///
107    /// # Errors
108    ///
109    /// [`NodeError::Config`] when the blob does not decode.
110    pub fn from_env_value(value: &str) -> Result<Self> {
111        let config = NodeConfig::from_env_value(value)?;
112        Ok(Self::new().with_config(config))
113    }
114
115    /// Seeds the builder from an already-decoded configuration.
116    #[must_use]
117    pub fn with_config(mut self, config: NodeConfig) -> Self {
118        self.config = Some(Box::new(config));
119        self
120    }
121
122    /// Sets the node's id.
123    ///
124    /// # Errors
125    ///
126    /// [`NodeError::Id`] when the name fails the identifier grammar.
127    pub fn node_id(mut self, node_id: impl AsRef<str>) -> Result<Self> {
128        self.node_id = Some(NodeId::new(node_id.as_ref())?);
129        Ok(self)
130    }
131
132    /// Sets the dataflow to join.
133    #[must_use]
134    pub const fn dataflow(mut self, dataflow: DataflowId) -> Self {
135        self.dataflow = Some(dataflow);
136        self
137    }
138
139    /// Adds an endpoint to dial, overriding the configuration's list.
140    #[must_use]
141    pub fn daemon(mut self, endpoint: impl Into<String>) -> Self {
142        self.endpoints.push(endpoint.into());
143        self
144    }
145
146    /// Sets the cluster token (§16).
147    #[must_use]
148    pub fn auth(mut self, auth: AuthToken) -> Self {
149        self.auth = Some(auth);
150        self
151    }
152
153    /// Marks the node as attaching itself (§8.3).
154    #[must_use]
155    pub const fn dynamic(mut self, dynamic: bool) -> Self {
156        self.dynamic = dynamic;
157        self
158    }
159
160    /// Declares an input a dynamic node intends to read.
161    ///
162    /// # Errors
163    ///
164    /// [`NodeError::Id`] when the name fails the identifier grammar.
165    pub fn input(mut self, input: impl AsRef<str>) -> Result<Self> {
166        self.inputs.push(DataId::new(input.as_ref())?);
167        Ok(self)
168    }
169
170    /// Declares an output a dynamic node intends to write.
171    ///
172    /// # Errors
173    ///
174    /// [`NodeError::Id`] when the name fails the identifier grammar.
175    pub fn output(mut self, output: impl AsRef<str>) -> Result<Self> {
176        self.outputs.push(DataId::new(output.as_ref())?);
177        Ok(self)
178    }
179
180    /// Subscribes to a subset of the node's inputs; the default is all of
181    /// them.
182    ///
183    /// # Errors
184    ///
185    /// [`NodeError::Id`] when the name fails the identifier grammar.
186    pub fn subscribe(mut self, input: impl AsRef<str>) -> Result<Self> {
187        self.subscribe.push(DataId::new(input.as_ref())?);
188        Ok(self)
189    }
190
191    /// Overrides the §9.2 type-check mode.
192    #[must_use]
193    pub const fn type_check(mut self, mode: TypeCheckMode) -> Self {
194        self.type_check = Some(mode);
195        self
196    }
197
198    /// Overrides the §6.2 zero-copy threshold.
199    #[must_use]
200    pub const fn zero_copy_threshold(mut self, bytes: u64) -> Self {
201        self.zero_copy_threshold = Some(bytes);
202        self
203    }
204
205    /// Watches `pid` as the supervising process (§4.2).
206    #[must_use]
207    pub const fn parent_pid(mut self, pid: u32) -> Self {
208        self.parent_pid = Some(pid);
209        self
210    }
211
212    /// Turns the orphan guard off, for a node that outlives its launcher on
213    /// purpose.
214    #[must_use]
215    pub const fn orphan_guard(mut self, enabled: bool) -> Self {
216        self.orphan_guard = enabled;
217        self
218    }
219
220    /// Bounds the dial and greeting.
221    #[must_use]
222    pub const fn connect_timeout(mut self, timeout: Duration) -> Self {
223        self.connect_timeout = timeout;
224        self
225    }
226
227    /// Sets the label the greeting carries, shown in `astrs list`.
228    #[must_use]
229    pub fn label(mut self, label: impl Into<String>) -> Self {
230        self.label = Some(label.into());
231        self
232    }
233
234    /// The endpoints this builder will dial, in order.
235    ///
236    /// Explicit endpoints win; then the configuration blob's; then the §24.2
237    /// defaults (Unix socket, then TCP loopback).
238    ///
239    /// # Errors
240    ///
241    /// [`NodeError::BadEnv`] when `ASTRS_DAEMON_PORT` is not a port.
242    pub fn resolved_endpoints(&self) -> Result<Vec<String>> {
243        if !self.endpoints.is_empty() {
244            return Ok(self.endpoints.clone());
245        }
246        if let Some(config) = &self.config
247            && !config.endpoints.is_empty()
248        {
249            return Ok(config.endpoints.clone());
250        }
251        Ok(vec![
252            format!("uds://{}", env::daemon_socket_path().display()),
253            format!("tcp://127.0.0.1:{}", env::daemon_port()?),
254        ])
255    }
256
257    /// The token this builder will present.
258    ///
259    /// # Errors
260    ///
261    /// [`NodeError::BadEnv`] when `ASTRS_AUTH_TOKEN` is set but not valid hex.
262    pub fn resolved_auth(&self) -> Result<AuthToken> {
263        if let Some(auth) = &self.auth {
264            return Ok(auth.clone());
265        }
266        if let Some(config) = &self.config {
267            return Ok(config.auth.clone());
268        }
269        match std::env::var(ENV_AUTH_TOKEN) {
270            Ok(hex) if !hex.trim().is_empty() => {
271                AuthToken::parse_hex(hex.trim()).map_err(|error| NodeError::BadEnv {
272                    name: ENV_AUTH_TOKEN,
273                    value: "<redacted>".to_owned(),
274                    reason: error.to_string(),
275                })
276            }
277            _ => Ok(AuthToken::ZERO),
278        }
279    }
280
281    /// The registration this builder will send.
282    ///
283    /// # Errors
284    ///
285    /// [`NodeError::Pattern`] when neither a configuration blob nor a node id
286    /// was supplied, since there is then nothing to register *as*.
287    pub fn handshake(&self) -> Result<NodeHandshake> {
288        let (dataflow, node, generation) = self.identity()?;
289        let handshake = if self.dynamic {
290            NodeHandshake::dynamic(dataflow, node)
291                .with_inputs(self.inputs.clone())
292                .with_outputs(self.outputs.clone())
293        } else {
294            NodeHandshake::new(dataflow, node, generation)
295        };
296        Ok(handshake.with_pid(std::process::id()))
297    }
298
299    /// The specification a dynamic node registers with, when it has no blob.
300    ///
301    /// # Errors
302    ///
303    /// As [`NodeBuilder::handshake`].
304    pub fn provisional_spec(&self) -> Result<NodeSpawnSpec> {
305        if let Some(config) = &self.config {
306            return Ok(config.spec.clone());
307        }
308        let (dataflow, node, generation) = self.identity()?;
309        Ok(NodeSpawnSpec::new(
310            dataflow,
311            node,
312            generation,
313            NodeSource::Dynamic,
314        ))
315    }
316
317    /// Connects, registers and starts the session.
318    ///
319    /// # Errors
320    ///
321    /// [`NodeError::Connect`] when no endpoint answered, [`NodeError::Handshake`]
322    /// when the greeting was refused, and [`NodeError::Registration`] when the
323    /// daemon refused the registration.
324    pub fn connect(self) -> Result<(Node, EventStream)> {
325        let runtime = NodeRuntime::acquire()?;
326        let handle = runtime.clone();
327        handle.block_on("Node::init", "NodeBuilder::connect_async", async move {
328            self.connect_with(runtime).await
329        })?
330    }
331
332    /// The async form of [`NodeBuilder::connect`].
333    ///
334    /// # Errors
335    ///
336    /// As [`NodeBuilder::connect`].
337    pub async fn connect_async(self) -> Result<(Node, EventStream)> {
338        let runtime = NodeRuntime::acquire()?;
339        self.connect_with(runtime).await
340    }
341
342    /// Connects on a runtime the caller chose.
343    ///
344    /// # Errors
345    ///
346    /// As [`NodeBuilder::connect`].
347    pub async fn connect_with(self, runtime: NodeRuntime) -> Result<(Node, EventStream)> {
348        let endpoints = self.resolved_endpoints()?;
349        let auth = self.resolved_auth()?;
350        let handshake = self.handshake()?;
351        let link =
352            connect::dial(&endpoints, &auth, self.label.clone(), self.connect_timeout).await?;
353        self.finish(link, handshake, runtime).await
354    }
355
356    /// Registers over an already-established link.
357    ///
358    /// The seam the testing harness uses: it supplies a link over a
359    /// `tokio::io::duplex` pair rather than a socket.
360    ///
361    /// # Errors
362    ///
363    /// As [`NodeBuilder::connect`].
364    pub async fn finish(
365        self,
366        link: connect::NodeLink,
367        handshake: NodeHandshake,
368        runtime: NodeRuntime,
369    ) -> Result<(Node, EventStream)> {
370        let type_check = match self.type_check {
371            Some(mode) => mode,
372            None => TypeCheckMode::from_env()?,
373        };
374        let threshold = match self.zero_copy_threshold {
375            Some(threshold) => threshold,
376            None => match &self.config {
377                Some(config) => config.zero_copy_threshold,
378                None => env::zero_copy_threshold()?,
379            },
380        };
381        // The daemon's own answer to "where do I attach segments?", straight
382        // from the handshake blob: a node must never recompute it from the
383        // environment, because `astrs run --runtime-dir` moves it (§6.2).
384        let broker = self
385            .config
386            .as_ref()
387            .and_then(|config| config.shm_broker.clone())
388            .map(std::path::PathBuf::from);
389        let registration = init::register_with(
390            link,
391            handshake,
392            runtime.clone(),
393            threshold,
394            self.subscribe.clone(),
395            broker,
396        )
397        .await?;
398
399        let parent = match self.parent_pid {
400            Some(pid) => Some(pid),
401            None => env::parent_pid()?,
402        };
403        let orphan = if self.orphan_guard {
404            OrphanGuard::maybe_watch(
405                parent,
406                &runtime,
407                std::sync::Arc::clone(&registration.shared.source),
408                DEFAULT_POLL_INTERVAL,
409            )
410        } else {
411            None
412        };
413
414        Ok(Node::from_registration(registration, type_check, orphan))
415    }
416
417    /// The `(dataflow, node, generation)` triple this builder registers as.
418    fn identity(&self) -> Result<(DataflowId, NodeId, u64)> {
419        if let Some(config) = &self.config {
420            let node = self
421                .node_id
422                .clone()
423                .unwrap_or_else(|| config.node().clone());
424            let dataflow = self.dataflow.unwrap_or_else(|| config.dataflow());
425            return Ok((dataflow, node, config.generation()));
426        }
427        let Some(node) = self.node_id.clone() else {
428            return Err(NodeError::Pattern(
429                "a node needs either ASTRS_NODE_CONFIG or an explicit node id".to_owned(),
430            ));
431        };
432        Ok((
433            self.dataflow.unwrap_or_else(|| DataflowId::from_u128(0)),
434            node,
435            0,
436        ))
437    }
438}
439
440#[cfg(test)]
441mod tests {
442    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
443
444    use super::*;
445    use astrs_wire::DaemonId;
446
447    fn config() -> NodeConfig {
448        let spec = NodeSpawnSpec::new(
449            DataflowId::from_u128(9),
450            NodeId::new("camera").unwrap(),
451            3,
452            NodeSource::Executable {
453                path: "./camera".to_owned(),
454            },
455        );
456        NodeConfig::new(
457            spec,
458            DaemonId::generate(None),
459            AuthToken::from_bytes([4; 32]),
460        )
461        .with_endpoint("uds:///tmp/astrs/daemon.sock")
462        .with_zero_copy_threshold(8192)
463    }
464
465    #[test]
466    fn a_configured_builder_takes_its_identity_from_the_blob() {
467        let builder = NodeBuilder::new().with_config(config());
468        let handshake = builder.handshake().unwrap();
469        assert_eq!(handshake.node.as_str(), "camera");
470        assert_eq!(handshake.generation, 3);
471        assert!(!handshake.dynamic);
472        assert_eq!(handshake.pid, Some(std::process::id()));
473        assert_eq!(
474            builder.resolved_endpoints().unwrap(),
475            vec!["uds:///tmp/astrs/daemon.sock"]
476        );
477        assert_eq!(
478            builder.resolved_auth().unwrap(),
479            AuthToken::from_bytes([4; 32])
480        );
481        assert_eq!(builder.provisional_spec().unwrap().generation, 3);
482    }
483
484    #[test]
485    fn a_dynamic_builder_declares_its_ports() {
486        let builder = NodeBuilder::new()
487            .node_id("probe")
488            .unwrap()
489            .dynamic(true)
490            .input("frames")
491            .unwrap()
492            .output("samples")
493            .unwrap();
494        let handshake = builder.handshake().unwrap();
495        assert!(handshake.dynamic);
496        assert_eq!(handshake.generation, 0);
497        assert!(handshake.declares_ports());
498        assert_eq!(handshake.inputs.len(), 1);
499        assert_eq!(handshake.outputs.len(), 1);
500        assert!(matches!(
501            builder.provisional_spec().unwrap().source,
502            NodeSource::Dynamic
503        ));
504    }
505
506    #[test]
507    fn a_builder_with_neither_blob_nor_id_is_refused() {
508        let error = NodeBuilder::new().handshake().unwrap_err();
509        assert!(matches!(error, NodeError::Pattern(_)), "{error}");
510    }
511
512    #[test]
513    fn explicit_endpoints_win_over_the_blob() {
514        let builder = NodeBuilder::new()
515            .with_config(config())
516            .daemon("tcp://10.0.0.2:7408");
517        assert_eq!(
518            builder.resolved_endpoints().unwrap(),
519            vec!["tcp://10.0.0.2:7408"]
520        );
521    }
522
523    #[test]
524    fn a_bare_builder_falls_back_to_the_appendix_defaults() {
525        let builder = NodeBuilder::new().node_id("probe").unwrap();
526        let endpoints = builder.resolved_endpoints().unwrap();
527        assert_eq!(endpoints.len(), 2, "uds first, tcp second");
528        assert!(endpoints[0].starts_with("uds://"), "{endpoints:?}");
529        assert!(
530            endpoints[1].starts_with("tcp://127.0.0.1:"),
531            "{endpoints:?}"
532        );
533    }
534
535    #[test]
536    fn an_explicit_token_wins_over_everything() {
537        let token = AuthToken::from_bytes([7; 32]);
538        let builder = NodeBuilder::new().with_config(config()).auth(token.clone());
539        assert_eq!(builder.resolved_auth().unwrap(), token);
540    }
541
542    #[test]
543    fn a_missing_environment_blob_is_named() {
544        // `from_env_value` is exercised directly; the process environment is
545        // shared with parallel tests.
546        let error = NodeBuilder::from_env_value("!!!!").unwrap_err();
547        assert!(matches!(error, NodeError::Config(_)), "{error}");
548
549        let blob = config().to_env_value().unwrap();
550        let builder = NodeBuilder::from_env_value(&blob).unwrap();
551        assert_eq!(builder.handshake().unwrap().node.as_str(), "camera");
552    }
553
554    #[test]
555    fn builder_settings_are_recorded() {
556        let builder = NodeBuilder::new()
557            .node_id("probe")
558            .unwrap()
559            .dataflow(DataflowId::from_u128(2))
560            .type_check(TypeCheckMode::Error)
561            .zero_copy_threshold(1)
562            .parent_pid(42)
563            .orphan_guard(false)
564            .connect_timeout(Duration::from_millis(5))
565            .label("probe-1")
566            .subscribe("frames")
567            .unwrap();
568        assert_eq!(builder.type_check, Some(TypeCheckMode::Error));
569        assert_eq!(builder.zero_copy_threshold, Some(1));
570        assert_eq!(builder.parent_pid, Some(42));
571        assert!(!builder.orphan_guard);
572        assert_eq!(builder.connect_timeout, Duration::from_millis(5));
573        assert_eq!(builder.label.as_deref(), Some("probe-1"));
574        assert_eq!(builder.subscribe.len(), 1);
575        let handshake = builder.handshake().unwrap();
576        assert_eq!(handshake.dataflow, DataflowId::from_u128(2));
577    }
578
579    #[test]
580    fn connecting_to_nothing_reports_every_attempt() {
581        let error = NodeBuilder::new()
582            .node_id("probe")
583            .unwrap()
584            .daemon(format!(
585                "uds://{}",
586                std::env::temp_dir().join("astrs-absent.sock").display()
587            ))
588            .connect_timeout(Duration::from_millis(100))
589            .connect()
590            .unwrap_err();
591        assert!(matches!(error, NodeError::Connect { .. }), "{error}");
592    }
593
594    #[test]
595    fn the_documented_constants_are_stable() {
596        assert_eq!(ENV_AUTH_TOKEN, "ASTRS_AUTH_TOKEN");
597        assert_eq!(DEFAULT_CONNECT_TIMEOUT, Duration::from_secs(10));
598    }
599}