[protocol] side-band channel encoding and decoding

Author: Byron

README.md

@@ -97,7 +97,7 @@ Please see _'Development Status'_ for a listing of all crates and their capabili
     * [x] encode
     * [x] decode (zero-copy)
     * [x] [error line](https://github.com/git/git/blob/master/Documentation/technical/pack-protocol.txt#L28:L28)
-    * [ ] [V2 additions](https://github.com/git/git/blob/master/Documentation/technical/protocol-v2.txt#L35:L36)
+    * [x] [V2 additions](https://github.com/git/git/blob/master/Documentation/technical/protocol-v2.txt#L35:L36)
     * [ ] [side-band mode](https://github.com/git/git/blob/master/Documentation/technical/pack-protocol.txt#L467:L467)
   * [ ] `Iterator` for multi-plexed pack lines from `Read`
   * [ ] parse and serialize [capabilities](https://github.com/git/git/blob/master/Documentation/technical/protocol-capabilities.txt#L1:L1)

git-protocol/src/packet_line/encode.rs

@@ -1,4 +1,4 @@
-use crate::packet_line::{DELIMITER_LINE, ERR_PREFIX, FLUSH_LINE, MAX_DATA_LEN, RESPONSE_END_LINE};
+use crate::packet_line::{Channel, DELIMITER_LINE, ERR_PREFIX, FLUSH_LINE, MAX_DATA_LEN, RESPONSE_END_LINE};
 use quick_error::quick_error;
 use std::io;
 
@@ -32,29 +32,34 @@ pub fn flush_to_write(mut out: impl io::Write) -> io::Result<usize> {
 }
 
 pub fn error_to_write(data: &[u8], out: impl io::Write) -> Result<usize, Error> {
-    let data_with_prefix_end = data.len() + ERR_PREFIX.len();
-    if data_with_prefix_end > MAX_DATA_LEN {
-        return Err(Error::DataLengthLimitExceeded(data.len() - ERR_PREFIX.len()));
-    }
-    // This is a big buffer, but it's only used on error, so the program is on the way out
-    let mut buf = [0u8; MAX_DATA_LEN];
-    buf[..ERR_PREFIX.len()].copy_from_slice(ERR_PREFIX);
-    buf[ERR_PREFIX.len()..data_with_prefix_end].copy_from_slice(data);
-    data_to_write(&buf[..data_with_prefix_end], out)
+    prefixed_data_to_write(ERR_PREFIX, data, out)
+}
+
+pub fn band_to_write(kind: Channel, data: &[u8], out: impl io::Write) -> Result<usize, Error> {
+    prefixed_data_to_write(&[kind as u8], data, out)
 }
 
-pub fn data_to_write(data: &[u8], mut out: impl io::Write) -> Result<usize, Error> {
-    if data.len() > MAX_DATA_LEN {
-        return Err(Error::DataLengthLimitExceeded(data.len()));
+pub fn data_to_write(data: &[u8], out: impl io::Write) -> Result<usize, Error> {
+    prefixed_data_to_write(&[], data, out)
+}
+
+fn prefixed_data_to_write(prefix: &[u8], data: &[u8], mut out: impl io::Write) -> Result<usize, Error> {
+    let data_len = prefix.len() + data.len();
+    if data_len > MAX_DATA_LEN {
+        return Err(Error::DataLengthLimitExceeded(data_len));
     }
     if data.is_empty() {
         return Err(Error::DataIsEmpty);
     }
 
     let mut buf = [0u8; 4];
-    let data_len = data.len() + 4;
+    let data_len = data_len + 4;
     hex::encode_to_slice((data_len as u16).to_be_bytes(), &mut buf).expect("two bytes to 4 hex chars never fails");
+
     out.write_all(&buf)?;
+    if !prefix.is_empty() {
+        out.write_all(prefix)?;
+    }
     out.write_all(data)?;
     Ok(data_len)
 }

git-protocol/src/packet_line/mod.rs

@@ -40,8 +40,35 @@ impl<'a> Borrowed<'a> {
     pub fn to_error(&self) -> Error {
         Error(self.as_slice())
     }
+    pub fn to_band(&self, kind: Channel) -> Band {
+        let d = match self {
+            Borrowed::Data(d) => d,
+            _ => panic!("cannot side-channel non-data lines"),
+        };
+
+        match kind {
+            Channel::Data => Band::Data(d),
+            Channel::Progress => Band::Progress(d),
+            Channel::Error => Band::Error(d),
+        }
+    }
+    /// Decode the band of the line, or panic if it is not actually a side-band line
+    pub fn decode_band(&self) -> Band {
+        let d = match self {
+            Borrowed::Data(d) => d,
+            _ => panic!("cannot decode side-channel information from non-data lines"),
+        };
+        match d[0] {
+            1 => Band::Data(&d[1..]),
+            2 => Band::Progress(&d[1..]),
+            3 => Band::Error(&d[1..]),
+            _ => panic!("attempt to decode a non-side channel line"),
+        }
+    }
 }
 
+#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
+#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
 pub struct Error<'a>(&'a [u8]);
 
 impl<'a> Error<'a> {
@@ -50,5 +77,31 @@ impl<'a> Error<'a> {
     }
 }
 
+#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
+#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
+pub enum Band<'a> {
+    Data(&'a [u8]),
+    Progress(&'a [u8]),
+    Error(&'a [u8]),
+}
+
+impl<'a> Band<'a> {
+    pub fn to_write(&self, out: impl io::Write) -> Result<usize, encode::Error> {
+        match self {
+            Band::Data(d) => encode::band_to_write(Channel::Data, d, out),
+            Band::Progress(d) => encode::band_to_write(Channel::Progress, d, out),
+            Band::Error(d) => encode::band_to_write(Channel::Error, d, out),
+        }
+    }
+}
+
+#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
+#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
+pub enum Channel {
+    Data = 1,
+    Progress = 2,
+    Error = 3,
+}
+
 pub mod decode;
 pub mod encode;

git-protocol/tests/packet_line/decode.rs

@@ -1,5 +1,6 @@
 mod streaming {
     use crate::packet_line::assert_err_display;
+    use git_protocol::packet_line::Channel;
     use git_protocol::{
         packet_line::decode::{self, streaming, Stream},
         PacketLine,
@@ -87,6 +88,23 @@ mod streaming {
         Ok(())
     }
 
+    #[test]
+    fn roundtrip_side_bands() -> crate::Result {
+        for channel in &[Channel::Data, Channel::Error, Channel::Progress] {
+            let mut out = Vec::new();
+            let band = PacketLine::Data(b"band data").to_band(*channel);
+            band.to_write(&mut out)?;
+            match streaming(&out)? {
+                Stream::Complete { line, bytes_consumed } => {
+                    assert_eq!(bytes_consumed, out.len());
+                    assert_eq!(line.decode_band(), band);
+                }
+                Stream::Incomplete { .. } => panic!("roundtrips are never incomplete"),
+            }
+        }
+        Ok(())
+    }
+
     mod incomplete {
         use git_protocol::packet_line::decode::{self, streaming, Stream};