Document that read::GzDecoder consumes bytes after end of gzip

Add tests showing that the `GzDecoder`s in `bufread` and `write`
support reading immediately after end of gzip data.

Co-authored-by: Sebastian Thiel <sebastian.thiel@icloud.com>

src/gz/bufread.rs

@@ -432,3 +432,50 @@ impl<R: BufRead> Read for MultiGzDecoder<R> {
         self.0.read(into)
     }
 }
+
+#[cfg(test)]
+mod test {
+    use crate::bufread::GzDecoder;
+    use crate::gz::write;
+    use crate::Compression;
+    use std::io::{Read, Write};
+
+    // GzDecoder consumes one gzip member and then returns 0 for subsequent reads, allowing any
+    // additional data to be consumed by the caller.
+    #[test]
+    fn decode_extra_data() {
+        let expected = "Hello World";
+
+        let compressed = {
+            let mut e = write::GzEncoder::new(Vec::new(), Compression::default());
+            e.write(expected.as_ref()).unwrap();
+            let mut b = e.finish().unwrap();
+            b.push(b'x');
+            b
+        };
+
+        let mut output = Vec::new();
+        let mut decoder = GzDecoder::new(compressed.as_slice());
+        let decoded_bytes = decoder.read_to_end(&mut output).unwrap();
+        assert_eq!(decoded_bytes, output.len());
+        let actual = std::str::from_utf8(&output).expect("String parsing error");
+        assert_eq!(
+            actual, expected,
+            "after decompression we obtain the original input"
+        );
+
+        output.clear();
+        assert_eq!(
+            decoder.read(&mut output).unwrap(),
+            0,
+            "subsequent read of decoder returns 0, but inner reader can return additional data"
+        );
+        let mut reader = decoder.into_inner();
+        assert_eq!(
+            reader.read_to_end(&mut output).unwrap(),
+            1,
+            "extra data is accessible in underlying buf-read"
+        );
+        assert_eq!(output, b"x");
+    }
+}

src/gz/read.rs

@@ -90,7 +90,7 @@ impl<R: Read + Write> Write for GzEncoder<R> {
     }
 }
 
-/// A decoder for the first member of a [gzip file].
+/// A decoder for a single member of a [gzip file].
 ///
 /// This structure exposes a [`Read`] interface that will consume compressed
 /// data from the underlying reader and emit uncompressed data.
@@ -155,19 +155,29 @@ impl<R> GzDecoder<R> {
     }
 
     /// Acquires a reference to the underlying reader.
+    ///
+    /// Note that the decoder may have read past the end of the gzip data.
+    /// To prevent this use [`bufread::GzDecoder`] instead.
     pub fn get_ref(&self) -> &R {
         self.inner.get_ref().get_ref()
     }
 
     /// Acquires a mutable reference to the underlying stream.
     ///
     /// Note that mutation of the stream may result in surprising results if
-    /// this decoder is continued to be used.
+    /// this decoder continues to be used.
+    ///
+    /// Note that the decoder may have read past the end of the gzip data.
+    /// To prevent this use [`bufread::GzDecoder`] instead.
     pub fn get_mut(&mut self) -> &mut R {
         self.inner.get_mut().get_mut()
     }
 
     /// Consumes this decoder, returning the underlying reader.
+    ///
+    /// Note that the decoder may have read past the end of the gzip data.
+    /// Subsequent reads will skip those bytes. To prevent this use
+    /// [`bufread::GzDecoder`] instead.
     pub fn into_inner(self) -> R {
         self.inner.into_inner().into_inner()
     }

src/gz/write.rs

@@ -610,4 +610,32 @@ mod tests {
         let expected = STR.repeat(2);
         assert_eq!(return_string, expected);
     }
+
+    // GzDecoder consumes one gzip member and then returns 0 for subsequent writes, allowing any
+    // additional data to be consumed by the caller.
+    #[test]
+    fn decode_extra_data() {
+        let compressed = {
+            let mut e = GzEncoder::new(Vec::new(), Compression::default());
+            e.write(STR.as_ref()).unwrap();
+            let mut b = e.finish().unwrap();
+            b.push(b'x');
+            b
+        };
+
+        let mut writer = Vec::new();
+        let mut decoder = GzDecoder::new(writer);
+        let mut consumed_bytes = 0;
+        loop {
+            let n = decoder.write(&compressed[consumed_bytes..]).unwrap();
+            if n == 0 {
+                break;
+            }
+            consumed_bytes += n;
+        }
+        writer = decoder.finish().unwrap();
+        let actual = String::from_utf8(writer).expect("String parsing error");
+        assert_eq!(actual, STR);
+        assert_eq!(&compressed[consumed_bytes..], b"x");
+    }
 }

src/lib.rs

@@ -117,7 +117,14 @@ mod zlib;
 /// Types which operate over [`Read`] streams, both encoders and decoders for
 /// various formats.
 ///
+/// Note that the `read` decoder types may read past the end of the compressed
+/// data while decoding. If the caller requires subsequent reads to start
+/// immediately following the compressed data  wrap the `Read` type in a
+/// [`BufReader`] and use the `BufReader` with the equivalent decoder from the
+/// `bufread` module and also for the subsequent reads.
+///
 /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
+/// [`BufReader`]: https://doc.rust-lang.org/std/io/struct.BufReader.html
 pub mod read {
     pub use crate::deflate::read::DeflateDecoder;
     pub use crate::deflate::read::DeflateEncoder;