Skip to main content

prolink_capture/
error.rs

1// SPDX-License-Identifier: GPL-3.0-only
2
3//! The one error type this crate returns.
4
5/// What went wrong reading a capture.
6#[derive(Debug, thiserror::Error)]
7pub enum Error {
8    /// The leading bytes are neither a pcap magic nor a pcapng section header.
9    ///
10    /// Whatever the file is — a text log, a JSONL journal, a truncated
11    /// download — it is not a capture, and no amount of further reading will
12    /// make it one.
13    #[error("not a capture: leading bytes {magic:02x?} are no pcap or pcapng magic")]
14    NotACapture {
15        /// The four bytes that were there instead.
16        magic: [u8; 4],
17    },
18
19    /// The file ends part-way through a record.
20    ///
21    /// Kept apart from [`Error::Malformed`] because it is the *expected* state
22    /// of a capture whose `tcpdump` was killed rather than stopped, which any
23    /// real corpus contains. Everything yielded before it is good; only the
24    /// tail is missing. See [`Error::is_truncated`].
25    #[error("the capture ends part-way through a record")]
26    Truncated,
27
28    /// A record's fields contradict the format or each other. More bytes will
29    /// not help.
30    #[error("malformed capture: {reason}")]
31    Malformed {
32        /// What the underlying reader objected to.
33        reason: String,
34    },
35
36    /// Reading the file failed.
37    #[error("i/o error reading the capture")]
38    Io(#[from] std::io::Error),
39
40    /// Frames recorded from a link layer this crate does not dissect.
41    ///
42    /// Raised rather than silently skipped: a capture taken on a `pktap` or
43    /// `usbmon` interface would otherwise yield zero packets and look exactly
44    /// like a capture with no Pro DJ Link traffic in it.
45    #[error("link type {link_type} is not dissected; this crate handles Ethernet (1) only")]
46    UnsupportedLinkType {
47        /// The [tcpdump.org] link-layer header type code.
48        ///
49        /// [tcpdump.org]: https://www.tcpdump.org/linktypes.html
50        link_type: u32,
51    },
52}
53
54impl Error {
55    /// True when the file was cut short rather than being the wrong thing.
56    ///
57    /// The distinction a corpus walker needs: a truncated capture is worth
58    /// keeping the packets from, a malformed one is worth a warning.
59    pub fn is_truncated(&self) -> bool {
60        matches!(self, Self::Truncated)
61    }
62}
63
64/// Result alias for this crate.
65pub type Result<T, E = Error> = std::result::Result<T, E>;