omnizip 0.4.7-arm-linux

data/lib/omnizip/backends.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Omnizip
+  # Byte-level codec backend resolution — THE tier switch
+  # (TODO.ref-parity/62). Both paths share the algorithm classes'
+  # IO plumbing; only the byte core swaps.
+  #
+  # Policy:
+  #   OMNIZIP_BACKEND=ruby   force pure Ruby everywhere
+  #   OMNIZIP_BACKEND=rust   require the Rust library (raises when absent)
+  #   OMNIZIP_BACKEND=auto   (default) Rust for directions marked
+  #                          safe, Ruby otherwise, whenever the
+  #                          cdylib is loadable
+  #
+  # Safety marks (owner guidance 2026-09-19: some Ruby cores are
+  # LESS accurate than the Rust ports — be careful which tier is
+  # trusted for what):
+  #   - decompress -> :rust by default. Decode is output-invariant
+  #     AND the Rust decoders carry fixes the Ruby cores lack;
+  #     disagreements are treated as Ruby-side accuracy findings
+  #     (see the cross-tier differential spec), not coin flips.
+  #   - compress -> :ruby by default. Byte-stability for content
+  #     addressing (DropId dedup assumes identical frames); the
+  #     Rust encoders produce DIFFERENT valid streams (probed:
+  #     bzip2 L6, Ruby 906 B vs Rust 874 B). OMNIZIP_BACKEND=rust
+  #     opts into Rust encode where correctness-of-ratio is wanted
+  #     over frame stability.
+  module Backends
+    # Codecs whose Rust encoder is BYTE-IDENTICAL to the pure-Ruby
+    # 2026-09-20 policy flip (owner directive): RUST IS THE AUTHORITY
+    # — its encoders/decoders are the ports validated against the
+    # reference C/C++ implementations (bzip2, xz/liblzma, zstd,
+    # libdeflate), and they are determinism-contracted (same input +
+    # level => same bytes on every machine). :auto therefore routes
+    # BOTH directions through Rust whenever the cdylib loads; encode
+    # falls back to the Ruby core on any Rust error, so :auto is
+    # never worse than pure Ruby. The pure-Ruby cores remain the
+    # portable fallback and the OMNIZIP_BACKEND=ruby escape hatch.
+    RUST_AUTHORITATIVE = true
+
+    # usize::MAX — the FFI's "caller does not know the plaintext
+    # size" sentinel (streaming decode contract).
+    UNKNOWN_LENGTH = 0xFFFF_FFFF_FFFF_FFFF
+
+    class << self
+      def for(codec, _direction)
+        mode = ENV.fetch("OMNIZIP_BACKEND", "auto")
+
+        return backend_rust if mode == "rust"
+        return backend_ruby if mode == "ruby"
+
+        return backend_ruby unless Implementations::Rust::Library.available?
+        return backend_ruby unless Implementations::Rust::Library.supports?(codec)
+
+        backend_rust
+      end
+
+      # Compress through the tier-selected backend. The block is
+      # the pure-Ruby core — evaluated ONLY on the Ruby path, so
+      # the accelerated path never pays for it. A Rust encode error
+      # falls back to the Ruby core (auto is never worse than pure
+      # Ruby); only the forced `rust` mode propagates.
+      def compress(codec, data, level, &ruby_core)
+        backend = Backends.for(codec, :encode)
+        return yield if backend == RubyBackend
+
+        begin
+          backend.compress(codec, data, level)
+        rescue Implementations::Rust::Error => e
+          raise if ENV.fetch("OMNIZIP_BACKEND", "auto") == "rust"
+
+          warn "omnizip: rust #{codec} encode failed (#{e.message}); using ruby" if ENV["OMNIZIP_BACKEND_DEBUG"]
+          yield
+        end
+      end
+
+      # Decompress through the tier-selected backend (output-
+      # invariant: :auto prefers Rust whenever loadable). A Rust
+      # failure falls back to the Ruby core — the Ruby readers are
+      # the tolerant superset (legacy container variants, malformed
+      # inputs they historically accept), so :auto must never be
+      # WORSE than pure Ruby. Only the forced `rust` mode propagates.
+      def decompress(codec, data, expected_len, &ruby_core)
+        backend = Backends.for(codec, :decode)
+        return yield if backend == RubyBackend
+
+        begin
+          backend.decompress(codec, data, expected_len)
+        rescue Implementations::Rust::Error => e
+          raise if ENV.fetch("OMNIZIP_BACKEND", "auto") == "rust"
+
+          warn "omnizip: rust #{codec} decode failed (#{e.message}); using ruby" if ENV["OMNIZIP_BACKEND_DEBUG"]
+          yield
+        end
+      end
+
+      # Whole-archive tier helpers: nil means "Rust unavailable or
+      # entry not found — caller falls back to the Ruby reader".
+      def archive_entry_names(path)
+        Omnizip::Implementations::Rust::Archive.open(File.binread(path)) { |a| return a.entry_names }
+      rescue Omnizip::Implementations::Rust::Archive::LibraryMissing, Omnizip::Implementations::Rust::Error, StandardError
+        nil
+      end
+
+      # rubocop:disable-next Lint/ReturnInVoidContext
+      def archive_read_entry(path, entry_name)
+        Omnizip::Implementations::Rust::Archive.open(File.binread(path)) do |a|
+          idx = a.entry_names.index(entry_name)
+          return nil if idx.nil?
+
+          return a.read_entry(idx)
+        end
+      rescue Omnizip::Implementations::Rust::Archive::LibraryMissing, Omnizip::Implementations::Rust::Error, StandardError
+        nil
+      end
+
+      private
+
+      def backend_rust
+        RustBackend
+      end
+
+      def backend_ruby
+        RubyBackend
+      end
+    end
+
+    # The pure-Ruby path: a no-op backend — callers fall back to
+    # their own in-tree cores, which ARE the reference. Kept as an
+    # object for symmetry with the Rust side.
+    module RubyBackend
+      module_function
+
+      # :nocov:
+      def compress(codec, _data, _level)
+        raise Error, "#{codec}: ruby core not wired through Backends (call it directly)"
+      end
+
+      def decompress(codec, _data, _expected_len)
+        raise Error, "#{codec}: ruby core not wired through Backends (call it directly)"
+      end
+      # :nocov:
+    end
+
+    # The Rust-accelerated path over the Fiddle handle.
+    module RustBackend
+      module_function
+
+      def compress(codec, data, level)
+        Implementations::Rust::Library.instance.compress(codec, data, level)
+      end
+
+      def decompress(codec, data, expected_len)
+        Implementations::Rust::Library.instance.decompress(codec, data, expected_len)
+      end
+    end
+
+    class Error < StandardError; end
+  end
+end

data/lib/omnizip/buffer/memory_archive.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Buffer
+    # Wrapper for in-memory archive operations
+    #
+    # Provides unified interface for adding entries to and reading entries
+    # from archives stored in memory (StringIO). Works with both OutputStream
+    # (for creating) and InputStream (for reading).
+    #
+    # @example Creating an archive
+    #   writer = Formats::Zip::Writer.new(nil)
+    #   archive = MemoryArchive.new(writer, :zip)
+    #   archive.add('file.txt', 'content')
+    #   writer.write_to_io(buffer)
+    #
+    # @example Reading an archive
+    #   archive = MemoryArchive.new(Formats::Zip::Reader.new(path), :zip)
+    #   archive.each_entry do |entry|
+    #     puts entry.name
+    #   end
+    class MemoryArchive
+      attr_reader :format, :stream
+
+      # Initialize memory archive wrapper
+      #
+      # @param stream [Formats::Zip::Writer, Formats::Zip::Reader]
+      #   Native writer (write mode) or reader (read mode)
+      # @param format [Symbol] Archive format (:zip)
+      def initialize(stream, format)
+        @stream = stream
+        @format = format
+        @entries_cache = nil
+      end
+
+      # Add file from memory (write mode only)
+      #
+      # @param name [String] Entry name (path within archive)
+      # @param data [String] Entry content
+      # @param options [Hash] Entry options
+      # @option options [Time] :time Modification time (default: now)
+      # @option options [String] :comment Entry comment
+      # @option options [Symbol] :compression Compression method
+      #   (:store, :deflate)
+      # @option options [Integer] :level Compression level (1-9)
+      # @return [self] For method chaining
+      #
+      # @example Add multiple files
+      #   archive.add('file1.txt', 'content1')
+      #          .add('file2.txt', 'content2')
+      #          .add('dir/', '')  # Directory entry
+      #
+      # @raise [RuntimeError] If stream is not an OutputStream
+      def add(name, data, **options)
+        ensure_write_mode!
+
+        if name.end_with?("/") && data.to_s.empty?
+          stream.add_directory(name)
+        else
+          method = if options[:compression] == :store
+                     Formats::Zip::Constants::COMPRESSION_STORE
+                   end
+          stream.add_data(name, data, nil, compression_method: method)
+        end
+
+        self
+      end
+
+      # Add data with block (write mode only)
+      #
+      # @param name [String] Entry name
+      # @param options [Hash] Entry options
+      # @yield Block that returns content
+      # @yieldreturn [String] Entry content
+      # @return [self] For method chaining
+      #
+      # @example Add with block
+      #   archive.add_data('file.txt') { File.read('source.txt') }
+      def add_data(name, **options)
+        ensure_write_mode!
+        data = yield
+        add(name, data, **options)
+      end
+
+      # Iterate entries (read mode only)
+      #
+      # @yield [entry] Block called for each entry
+      # @yieldparam entry [Entry] Archive entry
+      # @return [void]
+      #
+      # @example Process all entries
+      #   archive.each_entry do |entry|
+      #     puts "#{entry.name}: #{entry.size} bytes"
+      #     content = entry.read unless entry.directory?
+      #   end
+      #
+      # @raise [RuntimeError] If stream is not an InputStream
+      def each_entry
+        ensure_read_mode!
+
+        stream.entries.each do |zip_entry|
+          yield(Entry.new(zip_entry, stream))
+        end
+      end
+
+      # Extract all entries to memory (read mode only)
+      #
+      # @return [Hash<String, String>] Filename => content mapping
+      #
+      # @example Extract all
+      #   files = archive.extract_all_to_memory
+      #   files.each { |name, content| puts "#{name}: #{content.size}" }
+      def extract_all_to_memory
+        ensure_read_mode!
+
+        result = {}
+        each_entry do |entry|
+          result[entry.name] = entry.read unless entry.directory?
+        end
+        result
+      end
+
+      # Get underlying buffer as string (write mode only)
+      #
+      # @return [String] Complete archive as binary string
+      #
+      # @example Get archive data
+      #   archive_data = archive.to_s
+      #   File.binwrite('output.zip', archive_data)
+      #
+      # @raise [RuntimeError] If stream is not an OutputStream
+      def to_s
+        ensure_write_mode!
+
+        # The buffer is owned by Buffer.create; this method should be
+        # called on the StringIO it returns instead.
+        raise NotImplementedError,
+              "Use Buffer.create return value instead"
+      end
+
+      # Entry wrapper with read capability
+      #
+      # Wraps underlying ZIP entry to provide consistent interface
+      # for reading entry data from the stream.
+      class Entry
+        attr_reader :name, :size, :compressed_size, :time, :comment
+
+        # Initialize entry wrapper
+        #
+        # @param entry [Formats::Zip::CentralDirectoryHeader] entry
+        # @param reader [Formats::Zip::Reader] Native archive reader
+        def initialize(entry, reader)
+          @entry = entry
+          @reader = reader
+          @name = entry.filename
+          @size = entry.uncompressed_size
+          @compressed_size = entry.compressed_size
+          @time = entry.time
+          @comment = entry.comment.to_s
+          @directory = entry.directory?
+          @content = nil
+          @pos = 0
+        end
+
+        # Read entry content
+        #
+        # @param size [Integer, nil] Number of bytes to read (nil for all)
+        # @return [String, nil] Entry data or nil if EOF
+        #
+        # @example Read entire entry
+        #   content = entry.read
+        #
+        # @example Read in chunks
+        #   while (chunk = entry.read(8192))
+        #     process_chunk(chunk)
+        #   end
+        def read(size = nil)
+          # IO-like streaming semantics: successive reads return
+          # successive chunks, nil at end-of-content. Callers like
+          # Pipe::StreamDecompressor loop on this — a read that
+          # always returns data would loop forever.
+          @content ||= @reader.read_entry(@name)
+          return nil if @pos >= @content.bytesize
+
+          chunk = if size
+                    @content.byteslice(@pos, size)
+                  else
+                    @content.byteslice(@pos, @content.bytesize - @pos)
+                  end
+          @pos += chunk.bytesize
+          chunk
+        end
+
+        # Check if entry is a directory
+        #
+        # @return [Boolean] True if directory entry
+        def directory?
+          @directory
+        end
+
+        # Check if entry is a file
+        #
+        # @return [Boolean] True if file entry
+        def file?
+          !@directory
+        end
+
+        # Get compression method
+        #
+        # @return [Symbol] Compression method (:store, :deflate, etc.)
+        def compression_method
+          @entry.compression_method
+        end
+
+        # Get CRC32 checksum
+        #
+        # @return [Integer] CRC32 value
+        def crc32
+          @entry.crc32
+        end
+      end
+
+      private
+
+      # Ensure stream is in write mode (native Writer)
+      #
+      # @raise [Omnizip::IOError] If not in write mode
+      def ensure_write_mode!
+        return if stream.is_a?(Omnizip::Formats::Zip::Writer)
+
+        raise Omnizip::IOError,
+              "Operation requires write mode (Formats::Zip::Writer)"
+      end
+
+      # Ensure stream is in read mode (native Reader)
+      #
+      # @raise [Omnizip::IOError] If not in read mode
+      def ensure_read_mode!
+        return if stream.is_a?(Omnizip::Formats::Zip::Reader)
+
+        raise Omnizip::IOError,
+              "Operation requires read mode (Formats::Zip::Reader)"
+      end
+    end
+  end
+end

data/lib/omnizip/buffer/memory_extractor.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "tmpdir"
+
+module Omnizip
+  module Buffer
+    # Extract archive contents to memory
+    #
+    # Provides efficient extraction of archive entries to Hash without
+    # loading all files at once. Uses lazy evaluation where possible.
+    #
+    # @example Extract all files
+    #   extractor = MemoryExtractor.new(zip_data)
+    #   files = extractor.extract_all
+    #   # => {"file1.txt" => "content1", "file2.txt" => "content2"}
+    #
+    # @example Extract single file
+    #   extractor = MemoryExtractor.new(zip_data)
+    #   content = extractor.extract_entry('file1.txt')
+    #   # => "content1"
+    class MemoryExtractor
+      attr_reader :format
+
+      # Initialize extractor
+      #
+      # @param data [String, StringIO] Archive data
+      # @param format [Symbol, nil] Archive format (auto-detected if nil)
+      #
+      # @example Create extractor
+      #   extractor = MemoryExtractor.new(zip_data)
+      #   extractor = MemoryExtractor.new(zip_buffer, format: :zip)
+      def initialize(data, format: nil)
+        @buffer = data.is_a?(StringIO) ? data : StringIO.new(data.b)
+        @format = format || detect_format
+        @extracted_cache = {}
+      end
+
+      # Extract all entries to Hash
+      #
+      # @return [Hash<String, String>] Filename => content mapping
+      #
+      # @example Extract everything
+      #   files = extractor.extract_all
+      #   files.keys  # => ["file1.txt", "file2.txt", "dir/file3.txt"]
+      def extract_all
+        result = {}
+
+        case @format
+        when :zip
+          extract_all_zip(result)
+        when :seven_zip, :"7z"
+          extract_all_seven_zip(result)
+        else
+          raise ArgumentError, "Unsupported format: #{@format}"
+        end
+
+        result
+      end
+
+      # Extract single entry by name
+      #
+      # @param name [String] Entry name to extract
+      # @return [String, nil] Entry content or nil if not found
+      #
+      # @example Extract specific file
+      #   content = extractor.extract_entry('readme.txt')
+      #   # => "Hello World"
+      def extract_entry(name)
+        # Check cache first
+        return @extracted_cache[name] if @extracted_cache.key?(name)
+
+        # Extract from archive
+        content = nil
+
+        case @format
+        when :zip
+          content = extract_entry_zip(name)
+        when :seven_zip, :"7z"
+          content = extract_entry_seven_zip(name)
+        else
+          raise ArgumentError, "Unsupported format: #{@format}"
+        end
+
+        # Cache the result
+        @extracted_cache[name] = content if content
+        content
+      end
+
+      # List all entry names without extracting
+      #
+      # @return [Array<String>] Entry names
+      #
+      # @example List files
+      #   extractor.list_entries
+      #   # => ["file1.txt", "dir/", "dir/file2.txt"]
+      def list_entries
+        names = []
+
+        case @format
+        when :zip
+          list_entries_zip(names)
+        when :seven_zip, :"7z"
+          SevenZipBridge.open(@buffer) { |archive| names.concat(archive.entry_names) }
+        else
+          raise ArgumentError, "Unsupported format: #{@format}"
+        end
+
+        names
+      end
+
+      # Check if entry exists in archive
+      #
+      # @param name [String] Entry name
+      # @return [Boolean] True if entry exists
+      #
+      # @example Check existence
+      #   extractor.entry_exists?('file.txt')  # => true
+      def entry_exists?(name)
+        list_entries.include?(name)
+      end
+
+      # Get total number of entries
+      #
+      # @return [Integer] Number of entries
+      def entry_count
+        list_entries.size
+      end
+
+      # Extract entries matching pattern
+      #
+      # @param pattern [Regexp, String] Pattern to match
+      # @return [Hash<String, String>] Matching entries
+      #
+      # @example Extract by pattern
+      #   extractor.extract_matching(/\.txt$/)
+      #   # => {"file1.txt" => "content1", "file2.txt" => "content2"}
+      def extract_matching(pattern)
+        pattern = Regexp.new(pattern) if pattern.is_a?(String)
+        result = {}
+
+        list_entries.each do |name|
+          next unless name&.match?(pattern)
+          next if name.end_with?("/") # Skip directories
+
+          content = extract_entry(name)
+          result[name] = content if content
+        end
+
+        result
+      end
+
+      private
+
+      # Delegate to the shared buffer-side sniffer
+      #
+      # @return [Symbol] Detected format
+      # @raise [Omnizip::FormatError] If format cannot be detected
+      def detect_format
+        Omnizip::Buffer.detect_format(@buffer)
+      end
+
+      # The native ZIP reader parses from a path; spill the buffer to
+      # a temporary file and yield a reader over it.
+      def with_zip_reader
+        @buffer.rewind
+        Dir.mktmpdir("omnizip_extractor_zip") do |tmp|
+          path = File.join(tmp, "buffer.zip")
+          File.binwrite(path, @buffer.read)
+          yield Omnizip::Formats::Zip::Reader.new(path)
+        end
+      end
+
+      # Extract all entries from ZIP through the native reader
+      #
+      # @param result [Hash] Hash to populate with entries
+      def extract_all_zip(result)
+        with_zip_reader do |reader|
+          reader.entries.each do |entry|
+            next if entry.directory?
+
+            content = reader.read_entry(entry.filename)
+            result[entry.filename] = content
+            @extracted_cache[entry.filename] = content
+          end
+        end
+      end
+
+      # Extract every file entry from 7z
+      #
+      # @param result [Hash] Hash to populate with entries
+      def extract_all_seven_zip(result)
+        @buffer.rewind
+        SevenZipBridge.open(@buffer) do |archive|
+          archive.extract_all_to_memory.each do |name, content|
+            result[name] = content
+            @extracted_cache[name] = content
+          end
+        end
+      end
+
+      # Extract single entry from 7z
+      #
+      # @param name [String] Entry name
+      # @return [String, nil] Entry content or nil if not found
+      def extract_entry_seven_zip(name)
+        @buffer.rewind
+        SevenZipBridge.open(@buffer) do |archive|
+          archive.read_entry(name)
+        end
+      end
+
+      # Extract single entry from ZIP through the native reader
+      #
+      # @param name [String] Entry name
+      # @return [String, nil] Entry content or nil if not found
+      def extract_entry_zip(name)
+        with_zip_reader do |reader|
+          entry = reader.entries.find { |e| e.filename == name }
+          reader.read_entry(name) if entry && !entry.directory?
+        end
+      end
+
+      # List all entry names from ZIP through the native reader
+      #
+      # @param names [Array] Array to populate with names
+      def list_entries_zip(names)
+        with_zip_reader do |reader|
+          reader.entries.each { |entry| names << entry.filename }
+        end
+      end
+    end
+  end
+end