|
| 1 | +// DO NOT EDIT - this is a copy of gix-packetline/src/decode.rs. Run `just copy-packetline` to update it. |
| 2 | + |
| 3 | +use bstr::BString; |
| 4 | + |
| 5 | +use crate::{PacketLineRef, DELIMITER_LINE, FLUSH_LINE, MAX_DATA_LEN, MAX_LINE_LEN, RESPONSE_END_LINE, U16_HEX_BYTES}; |
| 6 | + |
| 7 | +/// The error used in the [`decode`][mod@crate::decode] module |
| 8 | +#[derive(Debug, thiserror::Error)] |
| 9 | +#[allow(missing_docs)] |
| 10 | +pub enum Error { |
| 11 | + #[error("Failed to decode the first four hex bytes indicating the line length: {err}")] |
| 12 | + HexDecode { err: String }, |
| 13 | + #[error("The data received claims to be larger than the maximum allowed size: got {length_in_bytes}, exceeds {MAX_DATA_LEN}")] |
| 14 | + DataLengthLimitExceeded { length_in_bytes: usize }, |
| 15 | + #[error("Received an invalid empty line")] |
| 16 | + DataIsEmpty, |
| 17 | + #[error("Received an invalid line of length 3")] |
| 18 | + InvalidLineLength, |
| 19 | + #[error("{data:?} - consumed {bytes_consumed} bytes")] |
| 20 | + Line { data: BString, bytes_consumed: usize }, |
| 21 | + #[error("Needing {bytes_needed} additional bytes to decode the line successfully")] |
| 22 | + NotEnoughData { bytes_needed: usize }, |
| 23 | +} |
| 24 | + |
| 25 | +/// |
| 26 | +#[allow(clippy::empty_docs)] |
| 27 | +pub mod band { |
| 28 | + /// The error used in [`PacketLineRef::decode_band()`][super::PacketLineRef::decode_band()]. |
| 29 | + #[derive(Debug, thiserror::Error)] |
| 30 | + #[allow(missing_docs)] |
| 31 | + pub enum Error { |
| 32 | + #[error("attempt to decode a non-side channel line or input was malformed: {band_id}")] |
| 33 | + InvalidSideBand { band_id: u8 }, |
| 34 | + #[error("attempt to decode a non-data line into a side-channel band")] |
| 35 | + NonDataLine, |
| 36 | + } |
| 37 | +} |
| 38 | + |
| 39 | +/// A utility return type to support incremental parsing of packet lines. |
| 40 | +#[derive(Debug, Clone)] |
| 41 | +pub enum Stream<'a> { |
| 42 | + /// Indicate a single packet line was parsed completely |
| 43 | + Complete { |
| 44 | + /// The parsed packet line |
| 45 | + line: PacketLineRef<'a>, |
| 46 | + /// The amount of bytes consumed from input |
| 47 | + bytes_consumed: usize, |
| 48 | + }, |
| 49 | + /// A packet line could not yet be parsed due to missing bytes |
| 50 | + Incomplete { |
| 51 | + /// The amount of additional bytes needed for the parsing to complete |
| 52 | + bytes_needed: usize, |
| 53 | + }, |
| 54 | +} |
| 55 | + |
| 56 | +/// The result of [`hex_prefix()`] indicating either a special packet line or the amount of wanted bytes |
| 57 | +pub enum PacketLineOrWantedSize<'a> { |
| 58 | + /// The special kind of packet line decoded from the hex prefix. It never contains actual data. |
| 59 | + Line(PacketLineRef<'a>), |
| 60 | + /// The amount of bytes indicated by the hex prefix of the packet line. |
| 61 | + Wanted(u16), |
| 62 | +} |
| 63 | + |
| 64 | +/// Decode the `four_bytes` packet line prefix provided in hexadecimal form and check it for validity. |
| 65 | +pub fn hex_prefix(four_bytes: &[u8]) -> Result<PacketLineOrWantedSize<'_>, Error> { |
| 66 | + debug_assert_eq!(four_bytes.len(), 4, "need four hex bytes"); |
| 67 | + for (line_bytes, line_type) in &[ |
| 68 | + (FLUSH_LINE, PacketLineRef::Flush), |
| 69 | + (DELIMITER_LINE, PacketLineRef::Delimiter), |
| 70 | + (RESPONSE_END_LINE, PacketLineRef::ResponseEnd), |
| 71 | + ] { |
| 72 | + if four_bytes == *line_bytes { |
| 73 | + return Ok(PacketLineOrWantedSize::Line(*line_type)); |
| 74 | + } |
| 75 | + } |
| 76 | + |
| 77 | + let mut buf = [0u8; U16_HEX_BYTES / 2]; |
| 78 | + faster_hex::hex_decode(four_bytes, &mut buf).map_err(|err| Error::HexDecode { err: err.to_string() })?; |
| 79 | + let wanted_bytes = u16::from_be_bytes(buf); |
| 80 | + |
| 81 | + if wanted_bytes == 3 { |
| 82 | + return Err(Error::InvalidLineLength); |
| 83 | + } |
| 84 | + if wanted_bytes == 4 { |
| 85 | + return Err(Error::DataIsEmpty); |
| 86 | + } |
| 87 | + debug_assert!( |
| 88 | + wanted_bytes as usize > U16_HEX_BYTES, |
| 89 | + "by now there should be more wanted bytes than prefix bytes" |
| 90 | + ); |
| 91 | + Ok(PacketLineOrWantedSize::Wanted(wanted_bytes - U16_HEX_BYTES as u16)) |
| 92 | +} |
| 93 | + |
| 94 | +/// Obtain a `PacketLine` from `data` after assuring `data` is small enough to fit. |
| 95 | +pub fn to_data_line(data: &[u8]) -> Result<PacketLineRef<'_>, Error> { |
| 96 | + if data.len() > MAX_LINE_LEN { |
| 97 | + return Err(Error::DataLengthLimitExceeded { |
| 98 | + length_in_bytes: data.len(), |
| 99 | + }); |
| 100 | + } |
| 101 | + |
| 102 | + Ok(PacketLineRef::Data(data)) |
| 103 | +} |
| 104 | + |
| 105 | +/// Decode `data` as packet line while reporting whether the data is complete or not using a [`Stream`]. |
| 106 | +pub fn streaming(data: &[u8]) -> Result<Stream<'_>, Error> { |
| 107 | + let data_len = data.len(); |
| 108 | + if data_len < U16_HEX_BYTES { |
| 109 | + return Ok(Stream::Incomplete { |
| 110 | + bytes_needed: U16_HEX_BYTES - data_len, |
| 111 | + }); |
| 112 | + } |
| 113 | + let wanted_bytes = match hex_prefix(&data[..U16_HEX_BYTES])? { |
| 114 | + PacketLineOrWantedSize::Wanted(s) => s as usize, |
| 115 | + PacketLineOrWantedSize::Line(line) => { |
| 116 | + return Ok(Stream::Complete { |
| 117 | + line, |
| 118 | + bytes_consumed: 4, |
| 119 | + }) |
| 120 | + } |
| 121 | + } + U16_HEX_BYTES; |
| 122 | + if wanted_bytes > MAX_LINE_LEN { |
| 123 | + return Err(Error::DataLengthLimitExceeded { |
| 124 | + length_in_bytes: wanted_bytes, |
| 125 | + }); |
| 126 | + } |
| 127 | + if data_len < wanted_bytes { |
| 128 | + return Ok(Stream::Incomplete { |
| 129 | + bytes_needed: wanted_bytes - data_len, |
| 130 | + }); |
| 131 | + } |
| 132 | + |
| 133 | + Ok(Stream::Complete { |
| 134 | + line: to_data_line(&data[U16_HEX_BYTES..wanted_bytes])?, |
| 135 | + bytes_consumed: wanted_bytes, |
| 136 | + }) |
| 137 | +} |
| 138 | + |
| 139 | +/// Decode an entire packet line from data or fail. |
| 140 | +/// |
| 141 | +/// Note that failure also happens if there is not enough data to parse a complete packet line, as opposed to [`streaming()`] decoding |
| 142 | +/// succeeds in that case, stating how much more bytes are required. |
| 143 | +pub fn all_at_once(data: &[u8]) -> Result<PacketLineRef<'_>, Error> { |
| 144 | + match streaming(data)? { |
| 145 | + Stream::Complete { line, .. } => Ok(line), |
| 146 | + Stream::Incomplete { bytes_needed } => Err(Error::NotEnoughData { bytes_needed }), |
| 147 | + } |
| 148 | +} |
0 commit comments