Skip to main content

astrs_record_node/
lib.rs

1//! The AstRS recorder node.
2//!
3//! A normal graph node (also reachable through `record:` manifest sugar
4//! and `astrs record start`) that subscribes to the selected outputs and
5//! streams them into an `.arec` session through `astrs-recording` —
6//! HLC-ordered, zstd-framed and seekable (blueprint §14).
7//!
8//! # Convention-agnostic by design
9//!
10//! This binary is spawned two different ways, and each names this node's
11//! own inputs differently:
12//!
13//! - `record:` manifest sugar lowers to inputs named `_record_0`,
14//!   `_record_1`, … (`astrs_manifest::Node::record_sugar_inputs`).
15//! - `astrs record start`'s dynamic-node path names them `in0`, `in1`, …
16//!   (the coordinator's own synthesis).
17//!
18//! [`record`] never looks at its own input names at all. For every
19//! [`Event::Input`], [`Node::input_source`] answers "which producer port
20//! did this actually come from" — a property of the wiring, not of the
21//! message — and that answer is what becomes the entry's `node`/`output`
22//! fields. The same binary therefore serves both spawn paths (and any
23//! future one) without caring which it was.
24//!
25//! # Usage
26//!
27//! ```text
28//! astrs-record-node <output.arec> [--rotate-bytes N] [--rotate-seconds N]
29//! ```
30//!
31//! The daemon supplies `<output.arec>` as this process's first argument
32//! (see `astrs-daemon`'s `command_for`); `--rotate-*` are not set by
33//! either spawn path today, but are here for a caller (a future manifest
34//! field, direct invocation) that wants bounded file sizes.
35
36use std::path::PathBuf;
37use std::time::Duration;
38
39use astrs_node_api::{Event, EventStream, Node, NodeError};
40use astrs_recording::{RecordingError, RotationPolicy, Writer, WriterOptions};
41use astrs_wire::{DataId, NodeId, PortRef};
42use clap::Parser;
43
44/// `astrs-record-node` command-line arguments.
45#[derive(Debug, Clone, Parser)]
46#[command(
47    name = "astrs-record-node",
48    about = "Writes a dataflow's inputs into an .arec recording (blueprint §14)."
49)]
50pub struct RecordArgs {
51    /// The `.arec` file to write (numbered segments if rotation is set —
52    /// see [`astrs_recording::Writer`]).
53    pub output: PathBuf,
54    /// Rotate to a new file once the current one would exceed this many
55    /// bytes.
56    #[arg(long = "rotate-bytes")]
57    pub rotate_bytes: Option<u64>,
58    /// Rotate to a new file once the current one has been open this many
59    /// seconds.
60    #[arg(long = "rotate-seconds")]
61    pub rotate_seconds: Option<u64>,
62}
63
64impl RecordArgs {
65    /// Arguments for `output`, with no rotation — the common case for a
66    /// direct caller (tests, an embedder) that does not need `clap`.
67    #[must_use]
68    pub fn new(output: impl Into<PathBuf>) -> Self {
69        Self {
70            output: output.into(),
71            rotate_bytes: None,
72            rotate_seconds: None,
73        }
74    }
75
76    /// Sets the byte-count rotation bound.
77    #[must_use]
78    pub const fn with_rotate_bytes(mut self, bytes: u64) -> Self {
79        self.rotate_bytes = Some(bytes);
80        self
81    }
82
83    /// Sets the wall-clock rotation bound.
84    #[must_use]
85    pub const fn with_rotate_seconds(mut self, seconds: u64) -> Self {
86        self.rotate_seconds = Some(seconds);
87        self
88    }
89
90    /// This session's [`RotationPolicy`], derived from the `--rotate-*`
91    /// flags.
92    #[must_use]
93    pub fn rotation_policy(&self) -> RotationPolicy {
94        RotationPolicy {
95            max_bytes: self.rotate_bytes,
96            max_duration: self.rotate_seconds.map(Duration::from_secs),
97        }
98    }
99}
100
101/// Errors `astrs-record-node` can report.
102#[derive(Debug, thiserror::Error)]
103#[non_exhaustive]
104pub enum RecordNodeError {
105    /// Joining the dataflow failed.
106    #[error("node initialization failed: {0}")]
107    Node(#[from] NodeError),
108    /// Writing the `.arec` session failed.
109    #[error(".arec write failed: {0}")]
110    Recording(#[from] RecordingError),
111}
112
113/// Connects as an ordinary node (§9.1's [`Node::init_from_env`]) and
114/// records every input until told to stop.
115///
116/// # Errors
117///
118/// [`RecordNodeError::Node`] if the daemon handshake fails, or
119/// [`RecordNodeError::Recording`] if the `.arec` file cannot be created
120/// or written.
121pub fn run(args: &RecordArgs) -> Result<(), RecordNodeError> {
122    let (mut node, mut events) = Node::init_from_env()?;
123    record(&mut node, &mut events, args)
124}
125
126/// The recording loop itself, parameterized over an already-connected
127/// node — the seam [`astrs_node_api::testing::MockDaemon`]-driven tests
128/// use to exercise this without a real daemon or a real file-descriptor
129/// handshake.
130///
131/// Every [`Event::Input`] is appended as one `.arec` entry, its `node`
132/// and `output` taken from [`Node::input_source`] rather than from this
133/// node's own input id (see the module docs). The loop ends — and the
134/// file is finalized with its footer and trailer — on [`Event::Stop`] or
135/// [`Event::AllInputsClosed`], or when the event stream itself ends
136/// (`recv` returning [`None`], e.g. the daemon connection closing).
137/// Every other event is ignored: a recorder has nothing useful to do
138/// with a parameter update or a peer's restart.
139///
140/// # Errors
141///
142/// [`RecordNodeError::Recording`] if the file cannot be created or a
143/// write fails. A write failure partway through still leaves every
144/// entry appended before it durable — see [`astrs_recording::Writer`]'s
145/// own crash-tolerance docs — so this is never a total loss.
146pub fn record(
147    node: &mut Node,
148    events: &mut EventStream,
149    args: &RecordArgs,
150) -> Result<(), RecordNodeError> {
151    let options = WriterOptions::new(node.dataflow_id(), node.hlc_now())
152        .with_rotation(args.rotation_policy());
153    let mut writer = Writer::create(&args.output, options)?;
154
155    while let Some(event) = events.recv() {
156        match event {
157            Event::Input { id, meta, data } => {
158                let (source_node, source_output) = source_of(node, &id);
159                writer.append_parts(source_node, source_output, meta, data.to_vec())?;
160            }
161            Event::Stop(_) | Event::AllInputsClosed => break,
162            _ => {}
163        }
164    }
165
166    writer.finish()?;
167    Ok(())
168}
169
170/// The producer `(node, output)` behind one of this node's inputs.
171///
172/// Resolves through [`Node::input_source`] unconditionally — see the
173/// module docs for why. The fallback (this node's own input id, doubling
174/// as both halves) is defensive only: every input the daemon actually
175/// delivers an [`Event::Input`] for has a declared source in this node's
176/// [`astrs_wire::NodeSpawnSpec`], so it should be unreachable in
177/// practice.
178fn source_of(node: &Node, input: &DataId) -> (NodeId, DataId) {
179    node.input_source(input.as_str())
180        .map(PortRef::into_parts)
181        .unwrap_or_else(|| (NodeId::sanitized(input.as_str()), input.clone()))
182}
183
184#[cfg(test)]
185mod tests {
186    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
187    use super::*;
188    use astrs_node_api::testing::MockDaemon;
189    use astrs_recording::Reader;
190    use astrs_time::HlcTimestamp;
191    use astrs_wire::{InputSpec, Metadata, NodeSource, NodeSpawnSpec, StopCause};
192    use std::path::PathBuf;
193
194    fn uniq() -> u64 {
195        use std::sync::atomic::{AtomicU64, Ordering};
196        static NEXT: AtomicU64 = AtomicU64::new(1);
197        NEXT.fetch_add(1, Ordering::Relaxed)
198    }
199
200    fn temp_path(label: &str) -> PathBuf {
201        std::env::temp_dir().join(format!(
202            "astrs-record-node-test-{}-{}-{label}.arec",
203            std::process::id(),
204            uniq()
205        ))
206    }
207
208    /// A recorder node spec with one input per `(input_name, source_node,
209    /// source_output)` triple, mirroring the shape either spawn path
210    /// (`record:` sugar's `_record_<i>` or `astrs record start`'s
211    /// `in<i>`) actually builds.
212    fn recorder_spec(daemon: &MockDaemon, inputs: &[(&str, &str, &str)]) -> NodeSpawnSpec {
213        let mut spec = NodeSpawnSpec::new(
214            daemon.dataflow(),
215            NodeId::new("recorder").unwrap(),
216            0,
217            NodeSource::Dynamic,
218        );
219        for (name, node, output) in inputs {
220            spec = spec.with_input(InputSpec::new(
221                DataId::new(*name).unwrap(),
222                PortRef::from_parts(node, output).unwrap(),
223            ));
224        }
225        spec
226    }
227
228    /// Runs [`record`] on a background thread, since it blocks until
229    /// `Stop`/`AllInputsClosed`.
230    ///
231    /// A test needs this rather than calling `record` inline because
232    /// `EventStream`'s control lane deliberately jumps ahead of already
233    /// -queued data (§11.3: "control... delivered before any data") —
234    /// sending every input and then `Stop` back-to-back, *before*
235    /// anything has started draining the stream, would let `Stop` be
236    /// served first and the recorder would capture nothing. Running the
237    /// loop concurrently and waiting (via [`wait_for_recovered_count`])
238    /// for it to have actually written what was sent so far is what a
239    /// real recorder's continuously-draining loop gets for free.
240    fn spawn_record(
241        mut node: Node,
242        mut events: EventStream,
243        args: RecordArgs,
244    ) -> std::thread::JoinHandle<Result<(), RecordNodeError>> {
245        std::thread::spawn(move || record(&mut node, &mut events, &args))
246    }
247
248    /// Polls (never sleeping longer than a few milliseconds at a time,
249    /// bounded by `timeout`) an in-progress recording's scan-recoverable
250    /// entry count until it reaches `expected`.
251    ///
252    /// Safe to call while a [`Writer`] elsewhere is still appending to
253    /// the same path: every [`Writer::append`] flushes durably before
254    /// returning, and [`astrs_recording::recover::scan`] tolerates
255    /// (indeed, exists for) a file with no footer yet.
256    fn wait_for_recovered_count(
257        path: &std::path::Path,
258        expected: usize,
259        timeout: Duration,
260    ) -> usize {
261        let deadline = std::time::Instant::now() + timeout;
262        loop {
263            let count = astrs_recording::recover::scan(path)
264                .map(|report| report.index.len())
265                .unwrap_or(0);
266            if count >= expected || std::time::Instant::now() >= deadline {
267                return count;
268            }
269            std::thread::sleep(Duration::from_millis(5));
270        }
271    }
272
273    #[test]
274    fn records_inputs_named_however_the_spawn_path_named_them() {
275        let daemon = MockDaemon::start().unwrap();
276        let spec = recorder_spec(
277            &daemon,
278            &[
279                ("_record_0", "camera", "frames"),
280                ("in1", "detector", "boxes"),
281            ],
282        );
283        let recorder_id = NodeId::new("recorder").unwrap();
284        let (node, events) = daemon.connect_node(spec).unwrap();
285
286        let path = temp_path("basic");
287        let handle = spawn_record(node, events, RecordArgs::new(&path));
288
289        daemon
290            .send_input(
291                &recorder_id,
292                &DataId::new("_record_0").unwrap(),
293                Metadata::new(HlcTimestamp::new(10, 0)),
294                vec![1, 2, 3],
295            )
296            .unwrap();
297        daemon
298            .send_input(
299                &recorder_id,
300                &DataId::new("in1").unwrap(),
301                Metadata::new(HlcTimestamp::new(20, 0)),
302                vec![4, 5],
303            )
304            .unwrap();
305        assert_eq!(
306            wait_for_recovered_count(&path, 2, Duration::from_secs(5)),
307            2,
308            "both inputs must be durable before Stop is allowed to end the loop"
309        );
310        daemon.stop(&recorder_id, StopCause::Requested).unwrap();
311        handle.join().unwrap().unwrap();
312
313        let mut reader = Reader::open(&path).unwrap();
314        assert_eq!(reader.header().dataflow, daemon.dataflow());
315        let entries: Vec<_> = reader.iter_all().collect::<Result<Vec<_>, _>>().unwrap();
316        assert_eq!(entries.len(), 2);
317        assert_eq!(entries[0].node.as_str(), "camera");
318        assert_eq!(entries[0].output.as_str(), "frames");
319        assert_eq!(entries[0].payload, vec![1, 2, 3]);
320        assert_eq!(entries[1].node.as_str(), "detector");
321        assert_eq!(entries[1].output.as_str(), "boxes");
322        assert_eq!(entries[1].payload, vec![4, 5]);
323
324        let _ = std::fs::remove_file(&path);
325    }
326
327    #[test]
328    fn all_inputs_closed_also_finalizes_the_file() {
329        let daemon = MockDaemon::start().unwrap();
330        let spec = recorder_spec(&daemon, &[("_record_0", "camera", "frames")]);
331        let recorder_id = NodeId::new("recorder").unwrap();
332        let (node, events) = daemon.connect_node(spec).unwrap();
333
334        let path = temp_path("all-inputs-closed");
335        let handle = spawn_record(node, events, RecordArgs::new(&path));
336
337        daemon
338            .send_input(
339                &recorder_id,
340                &DataId::new("_record_0").unwrap(),
341                Metadata::new(HlcTimestamp::new(1, 0)),
342                vec![9],
343            )
344            .unwrap();
345        assert_eq!(
346            wait_for_recovered_count(&path, 1, Duration::from_secs(5)),
347            1
348        );
349        daemon
350            .send_event(&recorder_id, astrs_wire::NodeEvent::AllInputsClosed)
351            .unwrap();
352        handle.join().unwrap().unwrap();
353
354        // A finalized file has a trailer, so a plain `open` (no recovery
355        // fallback) must succeed.
356        let reader = Reader::open(&path).unwrap();
357        assert_eq!(reader.len(), 1);
358        let _ = std::fs::remove_file(&path);
359    }
360
361    #[test]
362    fn an_empty_recording_still_produces_a_valid_finalized_file() {
363        let daemon = MockDaemon::start().unwrap();
364        let spec = recorder_spec(&daemon, &[]);
365        let recorder_id = NodeId::new("recorder").unwrap();
366        let (mut node, mut events) = daemon.connect_node(spec).unwrap();
367        daemon.stop(&recorder_id, StopCause::Requested).unwrap();
368
369        let path = temp_path("empty");
370        record(&mut node, &mut events, &RecordArgs::new(&path)).unwrap();
371
372        let reader = Reader::open(&path).unwrap();
373        assert!(reader.is_empty());
374        let _ = std::fs::remove_file(&path);
375    }
376
377    #[test]
378    fn rotation_flags_produce_numbered_segments() {
379        let daemon = MockDaemon::start().unwrap();
380        let spec = recorder_spec(&daemon, &[("_record_0", "camera", "frames")]);
381        let recorder_id = NodeId::new("recorder").unwrap();
382        let (node, events) = daemon.connect_node(spec).unwrap();
383
384        let path = temp_path("rotate");
385        let args = RecordArgs::new(&path).with_rotate_bytes(64);
386        let handle = spawn_record(node, events, args);
387
388        for seq in 0..20u8 {
389            daemon
390                .send_input(
391                    &recorder_id,
392                    &DataId::new("_record_0").unwrap(),
393                    Metadata::new(HlcTimestamp::new(u64::from(seq) + 1, 0)),
394                    vec![seq; 8],
395                )
396                .unwrap();
397        }
398        // Rotation moves entries into numbered segments the base path
399        // itself never receives, so wait on the first segment rather
400        // than the (never-written-to, under rotation) base path.
401        let first_segment = path.with_file_name(format!(
402            "{}-0001.{}",
403            path.file_stem().unwrap().to_string_lossy(),
404            path.extension().unwrap().to_string_lossy()
405        ));
406        assert!(
407            wait_for_recovered_count(&first_segment, 1, Duration::from_secs(5)) >= 1,
408            "the first segment must receive at least one entry before Stop"
409        );
410        daemon.stop(&recorder_id, StopCause::Requested).unwrap();
411        handle.join().unwrap().unwrap();
412
413        // The first numbered segment must exist and be finalized.
414        assert!(first_segment.exists());
415        let reader = Reader::open(&first_segment).unwrap();
416        assert!(!reader.is_empty());
417
418        // Clean up every segment this test produced.
419        for sequence in 1..=10u32 {
420            let segment = path.with_file_name(format!(
421                "{}-{sequence:04}.{}",
422                path.file_stem().unwrap().to_string_lossy(),
423                path.extension().unwrap().to_string_lossy()
424            ));
425            if segment.exists() {
426                let _ = std::fs::remove_file(&segment);
427            }
428        }
429    }
430
431    #[test]
432    fn record_args_new_defaults_to_no_rotation() {
433        let args = RecordArgs::new(std::env::temp_dir().join("x.arec"));
434        assert!(args.rotate_bytes.is_none());
435        assert!(args.rotate_seconds.is_none());
436        assert!(!args.rotation_policy().is_enabled());
437    }
438
439    #[test]
440    fn record_args_builders_set_the_expected_fields() {
441        let args = RecordArgs::new(std::env::temp_dir().join("x.arec"))
442            .with_rotate_bytes(100)
443            .with_rotate_seconds(5);
444        assert_eq!(args.rotate_bytes, Some(100));
445        assert_eq!(args.rotate_seconds, Some(5));
446        assert!(args.rotation_policy().is_enabled());
447    }
448
449    #[test]
450    fn cli_parsing_accepts_the_positional_output_and_rotate_flags() {
451        let args = RecordArgs::try_parse_from([
452            "astrs-record-node",
453            "out.arec",
454            "--rotate-bytes",
455            "1024",
456            "--rotate-seconds",
457            "60",
458        ])
459        .unwrap();
460        assert_eq!(args.output, PathBuf::from("out.arec"));
461        assert_eq!(args.rotate_bytes, Some(1024));
462        assert_eq!(args.rotate_seconds, Some(60));
463    }
464}