omnizip 0.4.7-x86_64-linux

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

@@ -0,0 +1,159 @@
+# 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
+      # XXHash64 (https://github.com/Cyan4973/xxHash), single-shot.
+      #
+      # Zstandard frame checksums are the low 32 bits of XXHash64 of the
+      # decoded content with seed 0 (the zstd C reference truncates
+      # XXH64_digest to a U32; RFC 8878's "xxh64" wording agrees).
+      module XXHash64
+        MASK64 = 0xFFFFFFFFFFFFFFFF
+        MASK32 = 0xFFFFFFFF
+
+        PRIME64_1 = 0x9E3779B185EBCA87
+        PRIME64_2 = 0xC2B2AE3D27D4EB4F
+        PRIME64_3 = 0x165667B19E3779F9
+        PRIME64_4 = 0x85EBCA77C2B2AE63
+        PRIME64_5 = 0x27D4EB2F165667C5
+
+        module_function
+
+        # Digest `data` with seed 0.
+        #
+        # @param data [String] binary string
+        # @return [Integer] 64-bit digest
+        def digest(data)
+          digest_seeded(data, 0)
+        end
+
+        def digest_seeded(data, seed)
+          len = data.bytesize
+          hash = 0
+          tail_start = 0
+
+          if len >= 32
+            v1 = (seed + PRIME64_1 + PRIME64_2) & MASK64
+            v2 = (seed + PRIME64_2) & MASK64
+            v3 = seed & MASK64
+            v4 = (seed - PRIME64_1) & MASK64
+
+            i = 0
+            while i + 32 <= len
+              v1 = round64(v1, read_u64(data, i))
+              v2 = round64(v2, read_u64(data, i + 8))
+              v3 = round64(v3, read_u64(data, i + 16))
+              v4 = round64(v4, read_u64(data, i + 24))
+              i += 32
+            end
+
+            hash = rotl64(v1, 1)
+            hash = (hash + rotl64(v2, 7)) & MASK64
+            hash = (hash + rotl64(v3, 12)) & MASK64
+            hash = (hash + rotl64(v4, 18)) & MASK64
+
+            hash = merge_round64(hash, v1)
+            hash = merge_round64(hash, v2)
+            hash = merge_round64(hash, v3)
+            hash = merge_round64(hash, v4)
+
+            tail_start = len - (len % 32)
+          else
+            hash = (seed + PRIME64_5) & MASK64
+          end
+
+          hash = (hash + len) & MASK64
+
+          i = tail_start
+          while i + 8 <= len
+            k1 = round64(0, read_u64(data, i))
+            hash ^= k1
+            hash = ((rotl64(hash, 27) * PRIME64_1) & MASK64) + PRIME64_4
+            hash &= MASK64
+            i += 8
+          end
+          if i + 4 <= len
+            hash ^= (read_u32(data, i) * PRIME64_1) & MASK64
+            hash = ((rotl64(hash, 23) * PRIME64_2) & MASK64) + PRIME64_3
+            hash &= MASK64
+            i += 4
+          end
+          while i < len
+            hash ^= (data.getbyte(i) * PRIME64_5) & MASK64
+            hash = (rotl64(hash, 11) * PRIME64_1) & MASK64
+            i += 1
+          end
+
+          hash ^= hash >> 33
+          hash = (hash * PRIME64_2) & MASK64
+          hash ^= hash >> 29
+          hash = (hash * PRIME64_3) & MASK64
+          hash ^= hash >> 32
+          hash
+        end
+
+        # Zstandard frame checksum: low 32 bits of XXHash64.
+        #
+        # @return [Integer] 32-bit checksum
+        def frame_checksum(data)
+          digest(data) & MASK32
+        end
+
+        def read_u64(data, offset)
+          data.getbyte(offset) |
+            (data.getbyte(offset + 1) << 8) |
+            (data.getbyte(offset + 2) << 16) |
+            (data.getbyte(offset + 3) << 24) |
+            (data.getbyte(offset + 4) << 32) |
+            (data.getbyte(offset + 5) << 40) |
+            (data.getbyte(offset + 6) << 48) |
+            (data.getbyte(offset + 7) << 56)
+        end
+
+        def read_u32(data, offset)
+          data.getbyte(offset) |
+            (data.getbyte(offset + 1) << 8) |
+            (data.getbyte(offset + 2) << 16) |
+            (data.getbyte(offset + 3) << 24)
+        end
+
+        def rotl64(value, count)
+          ((value << count) | (value >> (64 - count))) & MASK64
+        end
+
+        def round64(acc, input)
+          acc = ((acc + (input * PRIME64_2)) & MASK64) & MASK64
+          acc = rotl64(acc, 31)
+          (acc * PRIME64_1) & MASK64
+        end
+
+        def merge_round64(acc, value)
+          value = round64(0, value)
+          acc ^= value
+          (((acc * PRIME64_1) & MASK64) + PRIME64_4) & MASK64
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/algorithms/zstandard.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+# 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
+    # Zstandard compression algorithm
+    #
+    # Zstandard (or Zstd) is a fast lossless compression algorithm developed
+    # by Facebook (now Meta). It provides:
+    # - Excellent compression ratios comparable to zlib/deflate
+    # - Very fast compression and decompression speeds
+    # - Wide range of compression levels (1-22)
+    # - Dictionary support for small data compression
+    # - Streaming and frame modes
+    #
+    # Pure Ruby implementation of the Zstandard format, interoperable
+    # with the reference zstd CLI in both directions.
+    #
+    # Zstandard is particularly effective for:
+    # - Real-time compression needs
+    # - Network protocol compression
+    # - Database compression
+    # - Log file compression
+    # - General-purpose compression with speed priority
+    class Zstandard < Algorithm
+      # Nested classes - autoloaded
+      autoload :Constants, "omnizip/algorithms/zstandard/constants"
+      autoload :Encoder, "omnizip/algorithms/zstandard/encoder"
+      autoload :Decoder, "omnizip/algorithms/zstandard/decoder"
+      autoload :Huffman, "omnizip/algorithms/zstandard/huffman"
+      autoload :HuffmanTableReader, "omnizip/algorithms/zstandard/huffman"
+      autoload :HuffmanEncoder, "omnizip/algorithms/zstandard/huffman_encoder"
+      autoload :LiteralsDecoder, "omnizip/algorithms/zstandard/literals"
+      autoload :LiteralsEncoder, "omnizip/algorithms/zstandard/literals_encoder"
+      autoload :SequencesDecoder, "omnizip/algorithms/zstandard/sequences"
+      autoload :SequenceExecutor, "omnizip/algorithms/zstandard/sequences"
+      autoload :SequencesEncoder,
+               "omnizip/algorithms/zstandard/sequences_encoder"
+      autoload :MatchFinder, "omnizip/algorithms/zstandard/match_finder"
+      autoload :LdmHashTable, "omnizip/algorithms/zstandard/ldm"
+      autoload :Dictionary, "omnizip/algorithms/zstandard/dictionary"
+      autoload :XXHash64, "omnizip/algorithms/zstandard/xxhash"
+
+      # Frame and FSE modules
+      autoload :Frame, "omnizip/algorithms/zstandard/frame"
+      autoload :FSE, "omnizip/algorithms/zstandard/fse"
+
+      # Get algorithm metadata
+      #
+      # @return [AlgorithmMetadata] Algorithm information
+      def self.metadata
+        Models::AlgorithmMetadata.new.tap do |meta|
+          meta.name = "zstandard"
+          meta.description = "Zstandard fast compression with " \
+                             "excellent ratios"
+          meta.version = "1.0.0"
+        end
+      end
+
+      # Compress data using Zstandard algorithm
+      #
+      # @param input_stream [IO] Input stream to compress
+      # @param output_stream [IO] Output stream for compressed data
+      # @param options [Models::CompressionOptions] Compression options
+      # @return [void]
+      def compress(input_stream, output_stream, options = nil)
+        input_data = input_stream.read
+        level = build_encoder_options(options)[:level] || 3
+        output_stream.write(
+          Backends.compress("zstd", input_data, level) do
+            encoder = Encoder.new(output_stream, build_encoder_options(options))
+            encoder.encode_stream(input_data)
+          end,
+        )
+      end
+
+      # Decompress Zstandard-compressed data
+      #
+      # @param input_stream [IO] Input stream of compressed data
+      # @param output_stream [IO] Output stream for decompressed data
+      # @param options [Models::CompressionOptions] Decompression options
+      # @return [void]
+      def decompress(input_stream, output_stream, _options = nil)
+        output_stream.set_encoding(Encoding::BINARY)
+        compressed = input_stream.read
+        decompressed = Backends.decompress("zstd", compressed, Backends::UNKNOWN_LENGTH) do
+          Decoder.new(StringIO.new(compressed)).decode_stream
+        end
+        output_stream.write(decompressed)
+      end
+
+      # Compress data primed with a dictionary prefix: the dictionary
+      # content acts as shared history the match finder can reference,
+      # dramatically improving ratios on small inputs. The resulting
+      # frame carries the dictionary's ID and requires
+      # decompress_with_dict to decode.
+      #
+      # @param input_stream [IO] plaintext
+      # @param output_stream [IO] compressed frame
+      # @param dict [Dictionary]
+      # @param options [Hash] :level, :checksum
+      # @return [void]
+      def compress_with_dict(input_stream, output_stream, dict, options = {})
+        encoder = Encoder.new(output_stream, build_encoder_options(options))
+        encoder.encode_stream_with_dict(input_stream.read, dict)
+      end
+
+      # Decompress a frame produced by compress_with_dict. The frame's
+      # dictionary ID is verified against `dict` before decoding.
+      #
+      # @param input_stream [IO] compressed frame
+      # @param output_stream [IO] plaintext
+      # @param dict [Dictionary]
+      # @return [void]
+      def decompress_with_dict(input_stream, output_stream, dict)
+        output_stream.set_encoding(Encoding::BINARY)
+        decoder = Decoder.new(input_stream)
+        output_stream.write(decoder.decode_stream_with_dict(dict))
+      end
+
+      # Class-level convenience mirrors of the dictionary API.
+      #
+      # @return [String] compressed frame / decompressed plaintext
+      def self.compress_with_dict(data, dict, **options)
+        output = StringIO.new
+        output.set_encoding(Encoding::BINARY)
+        new(options).compress_with_dict(
+          StringIO.new(data.to_s.b), output, dict, options
+        )
+        output.string
+      end
+
+      def self.decompress_with_dict(data, dict)
+        output = StringIO.new
+        output.set_encoding(Encoding::BINARY)
+        new.decompress_with_dict(StringIO.new(data.to_s.b), output, dict)
+        output.string
+      end
+
+      private
+
+      # Build encoder options from compression options
+      #
+      # Always sets :level, defaulting to the zstd default (3) so that
+      # `compress(data)` never silently degrades to stored frames
+      # (issue #27). Accepts a Hash (as forwarded by Algorithm.compress)
+      # or a Models::CompressionOptions.
+      #
+      # @param options [Models::CompressionOptions, Hash, nil]
+      # @return [Hash] Encoder options
+      def build_encoder_options(options)
+        level = case options
+                when nil then nil
+                when Hash then options[:level]
+                # allowed: options is a public parameter; any object with #level is honored
+                else options.level if options.respond_to?(:level)
+                end
+
+        { level: map_compression_level(level) }
+      end
+
+      # Map generic compression level (0-9) to Zstd level (1-22)
+      #
+      # @param level [Integer] Compression level (0-9)
+      # @return [Integer] Zstd compression level (1-22)
+      def map_compression_level(level)
+        return 3 if level.nil? # Zstd default
+
+        case level
+        when 0 then 1      # Fastest
+        when 1 then 2
+        when 2 then 3
+        when 3 then 5
+        when 4 then 7
+        when 5 then 10
+        when 6 then 13
+        when 7 then 16
+        when 8 then 19
+        when 9 then 22     # Maximum
+        else level
+        end
+      end
+    end
+  end
+end
+
+# Register the Zstandard algorithm
+Omnizip::AlgorithmRegistry.register(:zstandard,
+                                    Omnizip::Algorithms::Zstandard)

data/lib/omnizip/algorithms.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Omnizip
+  # High-level compression algorithm facades.
+  #
+  # Each top-level constant in this namespace (Deflate, BZip2, LZMA,
+  # LZMA2, Zstandard, PPMd7, PPMd8) is a facade that exposes the
+  # streaming +.compress+/+.decompress+ contract from +Omnizip::Algorithm+.
+  # Format-specific readers/writers call these facades for the actual
+  # compression work; the facades themselves do not know about archive
+  # container structure.
+  #
+  # Bit-level SDK ports (state machines, range coders, match finders)
+  # live under +Omnizip::Implementations+, not here. This namespace
+  # owns the *streaming contract*; that namespace owns the *primitives*.
+  # The boundary is: +Algorithms+ calls +Implementations+, never the
+  # reverse.
+  module Algorithms
+    autoload :PPMdBase, "omnizip/algorithms/ppmd_base"
+    autoload :LZMA2Const, "omnizip/algorithms/lzma2/constants"
+    autoload :LZMA, "omnizip/algorithms/lzma"
+    autoload :LZMA2, "omnizip/algorithms/lzma2"
+    autoload :LZMA2XzEncoderAdapter,
+             "omnizip/algorithms/lzma2/xz_encoder_adapter"
+    autoload :LZMA2Chunk, "omnizip/algorithms/lzma2/lzma2_chunk"
+    autoload :LZMA2Encoder, "omnizip/algorithms/lzma2/encoder"
+    autoload :XzUtilsDecoder, "omnizip/algorithms/lzma/xz_utils_decoder"
+    autoload :PPMd7, "omnizip/algorithms/ppmd7"
+    autoload :PPMd8, "omnizip/algorithms/ppmd8"
+    autoload :BZip2, "omnizip/algorithms/bzip2"
+    autoload :Deflate, "omnizip/algorithms/deflate"
+    autoload :Deflate64, "omnizip/algorithms/deflate64"
+    autoload :Zstandard, "omnizip/algorithms/zstandard"
+  end
+end

data/lib/omnizip/archive/builder.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Archive
+    # Block argument of +Archive.create+. Translates the documented
+    # +add_file+/+add_directory+/+add_data+ vocabulary onto the
+    # handler proxy's +add(name, source_path)+ / +add_data+ calls.
+    class Builder
+      def initialize(proxy)
+        @proxy = proxy
+      end
+
+      # Add a file from disk, optionally under a different archive
+      # path: +add_file('report.pdf', 'reports/report.pdf')+.
+      def add_file(file_path, archive_path = nil)
+        @proxy.add(archive_path || ::File.basename(file_path), file_path)
+      end
+
+      # Add a directory tree under its own name:
+      # +add_directory('photos/')+ stores +photos/x.jpg+.
+      def add_directory(dir_path)
+        prefix = ::File.basename(::File.expand_path(dir_path))
+        @proxy.add("#{prefix}/")
+        walk(dir_path, prefix)
+      end
+
+      # Add in-memory content at +archive_path+.
+      def add_data(archive_path, data)
+        @proxy.add_data(archive_path, data)
+      end
+
+      private
+
+      def walk(dir, prefix)
+        ::Dir.children(dir).sort.each do |child|
+          full = ::File.join(dir, child)
+          name = "#{prefix}/#{child}"
+          if ::File.directory?(full)
+            @proxy.add("#{name}/")
+            walk(full, name)
+          else
+            @proxy.add(name, full)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/archive/reader_session.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Omnizip
+  module Archive
+    # Block argument (and return value) of +Archive.open+. Delegates
+    # per operation to the resolved ArchiveHandler, which opens and
+    # closes the underlying reader on every call — the session itself
+    # holds no resources.
+    class ReaderSession
+      def initialize(handler, path, options = {})
+        @handler = handler
+        @path = path
+        @options = options
+      end
+
+      # Archive metadata records (see Archive::Entry).
+      def entries
+        @handler.list(@path, details: true, **@options).map do |h|
+          Entry.new(name: h[:name], size: h[:size], directory: h[:directory],
+                    mtime: h[:mtime] || h[:time])
+        end
+      end
+
+      def each_entry(&block)
+        entries.each(&block)
+      end
+
+      # Contents of a single entry, without extraction.
+      def read(entry_name)
+        @handler.read_entry(@path, entry_name, **@options)
+      end
+
+      # Extract one entry to an explicit destination path.
+      def extract(entry_name, dest_path)
+        entry = entries.find { |e| e.name == entry_name }
+        unless entry
+          raise Errno::ENOENT, "Entry not found: #{entry_name}"
+        end
+
+        if entry.directory?
+          ::FileUtils.mkdir_p(dest_path)
+          return dest_path
+        end
+
+        ::FileUtils.mkdir_p(::File.dirname(dest_path))
+        ::File.binwrite(dest_path, read(entry_name))
+        dest_path
+      end
+
+      def extract_all(output_dir)
+        @handler.extract_to(@path, output_dir, **@options)
+      end
+
+      # Extract every entry whose name matches +pattern+ under
+      # +output_dir+, preserving archive-relative paths.
+      def extract_matching(pattern, output_dir)
+        ::FileUtils.mkdir_p(output_dir)
+        entries.select do |e|
+          !e.directory? && ::File.fnmatch?(pattern, e.name,
+                                           ::File::FNM_PATHNAME)
+        end.map { |e| extract(e.name, ::File.join(output_dir, e.name)) }
+      end
+    end
+  end
+end

data/lib/omnizip/archive.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Omnizip
+  # High-level block-style archive facade over the registered
+  # ArchiveHandlers. This is the API the guides document:
+  #
+  #   Omnizip::Archive.create('backup.7z', format: :seven_zip,
+  #                           level: 9) do |archive|
+  #     archive.add_file('report.pdf', 'reports/report.pdf')
+  #     archive.add_directory('photos/')
+  #     archive.add_data('notes/readme.txt', "generated\n")
+  #   end
+  #
+  #   Omnizip::Archive.open('backup.7z') do |archive|
+  #     archive.entries.each { |e| puts "#{e.name} (#{e.size})" }
+  #     archive.read('notes/readme.txt')
+  #     archive.extract_all('output/')
+  #   end
+  #
+  # The format is resolved from the output path's extension when
+  # +format:+ is not given explicitly, exactly like the convenience
+  # methods. Passwords are supported for 7z only (ZIP writing and
+  # reading have no encryption support); asking for one elsewhere
+  # raises rather than silently producing an unprotected archive.
+  module Archive
+    autoload :Builder, "omnizip/archive/builder"
+    autoload :ReaderSession, "omnizip/archive/reader_session"
+
+    # Metadata record yielded by ReaderSession#entries. The +size+
+    # member intentionally shadows Struct#size: the documented
+    # contract is entry size in bytes, not the member count.
+    # rubocop:disable-next Lint/StructNewOverride -- documented byte size
+    Entry = Struct.new(:name, :size, :directory, :mtime, keyword_init: true) do
+      def directory?
+        directory
+      end
+    end
+
+    PASSWORD_FORMATS = %i[seven_zip rar].freeze
+    private_constant :PASSWORD_FORMATS
+
+    class << self
+      # Create an archive, yielding a Builder that translates the
+      # documented +add_file+/+add_directory+/+add_data+ calls onto
+      # the resolved handler. Returns the archive path.
+      def create(path, format: Convenience::DEFAULT_FORMAT, **options, &block)
+        resolved = Omnizip.resolve_archive_format(path, format)
+        check_password_support!(resolved, options[:password])
+
+        Omnizip::ArchiveHandler.for(resolved).create(path, **options) do |proxy|
+          block&.call(Builder.new(proxy))
+        end
+        path
+      end
+
+      # Open an archive for reading, yielding a ReaderSession. Without
+      # a block, returns the session. An explicit +password:+ wins
+      # over ENV['OMNIZIP_PASSWORD'].
+      def open(path, password: nil, **options, &block)
+        resolved = Omnizip.resolve_archive_format(
+          path, Convenience::DEFAULT_FORMAT, writing: false
+        )
+        pw = password || ENV.fetch("OMNIZIP_PASSWORD", nil)
+        check_password_support!(resolved, pw)
+
+        options[:password] = pw if pw
+        session = ReaderSession.new(
+          Omnizip::ArchiveHandler.for(resolved), path, options
+        )
+        return session unless block
+
+        yield session
+      end
+
+      private
+
+      def check_password_support!(resolved, password)
+        return unless password && !PASSWORD_FORMATS.include?(resolved)
+
+        raise Omnizip::UnsupportedFormatError,
+              "password is only supported for #{PASSWORD_FORMATS.join(', ')}; " \
+              "#{resolved.inspect} has no encryption support"
+      end
+    end
+  end
+end

data/lib/omnizip/archive_handler.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Omnizip
+  # Unified archive handler interface for the Convenience module.
+  #
+  # Each format that wants to participate in Omnizip.compress_file /
+  # extract_archive / etc. registers a Handler here. The Handler exposes
+  # a small canonical API (+create+, +open+, +extract_to+, +list+) that
+  # the Convenience module calls; the Handler then delegates to the
+  # format-specific reader/writer.
+  #
+  # @example Register a format
+  #   Omnizip::ArchiveHandler.register(:tar, TarHandler.new)
+  #
+  # @example Use from a caller
+  #   Omnizip::ArchiveHandler.for(:tar).create(path) { |w| w.add_file(...) }
+  module ArchiveHandler
+    @handlers = {}
+
+    class << self
+      # Register a handler for a format symbol.
+      #
+      # @param format [Symbol] e.g. +:zip+, +:tar+
+      # @param handler [Object] responding to the Handler interface
+      # @return [void]
+      def register(format, handler)
+        @handlers[format.to_sym] = handler
+      end
+
+      # Look up the handler for +format+. Triggers the registered lazy
+      # load constant if the format is one of the built-ins.
+      #
+      # @param format [Symbol]
+      # @return [Object]
+      # @raise [Omnizip::UnsupportedFormatError] if +format+ is unknown
+      def for(format)
+        handler = @handlers[format.to_sym]
+        return handler if handler
+
+        trigger = LAZY_LOAD_TRIGGERS[format.to_sym]
+        if trigger
+          trigger.call
+          handler = @handlers[format.to_sym]
+          return handler if handler
+        end
+
+        raise Omnizip::UnsupportedFormatError,
+              "No archive handler registered for #{format.inspect}. " \
+              "Registered: #{@handlers.keys.join(', ')}"
+      end
+
+      # List of registered format names.
+      #
+      # @return [Array<Symbol>]
+      def available
+        @handlers.keys
+      end
+
+      # Remove a handler (primarily for testing).
+      #
+      # @return [void]
+      def unregister(format)
+        @handlers.delete(format.to_sym)
+      end
+    end
+
+    # Lazy triggers — referencing the constant autoloads the handler's
+    # file, which then self-registers at the bottom of the file.
+    LAZY_LOAD_TRIGGERS = {
+      zip: -> { Omnizip::ArchiveHandlers::ZipHandler },
+      rpm: -> { Omnizip::ArchiveHandlers::RpmHandler },
+      xar: -> { Omnizip::ArchiveHandlers::XarHandler },
+      ole: -> { Omnizip::ArchiveHandlers::OleHandler },
+      tar: -> { Omnizip::ArchiveHandlers::TarHandler },
+      seven_zip: -> { Omnizip::ArchiveHandlers::SevenZipHandler },
+      rar: -> { Omnizip::ArchiveHandlers::RarHandler },
+      cpio: -> { Omnizip::ArchiveHandlers::CpioHandler },
+      iso: -> { Omnizip::ArchiveHandlers::IsoHandler },
+    }.freeze
+    private_constant :LAZY_LOAD_TRIGGERS
+  end
+end