feat: expose per-entry sizes via list_archive_entries

Adds list_archive_entries (and _with_encoding variant) returning
ArchiveEntryInfo { path, size } so callers can obtain uncompressed
sizes from the archive header without extracting the contents.
Mirrored across async_support, futures_support, and tokio_support.

list_archive_files_with_encoding is reimplemented on top of
list_archive_entries_with_encoding to share the header-walk loop.

ArchiveIterator already surfaces the same stat.st_size on
StartOfEntry for streaming users; its docs now call this out.

Closes #134

Author: otavio

CHANGES.md

@@ -4,6 +4,11 @@
 
 ## [Unreleased] - ReleaseDate
 
+* Add `list_archive_entries` (and `_with_encoding` variant) returning path and
+  uncompressed size per entry, so callers can obtain per-file sizes without
+  extracting the archive. Mirrored in `async_support`, `futures_support`, and
+  `tokio_support`. `ArchiveIterator`'s `StartOfEntry` already exposes the same
+  `stat.st_size` for streaming users [#134]
 * Fix partial unfinished archive reads [#133]
 * Add missing `advapi32` link library on Windows builds [#141]
 * Propagate `ENOSPC` during archive extraction instead of silently truncating files [#144]

src/async_support.rs

@@ -301,6 +301,36 @@ where
     wrap_async_seek_read(blocking_executor, source, crate::list_archive_files).await?
 }
 
+/// Async version of
+/// [`list_archive_entries_with_encoding`](crate::
+/// list_archive_entries_with_encoding).
+pub async fn list_archive_entries_with_encoding<B, R>(
+    blocking_executor: B,
+    source: R,
+    decode: DecodeCallback,
+) -> Result<Vec<crate::ArchiveEntryInfo>>
+where
+    B: BlockingExecutor,
+    R: AsyncRead + AsyncSeek + Unpin,
+{
+    wrap_async_seek_read(blocking_executor, source, move |source| {
+        crate::list_archive_entries_with_encoding(source, decode)
+    })
+    .await?
+}
+
+/// Async version of [`list_archive_entries`](crate::list_archive_entries).
+pub async fn list_archive_entries<B, R>(
+    blocking_executor: B,
+    source: R,
+) -> Result<Vec<crate::ArchiveEntryInfo>>
+where
+    B: BlockingExecutor,
+    R: AsyncRead + AsyncSeek + Unpin,
+{
+    wrap_async_seek_read(blocking_executor, source, crate::list_archive_entries).await?
+}
+
 /// Async version of [`uncompress_data`](crate::uncompress_data).
 pub async fn uncompress_data<B, R, W>(blocking_executor: B, source: R, target: W) -> Result<usize>
 where

src/futures_support.rs

@@ -47,6 +47,28 @@ where
     async_support::list_archive_files(FUTURES_BLOCKING_EXECUTOR, source).await
 }
 
+/// Async version of
+/// [`list_archive_entries_with_encoding`](crate::
+/// list_archive_entries_with_encoding).
+pub async fn list_archive_entries_with_encoding<R>(
+    source: R,
+    decode: DecodeCallback,
+) -> Result<Vec<crate::ArchiveEntryInfo>>
+where
+    R: AsyncRead + AsyncSeek + Unpin,
+{
+    async_support::list_archive_entries_with_encoding(FUTURES_BLOCKING_EXECUTOR, source, decode)
+        .await
+}
+
+/// Async version of [`list_archive_entries`](crate::list_archive_entries).
+pub async fn list_archive_entries<R>(source: R) -> Result<Vec<crate::ArchiveEntryInfo>>
+where
+    R: AsyncRead + AsyncSeek + Unpin,
+{
+    async_support::list_archive_entries(FUTURES_BLOCKING_EXECUTOR, source).await
+}
+
 /// Async version of [`uncompress_data`](crate::uncompress_data).
 pub async fn uncompress_data<R, W>(source: R, target: W) -> Result<usize>
 where

src/iterator.rs

@@ -259,6 +259,10 @@ impl<R: Read + Seek> ArchiveIterator<R> {
     /// Iterate over the contents of an archive, streaming the contents of each
     /// entry in small chunks.
     ///
+    /// The [`ArchiveContents::StartOfEntry`] variant carries the entry's
+    /// `stat` struct, so `stat.st_size` gives the uncompressed size reported
+    /// by the archive header without having to consume the data chunks.
+    ///
     /// ```no_run
     /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
     /// use compress_tools::*;
@@ -273,7 +277,10 @@ impl<R: Read + Seek> ArchiveIterator<R> {
     ///
     /// for content in &mut iter {
     ///     match content {
-    ///         ArchiveContents::StartOfEntry(s, _) => name = s,
+    ///         ArchiveContents::StartOfEntry(s, stat) => {
+    ///             name = s;
+    ///             println!("header reports {} bytes for {}", stat.st_size, name);
+    ///         }
     ///         ArchiveContents::DataChunk(v) => size += v.len(),
     ///         ArchiveContents::EndOfEntry => {
     ///             println!("Entry {} was {} bytes", name, size);

src/lib.rs

@@ -101,6 +101,17 @@ pub struct stat {
     pub st_ctime: libc::time_t,
 }
 
+/// Path and uncompressed size for a single archive entry.
+///
+/// `size` comes from the archive header and may be `0` for formats that do
+/// not record it there (some raw compressed streams, ZIP entries using a
+/// data descriptor). Tar and standard ZIP populate it reliably.
+#[derive(Clone, Debug)]
+pub struct ArchiveEntryInfo {
+    pub path: String,
+    pub size: u64,
+}
+
 /// Determine the ownership behavior when unpacking the archive.
 #[derive(Clone, Copy, Debug)]
 pub enum Ownership {
@@ -146,6 +157,61 @@ pub(crate) fn decode_utf8(bytes: &[u8]) -> Result<String> {
 /// # }
 /// ```
 pub fn list_archive_files_with_encoding<R>(source: R, decode: DecodeCallback) -> Result<Vec<String>>
+where
+    R: Read + Seek,
+{
+    Ok(list_archive_entries_with_encoding(source, decode)?
+        .into_iter()
+        .map(|e| e.path)
+        .collect())
+}
+
+/// Get all files in a archive using `source` as a reader.
+/// # Example
+///
+/// ```no_run
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// use compress_tools::*;
+/// use std::fs::File;
+///
+/// let mut source = File::open("tree.tar")?;
+///
+/// let file_list = list_archive_files(&mut source)?;
+/// # Ok(())
+/// # }
+/// ```
+pub fn list_archive_files<R>(source: R) -> Result<Vec<String>>
+where
+    R: Read + Seek,
+{
+    list_archive_files_with_encoding(source, decode_utf8)
+}
+
+/// Get entry metadata (path and uncompressed size) for every entry in an
+/// archive without extracting their contents.
+///
+/// See [`ArchiveEntryInfo`] for caveats on `size` reporting across formats.
+///
+/// # Example
+///
+/// ```no_run
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// use compress_tools::*;
+/// use std::fs::File;
+///
+/// let mut source = File::open("tree.tar")?;
+/// let decode_utf8 = |bytes: &[u8]| Ok(std::str::from_utf8(bytes)?.to_owned());
+///
+/// for entry in list_archive_entries_with_encoding(&mut source, decode_utf8)? {
+///     println!("{}: {} bytes", entry.path, entry.size);
+/// }
+/// # Ok(())
+/// # }
+/// ```
+pub fn list_archive_entries_with_encoding<R>(
+    source: R,
+    decode: DecodeCallback,
+) -> Result<Vec<ArchiveEntryInfo>>
 where
     R: Read + Seek,
 {
@@ -154,23 +220,28 @@ where
         Ownership::Ignore,
         source,
         |archive_reader, _, mut entry| unsafe {
-            let mut file_list = Vec::new();
+            let mut entries = Vec::new();
             loop {
                 match ffi::archive_read_next_header(archive_reader, &mut entry) {
-                    ffi::ARCHIVE_EOF => return Ok(file_list),
+                    ffi::ARCHIVE_EOF => return Ok(entries),
                     value => archive_result(value, archive_reader)?,
                 }
 
                 let _utf8_guard = ffi::WindowsUTF8LocaleGuard::new();
                 let cstr = libarchive_entry_pathname(entry)?;
-                let file_name = decode(cstr.to_bytes())?;
-                file_list.push(file_name);
+                let path = decode(cstr.to_bytes())?;
+                let size = libarchive_entry_size(entry);
+                entries.push(ArchiveEntryInfo { path, size });
             }
         },
     )
 }
 
-/// Get all files in a archive using `source` as a reader.
+/// Get entry metadata (path and uncompressed size) for every entry in an
+/// archive without extracting their contents.
+///
+/// See [`ArchiveEntryInfo`] for caveats on `size` reporting across formats.
+///
 /// # Example
 ///
 /// ```no_run
@@ -180,15 +251,17 @@ where
 ///
 /// let mut source = File::open("tree.tar")?;
 ///
-/// let file_list = list_archive_files(&mut source)?;
+/// for entry in list_archive_entries(&mut source)? {
+///     println!("{}: {} bytes", entry.path, entry.size);
+/// }
 /// # Ok(())
 /// # }
 /// ```
-pub fn list_archive_files<R>(source: R) -> Result<Vec<String>>
+pub fn list_archive_entries<R>(source: R) -> Result<Vec<ArchiveEntryInfo>>
 where
     R: Read + Seek,
 {
-    list_archive_files_with_encoding(source, decode_utf8)
+    list_archive_entries_with_encoding(source, decode_utf8)
 }
 
 /// Uncompress a file using the `source` need as reader and the `target` as a
@@ -621,6 +694,13 @@ fn libarchive_copy_data(
     }
 }
 
+fn libarchive_entry_size(entry: *mut ffi::archive_entry) -> u64 {
+    // `st_size` is `i32` on Windows (see the `stat` struct above) and `i64`
+    // on Unix. Widen through `i64` to keep the cast platform-agnostic.
+    let size = unsafe { (*ffi::archive_entry_stat(entry)).st_size } as i64;
+    size.max(0) as u64
+}
+
 fn libarchive_entry_pathname<'a>(entry: *mut ffi::archive_entry) -> Result<&'a CStr> {
     let pathname = unsafe { ffi::archive_entry_pathname(entry) };
     if pathname.is_null() {

src/tokio_support.rs

@@ -53,6 +53,32 @@ where
     async_support::list_archive_files(TOKIO_BLOCKING_EXECUTOR, source.compat()).await
 }
 
+/// Async version of
+/// [`list_archive_entries_with_encoding`](crate::
+/// list_archive_entries_with_encoding).
+pub async fn list_archive_entries_with_encoding<R>(
+    source: R,
+    decode: DecodeCallback,
+) -> Result<Vec<crate::ArchiveEntryInfo>>
+where
+    R: AsyncRead + AsyncSeek + Unpin,
+{
+    async_support::list_archive_entries_with_encoding(
+        TOKIO_BLOCKING_EXECUTOR,
+        source.compat(),
+        decode,
+    )
+    .await
+}
+
+/// Async version of [`list_archive_entries`](crate::list_archive_entries).
+pub async fn list_archive_entries<R>(source: R) -> Result<Vec<crate::ArchiveEntryInfo>>
+where
+    R: AsyncRead + AsyncSeek + Unpin,
+{
+    async_support::list_archive_entries(TOKIO_BLOCKING_EXECUTOR, source.compat()).await
+}
+
 /// Async version of [`uncompress_data`](crate::uncompress_data).
 pub async fn uncompress_data<R, W>(source: R, target: W) -> Result<usize>
 where

tests/integration_test.rs

@@ -153,6 +153,26 @@ fn successfully_list_archive_files() {
     );
 }
 
+#[test]
+fn successfully_list_archive_entries() {
+    let source = std::fs::File::open("tests/fixtures/tree.tar").unwrap();
+
+    let entries = list_archive_entries(source).unwrap();
+    let observed: Vec<(String, u64)> = entries.into_iter().map(|e| (e.path, e.size)).collect();
+
+    assert_eq!(
+        observed,
+        vec![
+            ("tree/".to_string(), 0),
+            ("tree/branch1/".to_string(), 0),
+            ("tree/branch1/leaf".to_string(), 12),
+            ("tree/branch2/".to_string(), 0),
+            ("tree/branch2/leaf".to_string(), 14),
+        ],
+        "entry list (path, size) did not match"
+    );
+}
+
 #[test]
 fn list_archive_zip() {
     let source = std::fs::File::open("tests/fixtures/test.zip").unwrap();