1use std::collections::BTreeSet;
41
42use serde::{Deserialize, Serialize};
43
44use crate::error::LogError;
45use crate::log::{FlightLog, LogFormat};
46use crate::records::{self, RecordLayout};
47use crate::table::{numbered_lines, short};
48
49pub const HEAD_LINES: usize = 1000;
51
52pub const MAX_NAME_CHARS: usize = 64;
54
55const FORMAT: &str = "console capture";
57
58const OPEN: &str = "----++++//[[( ";
60
61const START: &str = " start )]]\\\\++++----";
63
64const END: &str = " end )]]\\\\++++----";
66
67#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
69#[non_exhaustive]
70pub struct Block {
71 pub name: String,
73 pub line: usize,
75 pub bytes: Vec<u8>,
77}
78
79fn marker(line: &str) -> Option<(&str, bool)> {
81 let rest = line.trim().strip_prefix(OPEN)?;
82 let (name, start) = if let Some(name) = rest.strip_suffix(START) {
83 (name, true)
84 } else {
85 (rest.strip_suffix(END)?, false)
86 };
87 let named = !name.is_empty()
88 && name.len() <= MAX_NAME_CHARS
89 && name
90 .bytes()
91 .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-'));
92 named.then_some((name, start))
93}
94
95pub fn recognizes(text: &str) -> bool {
97 numbered_lines(text)
98 .take(HEAD_LINES)
99 .any(|(_, line)| marker(line).is_some_and(|(_, start)| start))
100}
101
102fn syntax(line: usize, message: String) -> LogError {
103 LogError::Syntax {
104 format: FORMAT,
105 line,
106 message,
107 }
108}
109
110fn sextet(byte: u8) -> Option<u32> {
112 match byte {
113 b'A'..=b'Z' => Some(u32::from(byte - b'A')),
114 b'a'..=b'z' => Some(u32::from(byte - b'a') + 26),
115 b'0'..=b'9' => Some(u32::from(byte - b'0') + 52),
116 b'+' => Some(62),
117 b'/' => Some(63),
118 _ => None,
119 }
120}
121
122struct Base64<'a> {
125 name: &'a str,
127 bytes: Vec<u8>,
129 group: [u32; 4],
131 filled: usize,
132 count: usize,
134 padding: usize,
136 padding_line: usize,
137 last_line: usize,
139 last_value: u32,
140}
141
142impl<'a> Base64<'a> {
143 fn new(name: &'a str) -> Self {
144 Self {
145 name,
146 bytes: Vec::new(),
147 group: [0; 4],
148 filled: 0,
149 count: 0,
150 padding: 0,
151 padding_line: 0,
152 last_line: 0,
153 last_value: 0,
154 }
155 }
156
157 fn line(&mut self, number: usize, line: &str) -> Result<(), LogError> {
159 let name = self.name;
160 for byte in line.bytes() {
161 self.count += 1;
162 self.last_line = number;
163 if byte == b'=' {
164 if self.padding == 0 {
165 self.padding_line = number;
166 }
167 self.padding += 1;
168 if self.padding > 2 {
169 return Err(syntax(
170 number,
171 format!(
172 "the block `{name}` ends in 3 `=` or more, where base64 pads with 2 at most"
173 ),
174 ));
175 }
176 continue;
177 }
178 let Some(value) = sextet(byte) else {
179 let what = if byte.is_ascii_graphic() {
180 format!("`{}`", char::from(byte))
181 } else {
182 format!("the byte 0x{byte:02X}")
183 };
184 return Err(syntax(
185 number,
186 format!("the block `{name}` holds {what}, which isn't base64"),
187 ));
188 };
189 if self.padding > 0 {
190 return Err(syntax(
191 self.padding_line,
192 format!("the block `{name}` holds `=` before its end, where only padding may"),
193 ));
194 }
195 self.last_value = value;
196 self.group[self.filled] = value;
197 self.filled += 1;
198 if self.filled == 4 {
199 let word = self
200 .group
201 .iter()
202 .fold(0u32, |word, value| word << 6 | value);
203 self.bytes.extend(&word.to_be_bytes()[1..]);
204 self.filled = 0;
205 }
206 }
207 Ok(())
208 }
209
210 fn finish(mut self, start: usize) -> Result<Vec<u8>, LogError> {
212 let name = self.name;
213 let line = if self.count == 0 {
214 start
215 } else {
216 self.last_line
217 };
218 if !self.count.is_multiple_of(4) {
219 return Err(syntax(
220 line,
221 format!(
222 "the block `{name}` holds {} base64 characters, not a multiple of 4",
223 self.count
224 ),
225 ));
226 }
227 if self.padding > 0 {
230 let spare = if self.padding == 2 { 0b1111 } else { 0b11 };
234 if self.last_value & spare != 0 {
235 return Err(syntax(
236 self.padding_line,
237 format!("the block `{name}` ends in bits its padding should leave zero"),
238 ));
239 }
240 let word = self.group[..self.filled]
241 .iter()
242 .fold(0u32, |word, value| word << 6 | value)
243 << (6 * self.padding);
244 self.bytes
245 .extend(&word.to_be_bytes()[1..1 + (3 - self.padding)]);
246 }
247 Ok(self.bytes)
248 }
249}
250
251#[cfg(test)]
253fn decode(name: &str, start: usize, lines: &[(usize, &str)]) -> Result<Vec<u8>, LogError> {
254 let mut base64 = Base64::new(name);
255 for &(number, line) in lines {
256 base64.line(number, line)?;
257 }
258 base64.finish(start)
259}
260
261type Open<'a> = (&'a str, usize, Base64<'a>);
263
264pub fn blocks(text: &str) -> Result<Vec<Block>, LogError> {
273 if !recognizes(text) {
274 return Err(LogError::NotThisFormat {
275 format: FORMAT,
276 message: format!(
277 "within its first {HEAD_LINES} lines there is no start marker, such as \
278 `----++++//[[( data start )]]\\\\++++----`"
279 ),
280 });
281 }
282 let mut blocks: Vec<Block> = Vec::new();
283 let mut seen: BTreeSet<&str> = BTreeSet::new();
284 let mut open: Option<Open<'_>> = None;
285 for (number, line) in numbered_lines(text) {
286 match (marker(line), open.take()) {
287 (Some((name, true)), None) => {
288 if !seen.insert(name) {
289 return Err(syntax(number, format!("a second block named `{name}`")));
290 }
291 open = Some((name, number, Base64::new(name)));
292 }
293 (Some((name, false)), Some((open_name, start, base64))) if name == open_name => {
294 blocks.push(Block {
295 name: name.to_owned(),
296 line: start,
297 bytes: base64.finish(start)?,
298 });
299 }
300 (Some((name, _)), Some((open_name, start, _))) => {
301 return Err(syntax(
302 number,
303 format!(
304 "a marker of the block `{name}` inside the block `{open_name}`, opened \
305 at line {start}"
306 ),
307 ));
308 }
309 (Some((name, false)), None) => {
310 return Err(syntax(
311 number,
312 format!("the block `{name}` ends here but never started"),
313 ));
314 }
315 (None, Some((name, start, mut base64))) => {
316 base64.line(number, line.trim())?;
317 open = Some((name, start, base64));
318 }
319 (None, None) => {}
320 }
321 }
322 if let Some((name, start, _)) = open {
323 return Err(syntax(
324 start,
325 format!("the block `{name}`, opened here, never ends"),
326 ));
327 }
328 Ok(blocks)
329}
330
331const LISTED: usize = 8;
333
334fn listed<'a>(names: impl Iterator<Item = &'a str>) -> String {
336 let mut named = Vec::new();
337 let mut more = 0usize;
338 for name in names {
339 if named.len() < LISTED {
340 named.push(format!("`{name}`"));
341 } else {
342 more += 1;
343 }
344 }
345 if more > 0 {
346 named.push(format!("{more} more"));
347 }
348 named.join(", ")
349}
350
351pub(crate) fn needs_a_layout(text: &str) -> LogError {
354 let names = numbered_lines(text)
355 .filter_map(|(_, line)| marker(line))
356 .filter(|(_, start)| *start)
357 .map(|(name, _)| name);
358 LogError::Layout {
359 message: format!(
360 "a serial console's capture of binary records as base64, its blocks {}. The capture \
361 doesn't state the records' layout, so read a block by the one the logger writes \
362 (`capture::read`)",
363 listed(names)
364 ),
365 }
366}
367
368pub fn read(text: &str, block: &str, layout: &RecordLayout) -> Result<FlightLog, LogError> {
376 let blocks = blocks(text)?;
377 let Some(found) = blocks.iter().find(|candidate| candidate.name == block) else {
378 return Err(LogError::Layout {
379 message: format!(
380 "the capture holds no block `{}`; its blocks are {}",
381 short(block),
382 listed(blocks.iter().map(|b| b.name.as_str()))
383 ),
384 });
385 };
386 let table = records::table(&found.bytes, layout)?;
387 let mut log = records::read_table(&table)?;
388 log.format = LogFormat::ConsoleCapture;
389 log.notes.insert(
390 0,
391 format!(
392 "read from the block `{}` of a console capture, line {}: {} bytes of base64 decoded",
393 found.name,
394 found.line,
395 found.bytes.len()
396 ),
397 );
398 Ok(log)
399}
400
401#[cfg(test)]
402mod tests {
403 use super::*;
404 use crate::records::{Field, FieldKind};
405
406 #[test]
408 fn base64_decodes_rfc_4648s_vectors() {
409 for (encoded, decoded) in [
410 ("", ""),
411 ("Zg==", "f"),
412 ("Zm8=", "fo"),
413 ("Zm9v", "foo"),
414 ("Zm9vYg==", "foob"),
415 ("Zm9vYmE=", "fooba"),
416 ("Zm9vYmFy", "foobar"),
417 ] {
418 let lines = [(2, encoded)];
419 let lines = if encoded.is_empty() {
420 &lines[..0]
421 } else {
422 &lines[..]
423 };
424 assert_eq!(
425 decode("d", 1, lines).unwrap(),
426 decoded.as_bytes(),
427 "{encoded}"
428 );
429 }
430 assert_eq!(
432 decode("d", 1, &[(2, "Zm9v"), (3, "YmFy")]).unwrap(),
433 b"foobar"
434 );
435 assert_eq!(
436 decode("d", 1, &[(2, "Zm9vY"), (3, "mFy")]).unwrap(),
437 b"foobar"
438 );
439 }
440
441 #[test]
442 fn base64_out_of_its_alphabet_or_form_is_refused_at_its_line() {
443 type Case<'a> = (&'a [(usize, &'a str)], usize, &'a str);
444 let cases: [Case<'_>; 10] = [
445 (
447 &[(3, "Zm-v"), (4, "YmFy"), (5, "YmF")],
448 3,
449 "holds `-`, which isn't base64",
450 ),
451 (
452 &[(2, "Zm9v"), (3, "Zm 9v")],
453 3,
454 "holds the byte 0x20, which isn't base64",
455 ),
456 (
457 &[(2, "Zm9v"), (3, "Ym-y")],
458 3,
459 "holds `-`, which isn't base64",
460 ),
461 (
462 &[(2, "Zm9v"), (3, "YmF")],
463 3,
464 "7 base64 characters, not a multiple of 4",
465 ),
466 (&[(2, "Zg=="), (3, "Zm9v")], 2, "`=` before its end"),
467 (&[(2, "Z=9v")], 2, "`=` before its end"),
468 (&[(2, "Zm9v"), (3, "Y===")], 3, "ends in 3 `=`"),
469 (
470 &[(2, "Zm9v"), (3, "Zh==")],
471 3,
472 "bits its padding should leave zero",
473 ),
474 (
475 &[(2, "Zm9v"), (3, "Zm9=")],
476 3,
477 "bits its padding should leave zero",
478 ),
479 (
480 &[(2, "Zm9v"), (3, "Ym\u{e9}")],
481 3,
482 "holds the byte 0xC3, which isn't base64",
483 ),
484 ];
485 for (lines, at, why) in cases {
486 match decode("d", 1, lines) {
487 Err(LogError::Syntax { line, message, .. }) => {
488 assert_eq!(line, at, "{message}");
489 assert!(message.contains(why), "{message} lacks {why}");
490 }
491 other => panic!("expected a refusal for {why}, got {other:?}"),
492 }
493 }
494 }
495
496 fn capture(blocks: &[(&str, &str)]) -> String {
497 let mut text = String::from("uart:~$ dump\n");
498 for (name, base64) in blocks {
499 text += &format!("----++++//[[( {name} start )]]\\\\++++----\n{base64}\n");
500 text += &format!("----++++//[[( {name} end )]]\\\\++++----\nuart:~$ \n");
501 }
502 text
503 }
504
505 #[test]
506 fn a_capture_is_recognized_by_a_start_marker_only() {
507 assert!(recognizes(&capture(&[("data", "Zm9v")])));
508 assert!(recognizes(
509 "\r\n ----++++//[[( a-b_9 start )]]\\\\++++---- \r\n"
510 ));
511 for text in [
512 "----++++//[[( data end )]]\\\\++++----\n",
513 "----++++//[[( start )]]\\\\++++----\n",
514 "----++++//[[( da ta start )]]\\\\++++----\n",
515 "----++++//[[( data start )]]\\++++----\n",
516 "x ----++++//[[( data start )]]\\\\++++----\n",
517 "uart:~$ dump\n",
518 ] {
519 assert!(!recognizes(text), "{text:?}");
520 }
521 let long = format!(
522 "----++++//[[( {} start )]]\\\\++++----\n",
523 "n".repeat(MAX_NAME_CHARS)
524 );
525 assert!(recognizes(&long));
526 let longer = long.replacen('n', "nn", 1);
527 assert!(!recognizes(&longer));
528 let late = "\n".repeat(HEAD_LINES) + &capture(&[("data", "Zm9v")]);
530 assert!(!recognizes(&late));
531 let within = "\n".repeat(HEAD_LINES - 1) + "----++++//[[( d start )]]\\\\++++----\n";
532 assert!(recognizes(&within));
533 }
534
535 #[test]
536 fn blocks_decode_in_order_with_the_shells_lines_skipped() {
537 let text = capture(&[("params", "Zm9v"), ("data", "Zm9v\n\n YmFy ")]);
538 let blocks = blocks(&text).unwrap();
539 assert_eq!(blocks.len(), 2);
540 assert_eq!((blocks[0].name.as_str(), blocks[0].line), ("params", 2));
541 assert_eq!(blocks[0].bytes, b"foo");
542 assert_eq!((blocks[1].name.as_str(), blocks[1].line), ("data", 6));
543 assert_eq!(blocks[1].bytes, b"foobar");
544 }
545
546 #[test]
547 fn a_malformed_capture_is_refused_naming_the_line() {
548 let start = |name: &str| format!("----++++//[[( {name} start )]]\\\\++++----\n");
549 let end = |name: &str| format!("----++++//[[( {name} end )]]\\\\++++----\n");
550 let cases = [
551 (
552 format!("{}Zm9v\n", start("data")),
553 1,
554 "the block `data`, opened here, never ends",
555 ),
556 (
557 format!("{}Zm9v\n{}{}", start("data"), start("more"), end("data")),
558 3,
559 "a marker of the block `more` inside the block `data`, opened at line 1",
560 ),
561 (
562 format!("{}{}{}", start("a"), end("b"), end("a")),
563 2,
564 "a marker of the block `b` inside the block `a`",
565 ),
566 (
567 format!("{}{}{}", start("a"), end("a"), end("a")),
568 3,
569 "the block `a` ends here but never started",
570 ),
571 (
572 format!("{}{}{}{}", start("a"), end("a"), start("a"), end("a")),
573 3,
574 "a second block named `a`",
575 ),
576 ];
577 for (text, at, why) in cases {
578 match blocks(&text) {
579 Err(LogError::Syntax { line, message, .. }) => {
580 assert_eq!(line, at, "{message}");
581 assert!(message.contains(why), "{message} lacks {why}");
582 }
583 other => panic!("expected a refusal for {why}, got {other:?}"),
584 }
585 }
586 assert!(matches!(
587 blocks("uart:~$\n"),
588 Err(LogError::NotThisFormat { .. })
589 ));
590 }
591
592 fn base64(bytes: &[u8]) -> String {
593 const ALPHABET: &[u8; 64] =
594 b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
595 let mut out = String::new();
596 for chunk in bytes.chunks(3) {
597 let mut word = [0u8; 3];
598 word[..chunk.len()].copy_from_slice(chunk);
599 let n = u32::from_be_bytes([0, word[0], word[1], word[2]]);
600 for i in 0..4 {
601 if i <= chunk.len() {
602 out.push(char::from(ALPHABET[(n >> (18 - 6 * i) & 63) as usize]));
603 } else {
604 out.push('=');
605 }
606 }
607 }
608 out
609 }
610
611 #[test]
612 fn a_block_is_read_by_the_callers_layout() {
613 let mut bytes = Vec::new();
614 for (ms, kpa) in [(1000_u32, 101.3_f32), (1010, 101.2), (1020, 101.1)] {
615 bytes.extend(ms.to_le_bytes());
616 bytes.extend(kpa.to_le_bytes());
617 }
618 bytes.extend([0xFF; 4]);
620 let encoded = base64(&bytes);
621 let text = capture(&[("params", "AAAA"), ("data", &encoded)]);
622 let layout = RecordLayout::new(vec![
623 Field::new("timestamp__ms", FieldKind::U32),
624 Field::new("pressure__kpa", FieldKind::F32),
625 ]);
626 let log = read(&text, "data", &layout).unwrap();
627 assert_eq!(log.format, LogFormat::ConsoleCapture);
628 assert_eq!(log.channels[0].time_s, [1.0, 1.01, 1.02]);
629 assert_eq!(log.channels[0].values[2], f64::from(101.1_f32) * 1000.0);
630 assert_eq!(
631 log.notes[..3],
632 [
633 "read from the block `data` of a console capture, line 6: 28 bytes of base64 decoded",
634 "3 binary records read by the caller's layout, written out as a table and read by its header",
635 "4 bytes past the last whole record, each 0xFF, dropped as erased memory",
636 ]
637 );
638 match read(&text, "flight", &layout) {
639 Err(LogError::Layout { message }) => {
640 assert!(
641 message.contains("no block `flight`; its blocks are `params`, `data`"),
642 "{message}"
643 );
644 }
645 other => panic!("expected a layout refusal, got {other:?}"),
646 }
647 }
648
649 #[test]
650 fn import_refuses_a_capture_for_its_layout_listing_a_few_blocks() {
651 let named: Vec<(String, &str)> = (0..10).map(|i| (format!("b{i}"), "Zm9v")).collect();
652 let named: Vec<(&str, &str)> = named.iter().map(|(n, b)| (n.as_str(), *b)).collect();
653 let text = capture(&named);
654 assert_eq!(
655 crate::import::detect(text.as_bytes()),
656 Some(LogFormat::ConsoleCapture)
657 );
658 match crate::import::read(text.as_bytes()) {
659 Err(LogError::Layout { message }) => {
660 assert!(message.contains("`b0`, `b1`"), "{message}");
661 assert!(message.contains("`b7`, 2 more. "), "{message}");
662 assert!(!message.contains("`b8`"), "{message}");
663 assert!(message.contains("capture::read"), "{message}");
664 }
665 other => panic!("expected a layout refusal, got {other:?}"),
666 }
667 let broken = capture(&[("data", "Zm9")]);
669 match crate::import::read(broken.as_bytes()) {
670 Err(LogError::Layout { message }) => {
671 assert!(message.contains("its blocks `data`. "), "{message}");
672 }
673 other => panic!("expected a layout refusal, got {other:?}"),
674 }
675 }
676}