zrip 0.1.2 → 0.2.1

data/lib/zrip/dict_trainer.rb

@@ -1,6 +1,38 @@
 # frozen_string_literal: true
 
 module Zrip
+  # FastCOVER-based Zstandard dictionary trainer.
+  #
+  # @!method self.new(max_dict_size)
+  #   Create a dictionary trainer.
+  #   @param max_dict_size [Integer] maximum dictionary size in bytes
+  #   @return [DictTrainer]
+  #
+  # @!method self._native_new(max_dict_size)
+  #   Native constructor used by `.new`.
+  #   @param max_dict_size [Integer] maximum dictionary size in bytes
+  #   @return [DictTrainer]
+  #
+  # @!method add_sample(bytes)
+  #   Add a training sample. Samples shorter than 4 bytes are ignored.
+  #   @param bytes [String] sample bytes
+  #   @return [nil]
+  #
+  # @!method train
+  #   Train and consume the trainer.
+  #   @return [String] dictionary bytes
+  #
+  # @!method sample_count
+  #   @return [Integer] accepted sample count
+  #
+  # @!method total_bytes
+  #   @return [Integer] total bytes from accepted samples
+  #
+  # @!method trained?
+  #   @return [Boolean]
+  #
+  # @!method max_dict_size
+  #   @return [Integer] configured maximum dictionary size
   class DictTrainer
     def self.new(max_dict_size)
       _native_new(max_dict_size)

data/lib/zrip/dictionary.rb

@@ -3,6 +3,13 @@
 require "digest"
 
 module Zrip
+  # Immutable Zstandard dictionary value.
+  #
+  # @!attribute [r] bytes
+  #   @return [String] frozen binary dictionary bytes
+  #
+  # @!attribute [r] id
+  #   @return [Integer] dictionary ID
   Dictionary = Data.define(:bytes, :id)
 
   class Dictionary
@@ -12,6 +19,8 @@ module Zrip
     USER_DICT_ID_SIZE = USER_DICT_ID_MAX - USER_DICT_ID_MIN + 1
 
 
+    # @param bytes [String] dictionary bytes
+    # @param id [Integer, nil] optional dictionary ID
     def initialize(bytes:, id: nil)
       b = bytes.b
       id ||= if b.byteslice(0, 4) == ZDICT_MAGIC
@@ -24,6 +33,7 @@ module Zrip
     end
 
 
+    # @return [Integer] dictionary size in bytes
     def size
       bytes.bytesize
     end

data/lib/zrip/frame_codec.rb

@@ -3,6 +3,64 @@
 require_relative "dictionary"
 
 module Zrip
+  # Zstandard frame-format codec.
+  #
+  # `FrameCodec` is Ractor-shareable. It uses an internal lock around native
+  # compression and decompression contexts.
+  #
+  # @!method self.new(dict: nil, level: DEFAULT_LEVEL)
+  #   Create a frame codec.
+  #   @param dict [Dictionary, String, nil] optional Zstandard dictionary
+  #   @param level [Integer] compression level
+  #   @return [FrameCodec]
+  #
+  # @!method self._native_new(dict, id, level)
+  #   Native constructor used by `.new`.
+  #   @param dict [String, nil] dictionary bytes
+  #   @param id [Integer] dictionary ID, or `0` without a dictionary
+  #   @param level [Integer] compression level
+  #   @return [FrameCodec]
+  #   @raise [CompressError]
+  #
+  # @!method self.get_frame_content_size(bytes)
+  #   Read `Frame_Content_Size` from a Zstandard frame header.
+  #   @param bytes [String] compressed Zstandard frame
+  #   @return [Integer, nil]
+  #   @raise [DecompressError]
+  #
+  # @!method compress(bytes)
+  #   Compress bytes to a Zstandard frame.
+  #   @param bytes [String] uncompressed bytes
+  #   @return [String]
+  #   @raise [CompressError]
+  #
+  # @!method decompress(bytes, max_output_size: nil)
+  #   Decompress a Zstandard frame.
+  #   @param bytes [String] compressed Zstandard frame
+  #   @param max_output_size [Integer, nil] optional output byte limit
+  #   @return [String]
+  #   @raise [DecompressError]
+  #   @raise [OutputSizeLimitError]
+  #
+  # @!method _native_decompress(bytes, max_output_size)
+  #   Native decompression entry used by #decompress.
+  #   @param bytes [String] compressed Zstandard frame
+  #   @param max_output_size [Integer] output byte limit, or `0` for unbounded
+  #   @return [String]
+  #   @raise [DecompressError]
+  #   @raise [OutputSizeLimitError]
+  #
+  # @!method has_dict?
+  #   @return [Boolean]
+  #
+  # @!method id
+  #   @return [Integer, nil] dictionary ID
+  #
+  # @!method size
+  #   @return [Integer] dictionary size in bytes
+  #
+  # @!method level
+  #   @return [Integer] compression level
   class FrameCodec
     def self.new(dict: nil, level: DEFAULT_LEVEL)
       case dict

data/lib/zrip/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zrip
-  VERSION = "0.1.2"
+  VERSION = "0.2.1"
 end

data/lib/zrip.rb

@@ -4,7 +4,21 @@ require_relative "zrip/zrip"        # Rust extension
 require_relative "zrip/version"
 
 module Zrip
+  # Default compression level used by `FrameCodec` and `BlockCodec`.
   DEFAULT_LEVEL = 1
+
+  # @!parse
+  #   # Raised when Zstandard decompression fails.
+  #   class DecompressError < StandardError; end
+  #
+  #   # Raised when Zstandard compression fails.
+  #   class CompressError < StandardError; end
+  #
+  #   # Reserved subclass for streams without a declared frame content size.
+  #   class MissingContentSizeError < DecompressError; end
+  #
+  #   # Raised when decompressed output exceeds the requested limit.
+  #   class OutputSizeLimitError < DecompressError; end
 end
 
 require_relative "zrip/dictionary"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zrip
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - Patrik Wenger
@@ -16,6 +16,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -23,7 +26,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description: Ruby bindings (via Rust/magnus) for zrip, a pure-Rust Zstandard implementation.
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+description: Ruby bindings (via Rust/rb-sys) for zrip, a pure-Rust Zstandard implementation.
   Frame-format and block-format compress/decompress with optional dictionary support,
   configurable compression levels, and FastCOVER-based dictionary training. Ractor-safe.
 email:
@@ -39,8 +45,10 @@ files:
 - LICENSE
 - README.md
 - ext/zrip/Cargo.toml
+- ext/zrip/build.rs
 - ext/zrip/extconf.rb
 - ext/zrip/src/lib.rs
+- ext/zrip/src/rb.rs
 - lib/zrip.rb
 - lib/zrip/block_codec.rb
 - lib/zrip/dict_trainer.rb
@@ -52,7 +60,8 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/paddor/zrip-rb
-  source_code_uri: https://github.com/paddor/zrip-rb
+  source_code_uri: https://github.com/paddor/zrip-rb/tree/main
+  documentation_uri: https://rubydoc.info/gems/zrip
   changelog_uri: https://github.com/paddor/zrip-rb/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -62,14 +71,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 4.0.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Ractor-safe Zstandard bindings for Ruby (pure-Rust zrip backend)
 test_files: []