feat!: require real archives on archive entry points

- Stop registering libarchive's "raw" format handler in list_archive_files,
  list_archive_entries, uncompress_archive, uncompress_archive_file,
  ArchiveIterator, and their _with_encoding and async variants, so
  non-archive input now errors instead of yielding a single "data" entry.
- Add ArchiveIteratorBuilder::raw_format(bool) so callers that relied on
  the old permissive behavior can opt back in explicitly.
- Keep uncompress_data unchanged since handling raw compressed streams
  (gzip, xz, ...) is its purpose.
- Document the stricter behavior in the crate docs and CHANGES.md, update
  affected tests to opt in where needed, and bump the version to 0.16.0
  to reflect the breaking change.

Author: otavio

CHANGES.md

@@ -4,6 +4,14 @@
 
 ## [Unreleased] - ReleaseDate
 
+* **Breaking:** libarchive's "raw" format handler is no longer registered on
+  the archive code paths. `list_archive_files`, `list_archive_entries`,
+  `uncompress_archive`, `uncompress_archive_file`, `ArchiveIterator`, and
+  their `_with_encoding` and async variants now return an error for input
+  that isn't a real archive, instead of treating it as a single-entry
+  archive named `data`. `uncompress_data` still supports raw streams
+  (that is its purpose). Callers that want the old iterator behavior can
+  opt back in with `ArchiveIteratorBuilder::raw_format(true)` [#77]
 * Rewind the source reader at the start of every seekable entry point
   (`list_archive_files`, `list_archive_entries`, `uncompress_archive`,
   `uncompress_archive_file`, `ArchiveIterator`, and their `_with_encoding`

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "compress-tools"
-version = "0.15.1"
+version = "0.16.0"
 authors = ["Jonathas-Conceicao <jadoliveira@inf.ufpel.edu.br>"]
 description = "Utility functions for compressed and archive files handling"
 repository = "https://github.com/OSSystems/compress-tools-rs"

src/iterator.rs

@@ -175,6 +175,7 @@ impl<R: Read + Seek> ArchiveIterator<R> {
         decode: DecodeCallback,
         filter: Option<Box<EntryFilterCallbackFn>>,
         password: Option<ArchivePassword>,
+        raw_format: bool,
     ) -> Result<ArchiveIterator<R>>
     where
         R: Read + Seek,
@@ -204,10 +205,12 @@ impl<R: Read + Seek> ArchiveIterator<R> {
                     archive_reader,
                 )?;
 
-                archive_result(
-                    ffi::archive_read_support_format_raw(archive_reader),
-                    archive_reader,
-                )?;
+                if raw_format {
+                    archive_result(
+                        ffi::archive_read_support_format_raw(archive_reader),
+                        archive_reader,
+                    )?;
+                }
 
                 archive_result(
                     ffi::archive_read_set_seek_callback(
@@ -304,7 +307,7 @@ impl<R: Read + Seek> ArchiveIterator<R> {
     where
         R: Read + Seek,
     {
-        Self::new(source, decode, None, None)
+        Self::new(source, decode, None, None, false)
     }
 
     /// Iterate over the contents of an archive, streaming the contents of each
@@ -343,7 +346,7 @@ impl<R: Read + Seek> ArchiveIterator<R> {
     where
         R: Read + Seek,
     {
-        Self::new(source, crate::decode_utf8, None, None)
+        Self::new(source, crate::decode_utf8, None, None, false)
     }
 
     /// Close the iterator, freeing up the associated resources.
@@ -479,6 +482,7 @@ where
     decoder: DecodeCallback,
     filter: Option<Box<EntryFilterCallbackFn>>,
     password: Option<ArchivePassword>,
+    raw_format: bool,
 }
 
 /// A builder to generate an archive iterator over the contents of an
@@ -518,6 +522,7 @@ where
             decoder: crate::decode_utf8,
             filter: None,
             password: None,
+            raw_format: false,
         }
     }
 
@@ -544,8 +549,25 @@ where
         self
     }
 
+    /// Enable libarchive's "raw" format handler, which parses any byte
+    /// stream as a single-entry archive with pathname `data`.
+    ///
+    /// Disabled by default so the iterator rejects input that isn't a real
+    /// archive. Enable it only when you intentionally want to iterate over
+    /// arbitrary non-archive streams (e.g. a standalone gzip file).
+    pub fn raw_format(mut self, enable: bool) -> ArchiveIteratorBuilder<R> {
+        self.raw_format = enable;
+        self
+    }
+
     /// Finish the builder and generate the configured `ArchiveIterator`.
     pub fn build(self) -> Result<ArchiveIterator<R>> {
-        ArchiveIterator::new(self.source, self.decoder, self.filter, self.password)
+        ArchiveIterator::new(
+            self.source,
+            self.decoder,
+            self.filter,
+            self.password,
+            self.raw_format,
+        )
     }
 }

src/lib.rs

@@ -46,6 +46,21 @@
 //! # Ok(())
 //! # }
 //! ```
+//!
+//! # Strict archive parsing
+//!
+//! Archive-listing and archive-extraction entry points (`list_archive_files`,
+//! `list_archive_entries`, `uncompress_archive`, `uncompress_archive_file`,
+//! `ArchiveIterator`, and their async/`_with_encoding` siblings) no longer
+//! register libarchive's "raw" format handler. They return an error for
+//! input that isn't a real archive instead of yielding a single entry
+//! called `data`, so callers can reliably distinguish archives from other
+//! files.
+//!
+//! Use [`uncompress_data`] for decompressing a single stream (gzip, xz, …)
+//! — it continues to support raw input because that is its purpose. For
+//! streaming iteration that should accept arbitrary bytes, opt back in
+//! with [`ArchiveIteratorBuilder::raw_format`].
 
 #[cfg(feature = "async_support")]
 pub mod async_support;
@@ -526,11 +541,6 @@ where
                 archive_reader,
             )?;
 
-            archive_result(
-                ffi::archive_read_support_format_raw(archive_reader),
-                archive_reader,
-            )?;
-
             archive_result(
                 ffi::archive_read_set_seek_callback(archive_reader, Some(libarchive_seek_callback)),
                 archive_reader,

tests/integration_test.rs

@@ -1064,7 +1064,11 @@ fn iterate_zip_with_cjk_pathname() {
 fn iterate_truncated_archive() {
     let source = std::fs::File::open("tests/fixtures/truncated.log.gz").unwrap();
 
-    for content in ArchiveIterator::from_read(source).unwrap() {
+    for content in ArchiveIteratorBuilder::new(source)
+        .raw_format(true)
+        .build()
+        .unwrap()
+    {
         if let ArchiveContents::Err(Error::Unknown) = content {
             return;
         }
@@ -1076,7 +1080,11 @@ fn iterate_truncated_archive() {
 fn uncompress_bytes_helper(bytes: &[u8]) {
     let wrapper = Cursor::new(bytes);
 
-    for content in ArchiveIterator::from_read(wrapper).unwrap() {
+    for content in ArchiveIteratorBuilder::new(wrapper)
+        .raw_format(true)
+        .build()
+        .unwrap()
+    {
         if let ArchiveContents::Err(Error::Unknown) = content {
             return;
         }
@@ -1128,7 +1136,7 @@ fn uncompress_archive_absolute_path() {
 
 #[test]
 fn decode_failure() {
-    let source = std::fs::File::open("tests/fixtures/file.txt.gz").unwrap();
+    let source = std::fs::File::open("tests/fixtures/tree.tar").unwrap();
     let decode_fail = |_bytes: &[u8]| Err(Error::Io(std::io::Error::from(ErrorKind::BrokenPipe)));
 
     for content in ArchiveIterator::from_read_with_encoding(source, decode_fail).unwrap() {
@@ -1371,3 +1379,55 @@ fn archive_password_with_nul_byte_rejected() {
         "passwords containing NUL must be rejected, not panic",
     );
 }
+
+// Arbitrary binary blob that matches no libarchive format handler. Used to
+// prove the "raw" handler is the thing making this parseable: strict mode
+// errors, raw_format(true) accepts it as a single "data" entry.
+const NON_ARCHIVE_BYTES: &[u8] = &[
+    0x00, 0x01, 0x02, 0x03, 0xff, 0xfe, 0xfd, 0xfc, 0x10, 0x20, 0x30, 0x40, 0x50, 0x60, 0x70, 0x80,
+];
+
+#[test]
+fn list_archive_files_rejects_non_archive_bytes() {
+    let source = Cursor::new(NON_ARCHIVE_BYTES);
+    assert!(
+        list_archive_files(source).is_err(),
+        "arbitrary bytes must no longer be listed as a single \"data\" entry",
+    );
+}
+
+#[test]
+fn uncompress_archive_rejects_non_archive_bytes() {
+    let source = Cursor::new(NON_ARCHIVE_BYTES);
+    let dir = tempfile::TempDir::new().unwrap();
+    assert!(uncompress_archive(source, dir.path(), Ownership::Ignore).is_err());
+}
+
+#[test]
+fn iterator_default_rejects_non_archive_bytes() {
+    let source = Cursor::new(NON_ARCHIVE_BYTES);
+    let saw_err = match ArchiveIterator::from_read(source) {
+        Err(_) => true,
+        Ok(iter) => iter.into_iter().any(|c| matches!(c, ArchiveContents::Err(_))),
+    };
+    assert!(
+        saw_err,
+        "strict iterator must surface an error on non-archive input"
+    );
+}
+
+#[test]
+fn iterator_raw_format_opt_in_accepts_non_archive_bytes() {
+    let source = Cursor::new(NON_ARCHIVE_BYTES);
+    let mut names = Vec::new();
+    for content in ArchiveIteratorBuilder::new(source)
+        .raw_format(true)
+        .build()
+        .expect("raw_format(true) should accept arbitrary bytes")
+    {
+        if let ArchiveContents::StartOfEntry(name, _) = content {
+            names.push(name);
+        }
+    }
+    assert_eq!(names, vec!["data".to_string()]);
+}