archive_r_ruby 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 073f63cf2d5a0b176c74824c73c10e2aa95e3038a01212812c8d10655c71727c
-  data.tar.gz: 84d8e7c7c4f2b83696024bec5df22d5e6943f42732f17ff7ad1be6fb20831bd1
+  metadata.gz: 648064959d139565d2e122215cb49ae178b9d5e735a99176b8d785238b753800
+  data.tar.gz: d9f05748fbcca7aa76bb615b53480c9133423905c1137005d1c6df895a8b09c3
 SHA512:
-  metadata.gz: acd57fa4d9d0009832296a1a48b53c2b04959a639f291ffe564f62f23d40feddc66ec42289f788668e89d11728f09d4ebb3d7f0abc185c20f62e05622140c0a0
-  data.tar.gz: 802effdd52cbc83796e27d81a87ec75745d4993c3f2bde1619a3489ab18730e4f6ed2b39f70f8987b5bbb7765f013a18ad360c54e52c59defe53ae0ccdf88cc5
+  metadata.gz: dd1b45fd72e08536d0b95b261b8ca071d68fa0a1840c984c9d5aae4d9449b394a11ad6e7f8a4ca8df53b68ee7aef68791468e98404fd6a4ec098a34d831affd6
+  data.tar.gz: ebf2a08b3ff59ba317b48cd175d87bf0624e2d4c67d2c95c90b1c8fb32cd9c1afa6ff48f0d24cb467401d3b9b2364cf368946cf4af01e8bdb744431ee9cd961f

data/LICENSE.txt

@@ -1,5 +1,5 @@
 archive_r License
-Version: 0.1.3 (2025-12-02)
+Version: 0.1.7 (2025-12-16)
 
 ----------------------------------------
 Primary License
@@ -66,12 +66,32 @@ The following components are redistributed only because libarchive (bundled with
    - Purpose: libarchive dependency providing Zstandard compression; shipped within archive_r binaries.
    - License: BSD License (https://github.com/facebook/zstd)
 
-8. OpenSSL 3
-   - Purpose: libarchive dependency providing cryptographic support for encrypted archives; included with archive_r packages.
-   - License: Apache License 2.0 with OpenSSL exception (https://www.openssl.org/source/license.html)
+8. Nettle
+   - Purpose: libarchive dependency providing cryptographic support (macOS/Linux); bundled with archive_r binaries.
+   - License: GNU LGPLv3+ or GNU GPLv2+ (https://www.lysator.liu.se/~nisse/nettle/)
 
-9. libiconv / libcharset
-   - Purpose: libxml2/libarchive dependency for character set conversion; redistributed with archive_r artifacts.
-   - License: GNU LGPLv2.1+ (https://www.gnu.org/software/libiconv/)
+9. mini-gmp
+   - Purpose: Nettle dependency for arithmetic operations (macOS/Linux); bundled with archive_r binaries.
+   - License: GNU LGPLv3+ or GNU GPLv2+ (https://gmplib.org/)
+
+10. OpenSSL 3
+   - Purpose: libarchive dependency providing cryptographic support (Windows); bundled with archive_r Windows wheels.
+    - License: Apache License 2.0 with OpenSSL exception (https://www.openssl.org/source/license.html)
+
+11. lz4
+   - Purpose: libarchive dependency providing LZ4 compression; shipped with archive_r artifacts when required.
+   - License: BSD 2-Clause (https://github.com/lz4/lz4)
+
+12. libb2 (BLAKE2)
+   - Purpose: libarchive dependency providing BLAKE2 hashing; bundled when archive formats require it.
+   - License: CC0 1.0 Universal (https://github.com/BLAKE2/libb2)
+
+13. libattr
+   - Purpose: libarchive dependency providing extended attribute support on POSIX platforms; included in POSIX builds only.
+   - License: LGPL-2.1-or-later for the library (https://savannah.nongnu.org/projects/attr)
+
+14. libacl
+   - Purpose: libarchive dependency providing POSIX ACL support; included in POSIX builds only.
+   - License: LGPL-2.1-or-later for the library (https://savannah.nongnu.org/projects/acl)
 Users of archive_r should review the linked third-party licenses to ensure
 compliance with their terms when redistributing this software.

data/README.md

@@ -1,5 +1,8 @@
 # archive_r Ruby Binding
 
+Ruby bindings for archive_r, a libarchive-based library for processing many archive formats.
+It streams entry data directly from the source to recursively read nested archives without extracting to temporary files or loading large in-memory buffers.
+
 Ruby bindings expose the archive_r traverser API with a natural, block-friendly interface. This document consolidates the Ruby-specific instructions that previously lived in the repository root README.
 
 ## Requirements
@@ -37,9 +40,9 @@ bundle exec rake build     # creates archive_r-<version>.gem locally
 
 The `rake test` task compiles the extension, installs it into `lib/`, and executes the Minitest suite.
 
-## Running the full repository test suite
+## Running the repository test suite
 
-`./run_tests.sh` prepares a clean GEM_HOME (`build/ruby_gem_home`), installs the gem produced in `build/bindings/ruby`, and runs `bindings/ruby/test/test_traverser.rb`. The script now streams the `gem install` log to the console and preserves it in `build/logs/ruby_gem_install.log` for later inspection.
+From the repository root run `./bindings/ruby/run_binding_tests.sh`. The script prepares a clean GEM_HOME (`build/ruby_gem_home`), installs the gem produced in `build/bindings/ruby`, runs `bindings/ruby/test/test_traverser.rb`, and saves the install log to `build/logs/ruby_gem_install.log`. CI invokes this script after the core tests.
 
 ## Usage Example
 

data/ext/archive_r/archive_r_ext.cc

@@ -72,11 +72,7 @@ static VALUE path_entry_to_rb(const PathEntry &entry) {
     }
     return array;
   }
-  VALUE array = rb_ary_new_capa(entry.nested_nodes().size());
-  for (const auto &child : entry.nested_nodes()) {
-    rb_ary_push(array, path_entry_to_rb(child));
-  }
-  return array;
+  return Qnil;
 }
 
 static VALUE path_hierarchy_to_rb(const PathHierarchy &hierarchy) {
@@ -118,7 +114,7 @@ public:
   }
 
   ~RubyUserStream() override {
-    release_active_io();
+    release_active_io_resources(false);
     rb_gc_unregister_address(&_ruby_stream);
   }
 
@@ -140,7 +136,7 @@ protected:
 
   void close_single_part() override {
     if (_has_open_part_io) {
-      release_active_io();
+      release_active_io_resources(true);
       if (_has_close_part_io) {
         rb_funcall(_ruby_stream, rb_id_close_part_io_method, 0);
       }
@@ -250,7 +246,7 @@ private:
     if (!rb_respond_to(io, rb_id_read_method)) {
       rb_raise(rb_eTypeError, "open_part_io must return an object responding to #read");
     }
-    release_active_io();
+    release_active_io_resources(true);
     _active_io = io;
     rb_gc_register_address(&_active_io);
     _active_io_seekable = rb_respond_to(io, rb_id_seek_method);
@@ -259,11 +255,11 @@ private:
     _active_io_has_size = rb_respond_to(io, rb_id_size_method);
   }
 
-  void release_active_io() {
+  void release_active_io_resources(bool close_io) {
     if (_active_io == Qnil) {
       return;
     }
-    if (_active_io_has_close) {
+    if (close_io && _active_io_has_close) {
       rb_funcall(_active_io, rb_id_close_method, 0);
     }
     rb_gc_unregister_address(&_active_io);
@@ -509,12 +505,7 @@ static PathEntry rb_value_to_path_entry(VALUE value) {
     return PathEntry::multi_volume(std::move(parts));
   }
 
-  PathEntry::NodeList nodes;
-  nodes.reserve(static_cast<size_t>(length));
-  for (long i = 0; i < length; ++i) {
-    nodes.emplace_back(rb_value_to_path_entry(rb_ary_entry(array, i)));
-  }
-  return PathEntry::nested(std::move(nodes));
+  rb_raise(rb_eTypeError, "PathEntry array must contain only Strings");
 }
 
 // Helper: Convert Ruby path argument into vector of PathHierarchy

data/ext/archive_r/extconf.rb

@@ -46,6 +46,7 @@ end
 archive_r_include = File.join(archive_r_root, 'include')
 archive_r_src = File.join(archive_r_root, 'src')
 archive_r_lib_dir = File.join(archive_r_root, 'build')
+archive_r_local_libs = File.expand_path('.libs', __dir__)
 glue_source = File.join(__dir__, 'archive_r_ext.cc')
 
 # Ensure make can locate vendored sources via VPATH
@@ -58,6 +59,11 @@ $VPATH << archive_r_src
 # Add include paths
 $INCFLAGS << " -I#{archive_r_include}"
 $INCFLAGS << " -I#{archive_r_src}"
+$LIBPATH.unshift(archive_r_local_libs)
+
+unless Gem.win_platform?
+  $LDFLAGS << ' -Wl,-rpath,$ORIGIN/.libs'
+end
 
 # C++17 standard
 $CXXFLAGS << " -std=c++17"
@@ -82,31 +88,30 @@ if ENV['LIBARCHIVE_LIBRARY_DIRS']
 end
 
 # Check for libarchive
-unless have_library('archive')
-  # Try alternative names for Windows/Static builds
-  unless have_library('archive_static') || have_library('libarchive')
-    abort "libarchive is required but not found"
-  end
+unless have_library('archive') || have_library('libarchive')
+  abort "libarchive is required but not found"
 end
 
-# Try to link with pre-built static library first
-prebuilt_lib = File.join(archive_r_lib_dir, 'libarchive_r_core.a')
-prebuilt_lib_win = File.join(archive_r_lib_dir, 'archive_r_core.lib')
-prebuilt_lib_win_release = File.join(archive_r_lib_dir, 'Release', 'archive_r_core.lib')
-
-if File.exist?(prebuilt_lib)
-  $LOCAL_LIBS << " #{prebuilt_lib}"
-  puts "Using pre-built archive_r core library (Unix style)"
-elsif File.exist?(prebuilt_lib_win)
-  $LOCAL_LIBS << " \"#{prebuilt_lib_win}\""
-  puts "Using pre-built archive_r core library (Windows style)"
-elsif File.exist?(prebuilt_lib_win_release)
-  $LOCAL_LIBS << " \"#{prebuilt_lib_win_release}\""
-  puts "Using pre-built archive_r core library (Windows Release style)"
+shared_candidates = [
+  File.join(archive_r_lib_dir, 'libarchive_r_core.so'),
+  File.join(archive_r_lib_dir, 'libarchive_r_core.dylib'),
+  File.join(archive_r_lib_dir, 'archive_r_core.dll'),
+  File.join(archive_r_lib_dir, 'archive_r_core.lib'),
+  File.join(archive_r_lib_dir, 'Release', 'archive_r_core.dll'),
+  File.join(archive_r_lib_dir, 'Release', 'archive_r_core.lib'),
+  File.join(archive_r_local_libs, 'libarchive_r_core.so'),
+  File.join(archive_r_local_libs, 'libarchive_r_core.dylib'),
+  File.join(archive_r_local_libs, 'archive_r_core.dll'),
+]
+
+found_shared = shared_candidates.find { |path| File.exist?(path) }
+
+if found_shared
+  $LIBPATH.unshift(File.dirname(found_shared))
+  $libs = "-larchive_r_core #{$libs}"
+  puts "Using pre-built shared archive_r core: #{found_shared}"
 else
-  # Build from source as fallback (ensure the Ruby glue source is compiled too)
-  puts "Pre-built library not found, will build from source"
-
+  puts "Pre-built shared library not found, will build from source"
   srcs = [glue_source] + Dir.glob(File.join(archive_r_src, '*.cc'))
   $srcs = srcs
 end

data/ext/archive_r/vendor/archive_r/LICENSE.txt

@@ -1,5 +1,5 @@
 archive_r License
-Version: 0.1.3 (2025-12-02)
+Version: 0.1.7 (2025-12-16)
 
 ----------------------------------------
 Primary License
@@ -66,12 +66,32 @@ The following components are redistributed only because libarchive (bundled with
    - Purpose: libarchive dependency providing Zstandard compression; shipped within archive_r binaries.
    - License: BSD License (https://github.com/facebook/zstd)
 
-8. OpenSSL 3
-   - Purpose: libarchive dependency providing cryptographic support for encrypted archives; included with archive_r packages.
-   - License: Apache License 2.0 with OpenSSL exception (https://www.openssl.org/source/license.html)
+8. Nettle
+   - Purpose: libarchive dependency providing cryptographic support (macOS/Linux); bundled with archive_r binaries.
+   - License: GNU LGPLv3+ or GNU GPLv2+ (https://www.lysator.liu.se/~nisse/nettle/)
 
-9. libiconv / libcharset
-   - Purpose: libxml2/libarchive dependency for character set conversion; redistributed with archive_r artifacts.
-   - License: GNU LGPLv2.1+ (https://www.gnu.org/software/libiconv/)
+9. mini-gmp
+   - Purpose: Nettle dependency for arithmetic operations (macOS/Linux); bundled with archive_r binaries.
+   - License: GNU LGPLv3+ or GNU GPLv2+ (https://gmplib.org/)
+
+10. OpenSSL 3
+   - Purpose: libarchive dependency providing cryptographic support (Windows); bundled with archive_r Windows wheels.
+    - License: Apache License 2.0 with OpenSSL exception (https://www.openssl.org/source/license.html)
+
+11. lz4
+   - Purpose: libarchive dependency providing LZ4 compression; shipped with archive_r artifacts when required.
+   - License: BSD 2-Clause (https://github.com/lz4/lz4)
+
+12. libb2 (BLAKE2)
+   - Purpose: libarchive dependency providing BLAKE2 hashing; bundled when archive formats require it.
+   - License: CC0 1.0 Universal (https://github.com/BLAKE2/libb2)
+
+13. libattr
+   - Purpose: libarchive dependency providing extended attribute support on POSIX platforms; included in POSIX builds only.
+   - License: LGPL-2.1-or-later for the library (https://savannah.nongnu.org/projects/attr)
+
+14. libacl
+   - Purpose: libarchive dependency providing POSIX ACL support; included in POSIX builds only.
+   - License: LGPL-2.1-or-later for the library (https://savannah.nongnu.org/projects/acl)
 Users of archive_r should review the linked third-party licenses to ensure
 compliance with their terms when redistributing this software.

data/ext/archive_r/vendor/archive_r/include/archive_r/data_stream.h

@@ -3,23 +3,13 @@
 
 #pragma once
 
+#include "archive_r/platform_compat.h"
 #include "archive_r/path_hierarchy.h"
 
 #include <functional>
 #include <memory>
-#include <sys/types.h>
 #include <cstdint>
 
-#ifdef _WIN32
-#include <basetsd.h>
-using ssize_t = SSIZE_T;
-#endif
-
-// Avoid conflict with potential 'read' macro on Windows
-#ifdef read
-#undef read
-#endif
-
 namespace archive_r {
 
 /**

data/ext/archive_r/vendor/archive_r/include/archive_r/entry.h

@@ -7,17 +7,12 @@
 #include <filesystem>
 #include <memory>
 #include <string>
-#include <sys/types.h>
 #include <vector>
 
-#ifdef _MSC_VER
-#include <BaseTsd.h>
-typedef SSIZE_T ssize_t;
-#endif
-
 #include "archive_r/entry_fault.h"
 #include "archive_r/entry_metadata.h"
 #include "archive_r/path_hierarchy.h"
+#include "archive_r/platform_compat.h"
 
 namespace archive_r {
 
@@ -36,8 +31,21 @@ struct MultiVolumeGroupOptions {
  * - Content access (read operations)
  * - Multi-volume archive grouping support
  *
- * Entry objects are typically obtained from ArchiveTraverser::Iterator and
- * remain valid until the iterator advances.
+ * \par Lifetime and Copying
+ * - An Entry& obtained while iterating a Traverser is typically valid until the
+ *   iterator advances.
+ * - Entry is copyable. Copies retain metadata (name/path/metadata/etc), but do not
+ *   retain traverser-managed traversal control state. Calling set_descent() or
+ *   set_multi_volume_group() on such copies will report a fault and has no effect.
+ *   Prefer calling these control methods on the Entry& inside the iteration loop,
+ *   before advancing.
+ *
+ * \par Reading
+ * - read() returns >0 for bytes read, 0 for EOF, -1 for error.
+ * - On error, read() dispatches an EntryFault via the registered fault callback
+ *   (if any).
+ * - After any successful read() (including EOF), descent is disabled until
+ *   explicitly re-enabled via set_descent(true).
  */
 class Entry {
 public:
@@ -89,8 +97,8 @@ public:
   /**
    * @brief Read data from the entry
    *
-  * Each call uses an internal ArchiveStackOrchestrator so reads remain valid even
-  * if the owning iterator advances or other traversal work continues in parallel.
+    * Each call uses an internal ArchiveStackOrchestrator so reads remain valid even
+    * if the owning iterator advances.
    *
    * @param buffer Buffer to read data into
    * @param length Maximum number of bytes to read
@@ -101,6 +109,9 @@ public:
   /**
    * @brief Enable or disable automatic descent into this entry
    * @param enabled true to descend (default), false to keep traversal at current level
+    *
+    * This control is only available for entries that are managed by a Traverser.
+    * Calling this on an Entry that is not traverser-managed reports a fault.
    */
   void set_descent(bool enabled);
 
@@ -128,6 +139,9 @@ public:
    *     }
    * }
    * @endcode
+  *
+  * This control is only available for entries that are managed by a Traverser.
+  * Calling this on an Entry that is not traverser-managed reports a fault.
    */
   void set_multi_volume_group(const std::string &base_name, const MultiVolumeGroupOptions &options = {});
 

data/ext/archive_r/vendor/archive_r/include/archive_r/path_hierarchy.h

@@ -18,7 +18,6 @@ namespace archive_r {
  * A component can be one of three shapes:
  * - single string value (most common)
  * - multi-volume part list (split archives that share a common base name)
- * - nested list of child entries (used for synthetic grouping)
  */
 class PathEntry {
 public:
@@ -27,8 +26,6 @@ public:
     enum class Ordering { Natural, Given } ordering = Ordering::Natural;
   };
 
-  using NodeList = std::vector<PathEntry>;
-
   PathEntry() = default;
 
   explicit PathEntry(std::string value)
@@ -37,9 +34,6 @@ public:
   explicit PathEntry(Parts parts)
       : _value(std::move(parts)) {}
 
-  explicit PathEntry(NodeList nodes)
-      : _value(std::move(nodes)) {}
-
   static PathEntry single(std::string entry) { return PathEntry(std::move(entry)); }
 
   static PathEntry multi_volume(std::vector<std::string> entries, Parts::Ordering ordering = Parts::Ordering::Natural) {
@@ -50,24 +44,14 @@ public:
     return PathEntry(std::move(parts));
   }
 
-  static PathEntry nested(NodeList hierarchies) {
-    if (hierarchies.empty()) {
-      throw std::invalid_argument("nested hierarchies cannot be empty");
-    }
-    return PathEntry(std::move(hierarchies));
-  }
-
   bool is_single() const { return std::holds_alternative<std::string>(_value); }
   bool is_multi_volume() const { return std::holds_alternative<Parts>(_value); }
-  bool is_nested() const { return std::holds_alternative<NodeList>(_value); }
   const std::string &single_value() const { return std::get<std::string>(_value); }
   const Parts &multi_volume_parts() const { return std::get<Parts>(_value); }
   Parts &multi_volume_parts_mut() { return std::get<Parts>(_value); }
-  const NodeList &nested_nodes() const { return std::get<NodeList>(_value); }
-  NodeList &nested_nodes_mut() { return std::get<NodeList>(_value); }
 
 private:
-  std::variant<std::string, Parts, NodeList> _value;
+  std::variant<std::string, Parts> _value;
 };
 
 using PathHierarchy = std::vector<PathEntry>;
@@ -76,11 +60,10 @@ using PathHierarchy = std::vector<PathEntry>;
  * Compare two entries using the ordering enforced throughout archive_r.
  *
  * Ordering rules:
- * 1. Entry categories are ordered single < multi-volume < nested node-list.
+ * 1. Entry categories are ordered single < multi-volume.
  * 2. Single entries compare by string value.
  * 3. Multi-volume entries first compare their ordering flag (Natural < Given),
  *    then compare corresponding part names lexicographically, finally by list length.
- * 4. Nested node-lists compare child entries pairwise using the same rules.
  */
 int compare_entries(const PathEntry &lhs, const PathEntry &rhs);
 

data/ext/archive_r/vendor/archive_r/include/archive_r/platform_compat.h

@@ -7,8 +7,8 @@
 
 #if defined(_WIN32)
 #  include <sys/stat.h>
+#  include <BaseTsd.h>
 #  if !defined(_SSIZE_T_DEFINED)
-#    include <BaseTsd.h>
 using ssize_t = SSIZE_T;
 #    define _SSIZE_T_DEFINED
 #  endif
@@ -17,3 +17,18 @@ using mode_t = unsigned short; // MSVC does not expose POSIX mode_t by default
 #    define _MODE_T_DEFINED
 #  endif
 #endif
+
+namespace archive_r {
+
+// Expose POSIX-like types within the archive_r namespace.
+// - On POSIX platforms, ssize_t/mode_t come from <sys/types.h>.
+// - On Windows, platform_compat provides fallback definitions above.
+#if defined(_WIN32)
+using ssize_t = SSIZE_T;
+using mode_t = unsigned short;
+#else
+using ssize_t = ::ssize_t;
+using mode_t = ::mode_t;
+#endif
+
+} // namespace archive_r

data/ext/archive_r/vendor/archive_r/include/archive_r/traverser.h

@@ -30,9 +30,31 @@ struct TraverserOptions {
  * and filesystem directories.
  *
  * Uses std::filesystem for directory traversal and ArchiveStackOrchestrator for archives.
-
  * @see Entry, ArchiveStackOrchestrator
  *
+ * \par Inputs
+ * - The input list must not be empty, and each PathHierarchy must not be empty.
+ *   Violations throw std::invalid_argument.
+ * - For the common single-root case, prefer make_single_path("...") or
+ *   Traverser(const std::string&, ...).
+ *
+ * \par How Roots Are Interpreted
+ * - If the root hierarchy is exactly one single path and it refers to a directory,
+ *   Traverser enumerates it using std::filesystem::recursive_directory_iterator.
+ * - Otherwise, Traverser attempts archive traversal using libarchive.
+ *
+ * \par Error Model (Exceptions vs Faults)
+ * - Invalid arguments are reported via exceptions (std::invalid_argument).
+ * - Recoverable data / I/O errors during archive traversal are reported via the
+ *   global fault callback (EntryFault) and traversal continues.
+ * - Directory traversal uses std::filesystem iterators; filesystem exceptions
+ *   (e.g. std::filesystem::filesystem_error) may be thrown and are not converted
+ *   to faults.
+ *
+ * \par Iterator Semantics
+ * - Traverser::Iterator is an input iterator (single-pass).
+ * - Dereferencing the end iterator throws std::logic_error.
+ *
  * Usage:
  *   Traverser traverser({make_single_path("archive.tar.gz")});  // or directory path
  *   for (Entry& entry : traverser) {
@@ -53,9 +75,21 @@ public:
    * Provide one or more paths to traverse. Single-path traversal can be
    * achieved by passing a container with one element:
    *   Traverser traverser({make_single_path("archive.tar.gz")});
+  *
+  * @throws std::invalid_argument if paths is empty or contains an empty hierarchy
    */
   explicit Traverser(std::vector<PathHierarchy> paths, TraverserOptions options = {});
 
+  /**
+   * @brief Construct traverser for a single hierarchy
+   */
+  explicit Traverser(PathHierarchy path, TraverserOptions options = {});
+
+  /**
+   * @brief Construct traverser for a single archive or directory path
+   */
+  explicit Traverser(const std::string &path, TraverserOptions options = {});
+
   ~Traverser();
 
   // Non-copyable

data/ext/archive_r/vendor/archive_r/src/archive_stack_cursor.cc

@@ -60,6 +60,11 @@ void StreamArchive::rewind() {
 
 PathHierarchy StreamArchive::source_hierarchy() const { return _stream->source_hierarchy(); }
 
+std::shared_ptr<StreamArchive> StreamArchive::parent_archive() const {
+  auto entry_stream = std::dynamic_pointer_cast<EntryPayloadStream>(_stream);
+  return entry_stream ? entry_stream->parent_archive() : nullptr;
+}
+
 la_ssize_t StreamArchive::read_callback_bridge(struct archive *a, void *client_data, const void **buff) {
   auto *archive = static_cast<StreamArchive *>(client_data);
 
@@ -120,7 +125,9 @@ EntryPayloadStream::EntryPayloadStream(std::shared_ptr<StreamArchive> parent_arc
   }
 }
 
-EntryPayloadStream::~EntryPayloadStream() = default;
+EntryPayloadStream::~EntryPayloadStream() {
+  deactivate_active_part();
+}
 
 std::shared_ptr<StreamArchive> EntryPayloadStream::parent_archive() const { return _parent_archive; }
 
@@ -143,11 +150,8 @@ void EntryPayloadStream::open_single_part(const PathHierarchy &single_part) {
 }
 
 void EntryPayloadStream::close_single_part() {
-  if (_parent_archive->current_entryname.empty()) {
-    return;
-  }
-
-  _parent_archive->skip_data();
+  // libarchive automatically skips unread data when reading the next header,
+  // so explicit skipping here is unnecessary and avoids potential exceptions in destructor.
 }
 
 ssize_t EntryPayloadStream::read_from_single_part(void *buffer, size_t size) {
@@ -170,7 +174,8 @@ int64_t EntryPayloadStream::size_of_single_part(const PathHierarchy &single_part
 
 ArchiveStackCursor::ArchiveStackCursor()
     : options_snapshot()
-    , stream_stack() {}
+    , _current_stream(nullptr)
+    , _current_archive(nullptr) {}
 
 void ArchiveStackCursor::configure(const ArchiveOption &options) {
   options_snapshot = options;
@@ -178,16 +183,16 @@ void ArchiveStackCursor::configure(const ArchiveOption &options) {
 
 void ArchiveStackCursor::reset() {
   options_snapshot = ArchiveOption{};
-  stream_stack.clear();
+  _current_stream = nullptr;
+  _current_archive = nullptr;
 }
 
 bool ArchiveStackCursor::descend() {
-  if (stream_stack.empty()) {
-    throw std::logic_error("stream stack is empty");
+  if (!_current_stream) {
+    throw std::logic_error("current stream is empty");
   }
 
-  auto stream = stream_stack.back();
-
+  auto stream = _current_stream;
   if (auto *archive = current_archive()) {
     if (stream && !archive->current_entry_content_ready()) {
       stream->rewind();
@@ -196,17 +201,22 @@ bool ArchiveStackCursor::descend() {
 
   PathHierarchy dummy_hierarchy = stream->source_hierarchy();
   auto archive_ptr = std::make_shared<StreamArchive>(std::move(stream), options_snapshot);
-  append_single(dummy_hierarchy, std::string{});
-  stream_stack.emplace_back(std::make_shared<EntryPayloadStream>(archive_ptr, std::move(dummy_hierarchy)));
+  _current_archive = archive_ptr;
+  _current_stream = nullptr;
   return true;
 }
 
 bool ArchiveStackCursor::ascend() {
-  if (stream_stack.size() <= 0) {
+  if (depth() <= 0) {
     return false;
   }
 
-  stream_stack.pop_back();
+  if (_current_archive) {
+    _current_stream = _current_archive->get_stream();
+    _current_archive = _current_archive->parent_archive();
+  } else {
+    _current_stream = nullptr;
+  }
 
   return true;
 }
@@ -217,6 +227,8 @@ bool ArchiveStackCursor::next() {
     return false;
   }
 
+  _current_stream = nullptr;
+
   while (true) {
     if (!archive->skip_to_next_header()) {
       return false;
@@ -225,7 +237,8 @@ bool ArchiveStackCursor::next() {
       break;
     }
   }
-  stream_stack.back() = create_stream(current_entry_hierarchy());
+
+  _current_stream = create_stream(current_entry_hierarchy());
   return true;
 }
 
@@ -233,33 +246,32 @@ bool ArchiveStackCursor::synchronize_to_hierarchy(const PathHierarchy &target_hi
   if (target_hierarchy.empty()) {
     throw_entry_fault("target hierarchy cannot be empty", {});
   }
- 
-  const size_t last_depth = target_hierarchy.size() - 1;
-  if (stream_stack.size() < target_hierarchy.size()) {
-    stream_stack.resize(target_hierarchy.size());
+
+  // 1. Ascend until we find a common ancestor
+  while (depth() > 0) {
+    auto current_h = _current_archive->source_hierarchy();
+    if (current_h.size() <= target_hierarchy.size() &&
+        hierarchies_equal(current_h, pathhierarchy_prefix_until(target_hierarchy, current_h.size() - 1))) {
+      break;
+    }
+    ascend();
   }
-  for (size_t depth = 0; depth < target_hierarchy.size(); ++depth) {
-    auto prefix = pathhierarchy_prefix_until(target_hierarchy, depth);
-    auto stream = stream_stack[depth];
 
-    // Reuse the existing stream when it already matches this prefix.
-    if (stream && hierarchies_equal(stream->source_hierarchy(), prefix)) {
-      continue;
+  // 2. Descend to target
+  for (size_t d = depth(); d < target_hierarchy.size(); ++d) {
+    auto prefix = pathhierarchy_prefix_until(target_hierarchy, d);
+
+    if (!_current_stream || !hierarchies_equal(_current_stream->source_hierarchy(), prefix)) {
+      _current_stream = create_stream(prefix);
+      _current_stream->rewind();
     }
-    // Shrink the stack to the current depth before creating a fresh stream.
-    stream_stack.resize(depth+1);
-    stream = create_stream(prefix);
-    stream_stack.back() = stream;
-    stream->rewind();
- 
-    if (depth == last_depth) {
-      return true;
+
+    if (d < target_hierarchy.size() - 1) {
+      descend();
     }
-    // Descend into the archive for the next level of the hierarchy.
-    descend();
   }
-  
-   return true;
+
+  return true;
 }
 
 ssize_t ArchiveStackCursor::read(void *buff, size_t len) {
@@ -267,38 +279,22 @@ ssize_t ArchiveStackCursor::read(void *buff, size_t len) {
     return 0;
   }
 
-  if (stream_stack.empty()) {
-    throw_entry_fault("Stream stack is empty", {});
+  if (StreamArchive *archive = current_archive()) {
+    return archive->read_current(buff, len);
   }
 
-  auto stream = stream_stack.back();
-  ssize_t bytes = 0;
-  bytes = stream->read(buff, len);
-
-  if (bytes < 0) {
-    const std::string message = "Failed to read from active stream";
-    throw_entry_fault(message, current_entry_hierarchy());
+  if (_current_stream) {
+    return _current_stream->read(buff, len);
   }
-
-  return bytes;
+  return 0;
 }
 
 StreamArchive *ArchiveStackCursor::current_archive() {
-  if (stream_stack.size() <= 0) {
-    return nullptr;
-  }
-
-  const auto stream = std::dynamic_pointer_cast<EntryPayloadStream>(stream_stack.back());
-  if (!stream) {
-    return nullptr;
-  }
-
-  auto parent_archive = stream->parent_archive();
-  return parent_archive ? parent_archive.get() : nullptr;
+  return _current_archive.get();
 }
 
 PathHierarchy ArchiveStackCursor::current_entry_hierarchy() {
-  if (stream_stack.empty() || !stream_stack.front()) {
+  if (depth() == 0 || (!_current_stream && !_current_archive)) {
     return {};
   }
 
@@ -310,7 +306,7 @@ PathHierarchy ArchiveStackCursor::current_entry_hierarchy() {
     return path;
   }
 
-  return stream_stack.front()->source_hierarchy();
+  return _current_stream->source_hierarchy();
 }
 
 std::shared_ptr<IDataStream> ArchiveStackCursor::create_stream(const PathHierarchy &hierarchy) {
@@ -322,9 +318,7 @@ std::shared_ptr<IDataStream> ArchiveStackCursor::create_stream(const PathHierarc
     }
     return std::make_shared<SystemFileStream>(hierarchy);
   }
-  auto stream = std::dynamic_pointer_cast<EntryPayloadStream>(stream_stack.back());
-
-  return std::make_shared<EntryPayloadStream>(stream->parent_archive(), hierarchy);
+  return std::make_shared<EntryPayloadStream>(_current_archive, hierarchy);
 }
 
 } // namespace archive_r

data/ext/archive_r/vendor/archive_r/src/archive_stack_cursor.h

@@ -31,6 +31,9 @@ public:
   void rewind() override;
 
   PathHierarchy source_hierarchy() const;
+  std::shared_ptr<StreamArchive> parent_archive() const;
+
+  std::shared_ptr<IDataStream> get_stream() const { return _stream; }
 
 private:
   static la_ssize_t read_callback_bridge(struct archive *a, void *client_data, const void **buff);
@@ -75,7 +78,7 @@ struct ArchiveStackCursor {
 
   void configure(const ArchiveOption &options);
   void reset();
-  bool has_stream() const { return !stream_stack.empty(); }
+  bool has_stream() const { return _current_stream != nullptr; }
 
   bool descend();
   bool ascend();
@@ -83,7 +86,16 @@ struct ArchiveStackCursor {
   bool synchronize_to_hierarchy(const PathHierarchy &hierarchy);
   ssize_t read(void *buffer, size_t len);
 
-  size_t depth() const { return stream_stack.size(); }
+  size_t depth() const {
+    size_t d = 0;
+    auto a = _current_archive;
+    while (a) {
+      d++;
+      a = a->parent_archive();
+    }
+    return d;
+  }
+
   StreamArchive *current_archive();
 
   PathHierarchy current_entry_hierarchy();
@@ -91,7 +103,10 @@ struct ArchiveStackCursor {
   std::shared_ptr<IDataStream> create_stream(const PathHierarchy &hierarchy);
 
   ArchiveOption options_snapshot;
-  std::vector<std::shared_ptr<IDataStream>> stream_stack;
+
+private:
+  std::shared_ptr<IDataStream> _current_stream;
+  std::shared_ptr<StreamArchive> _current_archive;
 };
 
 } // namespace archive_r

data/ext/archive_r/vendor/archive_r/src/multi_volume_stream_base.cc

@@ -20,6 +20,7 @@ struct MultiVolumeStreamBase::Impl {
   std::vector<int64_t> part_offsets;
   std::size_t total_parts = 0;
   std::size_t active_part_index = 0;
+  std::size_t open_part_index = 0;
   bool part_open = false;
   int64_t logical_offset = 0;
   int64_t total_size = -1;
@@ -84,7 +85,7 @@ void MultiVolumeStreamBase::rewind() {
 }
 
 bool MultiVolumeStreamBase::at_end() const {
-  return (_impl->active_part_index >= _impl->total_parts) && !_impl->part_open;
+  return _impl->active_part_index >= _impl->total_parts;
 }
 
 int64_t MultiVolumeStreamBase::seek(int64_t offset, int whence) {
@@ -122,14 +123,14 @@ int64_t MultiVolumeStreamBase::seek(int64_t offset, int whence) {
 int64_t MultiVolumeStreamBase::tell() const { return _impl->logical_offset; }
 
 void MultiVolumeStreamBase::Impl::ensure_part_active(std::size_t part_index) {
-  if (part_open && active_part_index == part_index) {
+  if (part_open && open_part_index == part_index) {
     return;
   }
 
   self.deactivate_active_part();
   PathHierarchy single_part = pathhierarchy_select_single_part(self._logical_path, part_index);
   self.open_single_part(single_part);
-  active_part_index = part_index;
+  open_part_index = part_index;
   part_open = true;
 }
 
@@ -144,7 +145,6 @@ bool MultiVolumeStreamBase::Impl::advance_to_next_part() {
   if (active_part_index >= total_parts) {
     return false;
   }
-  self.deactivate_active_part();
   ++active_part_index;
   return active_part_index < total_parts;
 }

data/ext/archive_r/vendor/archive_r/src/path_hierarchy.cc

@@ -14,14 +14,9 @@ int entry_type_rank(const PathEntry &entry) {
   if (entry.is_single()) {
     return 0;
   }
-  if (entry.is_multi_volume()) {
-    return 1;
-  }
-  return 2;
+  return 1;
 }
 
-int compare_node_lists_impl(const PathEntry::NodeList &lhs, const PathEntry::NodeList &rhs);
-
 int compare_entries_impl(const PathEntry &lhs, const PathEntry &rhs) {
   const int lhs_rank = entry_type_rank(lhs);
   const int rhs_rank = entry_type_rank(rhs);
@@ -69,22 +64,6 @@ int compare_entries_impl(const PathEntry &lhs, const PathEntry &rhs) {
     return 0;
   }
 
-  return compare_node_lists_impl(lhs.nested_nodes(), rhs.nested_nodes());
-}
-
-int compare_node_lists_impl(const PathEntry::NodeList &lhs, const PathEntry::NodeList &rhs) {
-  const std::size_t lsize = lhs.size();
-  const std::size_t rsize = rhs.size();
-  const std::size_t compare_count = lsize < rsize ? lsize : rsize;
-  for (std::size_t i = 0; i < compare_count; ++i) {
-    const int cmp = compare_entries_impl(lhs[i], rhs[i]);
-    if (cmp != 0) {
-      return cmp;
-    }
-  }
-  if (lsize != rsize) {
-    return lsize < rsize ? -1 : 1;
-  }
   return 0;
 }
 

data/ext/archive_r/vendor/archive_r/src/path_hierarchy_utils.cc

@@ -203,27 +203,6 @@ bool flatten_entry_to_string(const PathEntry &entry, std::string &output) {
     return true;
   }
 
-  if (entry.is_nested()) {
-    std::string result;
-    bool first = true;
-    for (const auto &child : entry.nested_nodes()) {
-      std::string component;
-      if (!flatten_entry_to_string(child, component)) {
-        return false;
-      }
-      if (component.empty()) {
-        return false;
-      }
-      if (!first) {
-        result.push_back('/');
-      }
-      result += component;
-      first = false;
-    }
-    output = result;
-    return !result.empty();
-  }
-
   return false;
 }
 
@@ -275,17 +254,7 @@ std::string path_entry_display(const PathEntry &entry) {
     value.push_back(']');
     return value;
   }
-  std::string value = "{";
-  bool first = true;
-  for (const auto &child : entry.nested_nodes()) {
-    if (!first) {
-      value.push_back('/');
-    }
-    value += path_entry_display(child);
-    first = false;
-  }
-  value.push_back('}');
-  return value;
+  return {};
 }
 
 std::string hierarchy_display(const PathHierarchy &hierarchy) {

data/ext/archive_r/vendor/archive_r/src/system_file_stream.cc

@@ -78,7 +78,9 @@ SystemFileStream::SystemFileStream(PathHierarchy logical_path)
   }
 }
 
-SystemFileStream::~SystemFileStream() = default;
+SystemFileStream::~SystemFileStream() {
+  deactivate_active_part();
+}
 
 void SystemFileStream::open_single_part(const PathHierarchy &single_part) {
   const PathEntry &entry = single_part.back();
@@ -104,8 +106,10 @@ void SystemFileStream::open_single_part(const PathHierarchy &single_part) {
 }
 
 void SystemFileStream::close_single_part() {
-  std::fclose(_handle);
-  _handle = nullptr;
+  if (_handle) {
+    std::fclose(_handle);
+    _handle = nullptr;
+  }
   _active_path.clear();
 }
 

data/ext/archive_r/vendor/archive_r/src/traverser.cc

@@ -10,7 +10,6 @@
 #include "archive_type.h"
 #include "entry_fault_error.h"
 #include "system_file_stream.h"
-#include <iostream>
 #include <filesystem>
 #include <memory>
 #include <stdexcept>
@@ -52,6 +51,12 @@ Traverser::Traverser(std::vector<PathHierarchy> paths, TraverserOptions options)
 
 }
 
+Traverser::Traverser(PathHierarchy path, TraverserOptions options)
+    : Traverser(std::vector<PathHierarchy>{std::move(path)}, std::move(options)) {}
+
+Traverser::Traverser(const std::string &path, TraverserOptions options)
+    : Traverser(std::vector<PathHierarchy>{make_single_path(path)}, std::move(options)) {}
+
 Traverser::~Traverser() = default;
 
 // ============================================================================

data/lib/archive_r.rb

@@ -35,7 +35,7 @@ rescue LoadError
 end
 
 module Archive_r
-  VERSION = "0.1.3"
+  VERSION = "0.1.7"
   # Common archive formats excluding libarchive's mtree/raw pseudo formats
   STANDARD_FORMATS = %w[
     7zip ar cab cpio empty iso9660 lha rar tar warc xar zip
@@ -87,6 +87,10 @@ module Archive_r
       def open(paths, opts = nil, &block)
         __archive_r_c_open(paths, Archive_r.normalize_options(opts), &block)
       end
+
+      def open_hierarchy(hierarchy, opts = nil, &block)
+        open([hierarchy], opts, &block)
+      end
     end
 
     alias_method :__archive_r_c_initialize, :initialize

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: archive_r_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - raizo.tcs
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -38,8 +37,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-description: Ruby bindings for archive_r that recursively walk nested and multipart
-  archives directly from the source stream without creating temporary files
+description: Ruby bindings for archive_r, a libarchive-based library for processing
+  many archive formats. It streams entry data directly from the source to recursively
+  read nested archives without extracting to temporary files or loading large in-memory
+  buffers.
 email:
 - raizo.tcs@users.noreply.github.com
 executables: []
@@ -91,7 +92,6 @@ metadata:
   source_code_uri: https://github.com/raizo-tcs/archive_r
   bug_tracker_uri: https://github.com/raizo-tcs/archive_r/issues
   changelog_uri: https://github.com/raizo-tcs/archive_r/releases
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -106,8 +106,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.20
-signing_key:
+rubygems_version: 4.0.1
 specification_version: 4
-summary: Ruby bindings for archive_r that traverse nested archives without temp extraction
+summary: 'Ruby bindings for archive_r: libarchive-based streaming traversal for recursive
+  nested archives (no temp files, no large in-memory buffers)'
 test_files: []