archive_r_ruby 0.1.0

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

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 archive_r Team
+
+#pragma once
+
+#include "archive_r/entry_fault.h"
+#include "archive_r/path_hierarchy.h"
+#include "entry.h"
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace archive_r {
+
+struct TraverserOptions {
+  std::vector<std::string> passphrases;   ///< Passphrases for encrypted archives
+  std::vector<std::string> formats;       ///< Specific archive formats to enable (empty = all)
+  std::vector<std::string> metadata_keys; ///< Metadata keys to capture for entries
+  bool descend_archives = true;           ///< Whether to descend into archives by default
+};
+
+/**
+ * @brief Iterator-based traversal for archives and directories
+ *
+ * Traverser provides a unified iterator-based interface for traversing
+ * entries within archives and directories, including support for nested
+ * archives and automatic descent.
+ *
+ * Supports multiple archive formats via libarchive (tar, zip, gzip, etc.)
+ * and filesystem directories.
+ *
+ * Uses std::filesystem for directory traversal and ArchiveStackOrchestrator for archives.
+
+ * @see Entry, ArchiveStackOrchestrator
+ *
+ * Usage:
+ *   Traverser traverser({make_single_path("archive.tar.gz")});  // or directory path
+ *   for (Entry& entry : traverser) {
+ *       // Process entry
+ *   }
+ *
+ * @note Thread Safety
+ * Traverser instances are not thread-safe. To use the traverser in a
+ * multi-threaded environment, create a separate Traverser instance for each
+ * thread. Do not share a single instance across multiple threads.
+ */
+class Traverser {
+public:
+  /**
+   * @brief Construct traverser for archives or directories
+   * @param paths Paths to archive files or directories
+   *
+   * 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")});
+   */
+  explicit Traverser(std::vector<PathHierarchy> paths, TraverserOptions options = {});
+
+  ~Traverser();
+
+  // Non-copyable
+  Traverser(const Traverser &) = delete;
+  Traverser &operator=(const Traverser &) = delete;
+
+  // ========================================================================
+  // Iterator API
+  // ========================================================================
+
+  /**
+   * @brief Forward iterator for traversing entries
+   *
+   * Satisfies InputIterator requirements:
+   * - Move-only (non-copyable)
+   * - Equality comparable
+   * - Dereferenceable (returns Entry&)
+   * - Incrementable
+   */
+  class Iterator {
+  public:
+    using iterator_category = std::input_iterator_tag;
+    using value_type = Entry;
+    using difference_type = std::ptrdiff_t;
+    using pointer = Entry *;
+    using reference = Entry &;
+
+    reference operator*();
+    pointer operator->();
+    Iterator &operator++();
+    bool operator==(const Iterator &other) const;
+    bool operator!=(const Iterator &other) const;
+
+    ~Iterator();
+    Iterator(const Iterator &) = delete;
+    Iterator &operator=(const Iterator &) = delete;
+    Iterator(Iterator &&) noexcept;
+    Iterator &operator=(Iterator &&) noexcept;
+
+  private:
+    friend class Traverser;
+    class Impl;
+    std::unique_ptr<Impl> _impl;
+    explicit Iterator(std::unique_ptr<Impl> impl);
+  };
+
+  /**
+   * @brief Get iterator to first entry
+   * @return Iterator pointing to first entry
+   */
+  Iterator begin();
+
+  /**
+   * @brief Get end iterator
+   * @return End iterator (sentinel)
+   */
+  Iterator end();
+
+private:
+  std::vector<PathHierarchy> _initial_paths; ///< Initial paths provided to constructor
+  TraverserOptions _options;                 ///< Options controlling archive handling
+};
+
+} // namespace archive_r

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

@@ -0,0 +1,330 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 archive_r Team
+
+#include "archive_stack_cursor.h"
+
+#include "archive_r/path_hierarchy_utils.h"
+#include "system_file_stream.h"
+#include <exception>
+#include <memory>
+#include <stdexcept>
+#include <typeinfo>
+#include <utility>
+
+namespace archive_r {
+
+namespace {
+
+[[noreturn]] void throw_entry_fault(const std::string &message, const PathHierarchy &hierarchy) { throw make_entry_fault_error(message, hierarchy); }
+
+} // namespace
+
+// ============================================================================
+// StreamArchive Implementation
+// ============================================================================
+
+StreamArchive::StreamArchive(std::shared_ptr<IDataStream> stream, ArchiveOption options)
+    : Archive()
+    , _stream(std::move(stream))
+    , _options(std::move(options)) {
+  if (!_stream) {
+    throw std::invalid_argument("StreamArchive requires a valid data stream");
+  }
+
+  open_archive();
+}
+
+StreamArchive::~StreamArchive() = default;
+
+void StreamArchive::open_archive() {
+  archive_ptr ar = new_read_archive_common(_options.passphrases, _options.formats, [this](struct archive *ar) -> int {
+    archive_read_set_callback_data(ar, this);
+    archive_read_set_read_callback(ar, read_callback_bridge);
+    if (_stream->can_seek()) {
+      archive_read_set_skip_callback(ar, skip_callback_bridge);
+      archive_read_set_seek_callback(ar, seek_callback_bridge);
+    }
+    return archive_read_open1(ar);
+  });
+
+  _ar = ar.release();
+  current_entryname.clear();
+  _at_eof = false;
+  _current_entry_content_ready = false;
+}
+
+void StreamArchive::rewind() {
+  _stream->rewind();
+  Archive::rewind();
+}
+
+PathHierarchy StreamArchive::source_hierarchy() const { return _stream->source_hierarchy(); }
+
+la_ssize_t StreamArchive::read_callback_bridge(struct archive *a, void *client_data, const void **buff) {
+  auto *archive = static_cast<StreamArchive *>(client_data);
+
+  ssize_t bytes_read = 0;
+  try {
+    bytes_read = archive->_stream->read(archive->_buffer.data(), archive->_buffer.size());
+  } catch (const std::exception &) {
+    return -1;
+  }
+  if (bytes_read < 0) {
+    return static_cast<la_ssize_t>(bytes_read);
+  }
+
+  *buff = archive->_buffer.data();
+
+  return static_cast<la_ssize_t>(bytes_read);
+}
+
+la_int64_t StreamArchive::seek_callback_bridge(struct archive *a, void *client_data, la_int64_t request, int whence) {
+  auto *archive = static_cast<StreamArchive *>(client_data);
+  try {
+    return archive->_stream->seek(request, whence);
+  } catch (const std::exception &) {
+    return -1;
+  }
+}
+
+la_int64_t StreamArchive::skip_callback_bridge(struct archive *a, void *client_data, la_int64_t request) {
+  auto *archive = static_cast<StreamArchive *>(client_data);
+  try {
+    la_int64_t current = archive->_stream->tell();
+    if (current < 0) {
+      current = archive->_stream->seek(0, SEEK_CUR);
+    }
+    if (current < 0) {
+      return 0;
+    }
+
+    auto result = archive->_stream->seek(request, SEEK_CUR);
+    if (result >= 0) {
+      return result - current;
+    }
+  } catch (const std::exception &) {
+    return 0;
+  }
+  return 0;
+}
+
+// ============================================================================
+// EntryPayloadStream Implementation
+// ============================================================================
+
+EntryPayloadStream::EntryPayloadStream(std::shared_ptr<StreamArchive> parent_archive, PathHierarchy logical_path)
+    : MultiVolumeStreamBase(std::move(logical_path), false)
+    , _parent_archive(std::move(parent_archive)) {
+  if (!_parent_archive) {
+    throw std::invalid_argument("Invalid parent archive context");
+  }
+}
+
+EntryPayloadStream::~EntryPayloadStream() = default;
+
+std::shared_ptr<StreamArchive> EntryPayloadStream::parent_archive() const { return _parent_archive; }
+
+void EntryPayloadStream::rewind() {
+  MultiVolumeStreamBase::rewind();
+  const PathHierarchy first_part = pathhierarchy_select_single_part(_logical_path, 0);
+  const std::string entry_name = first_part.back().single_value();
+
+  if (!_parent_archive->skip_to_entry(entry_name)) {
+    throw_entry_fault("Parent archive does not contain requested stream part", first_part);
+  }
+  // leave parent positioned at the beginning of the first part so subsequent reads start cleanly
+}
+
+void EntryPayloadStream::open_single_part(const PathHierarchy &single_part) {
+  const std::string entry_name = single_part.back().single_value();
+  if (!_parent_archive->skip_to_entry(entry_name)) {
+    throw_entry_fault("Parent archive does not contain requested stream part", single_part);
+  }
+}
+
+void EntryPayloadStream::close_single_part() {
+  if (_parent_archive->current_entryname.empty()) {
+    return;
+  }
+
+  _parent_archive->skip_data();
+}
+
+ssize_t EntryPayloadStream::read_from_single_part(void *buffer, size_t size) {
+  if (size == 0) {
+    return 0;
+  }
+  return _parent_archive->read_current(buffer, size);
+}
+
+int64_t EntryPayloadStream::seek_within_single_part(int64_t offset, int whence) { return -1; }
+
+int64_t EntryPayloadStream::size_of_single_part(const PathHierarchy &single_part) {
+  (void)single_part;
+  return -1;
+}
+
+// ============================================================================
+// ArchiveStackCursor Implementation
+// ============================================================================
+
+ArchiveStackCursor::ArchiveStackCursor()
+    : options_snapshot()
+    , stream_stack() {}
+
+void ArchiveStackCursor::configure(const ArchiveOption &options) {
+  options_snapshot = options;
+}
+
+void ArchiveStackCursor::reset() {
+  options_snapshot = ArchiveOption{};
+  stream_stack.clear();
+}
+
+bool ArchiveStackCursor::descend() {
+  if (stream_stack.empty()) {
+    throw std::logic_error("stream stack is empty");
+  }
+
+  auto stream = stream_stack.back();
+
+  if (auto *archive = current_archive()) {
+    if (stream && !archive->current_entry_content_ready()) {
+      stream->rewind();
+    }
+  }
+
+  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)));
+  return true;
+}
+
+bool ArchiveStackCursor::ascend() {
+  if (stream_stack.size() <= 0) {
+    return false;
+  }
+
+  stream_stack.pop_back();
+
+  return true;
+}
+
+bool ArchiveStackCursor::next() {
+  StreamArchive *archive = current_archive();
+  if (!archive) {
+    return false;
+  }
+
+  while (true) {
+    if (!archive->skip_to_next_header()) {
+      return false;
+    }
+    if (!archive->current_entryname.empty()) {
+      break;
+    }
+  }
+  stream_stack.back() = create_stream(current_entry_hierarchy());
+  return true;
+}
+
+bool ArchiveStackCursor::synchronize_to_hierarchy(const PathHierarchy &target_hierarchy) {
+  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());
+  }
+  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;
+    }
+    // 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;
+    }
+    // Descend into the archive for the next level of the hierarchy.
+    descend();
+  }
+  
+   return true;
+}
+
+ssize_t ArchiveStackCursor::read(void *buff, size_t len) {
+  if (len == 0) {
+    return 0;
+  }
+
+  if (stream_stack.empty()) {
+    throw_entry_fault("Stream stack is empty", {});
+  }
+
+  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());
+  }
+
+  return bytes;
+}
+
+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;
+}
+
+PathHierarchy ArchiveStackCursor::current_entry_hierarchy() {
+  if (stream_stack.empty() || !stream_stack.front()) {
+    return {};
+  }
+
+  if (StreamArchive *archive = current_archive()) {
+    PathHierarchy path = archive->source_hierarchy();
+    if (!archive->current_entryname.empty()) {
+      append_single(path, archive->current_entryname);
+    }
+    return path;
+  }
+
+  return stream_stack.front()->source_hierarchy();
+}
+
+std::shared_ptr<IDataStream> ArchiveStackCursor::create_stream(const PathHierarchy &hierarchy) {
+  if (hierarchy.size() == 1) {
+    if (auto factory = get_root_stream_factory()) {
+      if (auto stream = factory(hierarchy)) {
+        return stream;
+      }
+    }
+    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);
+}
+
+} // namespace archive_r

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

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 archive_r Team
+
+#pragma once
+
+#include "archive_r/data_stream.h"
+#include "archive_r/path_hierarchy.h"
+#include "archive_type.h"
+#include "entry_fault_error.h"
+#include "archive_r/multi_volume_stream_base.h"
+#include <array>
+#include <cstddef>
+#include <exception>
+#include <memory>
+#include <string>
+#include <sys/types.h>
+#include <vector>
+
+namespace archive_r {
+
+// ============================================================================
+// StreamArchive Interface
+// ============================================================================
+
+class StreamArchive : public Archive {
+public:
+  explicit StreamArchive(std::shared_ptr<IDataStream> stream, ArchiveOption options = {});
+
+  ~StreamArchive() override;
+
+  void open_archive() override;
+  void rewind() override;
+
+  PathHierarchy source_hierarchy() const;
+
+private:
+  static la_ssize_t read_callback_bridge(struct archive *a, void *client_data, const void **buff);
+  static la_int64_t seek_callback_bridge(struct archive *a, void *client_data, la_int64_t request, int whence);
+  static la_int64_t skip_callback_bridge(struct archive *a, void *client_data, la_int64_t request);
+
+  static constexpr size_t BUFFER_SIZE = 65536;
+  std::shared_ptr<IDataStream> _stream;
+  std::array<char, BUFFER_SIZE> _buffer;
+  ArchiveOption _options;
+};
+
+// ============================================================================
+// EntryPayloadStream Interface
+// ============================================================================
+
+class EntryPayloadStream : public MultiVolumeStreamBase {
+public:
+  EntryPayloadStream(std::shared_ptr<StreamArchive> parent_archive, PathHierarchy logical_path);
+  ~EntryPayloadStream() override;
+
+  std::shared_ptr<StreamArchive> parent_archive() const;
+  void rewind() override;
+
+private:
+  std::shared_ptr<StreamArchive> _parent_archive;
+
+  void open_single_part(const PathHierarchy &single_part) override;
+  void close_single_part() override;
+  ssize_t read_from_single_part(void *buffer, size_t size) override;
+  int64_t seek_within_single_part(int64_t offset, int whence) override;
+  int64_t size_of_single_part(const PathHierarchy &single_part) override;
+};
+
+// ============================================================================
+// ArchiveStackCursor Interface
+// ============================================================================
+
+struct ArchiveStackCursor {
+
+  ArchiveStackCursor();
+
+  void configure(const ArchiveOption &options);
+  void reset();
+  bool has_stream() const { return !stream_stack.empty(); }
+
+  bool descend();
+  bool ascend();
+  bool next();
+  bool synchronize_to_hierarchy(const PathHierarchy &hierarchy);
+  ssize_t read(void *buffer, size_t len);
+
+  size_t depth() const { return stream_stack.size(); }
+  StreamArchive *current_archive();
+
+  PathHierarchy current_entry_hierarchy();
+
+  std::shared_ptr<IDataStream> create_stream(const PathHierarchy &hierarchy);
+
+  ArchiveOption options_snapshot;
+  std::vector<std::shared_ptr<IDataStream>> stream_stack;
+};
+
+} // namespace archive_r

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

@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 archive_r Team
+
+#include "archive_stack_orchestrator.h"
+#include "archive_r/path_hierarchy_utils.h"
+#include "archive_r/entry_fault.h"
+#include "system_file_stream.h"
+
+#include <algorithm>
+#include <cstddef>
+#include <cstdio>
+#include <exception>
+#include <limits>
+#include <memory>
+#include <stdexcept>
+#include <typeinfo>
+#include <utility>
+
+namespace archive_r {
+
+ArchiveStackOrchestrator::ArchiveStackOrchestrator(const ArchiveOption &options)
+    : _archive_options(options)
+    , _metadata_keys(options.metadata_keys.begin(), options.metadata_keys.end()) {
+    _head.configure(_archive_options);
+}
+
+ArchiveStackOrchestrator::~ArchiveStackOrchestrator() = default;
+
+size_t ArchiveStackOrchestrator::depth() const { return _head.depth(); }
+
+StreamArchive *ArchiveStackOrchestrator::current_archive() { return _head.current_archive(); }
+
+// Drives the traversal state machine:
+// 1. Optionally descend into the current entry when requested.
+// 2. Attempt to advance within the active archive; report faults but keep looping.
+// 3. Drain any pending multi-volume groups before bubbling up to the parent so multipart
+//    archives are consumed contiguously.
+// 4. When leaving a multi-volume context, rewind the parent archive by skipping to EOF to
+//    avoid re-reading already processed entries.
+bool ArchiveStackOrchestrator::advance(bool descend_request) {
+  bool request_descend = descend_request;
+
+  while (true) {
+    if (depth() == 0) {
+      return false;
+    }
+    try {
+      if (request_descend) {
+        request_descend = false;
+        _head.descend();
+      }
+    } catch (const EntryFaultError &error) {
+      dispatch_fault(error.fault());
+      continue;
+    }
+
+    try {
+      if (_head.next()) {
+        return true;
+      }
+    } catch (const EntryFaultError &error) {
+      dispatch_fault(error.fault());
+      continue;
+    }
+
+    try {
+      // Consume any pending multi-volume siblings so we do not return to the parent mid-series.
+      if (descend_pending_multi_volumes()) {
+        continue;
+      }
+    } catch (const EntryFaultError &error) {
+      dispatch_fault(error.fault());
+    }
+
+    PathHierarchy prev_ascend_hierarchy = _head.current_entry_hierarchy();
+    _head.ascend();
+
+    if (!pathhierarchy_is_multivolume(prev_ascend_hierarchy)) {
+      continue;
+    }
+
+    try {
+      // If same-level multi-volume siblings remain, keep draining them before touching the parent next().
+      if (descend_pending_multi_volumes()) {
+        continue;
+      }
+    } catch (const EntryFaultError &error) {
+      dispatch_fault(error.fault());
+    }
+    try {
+      StreamArchive *archive = _head.current_archive();
+      if (archive) {
+        // After all volumes are processed, push the parent back to EOF to avoid duplicate next().
+        archive->skip_to_eof();
+      }
+    } catch (const EntryFaultError &error) {
+      dispatch_fault(error.fault());
+    }
+  }
+}
+
+const std::string &ArchiveStackOrchestrator::current_entryname() {
+  StreamArchive *archive = current_archive();
+  if (!archive) {
+    static const std::string empty;
+    return empty;
+  }
+  return archive->current_entryname;
+}
+
+PathHierarchy ArchiveStackOrchestrator::current_entry_hierarchy() { return _head.current_entry_hierarchy(); }
+
+bool ArchiveStackOrchestrator::synchronize_to_hierarchy(const PathHierarchy &path_hierarchy) {
+  try {
+    _head.synchronize_to_hierarchy(path_hierarchy);
+    return true;
+  } catch (const EntryFaultError &error) {
+    dispatch_fault(error.fault());
+    return false;
+  }
+}
+
+ssize_t ArchiveStackOrchestrator::read_head(void *buff, size_t len) {
+  try {
+    return _head.read(buff, len);
+  } catch (const EntryFaultError &error) {
+    dispatch_fault(error.fault());
+  }
+
+  return -1;
+}
+
+void ArchiveStackOrchestrator::mark_entry_as_multi_volume(const PathHierarchy &entry_path, const std::string &base_name, PathEntry::Parts::Ordering ordering) {
+  _multi_volume_manager.mark_entry_as_multi_volume(entry_path, base_name, ordering);
+}
+
+bool ArchiveStackOrchestrator::descend_pending_multi_volumes() {
+  const PathHierarchy current_hierarchy = _head.current_entry_hierarchy();
+  PathHierarchy multi_volume_target;
+  if (!_multi_volume_manager.pop_multi_volume_group(current_hierarchy, multi_volume_target)) {
+    return false;
+  }
+  
+  _head.synchronize_to_hierarchy(multi_volume_target);
+  _head.descend();
+  return true;
+}
+
+void ArchiveStackOrchestrator::open_root_hierarchy(const PathHierarchy &root_hierarchy) {
+  _head.synchronize_to_hierarchy(root_hierarchy);
+  _head.descend();
+}
+
+void ArchiveStackOrchestrator::dispatch_fault(EntryFault fault) {
+  if (fault.hierarchy.empty()) {
+    fault.hierarchy = _head.current_entry_hierarchy();
+  }
+
+  dispatch_registered_fault(fault);
+}
+
+} // namespace archive_r