Skip to main content

astrs_cli/command/
replay.rs

1//! `astrs replay` (blueprint §14, §17), in its two forms.
2//!
3//! Every node the recording covers (or every node `--replace` names
4//! explicitly) is replaced **in place**: its `id` and its `outputs:`
5//! are untouched, only its source becomes `path: astrs-replay-node` with
6//! `args:` pointing at the recording and restricting it to that node's
7//! own outputs. Because the id and outputs never change, every sibling
8//! node's `inputs: { x: camera/frames }` still resolves — nothing about
9//! the graph's wiring is rewritten, only what actually produces it.
10//!
11//! ```text
12//!   - id: camera              - id: camera
13//!     path: ./camera            path: astrs-replay-node
14//!     outputs: [frames]  ─►     outputs: [frames]
15//!                                args: [session.arec, --mode, real-time,
16//!                                       --only, camera/frames]
17//! ```
18//!
19//! # Two forms, one rewrite
20//!
21//! ```text
22//!   astrs replay s.arec --into graph.yml   offline: print the rewritten manifest
23//!   astrs replay s.arec perception         live:    cut the running graph over
24//! ```
25//!
26//! The offline form ([`run`]) is a pure function of a file and a manifest: it
27//! prints YAML and touches nothing. The live form ([`run_live`]) does the
28//! *same rewrite* — literally the same `rewrite_node` on the same
29//! `resolve_targets` result (both private to this module) — against the
30//! expanded manifest the coordinator
31//! is already holding for a running dataflow, and then hands each rewritten
32//! node to §8/§17's dynamic-topology machinery as a
33//! [`astrs_wire::ControlRequest::ReplaceNode`].
34//!
35//! Sharing the rewrite is the point, not an economy: "what a replay node
36//! would have looked like offline" and "what the running graph is cut over
37//! to" are the same question, and a second implementation of it would be a
38//! second answer waiting to disagree.
39//!
40//! # Why `ReplaceNode` and not `AddNode`
41//!
42//! A replay is a *substitution*: last week's sensor data standing in for the
43//! sensor, on the edges the sensor already had. `AddNode` would introduce a
44//! second producer beside the live one — two nodes publishing the same port,
45//! which is not what "test a new planner against last week's data" means.
46//! `ReplaceNode` keeps the target's id and therefore its edges, which is the
47//! whole reason the offline rewrite leaves `id:` and `outputs:` alone: the
48//! two forms are the same edit expressed against a file and against a live
49//! graph.
50
51use std::collections::{BTreeMap, BTreeSet};
52use std::io::Write;
53use std::path::PathBuf;
54
55use astrs_manifest::Manifest;
56use astrs_recording::Reader;
57use astrs_wire::{ControlReply, ControlRequest, DataflowId};
58
59use crate::cli::ReplayTimingMode;
60use crate::command::client::{Client, DataflowRef, Endpoint, reply_name, runtime};
61use crate::error::CliError;
62
63/// `astrs replay` arguments, independent of `clap`.
64#[derive(Debug, Clone)]
65pub struct ReplayIntoArgs {
66    /// The `.arec` file to replay.
67    pub input: PathBuf,
68    /// The manifest file to rewrite.
69    pub into: PathBuf,
70    /// The timing mode the generated replay node(s) pace entries with.
71    pub mode: ReplayTimingMode,
72    /// The real-time speed multiplier.
73    pub speed: Option<f64>,
74    /// The fixed-rate emission frequency.
75    pub rate: Option<f64>,
76    /// Whether the generated replay node(s) loop.
77    pub r#loop: bool,
78    /// Node ids to replace; every node the recording covers, if empty.
79    pub replace: Vec<String>,
80}
81
82/// What [`run`] did.
83#[derive(Debug, Clone, PartialEq)]
84pub struct ReplayIntoReport {
85    /// The rewritten manifest.
86    pub manifest: Manifest,
87    /// [`Self::manifest`] rendered as YAML — exactly what was printed.
88    pub yaml: String,
89    /// The node ids that were actually replaced, in manifest order.
90    pub replaced: Vec<String>,
91}
92
93/// Rewrites `args.into` (parsed, validated), replacing each node in
94/// [`ReplayIntoArgs::replace`] — or, if that is empty, every node whose
95/// id matches a producer `args.input`'s footer index recorded — with an
96/// `astrs-replay-node` instance, then validates and prints the result.
97///
98/// # Errors
99///
100/// - [`CliError::Recording`] if `args.input` cannot be opened (falling
101///   back to scan recovery for a footerless file, same as `bag info`).
102/// - [`CliError::Io`] / [`CliError::Manifest`] / [`CliError::Validation`]
103///   for the target manifest, exactly as `astrs expand`/`astrs validate`
104///   report them.
105/// - [`CliError::BadArgument`] if an explicit `--replace` id names no
106///   node in the manifest, or if nothing ends up replaced at all (every
107///   `--replace` id was bad, or auto-detection matched nothing — the
108///   recording and the manifest name disjoint node ids).
109pub fn run(out: &mut dyn Write, args: &ReplayIntoArgs) -> Result<ReplayIntoReport, CliError> {
110    let (reader, _recovery) = Reader::open_or_recover(&args.input)?;
111    let recorded_nodes: BTreeSet<String> = reader
112        .index()
113        .iter()
114        .map(|entry| entry.node.as_str().to_owned())
115        .collect();
116
117    let content =
118        std::fs::read_to_string(&args.into).map_err(|error| CliError::io(&args.into, error))?;
119    let mut manifest = Manifest::from_yaml_str(&content)?;
120    manifest.validate()?;
121
122    let targets = resolve_targets(&manifest, &recorded_nodes, &args.replace)?;
123    let replay_args = fixed_replay_args(args);
124
125    let mut replaced = Vec::new();
126    for node in &mut manifest.nodes {
127        if !targets.contains(&node.id) {
128            continue;
129        }
130        rewrite_node(node, &args.input, &replay_args);
131        replaced.push(node.id.clone());
132    }
133
134    manifest.validate()?;
135    let yaml = manifest.to_yaml().map_err(CliError::Manifest)?;
136    let _ = writeln!(out, "{yaml}");
137    let _ = out.flush();
138
139    Ok(ReplayIntoReport {
140        manifest,
141        yaml,
142        replaced,
143    })
144}
145
146/// The `--mode`/`--speed`/`--rate`/`--loop` flags every generated node
147/// gets, independent of which node it is.
148fn fixed_replay_args(args: &ReplayIntoArgs) -> Vec<String> {
149    fixed_replay_args_for(args.mode, args.speed, args.rate, args.r#loop)
150}
151
152/// The node ids to replace: `replace` verbatim if it names anything, else
153/// every manifest node whose id `recorded_nodes` contains.
154///
155/// # Errors
156///
157/// [`CliError::BadArgument`] if an explicit id names no manifest node, or
158/// if the result is empty either way.
159fn resolve_targets(
160    manifest: &Manifest,
161    recorded_nodes: &BTreeSet<String>,
162    replace: &[String],
163) -> Result<BTreeSet<String>, CliError> {
164    let declared: BTreeSet<&str> = manifest.nodes.iter().map(|node| node.id.as_str()).collect();
165
166    let targets: BTreeSet<String> = if replace.is_empty() {
167        manifest
168            .nodes
169            .iter()
170            .map(|node| node.id.clone())
171            .filter(|id| recorded_nodes.contains(id))
172            .collect()
173    } else {
174        for id in replace {
175            if !declared.contains(id.as_str()) {
176                return Err(CliError::BadArgument {
177                    flag: "replace",
178                    value: id.clone(),
179                    reason: "does not name a node in the target manifest".to_owned(),
180                });
181            }
182        }
183        replace.iter().cloned().collect()
184    };
185
186    if targets.is_empty() {
187        return Err(CliError::BadArgument {
188            flag: "replace",
189            value: String::new(),
190            reason: "no node was replaced — the recording and the manifest name disjoint \
191                     node ids; pass --replace explicitly"
192                .to_owned(),
193        });
194    }
195    Ok(targets)
196}
197
198/// Rewrites one node in place: clears every source field but `path`, and
199/// builds `args:` from the fixed replay flags plus one `--only
200/// <id>/<output>` per output this node declares.
201fn rewrite_node(node: &mut astrs_manifest::Node, input: &std::path::Path, fixed_args: &[String]) {
202    node.path = Some("astrs-replay-node".to_string());
203    node.git = None;
204    node.branch = None;
205    node.tag = None;
206    node.rev = None;
207    node.module = None;
208    node.operators = None;
209    node.ros2 = None;
210    node.record = None;
211    node.build = None;
212
213    let mut args = vec![input.display().to_string()];
214    args.extend(fixed_args.iter().cloned());
215    for output in &node.outputs {
216        args.push("--only".to_string());
217        args.push(format!("{}/{output}", node.id));
218    }
219    node.args = args;
220}
221
222// ---------------------------------------------------------------------
223// The live form
224// ---------------------------------------------------------------------
225
226/// `astrs replay <file> <dataflow>` arguments — the live form.
227#[derive(Debug, Clone)]
228pub struct ReplayLiveArgs {
229    /// The `.arec` file to replay.
230    pub input: PathBuf,
231    /// The running dataflow to cut over, by id or by name.
232    pub dataflow: DataflowRef,
233    /// The timing mode the replay node(s) pace entries with.
234    pub mode: ReplayTimingMode,
235    /// The real-time speed multiplier.
236    pub speed: Option<f64>,
237    /// The fixed-rate emission frequency.
238    pub rate: Option<f64>,
239    /// Whether the replay node(s) loop.
240    pub r#loop: bool,
241    /// Node ids to replace; every node the recording *and* the running graph
242    /// both name, if empty.
243    pub replace: Vec<String>,
244    /// Let each outgoing node drain its inputs before it is stopped (§8).
245    pub drain: bool,
246    /// Emit JSON rather than a human summary.
247    pub json: bool,
248}
249
250/// What [`run_live`] did.
251#[derive(Debug, Clone, PartialEq, Eq)]
252pub struct ReplayLiveReport {
253    /// The dataflow that was cut over.
254    pub dataflow: astrs_wire::DataflowId,
255    /// The node ids replaced, in manifest order.
256    pub replaced: Vec<String>,
257}
258
259impl ReplayLiveReport {
260    /// The `--json` form.
261    #[must_use]
262    pub fn to_json(&self) -> serde_json::Value {
263        serde_json::json!({
264            "dataflow": self.dataflow.to_string(),
265            "replaced": self.replaced,
266        })
267    }
268
269    /// The human line.
270    #[must_use]
271    pub fn summary(&self) -> String {
272        format!(
273            "replaced {} node(s) in {} with replay sources: {}",
274            self.replaced.len(),
275            self.dataflow,
276            self.replaced.join(", ")
277        )
278    }
279}
280
281/// Cuts a *running* dataflow over to a recording: every node the recording
282/// covers (or every node `--replace` names) is replaced in place by an
283/// `astrs-replay-node` reading `args.input`.
284///
285/// The graph the rewrite is computed against is the coordinator's own
286/// expanded manifest (`GetManifest`, §8.5 — every `module:` already
287/// flattened), not a file on this machine: the point of the live form is that
288/// the operator need not have the manifest that started the run, and a
289/// *different* file would rewrite a graph the cluster is not running.
290///
291/// # Errors
292///
293/// - [`CliError::Recording`] if `args.input` cannot be opened (falling back
294///   to scan recovery for a footerless file, as `bag info` does).
295/// - [`CliError::NoCluster`] / [`CliError::UnknownDataflow`] if the dataflow
296///   cannot be resolved.
297/// - [`CliError::BadArgument`] if `--replace` names a node the running graph
298///   does not have, or if nothing would be replaced at all.
299/// - [`CliError::Refused`] if the coordinator rejects a replacement — the
300///   first refusal stops the cutover, so a graph is never left half replayed
301///   by a rejection the operator has not seen.
302pub fn run_live(
303    out: &mut dyn Write,
304    endpoint: &Endpoint,
305    args: &ReplayLiveArgs,
306) -> Result<ReplayLiveReport, CliError> {
307    let (reader, _recovery) = Reader::open_or_recover(&args.input)?;
308    let recorded_nodes: BTreeSet<String> = reader
309        .index()
310        .iter()
311        .map(|entry| entry.node.as_str().to_owned())
312        .collect();
313    let replay_args = fixed_replay_args_for(args.mode, args.speed, args.rate, args.r#loop);
314
315    let runtime = runtime()?;
316    let report = runtime.block_on(async {
317        let mut client = Client::connect(endpoint).await?;
318        let dataflow = client.resolve(&args.dataflow).await?;
319        let manifest = live_manifest(&mut client, dataflow).await?;
320
321        let targets = resolve_targets(&manifest, &recorded_nodes, &args.replace)?;
322        // The rewrite is computed for every target *before* any of it is
323        // sent, so a fragment that cannot be expanded fails the whole verb
324        // rather than half of a running graph.
325        let mut specs = Vec::new();
326        for node in &manifest.nodes {
327            if !targets.contains(&node.id) {
328                continue;
329            }
330            let mut node = node.clone();
331            rewrite_node(&mut node, &args.input, &replay_args);
332            specs.push((node.id.clone(), node_spec(dataflow, &node)?));
333        }
334
335        let mut replaced = Vec::new();
336        for (id, spec) in specs {
337            client
338                .request_ok(
339                    "replay",
340                    &ControlRequest::ReplaceNode {
341                        dataflow,
342                        node: Box::new(spec),
343                        drain: args.drain,
344                    },
345                )
346                .await?;
347            replaced.push(id);
348        }
349        Ok::<_, CliError>(ReplayLiveReport { dataflow, replaced })
350    })?;
351
352    if args.json {
353        let _ = writeln!(
354            out,
355            "{}",
356            serde_json::to_string_pretty(&report.to_json()).unwrap_or_else(|_| "{}".to_owned())
357        );
358    } else {
359        let _ = writeln!(out, "{}", report.summary());
360    }
361    let _ = out.flush();
362    Ok(report)
363}
364
365/// The running dataflow's own expanded manifest, from the coordinator.
366async fn live_manifest(client: &mut Client, dataflow: DataflowId) -> Result<Manifest, CliError> {
367    match client
368        .request("replay", &ControlRequest::GetManifest { dataflow })
369        .await?
370    {
371        ControlReply::Manifest { yaml, .. } => Ok(Manifest::from_yaml_str(&yaml)?),
372        other => Err(CliError::UnexpectedReply {
373            request: "replay",
374            reply: reply_name(&other),
375        }),
376    }
377}
378
379/// One rewritten manifest node, expanded into the spawn specification
380/// `ReplaceNode` carries.
381///
382/// Delegated rather than built field by field: the expansion rules (`args:`
383/// resolution, port declaration, restart defaults) live in
384/// `astrs_coordinator::expand_node`, and a second hand-rolled path into
385/// `NodeSpawnSpec` would be a second set of defaults to keep in step.
386fn node_spec(
387    dataflow: DataflowId,
388    node: &astrs_manifest::Node,
389) -> Result<astrs_wire::NodeSpawnSpec, CliError> {
390    // Generation 0: the coordinator stamps the incarnation it actually
391    // assigns when it dispatches the replacement (§12), exactly as
392    // `astrs node replace` does.
393    Ok(astrs_coordinator::expand_node(dataflow, 0, node)?)
394}
395
396/// [`fixed_replay_args`], as the live form's flags rather than
397/// [`ReplayIntoArgs`]'s.
398///
399/// The two forms take the same four pacing flags and must produce the same
400/// `args:`, so both spell them here.
401fn fixed_replay_args_for(
402    mode: ReplayTimingMode,
403    speed: Option<f64>,
404    rate: Option<f64>,
405    looping: bool,
406) -> Vec<String> {
407    let mut out = vec!["--mode".to_string(), mode.as_str().to_string()];
408    if let Some(speed) = speed {
409        out.push("--speed".to_string());
410        out.push(speed.to_string());
411    }
412    if let Some(rate) = rate {
413        out.push("--rate".to_string());
414        out.push(rate.to_string());
415    }
416    if looping {
417        out.push("--loop".to_string());
418    }
419    out
420}
421
422/// Every `node/output` pair a recording's footer index covers, grouped by
423/// node — exposed for callers (tests, `astrs bag info`-adjacent tooling)
424/// that want the same grouping this module derives internally when it
425/// resolves replacement targets.
426#[must_use]
427pub fn ports_by_node(reader: &Reader) -> BTreeMap<String, BTreeSet<String>> {
428    let mut grouped: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
429    for entry in reader.index() {
430        grouped
431            .entry(entry.node.as_str().to_owned())
432            .or_default()
433            .insert(entry.output.as_str().to_owned());
434    }
435    grouped
436}
437
438#[cfg(test)]
439mod tests {
440    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
441    use super::*;
442    use astrs_recording::{Writer, WriterOptions};
443    use astrs_time::HlcTimestamp;
444    use astrs_wire::{DataId, DataflowId, Metadata, NodeId};
445
446    fn uniq() -> u64 {
447        use std::sync::atomic::{AtomicU64, Ordering};
448        static NEXT: AtomicU64 = AtomicU64::new(1);
449        NEXT.fetch_add(1, Ordering::Relaxed)
450    }
451
452    fn temp_dir(label: &str) -> PathBuf {
453        let dir = std::env::temp_dir().join(format!(
454            "astrs-cli-replay-test-{}-{}-{label}",
455            std::process::id(),
456            uniq()
457        ));
458        std::fs::create_dir_all(&dir).unwrap();
459        dir
460    }
461
462    fn sample_recording(path: &PathBuf) {
463        let options = WriterOptions::new(DataflowId::from_u128(1), HlcTimestamp::EPOCH);
464        let mut writer = Writer::create(path, options).unwrap();
465        writer
466            .append_parts(
467                NodeId::new("camera").unwrap(),
468                DataId::new("frames").unwrap(),
469                Metadata::new(HlcTimestamp::new(1, 0)),
470                vec![1],
471            )
472            .unwrap();
473        writer.finish().unwrap();
474    }
475
476    fn base_args(input: PathBuf, into: PathBuf) -> ReplayIntoArgs {
477        ReplayIntoArgs {
478            input,
479            into,
480            mode: ReplayTimingMode::AsFastAsPossible,
481            speed: None,
482            rate: None,
483            r#loop: false,
484            replace: Vec::new(),
485        }
486    }
487
488    #[test]
489    fn replaces_the_recorded_node_in_place_and_preserves_wiring() {
490        let dir = temp_dir("basic");
491        let recording = dir.join("session.arec");
492        sample_recording(&recording);
493        let manifest_path = dir.join("graph.yaml");
494        std::fs::write(
495            &manifest_path,
496            "nodes:\n\
497             \x20 - id: camera\n\
498             \x20   path: ./camera\n\
499             \x20   outputs: [frames]\n\
500             \x20 - id: detector\n\
501             \x20   path: ./detector\n\
502             \x20   inputs:\n\
503             \x20     frames: camera/frames\n",
504        )
505        .unwrap();
506
507        let mut out = Vec::new();
508        let report = run(&mut out, &base_args(recording.clone(), manifest_path)).unwrap();
509        assert_eq!(report.replaced, vec!["camera".to_string()]);
510
511        let camera = report
512            .manifest
513            .nodes
514            .iter()
515            .find(|n| n.id == "camera")
516            .unwrap();
517        assert_eq!(camera.path.as_deref(), Some("astrs-replay-node"));
518        assert_eq!(camera.outputs, vec!["frames".to_string()]);
519        assert!(camera.args.contains(&recording.display().to_string()));
520        assert!(camera.args.iter().any(|a| a == "camera/frames"));
521
522        let detector = report
523            .manifest
524            .nodes
525            .iter()
526            .find(|n| n.id == "detector")
527            .unwrap();
528        assert_eq!(
529            detector.inputs.get("frames").map(|i| i.source.as_str()),
530            Some("camera/frames"),
531            "sibling wiring must be untouched"
532        );
533
534        // The printed YAML round-trips to the identical manifest.
535        let printed = String::from_utf8(out).unwrap();
536        let reparsed = Manifest::from_yaml_str(printed.trim_end()).unwrap();
537        assert_eq!(reparsed, report.manifest);
538        reparsed.validate().expect("must still validate");
539
540        let _ = std::fs::remove_dir_all(&dir);
541    }
542
543    #[test]
544    fn explicit_replace_overrides_auto_detection() {
545        let dir = temp_dir("explicit");
546        let recording = dir.join("session.arec");
547        sample_recording(&recording); // only "camera" is recorded
548        let manifest_path = dir.join("graph.yaml");
549        std::fs::write(
550            &manifest_path,
551            "nodes:\n\
552             \x20 - id: camera\n\
553             \x20   path: ./camera\n\
554             \x20   outputs: [frames]\n\
555             \x20 - id: other\n\
556             \x20   path: ./other\n\
557             \x20   outputs: [x]\n",
558        )
559        .unwrap();
560
561        let mut args = base_args(recording, manifest_path);
562        args.replace = vec!["other".to_string()];
563        let mut out = Vec::new();
564        let report = run(&mut out, &args).unwrap();
565        assert_eq!(report.replaced, vec!["other".to_string()]);
566        let camera = report
567            .manifest
568            .nodes
569            .iter()
570            .find(|n| n.id == "camera")
571            .unwrap();
572        assert_eq!(camera.path.as_deref(), Some("./camera"), "untouched");
573
574        let _ = std::fs::remove_dir_all(&dir);
575    }
576
577    #[test]
578    fn an_unknown_replace_id_is_rejected() {
579        let dir = temp_dir("unknown-replace");
580        let recording = dir.join("session.arec");
581        sample_recording(&recording);
582        let manifest_path = dir.join("graph.yaml");
583        std::fs::write(
584            &manifest_path,
585            "nodes:\n  - id: camera\n    path: ./camera\n    outputs: [frames]\n",
586        )
587        .unwrap();
588
589        let mut args = base_args(recording, manifest_path);
590        args.replace = vec!["ghost".to_string()];
591        let mut out = Vec::new();
592        let error = run(&mut out, &args).unwrap_err();
593        assert!(matches!(
594            error,
595            CliError::BadArgument {
596                flag: "replace",
597                ..
598            }
599        ));
600
601        let _ = std::fs::remove_dir_all(&dir);
602    }
603
604    #[test]
605    fn disjoint_node_ids_are_rejected_rather_than_a_silent_no_op() {
606        let dir = temp_dir("disjoint");
607        let recording = dir.join("session.arec");
608        sample_recording(&recording); // records "camera"
609        let manifest_path = dir.join("graph.yaml");
610        std::fs::write(
611            &manifest_path,
612            "nodes:\n  - id: unrelated\n    path: ./unrelated\n",
613        )
614        .unwrap();
615
616        let mut out = Vec::new();
617        let error = run(&mut out, &base_args(recording, manifest_path)).unwrap_err();
618        assert!(matches!(
619            error,
620            CliError::BadArgument {
621                flag: "replace",
622                ..
623            }
624        ));
625
626        let _ = std::fs::remove_dir_all(&dir);
627    }
628
629    #[test]
630    fn fixed_args_carry_mode_speed_rate_and_loop() {
631        let args = ReplayIntoArgs {
632            input: PathBuf::from("x.arec"),
633            into: PathBuf::from("g.yaml"),
634            mode: ReplayTimingMode::FixedRate,
635            speed: Some(2.0),
636            rate: Some(30.0),
637            r#loop: true,
638            replace: Vec::new(),
639        };
640        let fixed = fixed_replay_args(&args);
641        assert_eq!(
642            fixed,
643            vec![
644                "--mode".to_string(),
645                "fixed-rate".to_string(),
646                "--speed".to_string(),
647                "2".to_string(),
648                "--rate".to_string(),
649                "30".to_string(),
650                "--loop".to_string(),
651            ]
652        );
653    }
654
655    #[test]
656    fn ports_by_node_groups_the_footer_index() {
657        let dir = temp_dir("ports-by-node");
658        let recording = dir.join("session.arec");
659        let options = WriterOptions::new(DataflowId::from_u128(1), HlcTimestamp::EPOCH);
660        let mut writer = Writer::create(&recording, options).unwrap();
661        writer
662            .append_parts(
663                NodeId::new("camera").unwrap(),
664                DataId::new("frames").unwrap(),
665                Metadata::default(),
666                vec![],
667            )
668            .unwrap();
669        writer
670            .append_parts(
671                NodeId::new("camera").unwrap(),
672                DataId::new("meta").unwrap(),
673                Metadata::default(),
674                vec![],
675            )
676            .unwrap();
677        writer.finish().unwrap();
678
679        let reader = Reader::open(&recording).unwrap();
680        let grouped = ports_by_node(&reader);
681        assert_eq!(
682            grouped.get("camera").cloned(),
683            Some(BTreeSet::from(["frames".to_string(), "meta".to_string()]))
684        );
685
686        let _ = std::fs::remove_dir_all(&dir);
687    }
688
689    // -----------------------------------------------------------------
690    // The live form
691    // -----------------------------------------------------------------
692
693    fn live_args(input: PathBuf, dataflow: &str) -> ReplayLiveArgs {
694        ReplayLiveArgs {
695            input,
696            dataflow: DataflowRef::parse(dataflow),
697            mode: ReplayTimingMode::RealTime,
698            speed: None,
699            rate: None,
700            r#loop: false,
701            replace: Vec::new(),
702            drain: false,
703            json: false,
704        }
705    }
706
707    /// Port 1 on loopback: never bound by this suite, refused instantly.
708    fn dead_endpoint() -> Endpoint {
709        Endpoint::new(
710            std::net::SocketAddr::from(([127, 0, 0, 1], 1)),
711            astrs_wire::AuthToken::ZERO,
712        )
713    }
714
715    #[test]
716    fn the_live_form_reads_the_recording_before_it_dials_anything() {
717        // A `.arec` this machine cannot open is the operator's mistake, and
718        // saying so beats a connection error that blames the cluster.
719        let dir = temp_dir("live-missing-recording");
720        let error = run_live(
721            &mut Vec::new(),
722            &dead_endpoint(),
723            &live_args(dir.join("absent.arec"), "perception"),
724        )
725        .unwrap_err();
726        assert!(matches!(error, CliError::Recording(_)), "{error}");
727    }
728
729    #[test]
730    fn the_live_form_reports_a_dead_cluster_rather_than_hanging() {
731        let dir = temp_dir("live-no-cluster");
732        let input = dir.join("session.arec");
733        sample_recording(&input);
734        let error = run_live(
735            &mut Vec::new(),
736            &dead_endpoint(),
737            &live_args(input, "perception"),
738        )
739        .unwrap_err();
740        assert!(matches!(error, CliError::NoCluster { .. }), "{error}");
741    }
742
743    #[test]
744    fn both_forms_rewrite_a_node_identically() {
745        // The property the two forms are built to have: whatever `--into`
746        // would have written into a manifest is exactly what the live form
747        // hands to `ReplaceNode`. Asserted on the rewrite itself, which is
748        // the single shared step.
749        let dir = temp_dir("both-forms");
750        let input = dir.join("session.arec");
751        sample_recording(&input);
752
753        let manifest = Manifest::from_yaml_str(
754            "nodes:\n  - id: camera\n    path: ./camera\n    outputs: [frames]\n",
755        )
756        .unwrap();
757        let mut offline = manifest.nodes[0].clone();
758        let mut live = manifest.nodes[0].clone();
759
760        let into = base_args(input.clone(), dir.join("graph.yml"));
761        rewrite_node(&mut offline, &input, &fixed_replay_args(&into));
762        // Same pacing flags on both sides, which is the whole comparison:
763        // given identical flags the two forms must produce identical `args:`.
764        let mut args = live_args(input.clone(), "perception");
765        args.mode = into.mode;
766        args.speed = into.speed;
767        args.rate = into.rate;
768        args.r#loop = into.r#loop;
769        rewrite_node(
770            &mut live,
771            &input,
772            &fixed_replay_args_for(args.mode, args.speed, args.rate, args.r#loop),
773        );
774
775        assert_eq!(offline.path, live.path);
776        assert_eq!(offline.args, live.args);
777        assert_eq!(offline.outputs, live.outputs);
778        assert_eq!(offline.id, live.id);
779    }
780
781    #[test]
782    fn a_rewritten_node_expands_into_a_spawn_spec_naming_the_replay_binary() {
783        // The step the live form adds on top of the shared rewrite: the
784        // rewritten node has to survive expansion into the `NodeSpawnSpec`
785        // `ReplaceNode` carries, with its outputs (and therefore its edges)
786        // intact.
787        let dir = temp_dir("expand");
788        let input = dir.join("session.arec");
789        sample_recording(&input);
790        let manifest = Manifest::from_yaml_str(
791            "nodes:\n  - id: camera\n    path: ./camera\n    outputs: [frames]\n",
792        )
793        .unwrap();
794        let mut node = manifest.nodes[0].clone();
795        let args = live_args(input.clone(), "perception");
796        rewrite_node(
797            &mut node,
798            &input,
799            &fixed_replay_args_for(args.mode, args.speed, args.rate, args.r#loop),
800        );
801
802        let spec = node_spec(DataflowId::from_u128(1), &node).unwrap();
803        assert_eq!(spec.node.as_str(), "camera");
804        assert_eq!(
805            spec.outputs.len(),
806            1,
807            "the edges' anchor survives: {spec:?}"
808        );
809        assert!(
810            format!("{:?}", spec.source).contains("astrs-replay-node"),
811            "{:?}",
812            spec.source
813        );
814        assert!(
815            spec.args.iter().any(|arg| arg == "--only"),
816            "the replay node is restricted to this node's own outputs: {:?}",
817            spec.args
818        );
819    }
820
821    #[test]
822    fn the_live_report_names_what_it_replaced() {
823        let report = ReplayLiveReport {
824            dataflow: DataflowId::from_u128(7),
825            replaced: vec!["camera".to_owned(), "lidar".to_owned()],
826        };
827        assert!(report.summary().contains("camera, lidar"));
828        assert_eq!(report.to_json()["replaced"][1], "lidar");
829    }
830}