omnizip 0.4.7-aarch64-linux

data/lib/omnizip/algorithms/ppmd_base.rb

@@ -0,0 +1,142 @@
+# 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 "stringio"
+
+module Omnizip
+  module Algorithms
+    # Base class for PPMd (Prediction by Partial Matching) algorithms
+    #
+    # This abstract base class provides common functionality for PPMd
+    # variants (PPMd7, PPMd8, etc.) while allowing each variant to
+    # implement its specific features.
+    #
+    # The design follows the Template Method pattern, where common
+    # operations are defined here and variant-specific operations
+    # are delegated to subclasses.
+    class PPMdBase < Algorithm
+      # Common constants for all PPMd variants
+      module BaseConstants
+        # Context order limits
+        MIN_ORDER = 2
+        MAX_ORDER = 16
+        DEFAULT_ORDER = 6
+
+        # Memory allocation
+        MIN_MEM_SIZE = 1 << 20  # 1 MB
+        MAX_MEM_SIZE = 1 << 30  # 1 GB
+        DEFAULT_MEM_SIZE = 1 << 24 # 16 MB
+
+        # Alphabet
+        ALPHABET_SIZE = 256
+
+        # Range coder constants
+        TOP_VALUE = 1 << 24
+        BOT_VALUE = 1 << 15
+      end
+
+      include BaseConstants
+
+      # Compress data using PPMd variant
+      #
+      # @param input [IO, String] Input data to compress
+      # @param output [IO, String] Output for compressed data
+      # @param options [Hash] Compression options
+      # @return [void]
+      def compress(input, output, options = {})
+        input = prepare_input(input)
+        output = prepare_output(output)
+
+        encoder = create_encoder(output, options)
+        encoder.encode_stream(input)
+      end
+
+      # Decompress data using PPMd variant
+      #
+      # @param input [IO, String] Compressed input data
+      # @param output [IO, String] Output for decompressed data
+      # @param options [Hash] Decompression options
+      # @return [void]
+      def decompress(input, output, options = {})
+        input = prepare_input(input)
+        output = prepare_output(output)
+
+        decoder = create_decoder(input, options)
+        result = decoder.decode_stream
+
+        output.write(result)
+      end
+
+      protected
+
+      # Template method for creating encoder
+      # Subclasses must implement this
+      #
+      # @param output [IO] Output stream
+      # @param options [Hash] Encoding options
+      # @return [Object] Encoder instance
+      # @raise [NotImplementedError] if not implemented by subclass
+      def create_encoder(output, options)
+        raise NotImplementedError,
+              "#{self.class} must implement #create_encoder"
+      end
+
+      # Template method for creating decoder
+      # Subclasses must implement this
+      #
+      # @param input [IO] Input stream
+      # @param options [Hash] Decoding options
+      # @return [Object] Decoder instance
+      # @raise [NotImplementedError] if not implemented by subclass
+      def create_decoder(input, options)
+        raise NotImplementedError,
+              "#{self.class} must implement #create_decoder"
+      end
+
+      private
+
+      # Prepare input for processing
+      #
+      # @param input [IO, String] Input data
+      # @return [IO] IO object ready for reading
+      def prepare_input(input)
+        # StringIO is not an ::IO, and its #to_s is Kernel's (the
+        # INSPECT string) — pass anything readable straight through.
+        return input if input.respond_to?(:read) # allowed: IO-duck detection — StringIO must pass through (its #to_s is the INSPECT string)
+
+        StringIO.new(input.to_s)
+      end
+
+      # Prepare output for processing
+      #
+      # @param output [IO, String, nil] Output destination
+      # @return [IO] IO object ready for writing
+      def prepare_output(output)
+        # StringIO is not an ::IO subclass — the old check discarded
+        # it for a fresh buffer, silently dropping the output.
+        return output if output.is_a?(IO) || output.is_a?(StringIO)
+
+        StringIO.new(String.new(encoding: Encoding::BINARY))
+      end
+    end
+  end
+end

data/lib/omnizip/algorithms/registration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Algorithm registration - triggers autoload and registers all algorithms
+# This file should be required after algorithms.rb which sets up autoloads
+
+module Omnizip
+  module Algorithms
+    # Touch constants to trigger autoload, then register
+    LZMA
+    LZMA2
+    PPMd7
+    PPMd8
+    BZip2
+    Deflate
+    Deflate64
+    Zstandard
+  end
+end
+
+# Now register all algorithms
+Omnizip::AlgorithmRegistry.register(:lzma, Omnizip::Algorithms::LZMA)
+Omnizip::Algorithms::LZMA2.register_algorithm
+Omnizip::AlgorithmRegistry.register(:ppmd7, Omnizip::Algorithms::PPMd7)
+Omnizip::AlgorithmRegistry.register(:ppmd8, Omnizip::Algorithms::PPMd8)
+Omnizip::AlgorithmRegistry.register(:bzip2, Omnizip::Algorithms::BZip2)
+Omnizip::AlgorithmRegistry.register(:deflate, Omnizip::Algorithms::Deflate)
+Omnizip::AlgorithmRegistry.register(:deflate64, Omnizip::Algorithms::Deflate64)
+Omnizip::AlgorithmRegistry.register(:zstandard, Omnizip::Algorithms::Zstandard)

data/lib/omnizip/algorithms/zstandard/constants.rb

@@ -0,0 +1,158 @@
+# 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 Algorithms
+    class Zstandard
+      # Constants from RFC 8878 (Zstandard Compression)
+      #
+      # @see https://datatracker.ietf.org/doc/html/rfc8878
+      module Constants
+        # Frame Constants
+        MAGIC_NUMBER = 0xFD2FB528
+        MAGIC_BYTES = [0x28, 0xB5, 0x2F, 0xFD].freeze
+        SKIPPABLE_MAGIC_BASE = 0x184D2A50
+        SKIPPABLE_MAGIC_MASK = 0xFFFFFFF0
+
+        # Block Types (RFC 8878 Section 3.1.1.2)
+        BLOCK_TYPE_RAW = 0
+        BLOCK_TYPE_RLE = 1
+        BLOCK_TYPE_COMPRESSED = 2
+        BLOCK_TYPE_RESERVED = 3
+        BLOCK_HEADER_SIZE = 3
+        BLOCK_MAX_SIZE = 128 * 1024
+
+        # Literals Block Types (RFC 8878 Section 3.1.1.3.1)
+        LITERALS_BLOCK_RAW = 0
+        LITERALS_BLOCK_RLE = 1
+        LITERALS_BLOCK_COMPRESSED = 2
+        LITERALS_BLOCK_TREELESS = 3
+        HUFFMAN_MAX_BITS = 11
+
+        # Sequence Compression Modes (RFC 8878 Section 3.1.1.3.2)
+        MODE_PREDEFINED = 0
+        MODE_RLE = 1
+        MODE_FSE = 2
+        MODE_REPEAT = 3
+
+        # FSE Accuracy Logs (RFC 8878 Section 4)
+        LITERALS_LENGTH_ACCURACY_LOG = 6
+        MATCH_LENGTH_ACCURACY_LOG = 6
+        OFFSET_ACCURACY_LOG = 5
+
+        # Repeat Offsets (RFC 8878 Section 3.1.2.2.3)
+        REPEAT_OFFSET_1 = 1
+        REPEAT_OFFSET_2 = 2
+        REPEAT_OFFSET_3 = 3
+        DEFAULT_REPEAT_OFFSETS = [1, 4, 8].freeze
+
+        # Window Constants (RFC 8878 Section 3.1.1.1.2)
+        WINDOW_LOG_MIN = 10
+        WINDOW_LOG_MAX = 41
+
+        # Huffman Constants (RFC 8878 Section 4.2.1)
+        HUFFMAN_MAX_LOG = 11
+        HUFFMAN_MAX_CODE_LENGTH = 11
+        HUFFMAN_STANDARD_TABLE_SIZE = 256
+        HUF_SYMBOLVALUE_MAX = 255
+
+        # FSE Table Limits (RFC 8878 Section 4.1)
+        FSE_MAX_ACCURACY_LOG = 9
+        FSE_MIN_ACCURACY_LOG = 5
+        FSE_DEFAULT_TABLELOG = 6
+
+        # Compression levels
+        MIN_LEVEL = 1
+        MAX_LEVEL = 22
+        DEFAULT_LEVEL = 3
+
+        # Long-distance matching kicks in at this level for inputs
+        # larger than one block (Btultra2 in the C strategy table).
+        LDM_MIN_LEVEL = 19
+
+        # Buffer size for streaming operations
+        BUFFER_SIZE = 128 * 1024 # 128KB
+
+        # Literal length codes (RFC 8878 Table: literals length codes)
+        # Each entry: [baseline, extra_bits]
+        LITERAL_LENGTH_TABLE = [
+          [0, 0], [1, 0], [2, 0], [3, 0], [4, 0], [5, 0], [6, 0], [7, 0],
+          [8, 0], [9, 0], [10, 0], [11, 0], [12, 0], [13, 0], [14, 0], [15, 0],
+          [16, 1], [18, 1], [20, 1], [22, 1], [24, 2], [28, 2], [32, 3], [40, 3],
+          [48, 4], [64, 6], [128, 7], [256, 8], [512, 9], [1024, 10], [2048, 11],
+          [4096, 12], [8192, 13], [16384, 14], [32768, 15], [65536, 16]
+        ].freeze
+
+        # Match length codes (RFC 8878 Table: match length codes, 53 entries)
+        # Each entry: [baseline, extra_bits]
+        MATCH_LENGTH_TABLE = [
+          [3, 0], [4, 0], [5, 0], [6, 0], [7, 0], [8, 0], [9, 0], [10, 0],
+          [11, 0], [12, 0], [13, 0], [14, 0], [15, 0], [16, 0], [17, 0], [18, 0],
+          [19, 0], [20, 0], [21, 0], [22, 0], [23, 0], [24, 0], [25, 0], [26, 0],
+          [27, 0], [28, 0], [29, 0], [30, 0], [31, 0], [32, 0], [33, 0], [34, 0],
+          [35, 1], [37, 1], [39, 1], [41, 1], [43, 2], [47, 2], [51, 3], [59, 3],
+          [67, 4], [83, 4], [99, 5], [131, 7], [259, 8], [515, 9], [1027, 10],
+          [2051, 11], [4099, 12], [8195, 13], [16387, 14], [32771, 15], [65539, 16]
+        ].freeze
+
+        # Offset codes (RFC 8878 Section 3.1.2.2.3.2)
+        # OF_BASE[c] + read(c bits) = match distance for c >= 2; codes 0 and
+        # 1 are the repeat-offset specials handled by the executor.
+        OF_BASE = [
+          0, 1, 1, 5, 13, 29, 61, 125, 253, 509, 1021, 2045, 4093, 8189,
+          16381, 32765, 65533, 131069, 262141, 524285, 1048573, 2097149,
+          4194301, 8388605, 16777213, 33554429, 67108861, 134217725,
+          268435453, 536870909, 1073741821, 2147483645
+        ].freeze
+        OF_BITS = (0..31).to_a.freeze
+
+        # Predefined FSE distributions (RFC 8878 Section 4.1.3, matching
+        # the zstd C reference). -1 marks a "less than 1" probability that
+        # occupies a single cell at the top of the table.
+        PREDEFINED_LL_DISTRIBUTION = [
+          4, 3, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1, 1, 1,
+          2, 2, 2, 2, 2, 2, 2, 2, 2, 3, 2, 1, 1, 1, 1, 1,
+          -1, -1, -1, -1
+        ].freeze
+
+        # Sum: 4+3+2*11+1*3 + 2*8+3+2*2+1*5 = 32 + 32 = 64 = 2^6
+        PREDEFINED_ML_DISTRIBUTION = [
+          1, 4, 3, 2, 2, 2, 2, 2, 2, 1, 1, 1, 1, 1, 1, 1,
+          1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
+          1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, -1, -1,
+          -1, -1, -1, -1, -1
+        ].freeze
+
+        # Sum: 27 positive + 5 low-probability = 32 = 2^5
+        PREDEFINED_OFFSET_DISTRIBUTION = [
+          1, 1, 1, 1, 1, 1, 2, 2, 2, 1, 1, 1, 1, 1, 1, 1,
+          1, 1, 1, 1, 1, 1, 1, 1, -1, -1, -1, -1, -1, 0, 0, 0
+        ].freeze
+
+        # floor(log2(x)); 0 for x == 0 (C ZSTD_highbit32 defensive value)
+        def self.highbit32(value)
+          value.zero? ? 0 : value.bit_length - 1
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/algorithms/zstandard/decoder.rb

@@ -0,0 +1,249 @@
+# 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 Algorithms
+    class Zstandard
+      # Pure Ruby Zstandard decoder (RFC 8878).
+      #
+      # Pipeline:
+      #
+      # 1. For each frame: parse the frame header and reset per-frame
+      #    state (repeat offsets, previous Huffman table, previous FSE
+      #    tables).
+      # 2. For each block: parse the 3-byte block header and dispatch on
+      #    the block type (raw copy, RLE expansion, or compressed =
+      #    literals + sequences).
+      # 3. Verify the optional content checksum: the low 32 bits of
+      #    XXHash64 over the decoded frame content.
+      class Decoder
+        include Constants
+
+        # @return [IO] input stream
+        attr_reader :input_stream
+
+        def initialize(input_stream)
+          @input_stream = input_stream
+          @executor = SequenceExecutor.new
+          @previous_huffman_table = nil
+          @previous_fse_tables = {}
+        end
+
+        # Decode a complete stream (one or more concatenated frames).
+        #
+        # @return [String] decompressed data (binary)
+        def decode_stream
+          data = read_all
+          output = String.new(encoding: Encoding::BINARY)
+          pos = 0
+
+          loop do
+            remaining = data.bytesize - pos
+            break if remaining.zero?
+            raise Omnizip::DecompressionError, "trailing bytes are not a frame" if remaining < 4
+
+            magic = data.byteslice(pos, 4).unpack1("V")
+
+            if (magic & SKIPPABLE_MAGIC_MASK) == SKIPPABLE_MAGIC_BASE
+              pos = skip_skippable_frame(data, pos)
+              next
+            end
+            unless magic == MAGIC_NUMBER
+              raise Omnizip::DecompressionError,
+                    "invalid Zstandard magic: 0x#{magic.to_s(16)}"
+            end
+
+            frame_output, pos = decode_frame(data, pos + 4)
+            output << frame_output
+          end
+
+          output
+        end
+
+        # Decode a stream produced by a dictionary-primed encoder: the
+        # dictionary's content primes the reconstruction window of
+        # frames carrying its ID (verified; mismatch raises).
+        #
+        # @param dict [Dictionary]
+        # @return [String] decompressed data (binary)
+        def decode_stream_with_dict(dict)
+          data = read_all
+          output = String.new(encoding: Encoding::BINARY)
+          pos = 0
+
+          loop do
+            remaining = data.bytesize - pos
+            break if remaining.zero?
+            raise Omnizip::DecompressionError, "trailing bytes are not a frame" if remaining < 4
+
+            magic = data.byteslice(pos, 4).unpack1("V")
+            unless magic == MAGIC_NUMBER
+              raise Omnizip::DecompressionError,
+                    "invalid Zstandard magic: 0x#{magic.to_s(16)}"
+            end
+
+            frame_output, pos = decode_frame(data, pos + 4, dict)
+            output << frame_output
+          end
+
+          output
+        end
+
+        private
+
+        def read_all
+          data = @input_stream.read
+          data ||= ""
+          data.dup.force_encoding(Encoding::BINARY)
+        end
+
+        def skip_skippable_frame(data, pos)
+          raise Omnizip::DecompressionError, "truncated skippable frame" if data.bytesize < pos + 8
+
+          size = data.byteslice(pos + 4, 4).unpack1("V")
+          end_pos = pos + 8 + size
+          if data.bytesize < end_pos
+            raise Omnizip::DecompressionError, "truncated skippable frame body"
+          end
+
+          end_pos
+        end
+
+        # Decode one frame (input positioned after the magic).
+        # Returns [frame_output, pos_after_frame].
+        #
+        # With a dictionary prefix, the reconstruction window is
+        # primed with the dictionary content so sequences can
+        # back-reference it; the prefix is verified (checksum) and
+        # stripped from the returned output.
+        def decode_frame(data, pos, dict = nil)
+          header, pos = Frame::Header.parse_from(data, pos)
+          verify_dictionary_id(header, dict)
+          prefix = dict&.content
+
+          # Reset per-frame state: repeat offsets, previous Huffman
+          # table, previous FSE tables.
+          @executor = SequenceExecutor.new
+          @previous_huffman_table = nil
+          @previous_fse_tables = {}
+
+          output = String.new(encoding: Encoding::BINARY)
+          output << prefix if prefix
+          loop do
+            block, pos = Frame::Block.parse_from(data, pos)
+            if block.reserved?
+              raise Omnizip::DecompressionError,
+                    "reserved block type in frame"
+            end
+
+            pos = decode_block(block, data, pos, output)
+            break if block.last_block
+          end
+
+          if header.content_checksum?
+            if data.bytesize < pos + 4
+              raise Omnizip::DecompressionError, "truncated frame checksum"
+            end
+
+            expected = data.byteslice(pos, 4).unpack1("V")
+            actual = XXHash64.frame_checksum(
+              prefix ? output.byteslice(prefix.bytesize..) : output,
+            )
+            if expected != actual
+              raise Omnizip::DecompressionError,
+                    "frame checksum mismatch: stored 0x#{expected.to_s(16)}, " \
+                    "computed 0x#{actual.to_s(16)}"
+            end
+            pos += 4
+          end
+
+          frame_output = prefix ? output.byteslice(prefix.bytesize..) : output
+          [frame_output, pos]
+        end
+
+        # A frame that carries a Dictionary_ID must be decoded with a
+        # dictionary of the same ID; a mismatched or missing
+        # dictionary would silently garble every back-reference.
+        def verify_dictionary_id(header, dict)
+          return unless header.dictionary_id?
+
+          frame_id = header.dictionary_id
+          if dict.nil?
+            raise Omnizip::DecompressionError,
+                  "frame requires dictionary #{frame_id}, none supplied"
+          end
+          return if dict.id == frame_id
+
+          raise Omnizip::DecompressionError,
+                "frame requires dictionary #{frame_id}, got #{dict.id}"
+        end
+
+        # Decode one block into `output`. Returns the position after
+        # the block's payload.
+        def decode_block(block, data, pos, output)
+          case block.block_type
+          when BLOCK_TYPE_RAW
+            if data.bytesize < pos + block.block_size
+              raise Omnizip::DecompressionError, "truncated raw block"
+            end
+
+            output << data.byteslice(pos, block.block_size)
+            pos + block.block_size
+          when BLOCK_TYPE_RLE
+            raise Omnizip::DecompressionError, "truncated RLE block" if data.bytesize < pos + 1
+
+            output << (data.getbyte(pos).chr * block.block_size)
+            pos + 1
+          when BLOCK_TYPE_COMPRESSED
+            block_end = pos + block.block_size
+            if data.bytesize < block_end
+              raise Omnizip::DecompressionError, "truncated compressed block"
+            end
+
+            decode_compressed_block(data.byteslice(pos...block_end), output)
+            block_end
+          end
+        end
+
+        def decode_compressed_block(block_input, output)
+          literals_decoder = LiteralsDecoder.decode(block_input,
+                                                    @previous_huffman_table)
+          @previous_huffman_table = literals_decoder.huffman_table ||
+            @previous_huffman_table
+
+          sequences_decoder = SequencesDecoder.decode(
+            block_input.byteslice(literals_decoder.consumed..),
+            @previous_fse_tables,
+            @executor,
+          )
+          # Merge: Repeat-mode tables are not re-emitted, so the entries
+          # carried from earlier blocks must survive.
+          @previous_fse_tables =
+            @previous_fse_tables.merge(sequences_decoder.fse_tables)
+
+          @executor.execute(literals_decoder.literals,
+                            sequences_decoder.sequences, output)
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/algorithms/zstandard/dictionary.rb

@@ -0,0 +1,73 @@
+# 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 Algorithms
+    class Zstandard
+      # Zstandard dictionary (port of the omnizip-rs dict.rs).
+      #
+      # A dictionary lets the encoder preload a reference-content
+      # window so small inputs compress dramatically better: the
+      # dictionary content is used as a match-finder prefix, and the
+      # frame header carries the dictionary's ID.
+      #
+      # Wire format (simplified form, as in the Rust reference):
+      # magic (4) + dictionary ID (4, LE) + raw content.
+      class Dictionary
+        DICT_MAGIC = 0xEC30A437
+
+        attr_reader :id, :content
+
+        # @param id [Integer] dictionary ID carried in frame headers
+        # @param content [String] corpus bytes used as the prefix
+        def initialize(id, content)
+          @id = id
+          @content = content.dup.force_encoding(Encoding::BINARY)
+        end
+
+        def self.from_raw(id, content)
+          new(id, content)
+        end
+
+        def self.deserialize(data)
+          if data.bytesize < 8
+            raise Omnizip::DecompressionError,
+                  "dictionary too short for magic + id"
+          end
+          if data.byteslice(0, 4).unpack1("V") != DICT_MAGIC
+            raise Omnizip::DecompressionError, "bad dictionary magic"
+          end
+
+          new(data.byteslice(4, 4).unpack1("V"), data.byteslice(8..))
+        end
+
+        def serialize
+          [DICT_MAGIC].pack("V") + [@id].pack("V") + @content
+        end
+
+        def ==(other)
+          other.is_a?(Dictionary) && id == other.id && content == other.content
+        end
+      end
+    end
+  end
+end