Skip to main content

astrs_cli/command/
bag.rs

1//! `astrs bag info` and `astrs bag convert` (blueprint §10.6, §14, §17).
2//!
3//! `info` reads whichever of the three formats this build understands
4//! (`.arec` via `astrs-recording`'s own footer index, `.db3`/`.mcap` via
5//! `astrs-rosbag`) the input's extension names —
6//! [`astrs_rosbag::convert::detect_format`] is the single place that
7//! sniffing happens, so this module and `astrs_rosbag::convert::convert_bag`
8//! never disagree about what a given path *is*. `convert` bridges between
9//! them via [`astrs_rosbag::convert::convert_bag`] directly.
10
11use std::collections::BTreeMap;
12use std::io::Write;
13use std::path::{Path, PathBuf};
14
15use astrs_recording::{Reader, RecoveryReport, Stats};
16use astrs_rosbag::convert::{BagFormat, ConversionReport, convert_bag, detect_format};
17use astrs_rosbag::db3::Reader as Db3Reader;
18use astrs_rosbag::mcap::Reader as McapReader;
19
20use crate::error::CliError;
21
22/// `astrs bag info` arguments.
23#[derive(Debug, Clone)]
24pub struct InfoArgs {
25    /// The bag file to inspect — `.arec`, `.db3`, or `.mcap`.
26    pub input: PathBuf,
27    /// Emit JSON rather than a human-readable summary.
28    pub json: bool,
29}
30
31/// One topic/channel's summary within a `.db3`/`.mcap` [`BagSummary`].
32#[derive(Debug, Clone, PartialEq, Eq)]
33pub struct TopicInfo {
34    /// The topic name (`.db3`) or channel topic (`.mcap`).
35    pub name: String,
36    /// The message type, or empty when unknown (see
37    /// [`astrs_rosbag::TopicRecord::type`]'s own docs on when that
38    /// happens).
39    pub r#type: String,
40    /// `.db3`'s `serialization_format` column / `.mcap`'s
41    /// `message_encoding` field.
42    pub serialization_format: String,
43    /// How many messages this topic carries.
44    pub message_count: u64,
45}
46
47/// A `.db3`/`.mcap` file's summary: every topic/channel plus the total
48/// message count — what [`crate::cli::BagInfoArgs`]'s own doc comment
49/// promises ("topics, types, message counts").
50#[derive(Debug, Clone, PartialEq, Eq)]
51pub struct BagSummary {
52    /// Which of the two formats `input` was.
53    pub format: BagFormat,
54    /// Every topic/channel, in the source format's own order.
55    pub topics: Vec<TopicInfo>,
56    /// The total message count across every topic.
57    pub message_count: u64,
58    /// Non-fatal notes the underlying reader accumulated (an unusable
59    /// `metadata.yaml` and its in-database fallback both failing, a
60    /// summary section that could not be used, and similar).
61    pub warnings: Vec<String>,
62}
63
64/// What [`info`] found, one variant per format family — `.arec`'s own
65/// footer-index [`Stats`] are a different shape than a `.db3`/`.mcap`
66/// topic table, so this is not forced into one struct.
67#[derive(Debug, Clone)]
68pub enum InfoReport {
69    /// `.arec` statistics, from [`astrs_recording::Stats::of`].
70    Recording {
71        /// The computed statistics.
72        stats: Stats,
73        /// Whether [`Reader::open`]'s trailer was missing or unusable and
74        /// a full scan (`astrs-recording::recover`) was needed instead.
75        recovered: bool,
76    },
77    /// A `.db3`/`.mcap` topic/message summary.
78    Bag(BagSummary),
79}
80
81/// Prints a bag's summary: for `.arec`, dataflow id, entry count, byte
82/// totals, the recorded time range, and a per-port breakdown (falling
83/// back to scan recovery rather than refusing a file still being
84/// written, exactly as before); for `.db3`/`.mcap`, every topic's type,
85/// serialization format and message count.
86///
87/// # Errors
88///
89/// [`CliError::Io`] if the file cannot be opened at all,
90/// [`CliError::Recording`] if an `.arec` cannot be made sense of even by
91/// scanning, or [`CliError::Rosbag`] if a `.db3`/`.mcap` cannot be opened
92/// or read, or if `input`'s extension names no format this build
93/// understands.
94pub fn info(out: &mut dyn Write, args: &InfoArgs) -> Result<InfoReport, CliError> {
95    let format = detect_format(&args.input)?;
96    match format {
97        BagFormat::Arec => info_recording(out, args),
98        BagFormat::Db3 => info_bag(out, args, BagFormat::Db3, info_db3(&args.input)?),
99        BagFormat::Mcap => info_bag(out, args, BagFormat::Mcap, info_mcap(&args.input)?),
100        // `BagFormat` is `#[non_exhaustive]`: a future astrs-rosbag release
101        // adding a fourth format compiles here (no silent match-arm gap)
102        // but needs an explicit `bag info` handler above before this CLI
103        // build can read one — an honest "not yet", not a panic.
104        _ => Err(CliError::BadArgument {
105            flag: "input",
106            value: args.input.display().to_string(),
107            reason: format!(
108                "astrs-rosbag recognizes `.{}` but this build's `bag info` has no handler for \
109                 it yet",
110                format.extension()
111            ),
112        }),
113    }
114}
115
116fn info_recording(out: &mut dyn Write, args: &InfoArgs) -> Result<InfoReport, CliError> {
117    let file_size = std::fs::metadata(&args.input)
118        .map_err(|error| CliError::io(&args.input, error))?
119        .len();
120    let (reader, report) = Reader::open_or_recover(&args.input)?;
121    let stats = Stats::of(&reader, file_size);
122    let recovered = report.was_recovered();
123
124    if args.json {
125        emit_recording_json(out, &args.input, &stats, &report);
126    } else {
127        emit_recording_human(out, &args.input, &stats, recovered);
128    }
129
130    Ok(InfoReport::Recording { stats, recovered })
131}
132
133fn info_bag(
134    out: &mut dyn Write,
135    args: &InfoArgs,
136    format: BagFormat,
137    (topics, message_count, warnings): (Vec<TopicInfo>, u64, Vec<String>),
138) -> Result<InfoReport, CliError> {
139    let summary = BagSummary {
140        format,
141        topics,
142        message_count,
143        warnings,
144    };
145    if args.json {
146        emit_bag_json(out, &args.input, &summary);
147    } else {
148        emit_bag_human(out, &args.input, &summary);
149    }
150    Ok(InfoReport::Bag(summary))
151}
152
153/// Opens a `.db3` and returns its topic summary — a single streaming pass
154/// over `messages` tallies each topic's count (bounded memory, mirroring
155/// [`Db3Reader::iter_messages`]'s own batching), since the schema carries
156/// no per-topic count directly.
157///
158/// # Errors
159///
160/// [`CliError::Rosbag`] if the file cannot be opened or read.
161fn info_db3(input: &Path) -> Result<(Vec<TopicInfo>, u64, Vec<String>), CliError> {
162    let reader = Db3Reader::open(input)?;
163    let mut counts: BTreeMap<i64, u64> = BTreeMap::new();
164    let mut total = 0u64;
165    for message in reader.iter_messages() {
166        let message = message?;
167        *counts.entry(message.topic_id).or_insert(0) += 1;
168        total += 1;
169    }
170    let topics = reader
171        .topics()
172        .iter()
173        .map(|(id, record)| TopicInfo {
174            name: record.topic.clone(),
175            r#type: record.r#type.clone(),
176            serialization_format: record.serialization_format.clone(),
177            message_count: counts.get(id).copied().unwrap_or(0),
178        })
179        .collect();
180    Ok((topics, total, reader.warnings().to_vec()))
181}
182
183/// Opens an `.mcap` and returns its channel summary. Per-channel counts
184/// come from the summary section's `Statistics.channel_message_counts`
185/// when the file is indexed and populated it (no message walk needed);
186/// otherwise falls back to draining [`McapReader::iter_messages`] once to
187/// tally them, the same two-pass shape
188/// [`astrs_rosbag::convert::mcap_to_arec::mcap_to_arec`] uses and for the
189/// same reason (an unindexed file's channel table itself is only
190/// complete after a full walk).
191///
192/// # Errors
193///
194/// [`CliError::Rosbag`] if the file cannot be opened or read.
195fn info_mcap(input: &Path) -> Result<(Vec<TopicInfo>, u64, Vec<String>), CliError> {
196    let mut reader = McapReader::open(input)?;
197    let counts: BTreeMap<u16, u64> = match reader
198        .statistics()
199        .filter(|stats| !stats.channel_message_counts.is_empty())
200    {
201        Some(stats) => stats.channel_message_counts.clone(),
202        None => {
203            let mut tally = BTreeMap::new();
204            for message in reader.iter_messages() {
205                let message = message?;
206                *tally.entry(message.channel.id).or_insert(0) += 1;
207            }
208            tally
209        }
210    };
211    let total = counts.values().sum();
212    let topics = reader
213        .channels()
214        .iter()
215        .map(|(id, channel)| {
216            let r#type = if channel.schema_id == 0 {
217                String::new()
218            } else {
219                reader
220                    .schemas()
221                    .get(&channel.schema_id)
222                    .map(|schema| schema.name.clone())
223                    .unwrap_or_default()
224            };
225            TopicInfo {
226                name: channel.topic.clone(),
227                r#type,
228                serialization_format: channel.message_encoding.clone(),
229                message_count: counts.get(id).copied().unwrap_or(0),
230            }
231        })
232        .collect();
233    Ok((topics, total, reader.warnings().to_vec()))
234}
235
236fn emit_recording_human(out: &mut dyn Write, path: &Path, stats: &Stats, recovered: bool) {
237    let _ = writeln!(out, "{}", path.display());
238    let _ = writeln!(out, "  dataflow:   {}", stats.dataflow);
239    let _ = writeln!(out, "  entries:    {}", stats.entry_count);
240    let _ = writeln!(out, "  file size:  {} bytes", stats.file_size_bytes);
241    let _ = writeln!(
242        out,
243        "  payload:    {} bytes (uncompressed)",
244        stats.uncompressed_payload_bytes
245    );
246    match stats.hlc_range {
247        Some((min, max)) => {
248            let _ = writeln!(out, "  hlc range:  {min} .. {max}");
249        }
250        None => {
251            let _ = writeln!(out, "  hlc range:  (empty)");
252        }
253    }
254    if recovered {
255        let _ = writeln!(out, "  note:       recovered by scan (no trailer found)");
256    }
257    let _ = writeln!(out, "  ports:");
258    for ((node, output), port_stats) in &stats.ports {
259        let _ = writeln!(
260            out,
261            "    {node}/{output}: {} entries, {} bytes",
262            port_stats.count, port_stats.payload_bytes
263        );
264    }
265    let _ = out.flush();
266}
267
268fn emit_recording_json(out: &mut dyn Write, path: &Path, stats: &Stats, report: &RecoveryReport) {
269    let ports: serde_json::Map<String, serde_json::Value> = stats
270        .ports
271        .iter()
272        .map(|((node, output), port_stats)| {
273            (
274                format!("{node}/{output}"),
275                serde_json::json!({
276                    "count": port_stats.count,
277                    "bytes": port_stats.payload_bytes,
278                }),
279            )
280        })
281        .collect();
282    let value = serde_json::json!({
283        "kind": "arec",
284        "path": path.display().to_string(),
285        "dataflow": stats.dataflow.to_string(),
286        "entries": stats.entry_count,
287        "file_size_bytes": stats.file_size_bytes,
288        "uncompressed_payload_bytes": stats.uncompressed_payload_bytes,
289        "hlc_range": stats.hlc_range.map(|(min, max)| serde_json::json!({
290            "min": min.physical_ns(),
291            "max": max.physical_ns(),
292        })),
293        "recovered": report.was_recovered(),
294        "ports": ports,
295    });
296    let _ = writeln!(
297        out,
298        "{}",
299        serde_json::to_string_pretty(&value).unwrap_or_else(|_| "{}".to_owned())
300    );
301    let _ = out.flush();
302}
303
304fn emit_bag_human(out: &mut dyn Write, path: &Path, summary: &BagSummary) {
305    let _ = writeln!(out, "{}", path.display());
306    let _ = writeln!(out, "  format:     .{}", summary.format.extension());
307    let _ = writeln!(out, "  messages:   {}", summary.message_count);
308    let _ = writeln!(out, "  topics:");
309    for topic in &summary.topics {
310        let type_label = if topic.r#type.is_empty() {
311            "(unknown type)"
312        } else {
313            topic.r#type.as_str()
314        };
315        let _ = writeln!(
316            out,
317            "    {} [{}] {type_label}: {} messages",
318            topic.name, topic.serialization_format, topic.message_count
319        );
320    }
321    for warning in &summary.warnings {
322        let _ = writeln!(out, "  warning:    {warning}");
323    }
324    let _ = out.flush();
325}
326
327fn emit_bag_json(out: &mut dyn Write, path: &Path, summary: &BagSummary) {
328    let topics: Vec<serde_json::Value> = summary
329        .topics
330        .iter()
331        .map(|topic| {
332            serde_json::json!({
333                "name": topic.name,
334                "type": topic.r#type,
335                "serialization_format": topic.serialization_format,
336                "message_count": topic.message_count,
337            })
338        })
339        .collect();
340    let value = serde_json::json!({
341        "kind": summary.format.extension(),
342        "path": path.display().to_string(),
343        "messages": summary.message_count,
344        "topics": topics,
345        "warnings": summary.warnings,
346    });
347    let _ = writeln!(
348        out,
349        "{}",
350        serde_json::to_string_pretty(&value).unwrap_or_else(|_| "{}".to_owned())
351    );
352    let _ = out.flush();
353}
354
355/// `astrs bag convert` arguments.
356#[derive(Debug, Clone)]
357pub struct ConvertArgs {
358    /// The input file (`.arec`, `.db3`, or `.mcap` — inferred from the
359    /// extension).
360    pub input: PathBuf,
361    /// The output file (extension selects the target format).
362    pub output: PathBuf,
363    /// Emit JSON rather than a human-readable summary.
364    pub json: bool,
365}
366
367/// Converts `args.input` to `args.output` via
368/// [`astrs_rosbag::convert::convert_bag`], printing a summary of what was
369/// written.
370///
371/// # Errors
372///
373/// [`CliError::Rosbag`] for anything [`convert_bag`] itself reports:
374/// an unrecognized extension on either side, `→ .mcap` (no `.mcap`
375/// writer), `.mcap → .db3` or a same-format pair (neither bridges without
376/// going through `.arec` — see [`astrs_rosbag::RosbagError::UnsupportedConversion`]),
377/// or a read/write failure on either file.
378pub fn convert(out: &mut dyn Write, args: &ConvertArgs) -> Result<ConversionReport, CliError> {
379    let report = convert_bag(&args.input, &args.output)?;
380
381    if args.json {
382        let value = serde_json::json!({
383            "input": report.input.display().to_string(),
384            "output": report.output.display().to_string(),
385            "direction": report.direction,
386            "topics": report.topics,
387            "messages": report.messages,
388            "warnings": report.warnings,
389        });
390        let _ = writeln!(
391            out,
392            "{}",
393            serde_json::to_string_pretty(&value).unwrap_or_else(|_| "{}".to_owned())
394        );
395    } else {
396        let _ = writeln!(
397            out,
398            "{} -> {} ({})",
399            report.input.display(),
400            report.output.display(),
401            report.direction
402        );
403        let _ = writeln!(out, "  topics:    {}", report.topics);
404        let _ = writeln!(out, "  messages:  {}", report.messages);
405        for warning in &report.warnings {
406            let _ = writeln!(out, "  warning:   {warning}");
407        }
408    }
409    let _ = out.flush();
410    Ok(report)
411}
412
413#[cfg(test)]
414mod tests {
415    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
416    use super::*;
417    use astrs_recording::{Writer, WriterOptions};
418    use astrs_rosbag::TopicRecord;
419    use astrs_rosbag::db3::Writer as Db3Writer;
420    use astrs_time::HlcTimestamp;
421    use astrs_wire::{DataId, DataflowId, Metadata, NodeId};
422
423    fn uniq() -> u64 {
424        use std::sync::atomic::{AtomicU64, Ordering};
425        static NEXT: AtomicU64 = AtomicU64::new(1);
426        NEXT.fetch_add(1, Ordering::Relaxed)
427    }
428
429    fn temp_dir(label: &str) -> PathBuf {
430        let dir = std::env::temp_dir().join(format!(
431            "astrs-cli-bag-test-{}-{}-{label}",
432            std::process::id(),
433            uniq()
434        ));
435        std::fs::create_dir_all(&dir).unwrap();
436        dir
437    }
438
439    fn sample_recording(path: &PathBuf, finish: bool) {
440        let options = WriterOptions::new(DataflowId::from_u128(42), HlcTimestamp::new(1, 0));
441        let mut writer = Writer::create(path, options).unwrap();
442        writer
443            .append_parts(
444                NodeId::new("camera").unwrap(),
445                DataId::new("frames").unwrap(),
446                Metadata::new(HlcTimestamp::new(10, 0)),
447                vec![0; 64],
448            )
449            .unwrap();
450        if finish {
451            writer.finish().unwrap();
452        } else {
453            std::mem::forget(writer);
454        }
455    }
456
457    #[test]
458    fn info_reports_stats_for_a_finished_recording() {
459        let dir = temp_dir("finished");
460        let path = dir.join("session.arec");
461        sample_recording(&path, true);
462        let mut out = Vec::new();
463        let report = info(
464            &mut out,
465            &InfoArgs {
466                input: path.clone(),
467                json: false,
468            },
469        )
470        .unwrap();
471        let InfoReport::Recording { stats, recovered } = report else {
472            panic!("expected a Recording report");
473        };
474        assert!(!recovered);
475        assert_eq!(stats.entry_count, 1);
476        let text = String::from_utf8(out).unwrap();
477        assert!(text.contains("camera/frames"));
478    }
479
480    #[test]
481    fn info_falls_back_to_recovery_for_a_footerless_file() {
482        let dir = temp_dir("footerless");
483        let path = dir.join("session.arec");
484        sample_recording(&path, false);
485        let mut out = Vec::new();
486        let report = info(
487            &mut out,
488            &InfoArgs {
489                input: path.clone(),
490                json: false,
491            },
492        )
493        .unwrap();
494        let InfoReport::Recording { recovered, .. } = report else {
495            panic!("expected a Recording report");
496        };
497        assert!(recovered);
498        let text = String::from_utf8(out).unwrap();
499        assert!(text.contains("recovered by scan"));
500    }
501
502    #[test]
503    fn info_emits_valid_json_for_a_recording() {
504        let dir = temp_dir("json");
505        let path = dir.join("session.arec");
506        sample_recording(&path, true);
507        let mut out = Vec::new();
508        info(
509            &mut out,
510            &InfoArgs {
511                input: path.clone(),
512                json: true,
513            },
514        )
515        .unwrap();
516        let value: serde_json::Value = serde_json::from_slice(&out).unwrap();
517        assert_eq!(value["entries"], 1);
518        assert_eq!(value["recovered"], false);
519        assert_eq!(value["kind"], "arec");
520    }
521
522    #[test]
523    fn a_missing_file_is_an_io_error() {
524        let path = std::env::temp_dir().join("astrs-cli-bag-does-not-exist.arec");
525        let mut out = Vec::new();
526        let error = info(
527            &mut out,
528            &InfoArgs {
529                input: path,
530                json: false,
531            },
532        )
533        .unwrap_err();
534        assert!(matches!(error, CliError::Io { .. }));
535    }
536
537    #[test]
538    fn an_unrecognized_extension_is_a_rosbag_error() {
539        let dir = temp_dir("unknown-ext");
540        let path = dir.join("session.bag");
541        std::fs::write(&path, b"anything").unwrap();
542        let mut out = Vec::new();
543        let error = info(
544            &mut out,
545            &InfoArgs {
546                input: path,
547                json: false,
548            },
549        )
550        .unwrap_err();
551        assert!(matches!(error, CliError::Rosbag(_)));
552    }
553
554    fn sample_db3(path: &PathBuf) {
555        let mut writer = Db3Writer::create(path, "jazzy").unwrap();
556        let topic_id = writer
557            .create_topic(&TopicRecord::new(
558                "/scan",
559                "sensor_msgs/msg/LaserScan",
560                "cdr",
561            ))
562            .unwrap();
563        writer
564            .write_messages(
565                vec![
566                    Ok((topic_id, 1_000, vec![1, 2, 3])),
567                    Ok((topic_id, 2_000, vec![4, 5, 6])),
568                ]
569                .into_iter(),
570            )
571            .unwrap();
572        writer.finish().unwrap();
573    }
574
575    #[test]
576    fn info_reads_a_db3_bag_with_per_topic_message_counts() {
577        let dir = temp_dir("db3");
578        let path = dir.join("session.db3");
579        sample_db3(&path);
580        let mut out = Vec::new();
581        let report = info(
582            &mut out,
583            &InfoArgs {
584                input: path.clone(),
585                json: false,
586            },
587        )
588        .unwrap();
589        let InfoReport::Bag(summary) = report else {
590            panic!("expected a Bag report");
591        };
592        assert_eq!(summary.format, BagFormat::Db3);
593        assert_eq!(summary.message_count, 2);
594        assert_eq!(summary.topics.len(), 1);
595        assert_eq!(summary.topics[0].name, "/scan");
596        assert_eq!(summary.topics[0].message_count, 2);
597        let text = String::from_utf8(out).unwrap();
598        assert!(text.contains("/scan"));
599        assert!(text.contains(".db3"));
600    }
601
602    #[test]
603    fn info_emits_valid_json_for_a_db3_bag() {
604        let dir = temp_dir("db3-json");
605        let path = dir.join("session.db3");
606        sample_db3(&path);
607        let mut out = Vec::new();
608        info(
609            &mut out,
610            &InfoArgs {
611                input: path,
612                json: true,
613            },
614        )
615        .unwrap();
616        let value: serde_json::Value = serde_json::from_slice(&out).unwrap();
617        assert_eq!(value["kind"], "db3");
618        assert_eq!(value["messages"], 2);
619        assert_eq!(value["topics"][0]["name"], "/scan");
620        assert_eq!(value["topics"][0]["message_count"], 2);
621    }
622
623    #[test]
624    fn convert_bridges_arec_to_db3_and_prints_a_summary() {
625        let dir = temp_dir("convert-arec-db3");
626        let input = dir.join("session.arec");
627        let output = dir.join("session.db3");
628        sample_recording(&input, true);
629
630        let mut out = Vec::new();
631        let report = convert(
632            &mut out,
633            &ConvertArgs {
634                input: input.clone(),
635                output: output.clone(),
636                json: false,
637            },
638        )
639        .unwrap();
640        assert_eq!(report.direction, "arec -> db3");
641        assert_eq!(report.messages, 1);
642        assert!(output.exists());
643        let text = String::from_utf8(out).unwrap();
644        assert!(text.contains("arec -> db3"));
645    }
646
647    #[test]
648    fn convert_emits_valid_json() {
649        let dir = temp_dir("convert-json");
650        let input = dir.join("session.arec");
651        let output = dir.join("session.db3");
652        sample_recording(&input, true);
653
654        let mut out = Vec::new();
655        convert(
656            &mut out,
657            &ConvertArgs {
658                input,
659                output,
660                json: true,
661            },
662        )
663        .unwrap();
664        let value: serde_json::Value = serde_json::from_slice(&out).unwrap();
665        assert_eq!(value["direction"], "arec -> db3");
666        assert_eq!(value["messages"], 1);
667    }
668
669    #[test]
670    fn convert_propagates_a_typed_error_for_an_unsupported_pair() {
671        let dir = temp_dir("convert-unsupported");
672        let input = dir.join("session.db3");
673        let output = dir.join("session.mcap");
674        sample_db3(&input);
675
676        let mut out = Vec::new();
677        let error = convert(
678            &mut out,
679            &ConvertArgs {
680                input,
681                output,
682                json: false,
683            },
684        )
685        .unwrap_err();
686        assert!(matches!(error, CliError::Rosbag(_)));
687    }
688}