rlz4 0.2.1 → 0.5.0

data/lib/rlz4/block_codec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "dictionary"
+
+module RLZ4
+  class BlockCodec
+    # Block-format LZ4 compression with a reusable scratch hash table.
+    #
+    # Dict is passed once at construction time and baked into the codec:
+    # the dict is hashed into a pristine table exactly once in `.new`, and
+    # every subsequent `#compress` call restores that pristine state via
+    # a 16 KiB memcpy before running the block compressor. This amortises
+    # dict initialisation across the codec's lifetime rather than paying
+    # ~3-5 µs per call to re-hash the dict.
+    #
+    # `#compress` mutates the scratch table; `#decompress` does not. Both
+    # live on the same class so callers hold one object per worker.
+    #
+    # A BlockCodec must not cross Ractor boundaries. Per-Ractor codecs are
+    # the natural unit.
+    #
+    # @param dict [Dictionary, String, nil] dictionary bytes or a
+    #   Dictionary value wrapping them. The id on a Dictionary is
+    #   ignored (block format has no Dict_ID field); we only consult
+    #   the bytes.
+    def self.new(dict: nil)
+      _native_new(Dictionary === dict ? dict.bytes : dict)
+    end
+
+
+    def decompress(bytes, decompressed_size:)
+      _decompress(bytes, decompressed_size)
+    end
+  end
+end

data/lib/rlz4/dictionary.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module RLZ4
+  # Pure value type for an LZ4 dictionary: raw bytes plus a 4-byte id.
+  # Built on `Data.define`, so it's immutable, gets `==` / `#hash` /
+  # `#deconstruct` for free, and is shareable across Ractors.
+  #
+  # The id defaults to `sha256(bytes)[0, 4]` interpreted little-endian
+  # — the same derivation LZ4 frame FLG.DictID uses. Callers can pass
+  # their own id (e.g. a value coordinated out of band) via `id:`.
+  #
+  # The id is load-bearing in the frame format (FrameCodec writes it
+  # into the FrameDescriptor); BlockCodec accepts a Dictionary for
+  # API symmetry but doesn't consult the id.
+  Dictionary = Data.define(:bytes, :id) do
+    def initialize(bytes:, id: Digest::SHA256.digest(bytes).byteslice(0, 4).unpack1("V"))
+      super(bytes: bytes.b.freeze, id: id)
+    end
+
+
+    def size
+      bytes.bytesize
+    end
+  end
+end

data/lib/rlz4/frame_codec.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "dictionary"
+
+module RLZ4
+  class FrameCodec
+    # Frame-format LZ4 codec, optionally dict-bound. Parallel in shape
+    # to BlockCodec, but emits a real LZ4 frame (magic `04 22 4D 18`)
+    # with the FLG.DictID bit set and `Dict_ID` written into the
+    # FrameDescriptor when a dict is installed. Output is interoperable
+    # with the reference `lz4` CLI given the same dictionary file.
+    #
+    # Unlike BlockCodec, FrameCodec holds no thread-local mutable state:
+    # it's a read-only dict bytes buffer plus a derived id. Shareable
+    # across Ractors.
+    #
+    # @param dict [Dictionary, String, nil] dictionary bytes or a
+    #   Dictionary value. Passing a Dictionary reuses its cached id
+    #   (skips the sha256 digest); a raw String derives the id on the
+    #   fly.
+    def self.new(dict: nil)
+      case dict
+      when nil
+        _native_new(nil, 0)
+      when Dictionary
+        _native_new(dict.bytes, dict.id)
+      when String
+        _native_new(dict, Dictionary.new(bytes: dict).id)
+      else
+        raise TypeError, "expected RLZ4::Dictionary, String, or nil; got #{dict.class}"
+      end
+    end
+  end
+end

data/lib/rlz4/version.rb

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

data/lib/rlz4.rb

@@ -1,20 +1,7 @@
 # frozen_string_literal: true
 
-require "digest"
-
-require_relative "rlz4/rlz4"
+require_relative "rlz4/rlz4"        # Rust extension (native classes + compress_bound)
 require_relative "rlz4/version"
-
-module RLZ4
-  class Dictionary
-    # Public constructor. Derives the LZ4 frame `Dict_ID` from the dictionary
-    # bytes (sha256 truncated to the first 4 bytes, little-endian) and forwards
-    # to the Rust extension. The id is what gets written into every emitted
-    # frame's FrameDescriptor and what `#decompress` asserts the incoming
-    # frame declares before decoding.
-    def self.new(bytes)
-      id = Digest::SHA256.digest(bytes).byteslice(0, 4).unpack1("V")
-      _native_new(bytes, id)
-    end
-  end
-end
+require_relative "rlz4/dictionary"
+require_relative "rlz4/block_codec"
+require_relative "rlz4/frame_codec"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rlz4
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Patrik Wenger
@@ -66,11 +66,10 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '5.0'
 description: |
-  Ruby bindings (via Rust/magnus) for the lz4_flex LZ4 implementation.
-  Provides LZ4 frame-format compress/decompress at module level and a
-  stateful Dictionary class for block-format compression with a shared
-  dictionary. Designed to be safe to call from multiple Ractors, unlike
-  existing Ruby LZ4 gems.
+  Ruby bindings (via Rust/magnus) for liblz4, using lz4-sys FFI.
+  Provides block-format and frame-format LZ4 compress/decompress with
+  optional dictionary support. Designed to be safe to call from multiple
+  Ractors, unlike existing Ruby LZ4 gems.
 email:
 - paddor@protonmail.ch
 executables: []
@@ -86,9 +85,10 @@ files:
 - ext/rlz4/extconf.rb
 - ext/rlz4/src/lib.rs
 - lib/rlz4.rb
+- lib/rlz4/block_codec.rb
+- lib/rlz4/dictionary.rb
+- lib/rlz4/frame_codec.rb
 - lib/rlz4/version.rb
-- tmp/x86_64-linux/stage/Cargo.toml
-- tmp/x86_64-linux/stage/ext/rlz4/Cargo.toml
 homepage: https://github.com/paddor/rlz4
 licenses:
 - MIT
@@ -111,5 +111,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: Ractor-safe LZ4 bindings for Ruby (Rust extension via lz4_flex)
+summary: Ractor-safe LZ4 bindings for Ruby (Rust extension via lz4-sys/liblz4)
 test_files: []

data/tmp/x86_64-linux/stage/Cargo.toml

@@ -1,9 +0,0 @@
-[workspace]
-members  = ["ext/rlz4"]
-resolver = "2"
-
-[profile.release]
-opt-level     = 3
-lto           = true
-codegen-units = 1
-panic         = "abort"

data/tmp/x86_64-linux/stage/ext/rlz4/Cargo.toml

@@ -1,16 +0,0 @@
-[package]
-name    = "rlz4"
-version = "0.2.0"
-edition = "2021"
-
-[lib]
-name       = "rlz4"
-crate-type = ["cdylib", "rlib"]
-
-[dependencies]
-lz4_flex = { git = "https://github.com/paddor/lz4_flex.git", rev = "dae9c784e890591e6445135ba23cacf344eafe8f", default-features = false, features = ["frame", "std", "safe-encode", "safe-decode"] }
-magnus   = "0.8"
-rb-sys   = "0.9"
-
-[build-dependencies]
-rb-sys = "0.9"