use std::time::Duration;
use astrs_wire::{
AuthToken, DataId, DataflowId, NodeConfig, NodeHandshake, NodeId, NodeSource, NodeSpawnSpec,
};
use crate::env::{self, TypeCheckMode};
use crate::error::{NodeError, Result};
use crate::events::EventStream;
use crate::node::{Node, init};
use crate::orphan::{DEFAULT_POLL_INTERVAL, OrphanGuard};
use crate::runtime::NodeRuntime;
use crate::session::connect;
pub const ENV_AUTH_TOKEN: &str = "ASTRS_AUTH_TOKEN";
pub const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
#[derive(Debug, Clone, Default)]
pub struct NodeBuilder {
config: Option<Box<NodeConfig>>,
node_id: Option<NodeId>,
dataflow: Option<DataflowId>,
endpoints: Vec<String>,
auth: Option<AuthToken>,
dynamic: bool,
inputs: Vec<DataId>,
outputs: Vec<DataId>,
subscribe: Vec<DataId>,
type_check: Option<TypeCheckMode>,
zero_copy_threshold: Option<u64>,
parent_pid: Option<u32>,
orphan_guard: bool,
connect_timeout: Duration,
label: Option<String>,
}
impl NodeBuilder {
#[must_use]
pub fn new() -> Self {
Self {
orphan_guard: true,
connect_timeout: DEFAULT_CONNECT_TIMEOUT,
..Self::default()
}
}
pub fn from_env() -> Result<Self> {
let value =
std::env::var(astrs_wire::ENV_NODE_CONFIG).map_err(|_| NodeError::MissingEnv {
name: astrs_wire::ENV_NODE_CONFIG,
})?;
Self::from_env_value(&value)
}
pub fn from_env_value(value: &str) -> Result<Self> {
let config = NodeConfig::from_env_value(value)?;
Ok(Self::new().with_config(config))
}
#[must_use]
pub fn with_config(mut self, config: NodeConfig) -> Self {
self.config = Some(Box::new(config));
self
}
pub fn node_id(mut self, node_id: impl AsRef<str>) -> Result<Self> {
self.node_id = Some(NodeId::new(node_id.as_ref())?);
Ok(self)
}
#[must_use]
pub const fn dataflow(mut self, dataflow: DataflowId) -> Self {
self.dataflow = Some(dataflow);
self
}
#[must_use]
pub fn daemon(mut self, endpoint: impl Into<String>) -> Self {
self.endpoints.push(endpoint.into());
self
}
#[must_use]
pub fn auth(mut self, auth: AuthToken) -> Self {
self.auth = Some(auth);
self
}
#[must_use]
pub const fn dynamic(mut self, dynamic: bool) -> Self {
self.dynamic = dynamic;
self
}
pub fn input(mut self, input: impl AsRef<str>) -> Result<Self> {
self.inputs.push(DataId::new(input.as_ref())?);
Ok(self)
}
pub fn output(mut self, output: impl AsRef<str>) -> Result<Self> {
self.outputs.push(DataId::new(output.as_ref())?);
Ok(self)
}
pub fn subscribe(mut self, input: impl AsRef<str>) -> Result<Self> {
self.subscribe.push(DataId::new(input.as_ref())?);
Ok(self)
}
#[must_use]
pub const fn type_check(mut self, mode: TypeCheckMode) -> Self {
self.type_check = Some(mode);
self
}
#[must_use]
pub const fn zero_copy_threshold(mut self, bytes: u64) -> Self {
self.zero_copy_threshold = Some(bytes);
self
}
#[must_use]
pub const fn parent_pid(mut self, pid: u32) -> Self {
self.parent_pid = Some(pid);
self
}
#[must_use]
pub const fn orphan_guard(mut self, enabled: bool) -> Self {
self.orphan_guard = enabled;
self
}
#[must_use]
pub const fn connect_timeout(mut self, timeout: Duration) -> Self {
self.connect_timeout = timeout;
self
}
#[must_use]
pub fn label(mut self, label: impl Into<String>) -> Self {
self.label = Some(label.into());
self
}
pub fn resolved_endpoints(&self) -> Result<Vec<String>> {
if !self.endpoints.is_empty() {
return Ok(self.endpoints.clone());
}
if let Some(config) = &self.config
&& !config.endpoints.is_empty()
{
return Ok(config.endpoints.clone());
}
Ok(vec![
format!("uds://{}", env::daemon_socket_path().display()),
format!("tcp://127.0.0.1:{}", env::daemon_port()?),
])
}
pub fn resolved_auth(&self) -> Result<AuthToken> {
if let Some(auth) = &self.auth {
return Ok(auth.clone());
}
if let Some(config) = &self.config {
return Ok(config.auth.clone());
}
match std::env::var(ENV_AUTH_TOKEN) {
Ok(hex) if !hex.trim().is_empty() => {
AuthToken::parse_hex(hex.trim()).map_err(|error| NodeError::BadEnv {
name: ENV_AUTH_TOKEN,
value: "<redacted>".to_owned(),
reason: error.to_string(),
})
}
_ => Ok(AuthToken::ZERO),
}
}
pub fn handshake(&self) -> Result<NodeHandshake> {
let (dataflow, node, generation) = self.identity()?;
let handshake = if self.dynamic {
NodeHandshake::dynamic(dataflow, node)
.with_inputs(self.inputs.clone())
.with_outputs(self.outputs.clone())
} else {
NodeHandshake::new(dataflow, node, generation)
};
Ok(handshake.with_pid(std::process::id()))
}
pub fn provisional_spec(&self) -> Result<NodeSpawnSpec> {
if let Some(config) = &self.config {
return Ok(config.spec.clone());
}
let (dataflow, node, generation) = self.identity()?;
Ok(NodeSpawnSpec::new(
dataflow,
node,
generation,
NodeSource::Dynamic,
))
}
pub fn connect(self) -> Result<(Node, EventStream)> {
let runtime = NodeRuntime::acquire()?;
let handle = runtime.clone();
handle.block_on("Node::init", "NodeBuilder::connect_async", async move {
self.connect_with(runtime).await
})?
}
pub async fn connect_async(self) -> Result<(Node, EventStream)> {
let runtime = NodeRuntime::acquire()?;
self.connect_with(runtime).await
}
pub async fn connect_with(self, runtime: NodeRuntime) -> Result<(Node, EventStream)> {
let endpoints = self.resolved_endpoints()?;
let auth = self.resolved_auth()?;
let handshake = self.handshake()?;
let link =
connect::dial(&endpoints, &auth, self.label.clone(), self.connect_timeout).await?;
self.finish(link, handshake, runtime).await
}
pub async fn finish(
self,
link: connect::NodeLink,
handshake: NodeHandshake,
runtime: NodeRuntime,
) -> Result<(Node, EventStream)> {
let type_check = match self.type_check {
Some(mode) => mode,
None => TypeCheckMode::from_env()?,
};
let threshold = match self.zero_copy_threshold {
Some(threshold) => threshold,
None => match &self.config {
Some(config) => config.zero_copy_threshold,
None => env::zero_copy_threshold()?,
},
};
let broker = self
.config
.as_ref()
.and_then(|config| config.shm_broker.clone())
.map(std::path::PathBuf::from);
let registration = init::register_with(
link,
handshake,
runtime.clone(),
threshold,
self.subscribe.clone(),
broker,
)
.await?;
let parent = match self.parent_pid {
Some(pid) => Some(pid),
None => env::parent_pid()?,
};
let orphan = if self.orphan_guard {
OrphanGuard::maybe_watch(
parent,
&runtime,
std::sync::Arc::clone(®istration.shared.source),
DEFAULT_POLL_INTERVAL,
)
} else {
None
};
Ok(Node::from_registration(registration, type_check, orphan))
}
fn identity(&self) -> Result<(DataflowId, NodeId, u64)> {
if let Some(config) = &self.config {
let node = self
.node_id
.clone()
.unwrap_or_else(|| config.node().clone());
let dataflow = self.dataflow.unwrap_or_else(|| config.dataflow());
return Ok((dataflow, node, config.generation()));
}
let Some(node) = self.node_id.clone() else {
return Err(NodeError::Pattern(
"a node needs either ASTRS_NODE_CONFIG or an explicit node id".to_owned(),
));
};
Ok((
self.dataflow.unwrap_or_else(|| DataflowId::from_u128(0)),
node,
0,
))
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use astrs_wire::DaemonId;
fn config() -> NodeConfig {
let spec = NodeSpawnSpec::new(
DataflowId::from_u128(9),
NodeId::new("camera").unwrap(),
3,
NodeSource::Executable {
path: "./camera".to_owned(),
},
);
NodeConfig::new(
spec,
DaemonId::generate(None),
AuthToken::from_bytes([4; 32]),
)
.with_endpoint("uds:///tmp/astrs/daemon.sock")
.with_zero_copy_threshold(8192)
}
#[test]
fn a_configured_builder_takes_its_identity_from_the_blob() {
let builder = NodeBuilder::new().with_config(config());
let handshake = builder.handshake().unwrap();
assert_eq!(handshake.node.as_str(), "camera");
assert_eq!(handshake.generation, 3);
assert!(!handshake.dynamic);
assert_eq!(handshake.pid, Some(std::process::id()));
assert_eq!(
builder.resolved_endpoints().unwrap(),
vec!["uds:///tmp/astrs/daemon.sock"]
);
assert_eq!(
builder.resolved_auth().unwrap(),
AuthToken::from_bytes([4; 32])
);
assert_eq!(builder.provisional_spec().unwrap().generation, 3);
}
#[test]
fn a_dynamic_builder_declares_its_ports() {
let builder = NodeBuilder::new()
.node_id("probe")
.unwrap()
.dynamic(true)
.input("frames")
.unwrap()
.output("samples")
.unwrap();
let handshake = builder.handshake().unwrap();
assert!(handshake.dynamic);
assert_eq!(handshake.generation, 0);
assert!(handshake.declares_ports());
assert_eq!(handshake.inputs.len(), 1);
assert_eq!(handshake.outputs.len(), 1);
assert!(matches!(
builder.provisional_spec().unwrap().source,
NodeSource::Dynamic
));
}
#[test]
fn a_builder_with_neither_blob_nor_id_is_refused() {
let error = NodeBuilder::new().handshake().unwrap_err();
assert!(matches!(error, NodeError::Pattern(_)), "{error}");
}
#[test]
fn explicit_endpoints_win_over_the_blob() {
let builder = NodeBuilder::new()
.with_config(config())
.daemon("tcp://10.0.0.2:7408");
assert_eq!(
builder.resolved_endpoints().unwrap(),
vec!["tcp://10.0.0.2:7408"]
);
}
#[test]
fn a_bare_builder_falls_back_to_the_appendix_defaults() {
let builder = NodeBuilder::new().node_id("probe").unwrap();
let endpoints = builder.resolved_endpoints().unwrap();
assert_eq!(endpoints.len(), 2, "uds first, tcp second");
assert!(endpoints[0].starts_with("uds://"), "{endpoints:?}");
assert!(
endpoints[1].starts_with("tcp://127.0.0.1:"),
"{endpoints:?}"
);
}
#[test]
fn an_explicit_token_wins_over_everything() {
let token = AuthToken::from_bytes([7; 32]);
let builder = NodeBuilder::new().with_config(config()).auth(token.clone());
assert_eq!(builder.resolved_auth().unwrap(), token);
}
#[test]
fn a_missing_environment_blob_is_named() {
let error = NodeBuilder::from_env_value("!!!!").unwrap_err();
assert!(matches!(error, NodeError::Config(_)), "{error}");
let blob = config().to_env_value().unwrap();
let builder = NodeBuilder::from_env_value(&blob).unwrap();
assert_eq!(builder.handshake().unwrap().node.as_str(), "camera");
}
#[test]
fn builder_settings_are_recorded() {
let builder = NodeBuilder::new()
.node_id("probe")
.unwrap()
.dataflow(DataflowId::from_u128(2))
.type_check(TypeCheckMode::Error)
.zero_copy_threshold(1)
.parent_pid(42)
.orphan_guard(false)
.connect_timeout(Duration::from_millis(5))
.label("probe-1")
.subscribe("frames")
.unwrap();
assert_eq!(builder.type_check, Some(TypeCheckMode::Error));
assert_eq!(builder.zero_copy_threshold, Some(1));
assert_eq!(builder.parent_pid, Some(42));
assert!(!builder.orphan_guard);
assert_eq!(builder.connect_timeout, Duration::from_millis(5));
assert_eq!(builder.label.as_deref(), Some("probe-1"));
assert_eq!(builder.subscribe.len(), 1);
let handshake = builder.handshake().unwrap();
assert_eq!(handshake.dataflow, DataflowId::from_u128(2));
}
#[test]
fn connecting_to_nothing_reports_every_attempt() {
let error = NodeBuilder::new()
.node_id("probe")
.unwrap()
.daemon(format!(
"uds://{}",
std::env::temp_dir().join("astrs-absent.sock").display()
))
.connect_timeout(Duration::from_millis(100))
.connect()
.unwrap_err();
assert!(matches!(error, NodeError::Connect { .. }), "{error}");
}
#[test]
fn the_documented_constants_are_stable() {
assert_eq!(ENV_AUTH_TOKEN, "ASTRS_AUTH_TOKEN");
assert_eq!(DEFAULT_CONNECT_TIMEOUT, Duration::from_secs(10));
}
}