omnizip 0.4.7-x86_64-linux

data/lib/omnizip/implementations/base/state_machine_base.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2025 Ribose Inc.
+#
+# 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.
+
+module Omnizip
+  module Implementations
+    module Base
+      # Abstract base class for LZMA state machines.
+      #
+      # Both XZ Utils and 7-Zip use a 12-state finite state machine (FSM)
+      # for tracking the encoding context. However, they have different
+      # transition tables between states.
+      #
+      # The 12 states are:
+      # - States 0-6: Literal mode (last symbol was a literal)
+      # - States 7-9: Match mode (last symbol was a match)
+      # - States 10-11: Short rep match mode (last symbol was a rep match of length 1)
+      #
+      # State transitions depend on whether the current symbol is:
+      # - A literal (byte)
+      # - A match (length + distance)
+      # - A repeated match (using rep0-rep3)
+      #
+      # Subclasses must provide their specific transition table via
+      # the {#update!} method.
+      #
+      # @abstract Subclasses must implement {#update!}
+      class StateMachineBase
+        # All valid LZMA states (0-11)
+        STATES = (0..11)
+
+        # States where literal encoding should use matched literal mode
+        # (i.e., compare with match byte at rep0)
+        LITERAL_MATCHED_STATES = [7, 8, 9, 10, 11].freeze
+
+        attr_reader :state
+
+        # Initialize the state machine.
+        #
+        # @param initial_state [Integer] Initial state value (default: 0)
+        def initialize(initial_state = 0)
+          unless STATES.include?(initial_state)
+            raise ArgumentError,
+                  "Invalid initial state: #{initial_state}, must be 0-11"
+          end
+
+          @state = initial_state
+        end
+
+        # Reset to initial state.
+        #
+        # @return [void]
+        def reset!
+          @state = 0
+        end
+
+        # Update state based on encoding decision.
+        #
+        # Both XZ Utils and 7-Zip use different transition tables.
+        # Subclasses must implement this with their specific table.
+        #
+        # @param is_match [Boolean] true if last symbol was a match, false if literal
+        # @param is_short_rep [Boolean] true if last symbol was a short rep (length=1)
+        # @raise [NotImplementedError] Always raised in base class
+        # @return [void]
+        def update!(is_match, is_short_rep: false)
+          raise NotImplementedError,
+                "#{self.class} must implement #update!"
+        end
+
+        # Update state for literal encoding.
+        #
+        # This is a convenience method that calls {#update!} with is_match=false.
+        #
+        # @return [void]
+        def update_literal!
+          update!(false)
+        end
+
+        # Update state for match encoding.
+        #
+        # This is a convenience method that calls {#update!} with is_match=true.
+        #
+        # @return [void]
+        def update_match!(_distance = nil)
+          update!(true)
+        end
+
+        # Update state for short rep match (length=1).
+        #
+        # This is a convenience method that calls {#update!} with appropriate params.
+        #
+        # @return [void]
+        def update_short_rep!
+          update!(true, is_short_rep: true)
+        end
+
+        # Update state for long rep match (length>1).
+        #
+        # This is a convenience method that calls {#update!} with appropriate params.
+        #
+        # @return [void]
+        def update_long_rep!
+          update!(true, is_short_rep: false)
+        end
+
+        # Check if currently in literal mode.
+        #
+        # States 0-6 are considered "literal mode" where the last symbol
+        # was a literal byte.
+        #
+        # @return [Boolean] true if in literal mode (states 0-6)
+        def literal_mode?
+          @state < 7
+        end
+
+        # Check if currently in match mode.
+        #
+        # States 7-11 are considered "match mode" where the last symbol
+        # was a match of some kind.
+        #
+        # @return [Boolean] true if in match mode (states 7-11)
+        def match_mode?
+          @state >= 7
+        end
+
+        # Check if matched literal encoding should be used.
+        #
+        # In states 7-11, literal encoding should compare with the match byte
+        # at rep0 for better compression.
+        #
+        # @return [Boolean] true if matched literal should be used
+        def use_matched_literal?
+          LITERAL_MATCHED_STATES.include?(@state)
+        end
+
+        # Get state as integer.
+        #
+        # This is used for probability model indexing.
+        #
+        # @return [Integer] Current state value (0-11)
+        def value
+          @state
+        end
+
+        # Set state directly.
+        #
+        # This is useful for initialization or testing.
+        #
+        # @param new_state [Integer] New state value (0-11)
+        # @raise [ArgumentError] If state is invalid
+        # @return [void]
+        def state=(new_state)
+          unless STATES.include?(new_state)
+            raise ArgumentError,
+                  "Invalid state: #{new_state}, must be 0-11"
+          end
+
+          @state = new_state
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/implementations/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Implementations
+    # Base classes for implementation inheritance
+    module Base
+      autoload :LZMADecoderBase,
+               "omnizip/implementations/base/lzma_decoder_base"
+      autoload :LZMAEncoderBase,
+               "omnizip/implementations/base/lzma_encoder_base"
+      autoload :LZMA2DecoderBase,
+               "omnizip/implementations/base/lzma2_decoder_base"
+      autoload :LZMA2EncoderBase,
+               "omnizip/implementations/base/lzma2_encoder_base"
+      autoload :StateMachineBase,
+               "omnizip/implementations/base/state_machine_base"
+    end
+  end
+end

data/lib/omnizip/implementations/rust/archive.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Implementations
+    module Rust
+      # Whole-archive acceleration over the cdylib: open any supported
+      # format (auto-detected), list entries, read entry bytes. This is
+      # the archive-level tier surface — the Ruby core remains the
+      # fallback (the cdylib unavailable ⇒ these raise LibraryMissing
+      # and callers fall back).
+      class Archive
+        class LibraryMissing < StandardError; end
+
+        # Built lazily inside #initialize: the Fiddle::TYPE_* constants
+        # only resolve after a successful require, and Ruby 4.0 moved
+        # fiddle out of the default gems (same reason
+        # Library.function_table is a method, not a constant).
+        def initialize(data, password: nil)
+          lib = Library.instance
+          raise LibraryMissing, "omnizip-ffi cdylib not loaded" unless lib
+
+          @lib = lib
+          funcs = function_table
+          @funcs = funcs.each_with_object({}) do |(key, (name, args, ret)), h|
+            h[key] = lib.bind(name, args, ret)
+          end
+
+          pw = password&.to_s
+          pw_ptr = pw && !pw.empty? ? Fiddle::Pointer[pw] : nil
+          @handle = @funcs[:arch_open].call(Fiddle::Pointer[data], data.bytesize, pw_ptr)
+          return unless @handle.null?
+
+          raise Error, @lib.last_error
+        end
+
+        def entry_count
+          @funcs[:arch_count].call(@handle)
+        end
+
+        def entry_names
+          (0...entry_count).map do |i|
+            ptr = @funcs[:arch_entry_name].call(@handle, i)
+            next nil if ptr.null?
+
+            ptr.to_s
+          end
+        end
+
+        def entry_size(index)
+          @funcs[:arch_entry_size].call(@handle, index)
+        end
+
+        # Read one entry's uncompressed bytes.
+        #
+        # @return [String] binary
+        def read_entry(index)
+          out_len = [0].pack("Q")
+          ptr = @funcs[:arch_read_entry].call(@handle, index, out_len)
+          raise Error, @lib.last_error if ptr.null?
+
+          @lib.take_buffer(ptr, out_len.unpack1("Q"))
+        end
+
+        def close
+          return unless @handle
+
+          @funcs[:arch_close].call(@handle)
+          @handle = nil
+        end
+
+        def self.open(data, password: nil)
+          archive = new(data, password: password)
+          yield archive
+        ensure
+          archive&.close
+        end
+
+        private
+
+        def function_table
+          {
+            arch_open: ["ozip_arch_open", %i[voidp size_t voidp], Fiddle::TYPE_VOIDP],
+            arch_count: ["ozip_arch_count", [:voidp], Fiddle::TYPE_SIZE_T],
+            arch_entry_name: ["ozip_arch_entry_name", %i[voidp size_t], Fiddle::TYPE_VOIDP],
+            arch_entry_size: ["ozip_arch_entry_size", %i[voidp size_t], Fiddle::TYPE_VOIDP],
+            arch_read_entry: ["ozip_arch_read_entry", %i[voidp size_t voidp], Fiddle::TYPE_VOIDP],
+            arch_close: ["ozip_arch_close", [:voidp], Fiddle::TYPE_VOID],
+          }
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/implementations/rust/library.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+begin
+  # Ruby 4.0 moved fiddle out of the default gems.
+  require "fiddle"
+  require "pathname"
+rescue LoadError
+  # :nocov:
+end
+
+module Omnizip
+  module Implementations
+    module Rust
+      # The loaded cdylib: one handle, lazily opened, thread-safe
+      # after initialization (Fiddle::Function is immutable once
+      # built; compress/decompress are pure C calls).
+      class Library
+        # Codecs the cdylib dispatches by name.
+        # Names the cdylib dispatches: the codec-level acceleration
+        # surface (both directions by default — Rust is the
+        # authority; Ruby is the fallback).
+        CODECS = %w[
+          bzip2 zstd lzma xz lzma-alone lzip
+          deflate deflate64 zlib gzip ppmd7 ppmd8
+        ].freeze
+
+        class << self
+          # The shared handle, or nil when the cdylib cannot load.
+          # Load failures are cached: a missing library is a stable
+          # condition, not something to re-attempt per call.
+          def instance
+            return @instance if defined?(@instance)
+
+            @instance = open
+          end
+
+          def available?
+            !instance.nil?
+          end
+
+          # Whether the cdylib dispatches this codec name — exact, or
+          # a param-carrying prefix ("ppmd7:o6:m16777216" under
+          # "ppmd7").
+          def supports?(name)
+            CODECS.any? { |c| name == c || name.start_with?("#{c}:") }
+          end
+
+          # Drop the cached handle so resolution reruns (test seam:
+          # specs exercising fallback/absence paths need a clean
+          # slate; production never calls this).
+          def forget!
+            # Remove the ivar entirely: assigning nil would leave it
+            # defined, and `instance`'s `defined?` guard would return
+            # the nil forever without ever re-opening the library.
+            remove_instance_variable(:@instance) if defined?(@instance)
+            nil
+          end
+
+          # Built lazily: the Fiddle::TYPE_* constants only resolve
+          # after a successful require; environments without fiddle
+          # (Ruby 4.0 without the gem) never touch this table.
+          def function_table
+            {
+              last_error: ["ozip_last_error", [], Fiddle::TYPE_VOIDP],
+              free: ["ozip_free", %i[voidp size_t], Fiddle::TYPE_VOID],
+              compress: [
+                "ozip_compress",
+                %i[voidp voidp size_t int voidp],
+                Fiddle::TYPE_VOIDP,
+              ],
+              decompress: [
+                "ozip_decompress",
+                %i[voidp voidp size_t size_t voidp],
+                Fiddle::TYPE_VOIDP,
+              ],
+            }
+          end
+
+          # The Rust release the loaded cdylib was built from (e.g.
+          # "0.21.108"), read through the ozip_version symbol — the
+          # platform-gem smoke gate asserts it matches. nil when the
+          # library is absent or predates the symbol.
+          def dylib_version
+            handle = instance&.instance_handle
+            return nil if handle.nil?
+
+            func = Fiddle::Function.new(handle["ozip_version"], [], Fiddle::TYPE_VOIDP)
+            ptr = func.call
+            ptr.null? ? nil : ptr.to_s
+          rescue StandardError
+            nil
+          end
+
+          # Resolve the cdylib path. Precedence:
+          #
+          #   1. OMNIZIP_NO_RUST=1 — hard kill switch (always nil, so
+          #      the pure-Ruby core handles everything; also the smoke
+          #      gate for "works without Rust").
+          #   2. OMNIZIP_FFI_DYLIB — explicit path (developer override).
+          #   3. vendor/ — the prebuilt cdylib. Platform gems ship it
+          #      here and `rake rust:build` writes here; rubygems
+          #      already matched the platform at install time, so no
+          #      runtime architecture probing is needed and the wrong
+          #      arch cannot be picked.
+          #   4. ext/ (legacy location).
+          #   5. A sibling omnizip-rs checkout.
+          #
+          # `dirs` overrides 3-5 (spec seam: staged candidate paths).
+          def resolve_path(dirs = nil)
+            return nil if ENV.fetch("OMNIZIP_NO_RUST", nil) == "1"
+
+            explicit = ENV.fetch("OMNIZIP_FFI_DYLIB", nil)
+            return Pathname.new(explicit) if explicit && File.file?(explicit)
+
+            candidates = dirs || [
+              Pathname.new(__dir__).join("../../../../vendor"),
+              Pathname.new(__dir__).join("../../../../ext/libomnizip_ffi"),
+              *sibling_checkout,
+            ]
+
+            %w[.dylib .so .dll].each do |ext|
+              candidates.each do |dir|
+                path = dir.join("libomnizip_ffi#{ext}")
+                return path if path.file?
+              end
+            end
+            nil
+          end
+
+          private
+
+          def open
+            path = resolve_path
+            return nil if path.nil?
+
+            handle = Fiddle.dlopen(path.to_s)
+            funcs = function_table.each_with_object({}) do |(key, (name, args, ret)), h|
+              h[key] = Fiddle::Function.new(handle[name], args, ret)
+            end
+            new(funcs, handle)
+          rescue StandardError => e # includes Fiddle::DLError
+            warn "omnizip: rust backend unavailable (#{e.message}); using pure Ruby" if ENV["OMNIZIP_BACKEND"] == "rust"
+            nil
+          end
+
+          # A sibling omnizip-rs checkout: ../omnizip-rs relative to
+          # this gem's repository root.
+          def sibling_checkout
+            gem_root = Pathname.new(__dir__).join("../../../../..")
+            %w[omnizip-rs target/release].map do |rel|
+              gem_root.join(rel, "target/release")
+            end
+          end
+        end
+
+        def initialize(functions, handle = nil)
+          @functions = functions.freeze
+          @handle = handle
+        end
+
+        def compress(codec, data, level)
+          out_len = [0].pack("Q")
+          ptr = call(:compress, codec, data, data.bytesize, level, out_len)
+          take(ptr, out_len.unpack1("Q"))
+        end
+
+        def decompress(codec, data, expected_len)
+          out_len = [0].pack("Q")
+          ptr = call(:decompress, codec, data, data.bytesize, expected_len, out_len)
+          take(ptr, out_len.unpack1("Q"))
+        end
+
+        # Bind one extra C symbol from the loaded cdylib (the archive
+        # surface uses this; Fiddle::Function is immutable once built).
+        def bind(symbol, args, ret)
+          handle = instance_handle
+          raise Error, "cdylib not loaded" if handle.nil?
+
+          Fiddle::Function.new(handle[symbol.to_s], args, ret)
+        end
+
+        def last_error
+          ptr = @functions[:last_error].call
+          ptr.null? ? "unknown error" : ptr.to_s
+        end
+
+        # The raw Fiddle::Handle (for extra symbol binds).
+        def instance_handle
+          @handle
+        end
+
+        # Copy out + free one returned buffer (public seam for the
+        # archive surface).
+        def take_buffer(ptr, len)
+          take(ptr, len)
+        end
+
+        private
+
+        def call(name, codec, input, input_len, a, out_len)
+          ptr = @functions[name].call(codec, input, input_len, a, out_len)
+          raise Error, last_error if ptr.null?
+
+          ptr
+        end
+
+        # Copy out + free in one breath: the buffer belongs to the
+        # Rust allocator and must never outlive ozip_free.
+        def take(ptr, len)
+          string = ptr.to_s(len)
+          @functions[:free].call(ptr, len)
+          string
+        end
+      end
+
+      # Raised when a codec call fails; #message carries the Rust
+      # side's last_error text.
+      class Error < StandardError; end
+    end
+  end
+end

data/lib/omnizip/implementations/rust.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Implementations
+    # Rust-accelerated codec backend (TODO.ref-parity/62).
+    #
+    # Loads the omnizip-ffi cdylib through stdlib Fiddle — no
+    # compiled Ruby extension, no rake-compiler. When the library
+    # is unavailable the gem transparently stays on the pure-Ruby
+    # path; nothing about the fallback is an error.
+    #
+    # Library resolution order:
+    #   1. ENV['OMNIZIP_FFI_DYLIB'] (explicit path)
+    #   2. ../target/release/ inside a sibling omnizip-rs checkout
+    #
+    # Tier policy (see Omnizip::Backends): Rust is the authority —
+    # validated against the reference C/C++ implementations and
+    # determinism-contracted — so `auto` routes BOTH directions
+    # through Rust whenever the library loads, with Ruby-core
+    # fallback on any Rust error.
+    module Rust
+      autoload :Library, "omnizip/implementations/rust/library"
+      autoload :Archive, "omnizip/implementations/rust/archive"
+    end
+  end
+end