omnizip 0.3.1

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

@@ -0,0 +1,75 @@
+# 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 LZMA2 decoders.
+      #
+      # This class defines the common interface and shared functionality
+      # for all LZMA2 decoder implementations (XZ Utils, 7-Zip, etc.).
+      #
+      # Subclasses must implement the {#decode} method.
+      #
+      # @abstract Subclasses must implement {#decode}
+      class LZMA2DecoderBase
+        attr_reader :dict_size
+
+        # Initialize the LZMA2 decoder.
+        #
+        # @param input [IO] Input stream of compressed data
+        # @param options [Hash] Decoding options
+        # @option options [Integer] :dict_size Dictionary size (read from properties)
+        def initialize(input, options = {})
+          @input = input
+          # Dictionary size will be read from LZMA2 property byte by subclasses
+          @dict_size = options.fetch(:dict_size, nil)
+        end
+
+        # Decode LZMA2 compressed data.
+        #
+        # Subclasses must implement this method to provide the specific
+        # decoding logic for their implementation (XZ Utils, 7-Zip, etc.).
+        #
+        # @param output [IO] Output stream for decompressed data
+        # @raise [NotImplementedError] Always raised in base class
+        # @return [void]
+        def decode(output = nil)
+          raise NotImplementedError,
+                "#{self.class} must implement #decode"
+        end
+
+        # Get the implementation identifier.
+        #
+        # Subclasses must implement this to return a symbol identifying
+        # their implementation (e.g., :xz_utils, :seven_zip).
+        #
+        # @raise [NotImplementedError] Always raised in base class
+        # @return [Symbol] Implementation identifier
+        def implementation_name
+          raise NotImplementedError,
+                "#{self.class} must implement #implementation_name"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+# 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 LZMA2 encoders.
+      #
+      # This class defines the common interface and shared functionality
+      # for all LZMA2 encoder implementations (XZ Utils, 7-Zip, etc.).
+      #
+      # LZMA2 is an improved version of LZMA that supports:
+      # - Uncompressed chunks for incompressible data
+      # - Dictionary/state resets for better compression
+      # - Simpler chunk format
+      #
+      # Subclasses must implement the {#encode} method.
+      #
+      # @abstract Subclasses must implement {#encode}
+      class LZMA2EncoderBase
+        attr_reader :dict_size, :lc, :lp, :pb
+
+        # Maximum uncompressed size per LZMA2 chunk (2MB)
+        UNCOMPRESSED_MAX = 1 << 21
+        # Maximum compressed size per LZMA2 chunk (64KB)
+        COMPRESSED_MAX = 1 << 16
+
+        # Initialize the LZMA2 encoder.
+        #
+        # @param options [Hash] Encoding options
+        # @option options [Integer] :dict_size Dictionary size (default: 8MB)
+        # @option options [Integer] :lc Literal context bits (default: 3)
+        # @option options [Integer] :lp Literal position bits (default: 0)
+        # @option options [Integer] :pb Position bits (default: 2)
+        # @option options [Boolean] :standalone Write property byte at start (default: true)
+        def initialize(options = {})
+          @dict_size = options.fetch(:dict_size, 8 * 1024 * 1024)
+          @lc = options.fetch(:lc, 3)
+          @lp = options.fetch(:lp, 0)
+          @pb = options.fetch(:pb, 2)
+          @standalone = options.fetch(:standalone, true)
+
+          validate_parameters!
+        end
+
+        # Encode data using LZMA2.
+        #
+        # Subclasses must implement this method to provide the specific
+        # encoding logic for their implementation (XZ Utils, 7-Zip, etc.).
+        #
+        # @param data [String] Input data to compress
+        # @raise [NotImplementedError] Always raised in base class
+        # @return [String] Compressed data
+        def encode(data)
+          raise NotImplementedError,
+                "#{self.class} must implement #encode"
+        end
+
+        # Get the implementation identifier.
+        #
+        # Subclasses must implement this to return a symbol identifying
+        # their implementation (e.g., :xz_utils, :seven_zip).
+        #
+        # @raise [NotImplementedError] Always raised in base class
+        # @return [Symbol] Implementation identifier
+        def implementation_name
+          raise NotImplementedError,
+                "#{self.class} must implement #implementation_name"
+        end
+
+        # Check if standalone mode is enabled.
+        #
+        # @return [Boolean] true if property byte should be written
+        def standalone?
+          @standalone
+        end
+
+        private
+
+        # Validate LZMA2 parameters.
+        #
+        # @raise [ArgumentError] If any parameter is out of valid range
+        # @return [void]
+        def validate_parameters!
+          unless @lc.between?(0, 8)
+            raise ArgumentError, "lc must be between 0 and 8, got #{@lc}"
+          end
+
+          unless @lp.between?(0, 4)
+            raise ArgumentError, "lp must be between 0 and 4, got #{@lp}"
+          end
+
+          unless @pb.between?(0, 4)
+            raise ArgumentError, "pb must be between 0 and 4, got #{@pb}"
+          end
+
+          # LZMA2 dictionary size constraints (from XZ Utils)
+          min_dict = 4096
+          max_dict = 1 << 28
+
+          unless @dict_size.between?(min_dict, max_dict)
+            raise ArgumentError,
+                  "dict_size must be between #{min_dict} and #{max_dict}, got #{@dict_size}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# 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 decoders.
+      #
+      # This class defines the common interface and shared functionality
+      # for all LZMA decoder implementations (XZ Utils, 7-Zip SDK, etc.).
+      #
+      # Subclasses must implement the {#decode_stream} method.
+      #
+      # @abstract Subclasses must implement {#decode_stream}
+      class LZMADecoderBase
+        attr_reader :lc, :lp, :pb, :dict_size, :uncompressed_size, :input
+
+        # Initialize the LZMA decoder.
+        #
+        # @param input [IO] Input stream of compressed data
+        # @param options [Hash] Decoding options
+        # @option options [Integer] :lc Literal context bits (read from header)
+        # @option options [Integer] :lp Literal position bits (read from header)
+        # @option options [Integer] :pb Position bits (read from header)
+        # @option options [Integer] :dict_size Dictionary size (read from header)
+        # @option options [Integer] :uncompressed_size Uncompressed size
+        def initialize(input, options = {})
+          @input = input
+          # Parameters will be read from LZMA header by subclasses
+          @lc = options.fetch(:lc, nil)
+          @lp = options.fetch(:lp, nil)
+          @pb = options.fetch(:pb, nil)
+          @dict_size = options.fetch(:dict_size, nil)
+          @uncompressed_size = options.fetch(:uncompressed_size, nil)
+        end
+
+        # Decode a stream of compressed data.
+        #
+        # Subclasses must implement this method to provide the specific
+        # decoding logic for their implementation (XZ Utils, 7-Zip, etc.).
+        #
+        # @param output [IO] Output stream for decompressed data
+        # @raise [NotImplementedError] Always raised in base class
+        # @return [void]
+        def decode_stream(output = nil)
+          raise NotImplementedError,
+                "#{self.class} must implement #decode_stream"
+        end
+
+        # Get the implementation identifier.
+        #
+        # Subclasses must implement this to return a symbol identifying
+        # their implementation (e.g., :xz_utils, :seven_zip).
+        #
+        # @raise [NotImplementedError] Always raised in base class
+        # @return [Symbol] Implementation identifier
+        def implementation_name
+          raise NotImplementedError,
+                "#{self.class} must implement #implementation_name"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# 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 encoders.
+      #
+      # This class defines the common interface and shared functionality
+      # for all LZMA encoder implementations (XZ Utils, 7-Zip SDK, etc.).
+      #
+      # Subclasses must implement the {#encode_stream} method.
+      #
+      # @abstract Subclasses must implement {#encode_stream}
+      class LZMAEncoderBase
+        attr_reader :lc, :lp, :pb, :dict_size, :output
+
+        # Initialize the LZMA encoder.
+        #
+        # @param output [IO] Output stream for compressed data
+        # @param options [Hash] Encoding options
+        # @option options [Integer] :lc Literal context bits (0-8, default: 3)
+        # @option options [Integer] :lp Literal position bits (0-4, default: 0)
+        # @option options [Integer] :pb Position bits (0-4, default: 2)
+        # @option options [Integer] :dict_size Dictionary size (default: 64KB)
+        # @raise [ArgumentError] If parameters are invalid
+        def initialize(output, options = {})
+          @output = output
+          @lc = options.fetch(:lc, 3)
+          @lp = options.fetch(:lp, 0)
+          @pb = options.fetch(:pb, 2)
+          @dict_size = options.fetch(:dict_size, 1 << 16) # 64KB default
+
+          validate_parameters!
+        end
+
+        # Encode a stream of data.
+        #
+        # Subclasses must implement this method to provide the specific
+        # encoding logic for their implementation (XZ Utils, 7-Zip, etc.).
+        #
+        # @param data [String] Input data to compress
+        # @raise [NotImplementedError] Always raised in base class
+        # @return [void]
+        def encode_stream(data)
+          raise NotImplementedError,
+                "#{self.class} must implement #encode_stream"
+        end
+
+        # Get the implementation identifier.
+        #
+        # Subclasses must implement this to return a symbol identifying
+        # their implementation (e.g., :xz_utils, :seven_zip).
+        #
+        # @raise [NotImplementedError] Always raised in base class
+        # @return [Symbol] Implementation identifier
+        def implementation_name
+          raise NotImplementedError,
+                "#{self.class} must implement #implementation_name"
+        end
+
+        private
+
+        # Validate LZMA parameters.
+        #
+        # @raise [ArgumentError] If any parameter is out of valid range
+        # @return [void]
+        def validate_parameters!
+          unless @lc.between?(0, 8)
+            raise ArgumentError, "lc must be between 0 and 8, got #{@lc}"
+          end
+
+          unless @lp.between?(0, 4)
+            raise ArgumentError, "lp must be between 0 and 4, got #{@lp}"
+          end
+
+          unless @pb.between?(0, 4)
+            raise ArgumentError, "pb must be between 0 and 4, got #{@pb}"
+          end
+
+          unless @dict_size.between?(4096, 1 << 28)
+            raise ArgumentError,
+                  "dict_size must be between 4096 and 268435456, got #{@dict_size}"
+          end
+        end
+      end
+    end
+  end
+end

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