omnizip 0.3.1

data/lib/omnizip/filters/registry.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2024 Ribose Inc.
+#
+# This file is part of Omnizip.
+#
+# Omnizip is a pure Ruby port of 7-Zip compression algorithms.
+# Based on the 7-Zip LZMA SDK by Igor Pavlov.
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# See the COPYING file for the complete text of the license.
+#
+
+require_relative "filter_base"
+require_relative "bcj_x86"
+require_relative "bcj_arm"
+require_relative "bcj_arm64"
+require_relative "bcj_ia64"
+require_relative "bcj_ppc"
+require_relative "bcj_sparc"
+require_relative "bcj2"
+require_relative "delta"
+require_relative "bcj" # Unified BCJ filter (Task 2)
+require_relative "../filter_registry"
+
+module Omnizip
+  module Filters
+    # Registry for auto-registering all preprocessing filters.
+    #
+    # This module centralizes filter registration, ensuring all filters
+    # are properly registered with their supported formats.
+    module Registry
+      # Register all BCJ filters with appropriate format support.
+      #
+      # BCJ filters are architecture-specific filters for executable code.
+      # XZ format supports a subset of architectures (no ARM64),
+      # while 7z supports all.
+      #
+      # @return [void]
+      def self.register_bcj_filters
+        # Individual BCJ architecture filters (use hyphens to match existing convention)
+        register_bcj_filter(:'bcj-x86', BcjX86, architecture: :x86)
+        register_bcj_filter(:'bcj-arm', BcjArm, architecture: :arm)
+        register_bcj_filter(:'bcj-arm64', BcjArm64, architecture: :arm64,
+                                                    xz_supported: false)
+        register_bcj_filter(:'bcj-ia64', BcjIa64, architecture: :ia64)
+        register_bcj_filter(:'bcj-ppc', BcjPpc, architecture: :powerpc)
+        register_bcj_filter(:'bcj-sparc', BcjSparc, architecture: :sparc)
+
+        # Unified BCJ filter (Task 2) - supports all architectures
+        # Note: We register it as 'bcj' without architecture suffix
+        Omnizip::FilterRegistry.register_with_formats(
+          :bcj,
+          Omnizip::Filters::BCJ,
+          formats: [:seven_zip], # Only 7z for now (uses architecture parameter)
+        )
+      end
+
+      # Register a BCJ filter with format support.
+      #
+      # @param name [Symbol] Filter name identifier
+      # @param filter_class [Class] Filter class to register
+      # @param architecture [Symbol] Target architecture
+      # @param xz_supported [Boolean] Whether XZ format supports this architecture
+      # @return [void]
+      def self.register_bcj_filter(name, filter_class, architecture:,
+xz_supported: true)
+        formats = [:seven_zip]
+        formats << :xz if xz_supported
+        Omnizip::FilterRegistry.register_with_formats(name, filter_class,
+                                                      formats: formats)
+      end
+
+      # Register Delta filter.
+      #
+      # Delta filter is supported by both XZ and 7z formats.
+      #
+      # @return [void]
+      def self.register_delta_filter
+        Omnizip::FilterRegistry.register_with_formats(
+          :delta,
+          Delta,
+          formats: %i[seven_zip xz],
+        )
+      end
+
+      # Register BCJ2 filter.
+      #
+      # BCJ2 is a 4-stream variant of BCJ, primarily used by 7z.
+      # XZ does not support BCJ2.
+      #
+      # @return [void]
+      def self.register_bcj2_filter
+        Omnizip::FilterRegistry.register_with_formats(
+          :bcj2,
+          Bcj2,
+          formats: [:seven_zip], # Only 7z supports BCJ2
+        )
+      end
+
+      # Register all filters.
+      #
+      # This method registers all available filters with their
+      # appropriate format support. Call this during application
+      # initialization to ensure all filters are available.
+      #
+      # @return [void]
+      def self.register_all
+        register_bcj_filters
+        register_delta_filter
+        register_bcj2_filter
+      end
+    end
+  end
+end
+
+# Auto-register all filters on load
+Omnizip::Filters::Registry.register_all

data/lib/omnizip/filters/xz_delta.rb

@@ -0,0 +1,258 @@
+# 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.
+#
+# XZ Utils Delta filter implementation.
+#
+# This is the XZ Utils Delta filter (filter ID 0x03), which is DIFFERENT
+# from the 7-Zip Delta filter. Both compute byte-wise differences but use
+# different algorithms:
+#
+# - 7-Zip Delta: Simple forward difference (new[i] = old[i] - old[i-distance])
+# - XZ Utils Delta: Uses a 256-byte circular history buffer
+#
+# Reference: /Users/mulgogi/src/external/xz/src/liblzma/delta/
+#
+# Algorithm summary:
+# - Maintains a 256-byte circular history buffer
+# - Encoder: out[i] = in[i] - history[(distance + pos) & 0xFF]
+# - Decoder: out[i] = in[i] + history[(distance + pos) & 0xFF]
+# - history[pos & 0xFF] = processed_byte (updated in both encode/decode)
+# - pos decrements each byte, wrapping via & 0xFF
+#
+# The distance parameter (1-256) determines how far back in the history
+# to look for the delta reference value.
+
+module Omnizip
+  module Filters
+    # XZ Utils Delta filter.
+    #
+    # This filter computes byte-wise differences using a 256-byte circular
+    # history buffer. It is particularly effective for:
+    # - Stereo audio (distance=4 for 16-bit samples)
+    # - RGB images (distance=3)
+    # - RGBA images (distance=4)
+    # - Multi-channel data with regular patterns
+    #
+    # This is DIFFERENT from the 7-Zip Delta filter which uses simple
+    # forward differences without a history buffer.
+    #
+    # Reference: XZ Utils delta_encoder.c, delta_decoder.c
+    class XzDeltaFilter
+      # Filter ID for XZ format
+      FILTER_ID = 0x03
+
+      # Minimum distance value (XZ Utils LZMA_DELTA_DIST_MIN)
+      DELTA_DIST_MIN = 1
+
+      # Maximum distance value (XZ Utils LZMA_DELTA_DIST_MAX)
+      DELTA_DIST_MAX = 256
+
+      # History buffer size (always 256 bytes in XZ Utils)
+      HISTORY_SIZE = 256
+
+      # Delta type (only BYTE is supported in XZ Utils)
+      DELTA_TYPE_BYTE = 0
+
+      attr_reader :distance
+
+      # Initialize the Delta filter.
+      #
+      # @param distance [Integer] Byte distance for delta calculation (1-256)
+      # @raise [ArgumentError] If distance is invalid
+      def initialize(distance = DELTA_DIST_MIN)
+        validate_distance(distance)
+        @distance = distance
+        # Initialize state (matches XZ Utils lzma_delta_coder_init)
+        @pos = 0
+        @history = ("\x00" * HISTORY_SIZE).b
+      end
+
+      # Encode (preprocess) data by computing forward differences.
+      #
+      # For each byte:
+      #   tmp = history[(distance + pos) & 0xFF]
+      #   history[pos & 0xFF] = in[i]
+      #   out[i] = in[i] - tmp (mod 256)
+      #   pos--
+      #
+      # Reference: XZ Utils delta_encoder.c:copy_and_encode
+      #
+      # @param data [String] Binary data to encode
+      # @return [String] Encoded binary data
+      def encode(data)
+        return data.dup.b if data.empty?
+
+        result = data.dup.b
+        data.bytes.each_with_index do |byte, i|
+          # Get historical value from distance positions back
+          tmp = @history.getbyte((@distance + @pos) & 0xFF)
+
+          # Store current byte in history
+          @history.setbyte(@pos & 0xFF, byte)
+
+          # Output is the difference
+          result.setbyte(i, (byte - tmp) & 0xFF)
+
+          # Move position backward (wraps via & 0xFF)
+          @pos = (@pos - 1) & 0xFF
+        end
+
+        result
+      end
+
+      # Decode (postprocess) data by restoring from differences.
+      #
+      # For each byte:
+      #   buffer[i] += history[(distance + pos) & 0xFF] (mod 256)
+      #   history[pos & 0xFF] = buffer[i]
+      #   pos--
+      #
+      # Reference: XZ Utils delta_decoder.c:decode_buffer
+      #
+      # @param data [String] Binary data to decode
+      # @return [String] Decoded binary data
+      def decode(data)
+        return data.dup.b if data.empty?
+
+        result = data.dup.b
+        data.bytes.each_with_index do |byte, i|
+          # Get historical value from distance positions back
+          tmp = @history.getbyte((@distance + @pos) & 0xFF)
+
+          # Restore original value by adding the difference
+          result.setbyte(i, (byte + tmp) & 0xFF)
+
+          # Store restored byte in history
+          @history.setbyte(@pos & 0xFF, result.getbyte(i))
+
+          # Move position backward (wraps via & 0xFF)
+          @pos = (@pos - 1) & 0xFF
+        end
+
+        result
+      end
+
+      # Reset the filter state.
+      #
+      # This clears the history buffer and resets position to 0.
+      # Used when initializing a new filter chain.
+      #
+      # @return [void]
+      def reset
+        @pos = 0
+        @history = ("\x00" * HISTORY_SIZE).b
+      end
+
+      class << self
+        # Decode properties byte to get distance.
+        #
+        # XZ Utils encodes distance as: props[0] = dist - 1
+        # So we decode as: dist = props[0] + 1
+        #
+        # Reference: XZ Utils delta_decoder.c:lzma_delta_props_decode
+        #
+        # @param properties [String] Properties byte (1 byte)
+        # @return [Integer] Distance value (1-256)
+        # @raise [ArgumentError] If properties size is invalid
+        def decode_properties(properties)
+          unless properties.is_a?(String) && properties.bytesize == 1
+            raise ArgumentError,
+                  "Delta filter requires exactly 1 property byte, got #{properties&.bytesize}"
+          end
+
+          props_byte = properties.getbyte(0)
+          # XZ Utils: opt->dist = props[0] + LZMA_DELTA_DIST_MIN
+          # where LZMA_DELTA_DIST_MIN = 1
+          distance = props_byte + DELTA_DIST_MIN
+
+          # Validate distance is in valid range (inline for class method)
+          unless distance.between?(DELTA_DIST_MIN, DELTA_DIST_MAX)
+            raise ArgumentError,
+                  "Invalid distance #{distance}, must be between #{DELTA_DIST_MIN} and #{DELTA_DIST_MAX}"
+          end
+
+          distance
+        end
+
+        # Encode distance to properties byte.
+        #
+        # XZ Utils encodes distance as: props[0] = dist - 1
+        #
+        # Reference: XZ Utils delta_encoder.c:lzma_delta_props_encode
+        #
+        # @param distance [Integer] Distance value (1-256)
+        # @return [String] Properties byte (1 byte)
+        # @raise [ArgumentError] If distance is invalid
+        def encode_properties(distance)
+          # Validate distance (inline for class method)
+          unless distance.is_a?(Integer)
+            raise ArgumentError,
+                  "Distance must be an integer, got #{distance.class}"
+          end
+
+          unless distance.between?(DELTA_DIST_MIN, DELTA_DIST_MAX)
+            raise ArgumentError,
+                  "Distance must be between #{DELTA_DIST_MIN} and #{DELTA_DIST_MAX}, got #{distance}"
+          end
+
+          # XZ Utils: out[0] = opt->dist - LZMA_DELTA_DIST_MIN
+          # where LZMA_DELTA_DIST_MIN = 1
+          props_byte = distance - DELTA_DIST_MIN
+
+          [props_byte].pack("C")
+        end
+
+        # Get metadata about this filter.
+        #
+        # @return [Hash] Filter metadata
+        def metadata
+          {
+            name: "XZ Delta",
+            description: "XZ Utils Delta filter with 256-byte circular history buffer",
+            filter_id: FILTER_ID,
+            typical_usage: "WAV audio (distance=4), BMP images (distance=3), " \
+                           "multi-channel data with regular patterns",
+          }
+        end
+      end
+
+      private
+
+      # Validate distance parameter.
+      #
+      # @param dist [Integer] Distance value to validate
+      # @raise [ArgumentError] If distance is invalid
+      # @return [void]
+      def validate_distance(dist)
+        unless dist.is_a?(Integer)
+          raise ArgumentError, "Distance must be an integer, got #{dist.class}"
+        end
+
+        unless dist.between?(DELTA_DIST_MIN, DELTA_DIST_MAX)
+          raise ArgumentError,
+                "Distance must be between #{DELTA_DIST_MIN} and #{DELTA_DIST_MAX}, got #{dist}"
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/format_detector.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Omnizip
+  # Detects archive format from file signature/magic bytes
+  #
+  # This class identifies archive formats based on their file signatures.
+  # It distinguishes between XZ Utils format (.xz) and 7-Zip format (.7z)
+  # which are DIFFERENT implementations of LZMA/LZMA2 compression.
+  #
+  # @example Basic usage
+  #   format = Omnizip::FormatDetector.detect("archive.xz")
+  #   case format
+  #   when :xz
+  #     # Use XZ Utils implementation
+  #   when :seven_zip
+  #     # Use 7-Zip implementation
+  #   end
+  #
+  class FormatDetector
+    # XZ Utils format signature: "\xFD7zXZ\x00"
+    XZ_SIGNATURE = [0xFD, 0x37, 0x7A, 0x58, 0x5A, 0x00].freeze
+
+    # 7-Zip format signature: "7z\xBC\xAF\x27\x1C"
+    SEVEN_ZIP_SIGNATURE = [0x37, 0x7A, 0xBC, 0xAF, 0x27, 0x1C].freeze
+
+    # RAR5 format signature: "Rar!\x1A\x07\x01\x00"
+    RAR5_SIGNATURE = [0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x01, 0x00].freeze
+
+    # RAR4 format signature: "Rar!\x1A\x07\x00"
+    RAR4_SIGNATURE = [0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x00].freeze
+
+    # ZIP format signature: "PK\x03\x04"
+    ZIP_SIGNATURE = [0x50, 0x4B, 0x03, 0x04].freeze
+
+    # GZIP format signature: "\x1F\x8B"
+    GZIP_SIGNATURE = [0x1F, 0x8B].freeze
+
+    # BZIP2 format signature: "BZ"
+    BZIP2_SIGNATURE = [0x42, 0x5A].freeze
+
+    # Detect archive format from file path
+    #
+    # @param file_path [String] Path to the archive file
+    # @return [Symbol, nil] Format identifier (:xz, :seven_zip, :rar5, :rar4,
+    #   :zip, :gzip, :bzip2, :lzma_alone) or nil if unknown
+    def self.detect(file_path)
+      return nil unless File.exist?(file_path)
+
+      header = File.binread(file_path, 16)
+      return nil if header.nil? || header.empty?
+
+      bytes = header.bytes
+
+      case bytes
+      in [0xFD, 0x37, 0x7A, 0x58, 0x5A, 0x00, *]
+        :xz
+      in [0x37, 0x7A, 0xBC, 0xAF, 0x27, 0x1C, *]
+        :seven_zip
+      in [0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x01, 0x00, *]
+        :rar5
+      in [0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x00, *]
+        :rar4
+      in [0x50, 0x4B, 0x03, 0x04, *]
+        :zip
+      in [0x1F, 0x8B, *]
+        :gzip
+      in [0x42, 0x5A, *]
+        :bzip2
+      else
+        # Check for LZMA_Alone format (13-byte header with properties)
+        detect_lzma_alone(bytes)
+      end
+    end
+
+    # Check if file is XZ Utils format
+    #
+    # @param file_path [String] Path to the file
+    # @return [Boolean] true if XZ format
+    def self.xz?(file_path)
+      detect(file_path) == :xz
+    end
+
+    # Check if file is 7-Zip format
+    #
+    # @param file_path [String] Path to the file
+    # @return [Boolean] true if 7-Zip format
+    def self.seven_zip?(file_path)
+      detect(file_path) == :seven_zip
+    end
+
+    # Check if file is RAR5 format
+    #
+    # @param file_path [String] Path to the file
+    # @return [Boolean] true if RAR5 format
+    def self.rar5?(file_path)
+      detect(file_path) == :rar5
+    end
+
+    # Check if file is RAR4 format
+    #
+    # @param file_path [String] Path to the file
+    # @return [Boolean] true if RAR4 format
+    def self.rar4?(file_path)
+      detect(file_path) == :rar4
+    end
+
+    # Get the appropriate reader class for the format
+    #
+    # @param file_path [String] Path to the archive file
+    # @return [Class, nil] Reader class or nil if unknown format
+    def self.reader_for(file_path)
+      case detect(file_path)
+      when :xz
+        require_relative "formats/xz"
+        Omnizip::Formats::Xz
+      when :seven_zip
+        require_relative "formats/seven_zip/reader"
+        Omnizip::Formats::SevenZip::Reader
+      when :rar5
+        require_relative "formats/rar5/reader"
+        Omnizip::Formats::Rar5::Reader
+      when :rar4
+        require_relative "formats/rar3/reader"
+        Omnizip::Formats::Rar3::Reader
+      when :zip
+        require_relative "formats/zip/reader"
+        Omnizip::Formats::Zip::Reader
+      end
+    end
+
+    # Detect LZMA_Alone format
+    #
+    # LZMA_Alone format has a 13-byte header:
+    # - 1 byte: properties (lc, lp, pb encoded)
+    # - 4 bytes: dictionary size (little-endian)
+    # - 8 bytes: uncompressed size (little-endian, -1 for unknown)
+    #
+    # @param bytes [Array<Integer>] First bytes of file
+    # @return [Symbol, nil] :lzma_alone or nil
+    def self.detect_lzma_alone(bytes)
+      return nil if bytes.size < 13
+
+      # Check properties byte (must be valid lc/lp/pb encoding)
+      props = bytes[0]
+      return nil if props > 225 # Max valid value is (9 * 5 * 5) - 1 = 224
+
+      lc = props % 9
+      lp = (props / 9) % 5
+      pb = props / 45
+
+      # Validate ranges
+      return nil if lc > 8 || lp > 4 || pb > 4
+
+      # Dictionary size should be power of 2 or close to it
+      dict_size = bytes[1, 4].pack("C*").unpack1("V")
+      return nil if dict_size.zero? || dict_size > (1 << 30) # Max ~1GB
+
+      :lzma_alone
+    end
+    private_class_method :detect_lzma_alone
+  end
+end

data/lib/omnizip/format_registry.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Omnizip
+  # Registry for archive format handlers
+  # Manages different archive format readers (7z, zip, tar, etc.)
+  class FormatRegistry
+    class << self
+      # Register a format handler
+      #
+      # @param extension [String] File extension (e.g., ".7z", ".zip")
+      # @param handler_class [Class] Format handler class
+      def register(extension, handler_class)
+        registry[normalize_extension(extension)] = handler_class
+      end
+
+      # Get format handler for extension
+      #
+      # @param extension [String] File extension
+      # @return [Class, nil] Handler class or nil if not found
+      def get(extension)
+        registry[normalize_extension(extension)]
+      end
+
+      # Check if format is supported
+      #
+      # @param extension [String] File extension
+      # @return [Boolean] true if supported
+      def supported?(extension)
+        registry.key?(normalize_extension(extension))
+      end
+
+      # List all supported formats
+      #
+      # @return [Array<String>] Supported extensions
+      def supported_formats
+        registry.keys.sort
+      end
+
+      private
+
+      # Format registry storage
+      #
+      # @return [Hash] Extension to handler class mapping
+      def registry
+        @registry ||= {}
+      end
+
+      # Normalize file extension
+      #
+      # @param ext [String] Extension
+      # @return [String] Normalized extension
+      def normalize_extension(ext)
+        ext = ext.to_s
+        ext = ".#{ext}" unless ext.start_with?(".")
+        ext.downcase
+      end
+    end
+  end
+end