omnizip 0.3.1

data/lib/omnizip/filter.rb

@@ -0,0 +1,139 @@
+# 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
+  # Abstract base class for all preprocessing filters
+  #
+  # Filters are reversible transformations applied to data before
+  # compression to improve compression ratios. This class defines the
+  # interface that all filter implementations must follow.
+  #
+  # The key innovation is format-aware ID resolution: different formats
+  # (7z, XZ) use different IDs for the same filter. This class provides the
+  # id_for_format(format) method to handle this mapping.
+  #
+  # @abstract Subclasses must implement encode, decode, metadata
+  #
+  # @example Create a custom filter
+  #   class MyFilter < Filter
+  #     def initialize(architecture:)
+  #       super(architecture: architecture, name: "MyFilter")
+  #     end
+  #
+  #     def id_for_format(format)
+  #       format == :xz ? 0x04 : 0x03
+  #     end
+  #
+  #     def encode(data, position = 0)
+  #       # encoding logic
+  #     end
+  #
+  #     def decode(data, position = 0)
+  #       # decoding logic
+  #     end
+  #
+  #     def self.metadata
+  #       { name: "MyFilter", description: "..." }
+  #     end
+  #   end
+  class Filter
+    # @return [Symbol] Architecture identifier (:x86, :arm, :arm64, :powerpc, :ia64, :sparc)
+    attr_reader :architecture
+
+    # @return [String] Human-readable filter name
+    attr_reader :name
+
+    # Initialize filter
+    #
+    # @param architecture [Symbol] Target architecture
+    # @param name [String] Human-readable name
+    def initialize(architecture:, name: "Unknown")
+      @architecture = architecture
+      @name = name
+    end
+
+    # Get filter ID for specific format
+    #
+    # This is the KEY METHOD that solves the filter ID mapping problem.
+    # Different formats (7z, XZ) use different IDs for the same filter.
+    #
+    # @param format [Symbol] Format identifier (:seven_zip, :xz)
+    # @return [Integer] Format-specific filter ID
+    # @raise [NotImplementedError] Subclass must implement
+    #
+    # @example Get XZ format ID for BCJ filter
+    #   bcj.id_for_format(:xz)  # => 0x04
+    #
+    # @example Get 7z format ID for BCJ filter
+    #   bcj.id_for_format(:seven_zip)  # => 0x03030103
+    def id_for_format(format)
+      raise NotImplementedError,
+            "#{self.class} must implement #id_for_format(format)"
+    end
+
+    # Encode (preprocess) data for compression
+    #
+    # Transforms data to make it more compressible. The transformation
+    # must be reversible - decode(encode(data)) == data.
+    #
+    # @param data [String] Binary data to encode
+    # @param position [Integer] Current stream position (default: 0)
+    # @return [String] Encoded binary data
+    # @raise [NotImplementedError] Subclass must implement
+    def encode(data, position = 0)
+      raise NotImplementedError,
+            "#{self.class} must implement #encode(data, position)"
+    end
+
+    # Decode (postprocess) data after decompression
+    #
+    # Reverses the encoding transformation, restoring original data.
+    #
+    # @param data [String] Binary data to decode
+    # @param position [Integer] Current stream position (default: 0)
+    # @return [String] Decoded binary data
+    # @raise [NotImplementedError] Subclass must implement
+    def decode(data, position = 0)
+      raise NotImplementedError,
+            "#{self.class} must implement #decode(data, position)"
+    end
+
+    class << self
+      # Get metadata about this filter
+      #
+      # @return [Hash] Filter metadata
+      # @option metadata [String] :name Human-readable name
+      # @option metadata [String] :description Filter description
+      # @option metadata [Array<Symbol>] :supported_archs Supported architectures
+      # @raise [NotImplementedError] Subclass must implement
+      #
+      # @example Get BCJ filter metadata
+      #   Omnizip::Filters::BCJ.metadata
+      #   # => { name: "BCJ", description: "...", supported_archs: [:x86, :arm, ...] }
+      def metadata
+        raise NotImplementedError,
+              "#{self} must implement .metadata"
+      end
+    end
+  end
+end

data/lib/omnizip/filter_pipeline.rb

@@ -0,0 +1,108 @@
+# 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.
+#
+
+module Omnizip
+  # Pipeline for chaining multiple filters together.
+  #
+  # Filters are applied in sequence during encoding, and in reverse
+  # order during decoding. Position tracking is maintained across
+  # the entire pipeline.
+  class FilterPipeline
+    attr_reader :filters
+
+    # Initialize an empty filter pipeline.
+    def initialize
+      @filters = []
+      @position = 0
+    end
+
+    # Add a filter to the pipeline.
+    #
+    # Filters are applied in the order they are added during encoding,
+    # and in reverse order during decoding.
+    #
+    # @param filter [Filters::FilterBase] Filter instance to add
+    # @return [self] For method chaining
+    def add_filter(filter)
+      @filters << filter
+      self
+    end
+
+    # Check if pipeline has any filters.
+    #
+    # @return [Boolean] True if pipeline contains filters
+    def empty?
+      @filters.empty?
+    end
+
+    # Get number of filters in pipeline.
+    #
+    # @return [Integer] Number of filters
+    def size
+      @filters.size
+    end
+
+    # Encode (preprocess) data by applying all filters in order.
+    #
+    # Filters are applied sequentially with the same position value.
+    # Position represents the current stream position for address
+    # calculations.
+    #
+    # @param data [String] Binary data to encode
+    # @param position [Integer] Current stream position
+    # @return [String] Encoded binary data
+    def encode(data, position = 0)
+      return data.dup if @filters.empty?
+
+      result = data
+      @filters.each do |filter|
+        result = filter.encode(result, position)
+      end
+
+      result
+    end
+
+    # Decode (postprocess) data by applying all filters in reverse order.
+    #
+    # Filters are applied in reverse order with the same position value
+    # to undo the encoding transformation.
+    #
+    # @param data [String] Binary data to decode
+    # @param position [Integer] Current stream position
+    # @return [String] Decoded binary data
+    def decode(data, position = 0)
+      return data.dup if @filters.empty?
+
+      result = data
+      # Apply filters in reverse order
+      @filters.reverse_each do |filter|
+        result = filter.decode(result, position)
+      end
+
+      result
+    end
+
+    # Clear all filters from the pipeline.
+    #
+    # @return [void]
+    def clear
+      @filters.clear
+      @position = 0
+    end
+  end
+end

data/lib/omnizip/filter_registry.rb

@@ -0,0 +1,166 @@
+# 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.
+#
+
+module Omnizip
+  # Registry for managing filter classes.
+  #
+  # This class provides a centralized registry for preprocessing filters,
+  # allowing filters to self-register and be retrieved by name.
+  # It implements a plugin-style architecture for extensibility.
+  class FilterRegistry
+    @filters = {}
+
+    class << self
+      # Register a filter class with the registry.
+      #
+      # @param name [Symbol, String] The name identifier for the filter
+      # @param klass [Class] The filter class to register
+      # @raise [ArgumentError] If name or klass is nil
+      # @return [void]
+      def register(name, klass)
+        raise ArgumentError, "Filter name cannot be nil" if name.nil?
+        raise ArgumentError, "Filter class cannot be nil" if klass.nil?
+
+        @filters[name.to_sym] = klass
+      end
+
+      # Retrieve a filter class by name.
+      #
+      # Handles both old-style (Class) and new-style (Hash with :class key)
+      # registrations for backward compatibility.
+      #
+      # @param name [Symbol, String] The name identifier for the filter
+      # @raise [UnknownFilterError] If filter is not registered
+      # @return [Class] The registered filter class
+      def get(name)
+        filter = @filters[name.to_sym]
+        unless filter
+          raise UnknownFilterError,
+                "Unknown filter: #{name}. " \
+                "Available: #{available.join(', ')}"
+        end
+
+        # Handle new-style registration (Hash with :class key)
+        return filter[:class] if filter.is_a?(Hash)
+
+        # Handle old-style registration (Class directly)
+        filter
+      end
+
+      # Check if a filter is registered.
+      #
+      # @param name [Symbol, String] The name identifier for the filter
+      # @return [Boolean] True if filter is registered, false otherwise
+      def registered?(name)
+        @filters.key?(name.to_sym)
+      end
+
+      # Get list of all registered filter names.
+      #
+      # @return [Array<Symbol>] Array of registered filter names
+      def available
+        @filters.keys
+      end
+
+      # Reset the registry (primarily for testing).
+      #
+      # @return [void]
+      def reset!
+        @filters.clear
+      end
+
+      # Register a filter class with format support.
+      #
+      # This format-aware registration stores which formats the filter
+      # supports, enabling format-specific filter retrieval.
+      #
+      # @param name [Symbol, String] The name identifier for the filter
+      # @param filter_class [Class] The filter class to register
+      # @param formats [Array<Symbol>] Supported formats (default: [:xz,
+      #   :seven_zip])
+      # @return [void]
+      def register_with_formats(name, filter_class, formats: %i[xz seven_zip])
+        raise ArgumentError, "Filter name cannot be nil" if name.nil?
+        raise ArgumentError, "Filter class cannot be nil" if filter_class.nil?
+
+        @filters[name.to_sym] = {
+          class: filter_class,
+          formats: formats,
+        }
+      end
+
+      # Get filter instance for specific format.
+      #
+      # Returns a new filter instance after verifying the filter supports
+      # the specified format.
+      #
+      # @param name [Symbol, String] The name identifier for the filter
+      # @param format [Symbol] Format identifier (:xz, :seven_zip)
+      # @raise [KeyError] If filter is not registered
+      # @raise [ArgumentError] If filter doesn't support the format
+      # @return [Object] New filter instance
+      def get_for_format(name, format)
+        filter_info = @filters[name.to_sym]
+        raise KeyError, "Filter not found: #{name}" unless filter_info
+
+        unless filter_info[:formats].include?(format)
+          raise ArgumentError,
+                "Filter #{name} not supported for format #{format}"
+        end
+
+        filter_info[:class].new
+      end
+
+      # Check if filter supports specific format.
+      #
+      # @param name [Symbol, String] The name identifier for the filter
+      # @param format [Symbol] Format identifier
+      # @return [Boolean] True if filter supports the format
+      def supports_format?(name, format)
+        return false unless @filters[name.to_sym]
+
+        filter_info = @filters[name.to_sym]
+        # Handle both old-style (Class) and new-style (Hash) registrations
+        if filter_info.is_a?(Hash)
+          filter_info[:formats]&.include?(format)
+        else
+          # Old-style registration - assume supports all formats
+          true
+        end
+      end
+
+      # Get all filters supporting a specific format.
+      #
+      # @param format [Symbol] Format identifier
+      # @return [Array<Symbol>] Filter names supporting the format
+      def filters_for_format(format)
+        @filters.select do |_, info|
+          if info.is_a?(Hash)
+            info[:formats]&.include?(format)
+          else
+            # Old-style registration - assume supports all formats
+            true
+          end
+        end.keys
+      end
+    end
+  end
+
+  # Error raised when an unknown filter is requested
+  class UnknownFilterError < StandardError; end
+end

data/lib/omnizip/filters/bcj.rb

@@ -0,0 +1,279 @@
+# 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.
+
+require_relative "../filter"
+
+module Omnizip
+  module Filters
+    # Unified BCJ (Branch/Call/Jump) filter for multiple architectures
+    #
+    # This filter preprocesses executable code by converting relative
+    # addresses in branch/call instructions to absolute addresses.
+    # The transformation is reversible and improves compression ratio.
+    #
+    # Supports x86, ARM, ARM Thumb, ARM64, PowerPC, IA64, SPARC architectures.
+    # Automatically returns correct filter ID for 7z or XZ format.
+    #
+    # @example Create x86 BCJ filter
+    #   bcj = Omnizip::Filters::BCJ.new(architecture: :x86)
+    #   bcj.id_for_format(:xz)         # => 0x04
+    #   bcj.id_for_format(:seven_zip)  # => 0x03030103
+    class BCJ < Filter
+      # Architecture-specific configurations
+      CONFIG = {
+        x86: {
+          opcodes: [0xE8, 0xE9],  # CALL, JMP
+          address_size: 4,
+          instruction_size: 5,
+          xz_id: 0x04,
+          seven_zip_id: 0x03030103,
+        },
+        arm: {
+          opcodes: [0x0A, 0x0B],  # ARM BL/B conditional
+          address_size: 4,
+          instruction_size: 4,
+          xz_id: 0x07,
+          seven_zip_id: 0x03030501,
+        },
+        armthumb: {
+          opcodes: [0xE8, 0xF0, 0xF1], # ARM Thumb BL/B conditional
+          address_size: 4,
+          instruction_size: 4,
+          xz_id: 0x08,
+          seven_zip_id: 0x03030701,
+        },
+        arm64: {
+          opcodes: [0x00], # ARM64 BL
+          address_size: 4,
+          instruction_size: 4,
+          xz_id: nil, # Not yet in XZ
+          seven_zip_id: 0x03030601,
+        },
+        powerpc: {
+          opcodes: [0x48, 0x18], # PowerPC branch instructions
+          address_size: 4,
+          instruction_size: 4,
+          xz_id: 0x05,
+          seven_zip_id: 0x03030205,
+        },
+        ia64: {
+          opcodes: [0x04, 0x05, 0x06, 0x07, 0x08], # IA64 branches
+          address_size: 4,
+          instruction_size: 4,
+          xz_id: 0x06,
+          seven_zip_id: 0x03030401,
+        },
+        sparc: {
+          opcodes: [0x04, 0x06, 0x07], # SPARC call/branch
+          address_size: 4,
+          instruction_size: 4,
+          xz_id: 0x09,
+          seven_zip_id: 0x03030805,
+        },
+      }.freeze
+
+      # @return [Symbol] Architecture identifier
+      attr_reader :architecture
+
+      # Initialize BCJ filter for specific architecture
+      #
+      # @param architecture [Symbol] Target architecture (:x86, :arm, :armthumb, :arm64, :powerpc, :ia64, :sparc)
+      # @raise [ArgumentError] If architecture is not supported
+      def initialize(architecture:)
+        unless CONFIG.key?(architecture)
+          raise ArgumentError, "Unsupported BCJ architecture: #{architecture}. " \
+                               "Supported: #{CONFIG.keys.join(', ')}"
+        end
+
+        @architecture = architecture
+        @config = CONFIG[architecture]
+        super(architecture: architecture, name: "BCJ-#{architecture.to_s.upcase}")
+      end
+
+      # Get filter ID for specific format
+      #
+      # @param format [Symbol] Format identifier (:seven_zip, :xz)
+      # @return [Integer] Format-specific filter ID
+      # @raise [ArgumentError] If format is not supported
+      # @raise [NotImplementedError] If architecture not supported in format
+      def id_for_format(format)
+        case format
+        when :seven_zip
+          @config[:seven_zip_id]
+        when :xz
+          id = @config[:xz_id]
+          if id.nil?
+            raise NotImplementedError,
+                  "#{@architecture} BCJ not yet supported in XZ format"
+          end
+
+          id
+        else
+          raise ArgumentError,
+                "Unknown format: #{format}. Supported: :seven_zip, :xz"
+        end
+      end
+
+      # Encode (preprocess) data for compression
+      #
+      # Scans for branch/call opcodes and converts relative addresses
+      # to absolute addresses.
+      #
+      # @param data [String] Binary executable data
+      # @param position [Integer] Current stream position (default: 0)
+      # @return [String] Encoded binary data
+      def encode(data, position = 0)
+        return data.dup if data.bytesize < @config[:instruction_size]
+
+        result = data.b
+        i = 0
+        limit = data.bytesize - @config[:instruction_size]
+
+        while i <= limit
+          opcode = result.getbyte(i)
+
+          if @config[:opcodes].include?(opcode)
+            # Extract address (little-endian)
+            address = extract_address(result, i + 1)
+
+            # Check if valid relative address
+            if valid_relative_address?(address)
+              # Convert to absolute
+              absolute = address + position + i + @config[:instruction_size]
+              write_address(result, i + 1, absolute)
+            end
+
+            i += @config[:instruction_size]
+          else
+            i += 1
+          end
+        end
+
+        result
+      end
+
+      # Decode (postprocess) data after decompression
+      #
+      # Reverses encoding by converting absolute addresses back to
+      # relative addresses.
+      #
+      # @param data [String] Binary executable data
+      # @param position [Integer] Current stream position (default: 0)
+      # @return [String] Decoded binary data
+      def decode(data, position = 0)
+        return data.dup if data.bytesize < @config[:instruction_size]
+
+        result = data.b
+        i = 0
+        limit = data.bytesize - @config[:instruction_size]
+
+        while i <= limit
+          opcode = result.getbyte(i)
+
+          if @config[:opcodes].include?(opcode)
+            # Extract absolute address
+            absolute = extract_address(result, i + 1)
+
+            # Convert to relative
+            address = absolute - (position + i + @config[:instruction_size])
+
+            if valid_relative_address?(address)
+              write_address(result, i + 1, address)
+            end
+
+            i += @config[:instruction_size]
+          else
+            i += 1
+          end
+        end
+
+        result
+      end
+
+      class << self
+        # Get metadata about this filter
+        #
+        # @return [Hash] Filter metadata
+        def metadata
+          {
+            name: "BCJ",
+            description: "Branch/Call/Jump converter for executable files",
+            supported_architectures: CONFIG.keys,
+            architectures: {
+              x86: "x86/x86-64",
+              arm: "ARM 32-bit",
+              arm64: "ARM 64-bit",
+              powerpc: "PowerPC",
+              ia64: "IA-64 (Itanium)",
+              sparc: "SPARC",
+            },
+          }
+        end
+      end
+
+      private
+
+      # Extract address from data at offset (little-endian)
+      #
+      # @param data [String] Binary data
+      # @param offset [Integer] Starting position
+      # @return [Integer] Address value
+      def extract_address(data, offset)
+        bytes = data.byteslice(offset, @config[:address_size]).bytes
+        value = bytes.each_with_index.reduce(0) do |acc, (byte, i)|
+          acc | (byte << (8 * i))
+        end
+
+        # Convert to signed if needed (for 32-bit addresses)
+        mask = (1 << (8 * @config[:address_size])) - 1
+        value.nobits?(~mask) ? value - (1 << (8 * @config[:address_size])) : value
+      end
+
+      # Write address to data at offset (little-endian)
+      #
+      # @param data [String] Binary data (modified in place)
+      # @param offset [Integer] Starting position
+      # @param value [Integer] Address value to write
+      # @return [void]
+      def write_address(data, offset, value)
+        @config[:address_size].times do |i|
+          data.setbyte(offset + i, value & 0xFF)
+          value >>= 8
+        end
+      end
+
+      # Check if address is a valid relative address
+      #
+      # Valid relative addresses have high byte of 0x00 or 0xFF,
+      # indicating small positive or negative offsets.
+      #
+      # @param value [Integer] Address value to check
+      # @return [Boolean] True if valid relative address
+      def valid_relative_address?(value)
+        unsigned = value & 0xFFFFFFFF
+        high_byte = (unsigned >> 24) & 0xFF
+        [0x00, 0xFF].include?(high_byte)
+      end
+    end
+  end
+end