Skip to main content

astrs_cli/command/
node.rs

1//! `astrs node add/remove/replace/connect/disconnect` (blueprint §8, §17:
2//! dynamic topology) — closing the loop
3//! [`crate::command::stub`] used to leave as a scheduled-later verb.
4//!
5//! ```text
6//!   astrs node add <flow> node.yml       ─► AddNode{node, start}     ─► Ok
7//!   astrs node remove <flow> <id>        ─► RemoveNode{node, grace}  ─► Ok
8//!   astrs node replace <flow> <id> f.yml ─► ReplaceNode{node, drain} ─► Ok
9//!   astrs node connect <flow> <id> <in> <src> ─► AddEdge{..}         ─► Ok
10//!   astrs node disconnect <flow> <id> <in>    ─► RemoveEdge{..}      ─► Ok
11//! ```
12//!
13//! `add`/`replace` read a *single-node* manifest fragment from disk (§8.3's
14//! per-node schema, with no `nodes:` wrapper) and expand it client-side
15//! into an [`astrs_wire::NodeSpawnSpec`] via
16//! [`astrs_coordinator::expand_node_fragment`]
17//! — the coordinator itself never reads manifest text for a dynamic node
18//! (see `astrs-coordinator`'s `handlers::topology` module docs); this is
19//! the one piece of that expansion a caller has to do instead.
20//!
21//! Every verb here is a thin, uniform shape: build the typed request,
22//! [`Client::request_ok`] it, print a one-line confirmation (or the `--json`
23//! equivalent). None of the five needs to inspect a reply beyond "did the
24//! coordinator accept it" — the interesting state (did the node actually
25//! come up, is the edge actually delivering) is what `astrs status`/`astrs
26//! top`/`astrs topic echo` are for.
27
28use std::io::Write;
29use std::path::Path;
30
31use astrs_wire::{ControlRequest, DataId, InputSpec, NodeId, PortRef, QueuePolicy};
32
33use crate::cli::QueuePolicyArg;
34use crate::command::client::{Client, DataflowRef, Endpoint, runtime};
35use crate::error::CliError;
36
37/// Reads a node manifest fragment and expands it into a spawn
38/// specification for `dataflow`, at `generation`.
39///
40/// # Errors
41///
42/// [`CliError::Io`] if `path` cannot be read. As
43/// [`astrs_coordinator::expand_node_fragment`] otherwise (via
44/// [`CliError::Coordinator`]).
45fn read_node_fragment(
46    path: &Path,
47    dataflow: astrs_wire::DataflowId,
48    generation: u64,
49) -> Result<astrs_wire::NodeSpawnSpec, CliError> {
50    let text = std::fs::read_to_string(path).map_err(|source| CliError::io(path, source))?;
51    Ok(astrs_coordinator::expand_node_fragment(
52        dataflow, generation, &text,
53    )?)
54}
55
56/// Parses a user-typed node id, naming the offending flag on failure.
57fn parse_node_id(flag: &'static str, value: &str) -> Result<NodeId, CliError> {
58    NodeId::new(value).map_err(|source| CliError::BadArgument {
59        flag,
60        value: value.to_owned(),
61        reason: source.to_string(),
62    })
63}
64
65// ---------------------------------------------------------------------
66// node add
67// ---------------------------------------------------------------------
68
69/// `astrs node add` arguments.
70#[derive(Debug, Clone)]
71pub struct AddArgs {
72    /// The dataflow to add the node to.
73    pub dataflow: DataflowRef,
74    /// Path to the single-node manifest fragment.
75    pub node_manifest: std::path::PathBuf,
76    /// Spawn it immediately rather than leaving it pending.
77    pub start: bool,
78    /// Emit JSON rather than a human line.
79    pub json: bool,
80}
81
82/// Adds a node to a running dataflow.
83///
84/// # Errors
85///
86/// As reading and expanding the manifest fragment, [`Client::resolve`]
87/// and [`Client::request_ok`].
88pub fn add(out: &mut dyn Write, endpoint: &Endpoint, args: &AddArgs) -> Result<(), CliError> {
89    let runtime = runtime()?;
90    let node_id = runtime.block_on(async {
91        let mut client = Client::connect(endpoint).await?;
92        let dataflow = client.resolve(&args.dataflow).await?;
93        let spec = read_node_fragment(&args.node_manifest, dataflow, 0)?;
94        let node_id = spec.node.clone();
95        client
96            .request_ok(
97                "node add",
98                &ControlRequest::AddNode {
99                    dataflow,
100                    node: Box::new(spec),
101                    start: args.start,
102                },
103            )
104            .await?;
105        Ok::<_, CliError>(node_id)
106    })?;
107    let text = format!(
108        "{node_id} added to {}{}",
109        args.dataflow,
110        if args.start { "" } else { " (not started)" }
111    );
112    emit(
113        out,
114        args.json,
115        &text,
116        || serde_json::json!({ "ok": true, "node": node_id.as_str(), "started": args.start }),
117    );
118    Ok(())
119}
120
121// ---------------------------------------------------------------------
122// node remove
123// ---------------------------------------------------------------------
124
125/// `astrs node remove` arguments.
126#[derive(Debug, Clone)]
127pub struct RemoveArgs {
128    /// The dataflow to remove the node from.
129    pub dataflow: DataflowRef,
130    /// The node id to remove.
131    pub node_id: String,
132    /// How long the node gets to finish before it is killed.
133    pub grace: Option<f64>,
134    /// Emit JSON rather than a human line.
135    pub json: bool,
136}
137
138/// Removes a node from a running dataflow.
139///
140/// # Errors
141///
142/// As [`Client::resolve`] and [`Client::request_ok`].
143pub fn remove(out: &mut dyn Write, endpoint: &Endpoint, args: &RemoveArgs) -> Result<(), CliError> {
144    let node = parse_node_id("node-id", &args.node_id)?;
145    let grace = args.grace.map(|secs| {
146        astrs_wire::DurationMs::from_duration(std::time::Duration::from_secs_f64(secs))
147    });
148    let runtime = runtime()?;
149    runtime.block_on(async {
150        let mut client = Client::connect(endpoint).await?;
151        let dataflow = client.resolve(&args.dataflow).await?;
152        client
153            .request_ok(
154                "node remove",
155                &ControlRequest::RemoveNode {
156                    dataflow,
157                    node: node.clone(),
158                    grace,
159                },
160            )
161            .await
162    })?;
163    let text = format!("{node} removed from {}", args.dataflow);
164    emit(
165        out,
166        args.json,
167        &text,
168        || serde_json::json!({ "ok": true, "node": node.as_str() }),
169    );
170    Ok(())
171}
172
173// ---------------------------------------------------------------------
174// node replace
175// ---------------------------------------------------------------------
176
177/// `astrs node replace` arguments.
178#[derive(Debug, Clone)]
179pub struct ReplaceArgs {
180    /// The dataflow whose node should be replaced.
181    pub dataflow: DataflowRef,
182    /// The node id to replace.
183    pub node_id: String,
184    /// Path to the replacement's single-node manifest fragment.
185    pub node_manifest: std::path::PathBuf,
186    /// Let the outgoing incarnation drain first.
187    ///
188    /// Accepted, but not yet enforced by the coordinator — see
189    /// `astrs_coordinator::handlers::topology::replace_node`'s own docs.
190    pub drain: bool,
191    /// Emit JSON rather than a human line.
192    pub json: bool,
193}
194
195/// Replaces a live node with a new definition, keeping its existing
196/// edges (a fresh generation cuts over with a brief dual-run window; see
197/// `astrs-daemon`'s `dataflow::topology` module).
198///
199/// # Errors
200///
201/// As reading and expanding the manifest fragment, [`Client::resolve`]
202/// and [`Client::request_ok`].
203pub fn replace(
204    out: &mut dyn Write,
205    endpoint: &Endpoint,
206    args: &ReplaceArgs,
207) -> Result<(), CliError> {
208    let target = parse_node_id("node-id", &args.node_id)?;
209    let runtime = runtime()?;
210    runtime.block_on(async {
211        let mut client = Client::connect(endpoint).await?;
212        let dataflow = client.resolve(&args.dataflow).await?;
213        let mut spec = read_node_fragment(&args.node_manifest, dataflow, 0)?;
214        spec.node = target.clone();
215        client
216            .request_ok(
217                "node replace",
218                &ControlRequest::ReplaceNode {
219                    dataflow,
220                    node: Box::new(spec),
221                    drain: args.drain,
222                },
223            )
224            .await
225    })?;
226    let text = format!("{target} in {} replaced", args.dataflow);
227    emit(
228        out,
229        args.json,
230        &text,
231        || serde_json::json!({ "ok": true, "node": target.as_str() }),
232    );
233    Ok(())
234}
235
236// ---------------------------------------------------------------------
237// node connect / disconnect
238// ---------------------------------------------------------------------
239
240/// `astrs node connect` arguments.
241#[derive(Debug, Clone)]
242pub struct ConnectArgs {
243    /// The dataflow to edit.
244    pub dataflow: DataflowRef,
245    /// The node whose input is being connected (or rewired).
246    pub node_id: String,
247    /// The input's name.
248    pub input: String,
249    /// The producer port to read from, as `node/output`.
250    pub source: String,
251    /// How many messages to buffer, or the default (§24.2) if unset.
252    pub queue_size: Option<u32>,
253    /// What to do when the queue is full, or the default if unset.
254    pub queue_policy: Option<QueuePolicyArg>,
255    /// Emit JSON rather than a human line.
256    pub json: bool,
257}
258
259/// Adds — or, for an already-wired input, rewires — one input edge on a
260/// live node.
261///
262/// # Errors
263///
264/// [`CliError::BadArgument`] if `node_id`/`input`/`source` are not usable.
265/// As [`Client::resolve`] and [`Client::request_ok`] otherwise.
266pub fn connect(
267    out: &mut dyn Write,
268    endpoint: &Endpoint,
269    args: &ConnectArgs,
270) -> Result<(), CliError> {
271    let consumer = parse_node_id("node-id", &args.node_id)?;
272    let input_id = DataId::new(&args.input).map_err(|source| CliError::BadArgument {
273        flag: "input",
274        value: args.input.clone(),
275        reason: source.to_string(),
276    })?;
277    let source: PortRef = args.source.parse().map_err(|_| CliError::BadArgument {
278        flag: "source",
279        value: args.source.clone(),
280        reason: "expected a `node/output` port reference".to_owned(),
281    })?;
282    let mut input = InputSpec::new(input_id, source);
283    if let Some(size) = args.queue_size {
284        input.queue_size = size;
285    }
286    input.queue_policy = match args.queue_policy {
287        Some(QueuePolicyArg::Backpressure) => QueuePolicy::Backpressure,
288        Some(QueuePolicyArg::DropOldest) | None => QueuePolicy::DropOldest,
289    };
290
291    let runtime = runtime()?;
292    runtime.block_on(async {
293        let mut client = Client::connect(endpoint).await?;
294        let dataflow = client.resolve(&args.dataflow).await?;
295        client
296            .request_ok(
297                "node connect",
298                &ControlRequest::AddEdge {
299                    dataflow,
300                    consumer: consumer.clone(),
301                    input: input.clone(),
302                },
303            )
304            .await
305    })?;
306    let text = format!(
307        "{consumer}.{} in {} now reads from {}",
308        args.input, args.dataflow, input.source
309    );
310    emit(out, args.json, &text, || {
311        serde_json::json!({
312            "ok": true,
313            "node": consumer.as_str(),
314            "input": args.input,
315            "source": input.source.to_string(),
316        })
317    });
318    Ok(())
319}
320
321/// `astrs node disconnect` arguments.
322#[derive(Debug, Clone)]
323pub struct DisconnectArgs {
324    /// The dataflow to edit.
325    pub dataflow: DataflowRef,
326    /// The node whose input is being disconnected.
327    pub node_id: String,
328    /// The input's name.
329    pub input: String,
330    /// Emit JSON rather than a human line.
331    pub json: bool,
332}
333
334/// Disconnects one input edge from a live node — the consumer is told
335/// [`astrs_wire::NodeEvent::InputClosed`] with
336/// [`astrs_wire::RouteCloseReason::Disconnected`], not treated as a
337/// producer failure.
338///
339/// # Errors
340///
341/// [`CliError::BadArgument`] if `node_id`/`input` are not usable. As
342/// [`Client::resolve`] and [`Client::request_ok`] otherwise.
343pub fn disconnect(
344    out: &mut dyn Write,
345    endpoint: &Endpoint,
346    args: &DisconnectArgs,
347) -> Result<(), CliError> {
348    let consumer = parse_node_id("node-id", &args.node_id)?;
349    let input_id = DataId::new(&args.input).map_err(|source| CliError::BadArgument {
350        flag: "input",
351        value: args.input.clone(),
352        reason: source.to_string(),
353    })?;
354
355    let runtime = runtime()?;
356    runtime.block_on(async {
357        let mut client = Client::connect(endpoint).await?;
358        let dataflow = client.resolve(&args.dataflow).await?;
359        client
360            .request_ok(
361                "node disconnect",
362                &ControlRequest::RemoveEdge {
363                    dataflow,
364                    consumer: consumer.clone(),
365                    input: input_id.clone(),
366                },
367            )
368            .await
369    })?;
370    let text = format!(
371        "{consumer}.{} in {} disconnected",
372        args.input, args.dataflow
373    );
374    emit(
375        out,
376        args.json,
377        &text,
378        || serde_json::json!({ "ok": true, "node": consumer.as_str(), "input": args.input }),
379    );
380    Ok(())
381}
382
383/// Writes either the human line or the JSON object — this module's own
384/// copy of `command::lifecycle`'s private helper of the same shape (kept
385/// local rather than made `pub(crate)` there, to leave that module's own
386/// concurrent edits alone).
387fn emit(out: &mut dyn Write, json: bool, text: &str, value: impl FnOnce() -> serde_json::Value) {
388    if json {
389        let _ = writeln!(out, "{}", value());
390    } else {
391        let _ = writeln!(out, "{text}");
392    }
393    let _ = out.flush();
394}
395
396#[cfg(test)]
397mod tests {
398    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
399
400    use super::*;
401
402    fn scratch(name: &str) -> std::path::PathBuf {
403        let dir =
404            std::env::temp_dir().join(format!("astrs-cli-node-{}-{name}", std::process::id()));
405        let _ = std::fs::create_dir_all(&dir);
406        dir
407    }
408
409    fn write_fragment(dir: &Path, name: &str, yaml: &str) -> std::path::PathBuf {
410        let path = dir.join(name);
411        std::fs::write(&path, yaml).unwrap();
412        path
413    }
414
415    fn dead_endpoint() -> Endpoint {
416        // Port 1 on loopback: privileged, never bound in this test suite,
417        // refused immediately rather than timing out — every verb below
418        // only needs to prove it reaches the network layer with the right
419        // request shape, not that a coordinator answers.
420        Endpoint::new(
421            std::net::SocketAddr::from(([127, 0, 0, 1], 1)),
422            astrs_wire::AuthToken::ZERO,
423        )
424    }
425
426    #[test]
427    fn read_node_fragment_expands_a_bare_node_yaml() {
428        let dir = scratch("fragment");
429        let path = write_fragment(
430            &dir,
431            "extra.yml",
432            "id: extra\npath: ./extra\noutputs: [out]\n",
433        );
434        let spec = read_node_fragment(&path, astrs_wire::DataflowId::generate(), 0).unwrap();
435        assert_eq!(spec.node.as_str(), "extra");
436        assert_eq!(spec.outputs.len(), 1);
437    }
438
439    #[test]
440    fn read_node_fragment_reports_a_missing_file() {
441        let err = read_node_fragment(
442            Path::new("/does/not/exist/node.yml"),
443            astrs_wire::DataflowId::generate(),
444            0,
445        )
446        .unwrap_err();
447        assert!(matches!(err, CliError::Io { .. }));
448    }
449
450    #[test]
451    fn read_node_fragment_reports_a_malformed_fragment() {
452        let dir = scratch("bad-fragment");
453        let path = write_fragment(&dir, "bad.yml", "not: [valid");
454        let err = read_node_fragment(&path, astrs_wire::DataflowId::generate(), 0).unwrap_err();
455        assert!(matches!(err, CliError::Coordinator(_)));
456    }
457
458    #[test]
459    fn parse_node_id_names_the_offending_flag() {
460        let err = parse_node_id("node-id", "not a legal id!").unwrap_err();
461        match err {
462            CliError::BadArgument { flag, value, .. } => {
463                assert_eq!(flag, "node-id");
464                assert_eq!(value, "not a legal id!");
465            }
466            other => panic!("unexpected {other:?}"),
467        }
468    }
469
470    #[test]
471    fn add_against_no_cluster_reports_no_cluster_not_a_panic() {
472        let dir = scratch("add-no-cluster");
473        let path = write_fragment(&dir, "extra.yml", "id: extra\npath: ./extra\n");
474        let mut out = Vec::new();
475        let err = add(
476            &mut out,
477            &dead_endpoint(),
478            &AddArgs {
479                dataflow: DataflowRef::parse("flow"),
480                node_manifest: path,
481                start: true,
482                json: false,
483            },
484        )
485        .unwrap_err();
486        assert!(matches!(
487            err,
488            CliError::NoCluster { .. } | CliError::Transport(_)
489        ));
490    }
491
492    #[test]
493    fn remove_rejects_a_malformed_node_id_before_dialling_anything() {
494        let mut out = Vec::new();
495        let err = remove(
496            &mut out,
497            &dead_endpoint(),
498            &RemoveArgs {
499                dataflow: DataflowRef::parse("flow"),
500                node_id: "not a legal id!".to_owned(),
501                grace: None,
502                json: false,
503            },
504        )
505        .unwrap_err();
506        assert!(matches!(err, CliError::BadArgument { .. }));
507        assert!(out.is_empty(), "a rejected argument must print nothing");
508    }
509
510    #[test]
511    fn connect_rejects_a_malformed_source_before_dialling_anything() {
512        let mut out = Vec::new();
513        let err = connect(
514            &mut out,
515            &dead_endpoint(),
516            &ConnectArgs {
517                dataflow: DataflowRef::parse("flow"),
518                node_id: "detector".to_owned(),
519                input: "frames".to_owned(),
520                source: "not-a-port-ref".to_owned(),
521                queue_size: None,
522                queue_policy: None,
523                json: false,
524            },
525        )
526        .unwrap_err();
527        assert!(matches!(err, CliError::BadArgument { flag: "source", .. }));
528    }
529
530    #[test]
531    fn disconnect_rejects_a_malformed_input_before_dialling_anything() {
532        let mut out = Vec::new();
533        let err = disconnect(
534            &mut out,
535            &dead_endpoint(),
536            &DisconnectArgs {
537                dataflow: DataflowRef::parse("flow"),
538                node_id: "detector".to_owned(),
539                input: "not a legal id!".to_owned(),
540                json: false,
541            },
542        )
543        .unwrap_err();
544        assert!(matches!(err, CliError::BadArgument { flag: "input", .. }));
545    }
546}