archive_r_ruby 0.1.0

data/ext/archive_r/extconf.rb

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 archive_r Team
+
+require 'mkmf'
+
+def archive_r_core_root
+  candidates = []
+
+  env_root = ENV['ARCHIVE_R_CORE_ROOT']
+  candidates << File.expand_path(env_root) if env_root && !env_root.empty?
+
+  repo_root = File.expand_path('../../../..', __dir__)
+  candidates << repo_root
+
+  vendor_root = File.expand_path('vendor/archive_r', __dir__)
+  candidates << vendor_root
+
+  candidates.each do |root|
+    next unless root
+    include_dir = File.join(root, 'include')
+    src_dir = File.join(root, 'src')
+    return root if Dir.exist?(include_dir) && Dir.exist?(src_dir)
+  end
+
+  nil
+end
+archive_r_root = archive_r_core_root
+
+unless archive_r_root
+  abort <<~MSG
+    archive_r core library not found.
+    Please set ARCHIVE_R_CORE_ROOT to a repository checkout or use the vendored gem package.
+  MSG
+end
+
+vendor_root = File.expand_path('vendor/archive_r', __dir__)
+
+if archive_r_root == vendor_root
+  puts 'Using vendored archive_r core sources'
+elsif ENV['ARCHIVE_R_CORE_ROOT'] && File.expand_path(ENV['ARCHIVE_R_CORE_ROOT']) == archive_r_root
+  puts "Using archive_r core from #{archive_r_root} (ARCHIVE_R_CORE_ROOT)"
+else
+  puts "Using archive_r core from #{archive_r_root}"
+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')
+glue_source = File.join(__dir__, 'archive_r_ext.cc')
+
+# Ensure make can locate vendored sources via VPATH
+$VPATH ||= ''
+unless $VPATH.empty?
+  $VPATH << File::PATH_SEPARATOR
+end
+$VPATH << archive_r_src
+
+# Add include paths
+$INCFLAGS << " -I#{archive_r_include}"
+$INCFLAGS << " -I#{archive_r_src}"
+
+# C++17 standard
+$CXXFLAGS << " -std=c++17"
+
+# Check for libarchive
+unless have_library('archive')
+  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')
+
+if File.exist?(prebuilt_lib)
+  $LOCAL_LIBS << " #{prebuilt_lib}"
+  puts "Using pre-built archive_r core library"
+else
+  # Build from source as fallback (ensure the Ruby glue source is compiled too)
+  puts "Pre-built library not found, will build from source"
+
+  srcs = [glue_source] + Dir.glob(File.join(archive_r_src, '*.cc'))
+  $srcs = srcs
+end
+
+# Guarantee the Ruby glue source is part of the compilation list when $srcs is set
+if defined?($srcs) && $srcs
+  $srcs.unshift(glue_source) unless $srcs.include?(glue_source)
+end
+
+# Create Makefile
+create_makefile('archive_r/archive_r')

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

@@ -0,0 +1,56 @@
+archive_r License
+Version: 0.1.0 (2025-10-25)
+
+----------------------------------------
+Primary License
+----------------------------------------
+
+MIT License
+
+Copyright (c) 2025 archive_r Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+----------------------------------------
+Third-Party Notices
+----------------------------------------
+
+This distribution bundles or links against the following third-party
+components. Their respective license terms apply in addition to the MIT
+License shown above.
+
+1. libarchive
+   - Purpose: core archive reading and writing functionality for the C++
+     library and language bindings.
+   - License: New BSD License (https://www.libarchive.org/)
+
+2. pybind11
+   - Purpose: header-only binding generator for the Python extension module.
+   - License: BSD-style License (https://github.com/pybind/pybind11)
+
+3. rake (development dependency for Ruby bindings)
+   - Purpose: build and release tasks for the Ruby gem.
+   - License: MIT License (https://github.com/ruby/rake)
+
+4. minitest (development dependency for Ruby bindings)
+   - Purpose: unit testing framework for the Ruby gem.
+   - License: MIT License (https://github.com/minitest/minitest)
+
+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

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 archive_r Team
+
+#pragma once
+
+#include "archive_r/path_hierarchy.h"
+
+#include <functional>
+#include <memory>
+#include <sys/types.h>
+
+namespace archive_r {
+
+/**
+ * @brief Abstract stream interface used by the archive traversal stack
+ */
+class IDataStream {
+public:
+  virtual ~IDataStream() = default;
+  virtual ssize_t read(void *buffer, size_t size) = 0;
+  virtual void rewind() = 0;
+  virtual bool at_end() const = 0;
+  virtual int64_t seek(int64_t offset, int whence) { return -1; }
+  virtual int64_t tell() const { return -1; }
+  virtual bool can_seek() const { return false; }
+  virtual PathHierarchy source_hierarchy() const = 0;
+};
+
+using RootStreamFactory = std::function<std::shared_ptr<IDataStream>(const PathHierarchy &)>;
+
+/**
+ * @brief Register the default factory used for root PathHierarchy streams
+ */
+void set_root_stream_factory(RootStreamFactory factory);
+
+/**
+ * @brief Retrieve the currently registered root stream factory
+ */
+RootStreamFactory get_root_stream_factory();
+
+} // namespace archive_r

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

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 archive_r Team
+
+#pragma once
+
+#include <cstdint>
+#include <filesystem>
+#include <memory>
+#include <string>
+#include <sys/types.h>
+#include <vector>
+
+#include "archive_r/entry_fault.h"
+#include "archive_r/entry_metadata.h"
+#include "archive_r/path_hierarchy.h"
+
+namespace archive_r {
+
+class ArchiveStackOrchestrator;
+
+struct MultiVolumeGroupOptions {
+  PathEntry::Parts::Ordering ordering = PathEntry::Parts::Ordering::Natural;
+};
+
+/**
+ * @brief Represents a single entry in an archive traversal
+ *
+ * Entry objects encapsulate all information about an archive entry including:
+ * - Path information (path, path hierarchy)
+ * - Metadata (size, type, timestamps)
+ * - Content access (read operations)
+ * - Multi-volume archive grouping support
+ *
+ * Entry objects are typically obtained from ArchiveTraverser::Iterator and
+ * remain valid until the iterator advances.
+ */
+class Entry {
+public:
+  /**
+   * @brief Get the entry name (last element of the path hierarchy)
+   * @return Entry name relative to its containing archive (e.g., "dir/subdir/file.txt" when the
+   *         hierarchy is {"outer/archive.zip", "dir/subdir/file.txt"})
+   */
+  std::string name() const;
+
+  /**
+   * @brief Get the entry path as a string
+   * @return Joined path including outer archives (e.g., "outer/archive.zip/dir/subdir/file.txt"
+   * when the hierarchy is {"outer/archive.zip", "dir/subdir/file.txt"})
+   */
+  std::string path() const;
+
+  /**
+   * @brief Get the entry path as a hierarchy of components
+   * @return Vector describing each descent step (e.g., {"outer/archive.zip",
+   * "dir/subdir/file.txt"})
+   */
+  const PathHierarchy &path_hierarchy() const;
+
+  /**
+   * @brief Check if entry is a directory
+   * @return true if entry represents a directory
+   */
+  bool is_directory() const;
+
+  /**
+   * @brief Check if entry is a regular file
+   * @return true if entry represents a regular file
+   */
+  bool is_file() const;
+
+  /**
+   * @brief Get the uncompressed size of the entry
+   * @return Size in bytes, or 0 if unknown
+   */
+  uint64_t size() const;
+
+  /**
+   * @brief Get the archive nesting depth
+   * @return 0 for top-level archive, 1 for nested archive, etc.
+   */
+  size_t depth() const;
+
+  /**
+   * @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.
+   *
+   * @param buffer Buffer to read data into
+   * @param length Maximum number of bytes to read
+   * @return Number of bytes read, 0 on EOF, -1 on error
+   */
+  ssize_t read(void *buffer, size_t length);
+
+  /**
+   * @brief Enable or disable automatic descent into this entry
+   * @param enabled true to descend (default), false to keep traversal at current level
+   */
+  void set_descent(bool enabled);
+
+  /**
+   * @brief Check if automatic descent is currently enabled
+   */
+  bool descent_enabled() const;
+
+  /**
+   * @brief Register this entry as part of a multi-volume (split) archive
+   * @param base_name Base name without the volume suffix (e.g., "archive.tar.gz")
+   * @param options Optional configuration (e.g., preserve Given ordering)
+   *
+   * Register each entry that belongs to the same multi-volume group so that
+   * once traversal of the parent archive finishes, the parts are combined
+   * automatically. The traverser will then descend into the combined archive
+   * and continue processing its contents.
+   *
+   * Example:
+   * @code
+   * for (Entry& entry : traverser) {
+   *     if (entry.path().find(".part") != std::string::npos) {
+   *         std::string base = extract_base_name(entry.path());
+   *         entry.set_multi_volume_group(base);
+   *     }
+   * }
+   * @endcode
+   */
+  void set_multi_volume_group(const std::string &base_name, const MultiVolumeGroupOptions &options = {});
+
+  /**
+   * @brief Get metadata captured for this entry
+   * @return Immutable metadata map keyed by libarchive field names
+   */
+  const EntryMetadataMap &metadata() const;
+
+  /**
+   * @brief Look up a metadata value by key
+   * @param key Metadata key (e.g., "uid", "mtime")
+   * @return Pointer to the stored value, or nullptr if not present
+   */
+  const EntryMetadataValue *find_metadata(const std::string &key) const;
+
+  static std::unique_ptr<Entry> create(PathHierarchy hierarchy, std::shared_ptr<ArchiveStackOrchestrator> data_source_orchestrator, bool default_descent);
+
+  // Copy/move operations
+  Entry(const Entry &);
+  Entry &operator=(const Entry &);
+  Entry(Entry &&) noexcept;
+  Entry &operator=(Entry &&) noexcept;
+
+  ~Entry();
+
+private:
+  class Impl;
+  std::unique_ptr<Impl> _impl;
+
+  // Private constructor - only friends can create Entry objects
+  explicit Entry(Impl *impl);
+  Entry(const PathHierarchy &hierarchy, std::shared_ptr<ArchiveStackOrchestrator> data_source_orchestrator, bool default_descent);
+};
+
+} // namespace archive_r

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

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 archive_r Team
+
+#pragma once
+
+#include "archive_r/path_hierarchy.h"
+
+#include <functional>
+#include <string>
+
+namespace archive_r {
+
+/** Describes a recoverable failure encountered while visiting an entry. */
+struct EntryFault {
+  PathHierarchy hierarchy; ///< Path hierarchy where the fault occurred
+  std::string message;     ///< Human readable description
+  int errno_value = 0;     ///< Optional errno captured from the failing API
+};
+
+/** Callback signature used to surface EntryFault notifications. */
+using FaultCallback = std::function<void(const EntryFault &)>;
+
+/**
+ * @brief Register a global callback to receive EntryFault notifications.
+ * Pass an empty std::function to clear the callback.
+ */
+void register_fault_callback(FaultCallback callback);
+
+/**
+ * @brief Dispatch a fault through the globally registered callback, if any.
+ */
+void dispatch_registered_fault(const EntryFault &fault);
+
+} // namespace archive_r

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

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 archive_r Team
+
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <unordered_map>
+#include <variant>
+#include <vector>
+
+namespace archive_r {
+
+/** POSIX-style timestamp with sub-second precision. */
+struct EntryMetadataTime {
+  int64_t seconds;
+  int32_t nanoseconds;
+};
+
+/** Sparse file chunk (offset + stored length). */
+struct EntryMetadataSparseChunk {
+  int64_t offset;
+  int64_t length;
+};
+
+/** Extended attribute key/value pair. */
+struct EntryMetadataXattr {
+  std::string name;
+  std::vector<uint8_t> value;
+};
+
+/** Generic digest (algorithm + raw bytes). */
+struct EntryMetadataDigest {
+  std::string algorithm;
+  std::vector<uint8_t> value;
+};
+
+/** Device identifiers for special files. */
+struct EntryMetadataDeviceNumbers {
+  uint64_t major;
+  uint64_t minor;
+};
+
+/** BSD-style file flags (bits to set/clear). */
+struct EntryMetadataFileFlags {
+  uint64_t set;
+  uint64_t clear;
+};
+
+using EntryMetadataValue = std::variant<std::monostate, bool, int64_t, uint64_t, std::string, std::vector<uint8_t>, EntryMetadataTime, EntryMetadataDeviceNumbers, EntryMetadataFileFlags,
+                                        std::vector<EntryMetadataXattr>, std::vector<EntryMetadataSparseChunk>, std::vector<EntryMetadataDigest>>;
+
+/** Unordered map storing metadata captured during traversal. */
+using EntryMetadataMap = std::unordered_map<std::string, EntryMetadataValue>;
+
+} // namespace archive_r

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

@@ -0,0 +1,46 @@
+// 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 <cstddef>
+#include <cstdint>
+#include <memory>
+
+namespace archive_r {
+
+class MultiVolumeStreamBase : public IDataStream {
+public:
+  ~MultiVolumeStreamBase() override;
+
+  ssize_t read(void *buffer, size_t size) override;
+  void rewind() override;
+  bool at_end() const override;
+  int64_t seek(int64_t offset, int whence) override;
+  int64_t tell() const override;
+  bool can_seek() const override { return _supports_seek; }
+  PathHierarchy source_hierarchy() const override { return _logical_path; }
+
+protected:
+  MultiVolumeStreamBase(PathHierarchy logical_path, bool supports_seek);
+
+  virtual void open_single_part(const PathHierarchy &single_part) = 0;
+  virtual void close_single_part() = 0;
+  virtual ssize_t read_from_single_part(void *buffer, size_t size) = 0;
+  virtual int64_t seek_within_single_part(int64_t offset, int whence) = 0;
+  virtual int64_t size_of_single_part(const PathHierarchy &single_part) = 0;
+
+  PathHierarchy _logical_path;
+  void deactivate_active_part();
+
+private:
+  friend struct Impl;
+  struct Impl;
+  std::unique_ptr<Impl> _impl;
+  const bool _supports_seek;
+};
+
+} // namespace archive_r

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

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 archive_r Team
+
+#pragma once
+
+#include <cstddef>
+#include <stdexcept>
+#include <string>
+#include <utility>
+#include <variant>
+#include <vector>
+
+namespace archive_r {
+
+/**
+ * @brief Represents a single component within a logical path hierarchy.
+ *
+ * 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:
+  struct Parts {
+    std::vector<std::string> values;
+    enum class Ordering { Natural, Given } ordering = Ordering::Natural;
+  };
+
+  using NodeList = std::vector<PathEntry>;
+
+  PathEntry() = default;
+
+  explicit PathEntry(std::string value)
+      : _value(std::move(value)) {}
+
+  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) {
+    Parts parts{ std::move(entries), ordering };
+    if (parts.values.empty()) {
+      throw std::invalid_argument("multi-volume parts cannot be empty");
+    }
+    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;
+};
+
+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.
+ * 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);
+
+/** Compare complete hierarchies lexicographically using compare_entries on each level. */
+int compare_hierarchies(const PathHierarchy &lhs, const PathHierarchy &rhs);
+
+/** Shorthand equality helpers for entries and hierarchies. */
+bool entries_equal(const PathEntry &lhs, const PathEntry &rhs);
+bool hierarchies_equal(const PathHierarchy &lhs, const PathHierarchy &rhs);
+
+/** Strict-weak-order functor suitable for associative containers. */
+struct PathHierarchyLess {
+  bool operator()(const PathHierarchy &lhs, const PathHierarchy &rhs) const;
+};
+
+/** Build a hierarchy containing a single leaf component. */
+PathHierarchy make_single_path(const std::string &root);
+
+/** Append helpers for single and multi-volume components. */
+void append_single(PathHierarchy &hierarchy, std::string value);
+void append_multi_volume(PathHierarchy &hierarchy, std::vector<std::string> parts, PathEntry::Parts::Ordering ordering = PathEntry::Parts::Ordering::Natural);
+
+/** Extract prefix/slice helpers. */
+PathHierarchy pathhierarchy_prefix_until(const PathHierarchy &hierarchy, size_t inclusive_index);
+PathHierarchy parent_hierarchy(const PathHierarchy &hierarchy);
+} // namespace archive_r

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

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 archive_r Team
+
+#pragma once
+
+#include "archive_r/path_hierarchy.h"
+#include <cstddef>
+#include <string>
+#include <vector>
+
+namespace archive_r {
+
+/** Return pointer to the Nth single value of an entry (nullptr if absent). */
+const std::string *path_entry_component_at(const PathEntry &entry, std::size_t index);
+
+/** Convenience helpers for multi-volume PathHierarchy nodes. */
+std::size_t pathhierarchy_volume_size(const PathHierarchy &logical);
+std::string pathhierarchy_volume_entry_name(const PathHierarchy &logical, std::size_t index);
+bool pathhierarchy_is_multivolume(const PathHierarchy &hierarchy);
+PathHierarchy pathhierarchy_select_single_part(const PathHierarchy &logical, std::size_t index);
+
+/** Combine sibling hierarchies that differ only by their terminal part list. */
+PathHierarchy merge_multi_volume_sources(const std::vector<PathHierarchy> &sources);
+
+/** Sort hierarchies using PathHierarchyLess semantics. */
+void sort_hierarchies(std::vector<PathHierarchy> &hierarchies);
+
+/** Render helpers converting entries to flattened strings for diagnostics. */
+bool flatten_entry_to_string(const PathEntry &entry, std::string &output);
+bool entry_name_from_component(const PathEntry &entry, std::string &output);
+
+/** Human readable pretty-printers used in logging and debug output. */
+std::string path_entry_display(const PathEntry &entry);
+std::string hierarchy_display(const PathHierarchy &hierarchy);
+
+
+} // namespace archive_r