zrip: Ractor-safe Zstandard for Ruby

CI Gem Version License: MIT Ruby

Ruby bindings for zrip, a pure-Rust Zstandard implementation. Built as an rb-sys native extension and declared Ractor-safe so you can compress from any Ractor without a global lock.

Features

  • Frame codec for standard Zstd frames (Ractor-shareable)
  • Block codec with per-Ractor context (no lock overhead)
  • Dictionary support for both frame and block codecs
  • FastCOVER-based dictionary trainer (DictTrainer)
  • Configurable compression levels (default: 1)
  • Bounded decompression with max_output_size: and frame content size checks
  • Ractor-safe: FrameCodec is shareable across Ractors, BlockCodec is per-Ractor (mutable context state)

Install

Requires Ruby >= 3.4 and a Rust toolchain (for building the native extension):

gem install zrip

Or in your Gemfile:

gem "zrip"

Usage

Frame codec (standard Zstd frames)

require "zrip"

codec = Zrip::FrameCodec.new
compressed = codec.compress("hello world " * 1000)
original   = codec.decompress(compressed)

Block codec

codec = Zrip::BlockCodec.new
compressed = codec.compress("hello world " * 1000)
original   = codec.decompress(compressed)

Compression levels

fast   = Zrip::FrameCodec.new(level: -3)   # negative = faster
strong = Zrip::FrameCodec.new(level: 19)    # higher = smaller output

Bounded decompression

codec = Zrip::FrameCodec.new

# Limit total output size to 1 MiB
codec.decompress(compressed, max_output_size: 1024 * 1024)

# Read frame content size from header (without decompressing)
Zrip::FrameCodec.get_frame_content_size(compressed)  #=> 12000

Dictionary compression

dict = Zrip::Dictionary.new(bytes: trained_dict_bytes)
codec = Zrip::FrameCodec.new(dict: dict)

compressed = codec.compress("common log prefix: event=login user=alice")
original   = codec.decompress(compressed)

Dictionary training

trainer = Zrip::DictTrainer.new(8192)
messages.each { |msg| trainer.add_sample(msg) }
dict_bytes = trainer.train

dict  = Zrip::Dictionary.new(bytes: dict_bytes)
codec = Zrip::FrameCodec.new(dict: dict)

Ractor safety

On Ruby VMs without Ractor support, the codecs still work normally; the Ractor-specific guarantees and examples do not apply.

codec = Zrip::FrameCodec.new

ractors = 4.times.map do |i|
  Ractor.new(codec) do |c|
    data = "ractor #{Ractor.current} payload " * 100
    ct   = c.compress(data)
    raise "mismatch" unless c.decompress(ct) == data
    :ok
  end
end

ractors.each { |r| p r.value }  # => :ok, :ok, :ok, :ok

Documentation

Reference: https://rubydoc.info/gems/zrip

License

MIT