1use 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
34pub const ENV_AUTH_TOKEN: &str = "ASTRS_AUTH_TOKEN";
41
42pub const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
44
45#[derive(Debug, Clone, Default)]
47pub struct NodeBuilder {
48 config: Option<Box<NodeConfig>>,
50 node_id: Option<NodeId>,
52 dataflow: Option<DataflowId>,
54 endpoints: Vec<String>,
56 auth: Option<AuthToken>,
58 dynamic: bool,
60 inputs: Vec<DataId>,
62 outputs: Vec<DataId>,
64 subscribe: Vec<DataId>,
66 type_check: Option<TypeCheckMode>,
68 zero_copy_threshold: Option<u64>,
70 parent_pid: Option<u32>,
72 orphan_guard: bool,
74 connect_timeout: Duration,
76 label: Option<String>,
78}
79
80impl NodeBuilder {
81 #[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 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 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 #[must_use]
117 pub fn with_config(mut self, config: NodeConfig) -> Self {
118 self.config = Some(Box::new(config));
119 self
120 }
121
122 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 #[must_use]
134 pub const fn dataflow(mut self, dataflow: DataflowId) -> Self {
135 self.dataflow = Some(dataflow);
136 self
137 }
138
139 #[must_use]
141 pub fn daemon(mut self, endpoint: impl Into<String>) -> Self {
142 self.endpoints.push(endpoint.into());
143 self
144 }
145
146 #[must_use]
148 pub fn auth(mut self, auth: AuthToken) -> Self {
149 self.auth = Some(auth);
150 self
151 }
152
153 #[must_use]
155 pub const fn dynamic(mut self, dynamic: bool) -> Self {
156 self.dynamic = dynamic;
157 self
158 }
159
160 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 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 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 #[must_use]
193 pub const fn type_check(mut self, mode: TypeCheckMode) -> Self {
194 self.type_check = Some(mode);
195 self
196 }
197
198 #[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 #[must_use]
207 pub const fn parent_pid(mut self, pid: u32) -> Self {
208 self.parent_pid = Some(pid);
209 self
210 }
211
212 #[must_use]
215 pub const fn orphan_guard(mut self, enabled: bool) -> Self {
216 self.orphan_guard = enabled;
217 self
218 }
219
220 #[must_use]
222 pub const fn connect_timeout(mut self, timeout: Duration) -> Self {
223 self.connect_timeout = timeout;
224 self
225 }
226
227 #[must_use]
229 pub fn label(mut self, label: impl Into<String>) -> Self {
230 self.label = Some(label.into());
231 self
232 }
233
234 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 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 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 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 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 pub async fn connect_async(self) -> Result<(Node, EventStream)> {
338 let runtime = NodeRuntime::acquire()?;
339 self.connect_with(runtime).await
340 }
341
342 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 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 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(®istration.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 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 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}