rzstd 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 831259e481d6ea30d50a765ed67b4e574a2e71ba2bdfaba53ec7e529d07373a7
+  data.tar.gz: 158331395ece67a5f87ca0c6c42d7e8cc6f92fcc0dfd4334aa3830a663bce47b
+SHA512:
+  metadata.gz: 60dafb7dde062a01c77db4d04b2aa337e29b831bcdc1d69eae5c7b89861e85f1c9f55326e9163bb2d66d913a55a5288e9de9a65e148462f5f2d7c2f32e442a3d
+  data.tar.gz: bef641270ddcc3b275579741a43143174f39e9ab6fba5c8fd899edb98a6ff8ddd0ba707ffdff62f5f0004b598ec778c85dcfaf346c3af6e8a22d625b25a51ada

data/Cargo.lock

@@ -0,0 +1,441 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "bindgen"
+version = "0.72.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
+dependencies = [
+ "bitflags",
+ "cexpr",
+ "clang-sys",
+ "itertools",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "rustc-hash",
+ "shlex",
+ "syn",
+]
+
+[[package]]
+name = "bitflags"
+version = "2.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
+
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
+[[package]]
+name = "cc"
+version = "1.2.60"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43c5703da9466b66a946814e1adf53ea2c90f10063b86290cc9eb67ce3478a20"
+dependencies = [
+ "find-msvc-tools",
+ "jobserver",
+ "libc",
+ "shlex",
+]
+
+[[package]]
+name = "cexpr"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
+dependencies = [
+ "nom",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "clang-sys"
+version = "1.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b023947811758c97c59bf9d1c188fd619ad4718dcaa767947df1cadb14f39f4"
+dependencies = [
+ "glob",
+ "libc",
+ "libloading",
+]
+
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
+[[package]]
+name = "either"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+ "wasip2",
+]
+
+[[package]]
+name = "glob"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
+
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "jobserver"
+version = "0.1.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9afb3de4395d6b3e67a780b6de64b51c978ecf11cb9a462c66be7d4ca9039d33"
+dependencies = [
+ "getrandom",
+ "libc",
+]
+
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
+[[package]]
+name = "libc"
+version = "0.2.184"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48f5d2a454e16a5ea0f4ced81bd44e4cfc7bd3a507b61887c99fd3538b28e4af"
+
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
+[[package]]
+name = "magnus"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b36a5b126bbe97eb0d02d07acfeb327036c6319fd816139a49824a83b7f9012"
+dependencies = [
+ "magnus-macros",
+ "rb-sys",
+ "rb-sys-env",
+ "seq-macro",
+]
+
+[[package]]
+name = "magnus-macros"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47607461fd8e1513cb4f2076c197d8092d921a1ea75bd08af97398f593751892"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
+
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
+[[package]]
+name = "pkg-config"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "rb-sys"
+version = "0.9.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "284799e73e899fe946fd77c7211b83bff61a1356e039ade7a2516a779e3212d0"
+dependencies = [
+ "rb-sys-build",
+]
+
+[[package]]
+name = "rb-sys-build"
+version = "0.9.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "855fc1ad8943d12c89ef12f9147f1cc531f5bf19fb744112fdd317bb6ee7b5c5"
+dependencies = [
+ "bindgen",
+ "lazy_static",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "shell-words",
+ "syn",
+]
+
+[[package]]
+name = "rb-sys-env"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
+
+[[package]]
+name = "regex"
+version = "1.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e10754a14b9137dd7b1e3e5b0493cc9171fdd105e0ab477f51b72e7f3ac0e276"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe"
+
+[[package]]
+name = "rzstd"
+version = "0.1.0"
+dependencies = [
+ "magnus",
+ "rb-sys",
+ "sha2",
+ "zstd-safe",
+]
+
+[[package]]
+name = "seq-macro"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
+
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
+[[package]]
+name = "shell-words"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
+
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "typenum"
+version = "1.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "wasip2"
+version = "1.0.2+wasi-0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9517f9239f02c069db75e65f174b3da828fe5f5b945c4dd26bd25d89c03ebcf5"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "wit-bindgen"
+version = "0.51.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7249219f66ced02969388cf2bb044a09756a083d0fab1e566056b04d9fbcaa5"
+
+[[package]]
+name = "zstd-safe"
+version = "7.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f49c4d5f0abb602a93fb8736af2a4f4dd9512e36f7f570d66e65ff867ed3b9d"
+dependencies = [
+ "zstd-sys",
+]
+
+[[package]]
+name = "zstd-sys"
+version = "2.0.16+zstd.1.5.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91e19ebc2adc8f83e43039e79776e3fda8ca919132d68a1fed6a5faca2683748"
+dependencies = [
+ "cc",
+ "pkg-config",
+]

data/Cargo.toml

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

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrik Wenger
+
+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.

data/README.md

@@ -0,0 +1,62 @@
+# rzstd
+
+[![Gem Version](https://img.shields.io/gem/v/rzstd?color=e9573f)](https://rubygems.org/gems/rzstd)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%204.0-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
+[![Rust](https://img.shields.io/badge/Rust-stable-dea584?logo=rust&logoColor=white)](https://www.rust-lang.org)
+
+Ractor-safe Zstandard bindings for Ruby with persistent contexts.
+
+`rzstd` provides Zstd frame compress/decompress at module level and a
+stateful `Dictionary` class for dict-bound compression. Internally it
+holds onto `ZSTD_CCtx` / `ZSTD_DCtx` state across calls instead of
+allocating fresh ~256 KB contexts every time, which is what makes it
+viable for small-message workloads where the upstream `zstd-ruby` gem
+loses to LZ4 purely on context-allocation overhead.
+
+API mirrors [`rlz4`](https://github.com/paddor/rlz4) 0.2.x:
+
+```ruby
+require "rzstd"
+
+# Module-level frame compression
+ct = RZstd.compress("the quick brown fox", level: 3)  # level: kwarg, default 3
+RZstd.decompress(ct)                                  # => "the quick brown fox"
+
+# Negative levels enable Zstd's fast strategy (trades ratio for speed).
+# Supported range: -131072..22. Typical useful range: -7..19.
+RZstd.compress(payload, level: -3)                    # fast strategy, low ratio
+RZstd.compress(payload, level: 19)                    # high ratio, slow
+
+# Dict-bound compression
+dict = RZstd::Dictionary.new(File.binread("schema.dict"), level: -3)
+dict.id                                               # => u32 from sha256(dict)[0..4] LE
+dict.size                                             # => byte length
+dict.compress("payload that shares the schema")
+dict.decompress(ct)
+
+# Dictionary training from sample payloads (wraps ZDICT_trainFromBuffer).
+# Gather representative messages, then train a dictionary once and reuse
+# it on both peers. Small-message workloads benefit the most.
+samples = 1000.times.map { generate_sample_message }
+dict_bytes = RZstd::Dictionary.train(samples, capacity: 64 * 1024)
+dict = RZstd::Dictionary.new(dict_bytes)
+```
+
+`Dictionary#id` is derived from `sha256(dict_bytes)[0..4]` interpreted
+little-endian. It is intended for **out-of-band** peer negotiation
+(e.g. via a `dict:sha256:<hex>` profile string in your application
+protocol). Raw-content Zstd dictionaries always carry a frame `dictID`
+of 0 by spec, so this id is not embedded in the on-wire frame itself.
+Wrong-dict decoding is caught by the content checksum the encoder
+enables — a peer using the wrong dictionary raises
+`RZstd::DecompressError` instead of returning corrupt bytes.
+
+## Ractor safety
+
+The extension is marked Ractor-safe. `Dictionary` instances are
+shareable. Module-level `RZstd.compress` / `RZstd.decompress` use a
+single global `CCtx` / `DCtx` behind a `Mutex`, which serializes
+calls across Ractors — if you need parallel throughput, give each
+Ractor its own `Dictionary` (each one owns its own per-instance
+contexts).

data/ext/rzstd/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name    = "rzstd"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+name       = "rzstd"
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+# Backend: gyscos/zstd-rs (libzstd via zstd-sys). Chosen because it exposes
+# persistent ZSTD_CCtx / ZSTD_DCtx contexts via `zstd-safe`, which is the
+# whole reason this gem exists — we need to reuse encoder/decoder state
+# across calls to compete fairly with rlz4 on small messages.
+#
+# The pure-Rust killingspark/zstd-rs option is the eventual goal; tracked
+# as a follow-up once it grows a persistent-context API.
+zstd-safe = { version = "7", default-features = false, features = ["std", "zdict_builder"] }
+magnus    = "0.8"
+rb-sys    = "0.9"
+sha2      = { version = "0.10", default-features = false }
+
+[build-dependencies]
+rb-sys = "0.9"

data/ext/rzstd/extconf.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("rzstd/rzstd") do |r|
+  r.profile = ENV.fetch("RB_SYS_CARGO_PROFILE", :release).to_sym
+end

data/ext/rzstd/src/lib.rs

@@ -0,0 +1,377 @@
+use magnus::{
+    exception::ExceptionClass, function, method, prelude::*, r_string::RString, value::Opaque,
+    Error, Ruby,
+};
+use std::sync::{Mutex, OnceLock};
+
+use zstd_safe::{CCtx, CParameter, DCtx};
+
+const ZSTD_FRAME_MAGIC: [u8; 4] = [0x28, 0xB5, 0x2F, 0xFD];
+
+static DECOMPRESS_ERROR: OnceLock<Opaque<ExceptionClass>> = OnceLock::new();
+
+fn decompress_error(ruby: &Ruby) -> ExceptionClass {
+    ruby.get_inner(
+        *DECOMPRESS_ERROR
+            .get()
+            .expect("DecompressError not initialized"),
+    )
+}
+
+// ---------- module-level: persistent CCtx / DCtx for the no-dict path ----------
+//
+// The whole reason this gem exists is that the upstream `zstd-ruby` gem
+// allocates a fresh ZSTD_CCtx / ZSTD_DCtx (~256 KB of internal state)
+// on every compress/decompress call. For small messages that overhead
+// dominates and biases LZ4-vs-Zstd benchmarks. We hold one CCtx and one
+// DCtx behind a Mutex for the lifetime of the process. Multiple Ractors
+// share these contexts and serialize on the Mutex; if you need parallel
+// throughput, give each Ractor its own `RZstd::Dictionary` (each one
+// owns its own per-instance CCtx/DCtx — see below).
+
+static GLOBAL_CCTX: OnceLock<Mutex<CCtx<'static>>> = OnceLock::new();
+static GLOBAL_DCTX: OnceLock<Mutex<DCtx<'static>>> = OnceLock::new();
+
+fn global_cctx() -> &'static Mutex<CCtx<'static>> {
+    GLOBAL_CCTX.get_or_init(|| Mutex::new(CCtx::create()))
+}
+
+fn global_dctx() -> &'static Mutex<DCtx<'static>> {
+    GLOBAL_DCTX.get_or_init(|| Mutex::new(DCtx::create()))
+}
+
+fn rzstd_compress(ruby: &Ruby, rb_input: RString, level: i32) -> Result<RString, Error> {
+    // SAFETY: copy borrowed bytes into an owned Vec before any Ruby allocation.
+    let input: Vec<u8> = unsafe { rb_input.as_slice().to_vec() };
+    let upper = zstd_safe::compress_bound(input.len());
+    let mut out = vec![0u8; upper];
+
+    let mut cctx = global_cctx().lock().expect("global CCtx mutex poisoned");
+    cctx.set_parameter(CParameter::CompressionLevel(level))
+        .map_err(|code| {
+            Error::new(
+                ruby.exception_runtime_error(),
+                format!("zstd set_parameter failed: {code}"),
+            )
+        })?;
+    let n = cctx.compress2(&mut out, &input).map_err(|code| {
+        Error::new(
+            ruby.exception_runtime_error(),
+            format!("zstd compress failed: {code}"),
+        )
+    })?;
+    out.truncate(n);
+    Ok(ruby.str_from_slice(&out))
+}
+
+fn rzstd_decompress(ruby: &Ruby, rb_input: RString) -> Result<RString, Error> {
+    // SAFETY: copy borrowed bytes before any Ruby allocation.
+    let compressed: Vec<u8> = unsafe { rb_input.as_slice().to_vec() };
+
+    // Reject anything that isn't a well-formed zstd frame up front. zstd
+    // permissively returns 0 for some malformed inputs and we'd rather not
+    // mask "sender forgot --compress" mistakes in callers.
+    if compressed.len() < ZSTD_FRAME_MAGIC.len() || compressed[..4] != ZSTD_FRAME_MAGIC {
+        return Err(Error::new(
+            decompress_error(ruby),
+            "zstd frame decode failed: bad magic (input is not a Zstd frame)",
+        ));
+    }
+
+    // Frames produced by `compress2` always carry frame_content_size, so
+    // we can preallocate exactly. For frames without it (third-party
+    // producers) we fall back to a 1 MiB ceiling and grow as needed.
+    let upper = match zstd_safe::get_frame_content_size(&compressed) {
+        Ok(Some(n)) if n <= u64::from(u32::MAX) => n as usize,
+        _ => 1024 * 1024,
+    };
+    let mut out = vec![0u8; upper];
+    let mut dctx = global_dctx().lock().expect("global DCtx mutex poisoned");
+    let n = dctx.decompress(&mut out, &compressed).map_err(|code| {
+        Error::new(
+            decompress_error(ruby),
+            format!("zstd frame decode failed: {code}"),
+        )
+    })?;
+    out.truncate(n);
+    Ok(ruby.str_from_slice(&out))
+}
+
+// ---------- Dictionary: persistent dict-bound CCtx / DCtx ----------
+//
+// `Dict_ID` is supplied by the caller (the Ruby wrapper in `lib/rzstd.rb`
+// derives it from `sha256(dict_bytes)[0..4]` interpreted little-endian).
+// Doing the digest in Ruby keeps a hash crate out of the Rust extension's
+// dependency tree, exactly like rlz4 0.2.x.
+//
+// Each `Dictionary` instance owns:
+//   - the dict bytes (leaked to `&'static [u8]` so the CCtx can hold a
+//     by-reference dict load with no self-referential struct gymnastics —
+//     `Dictionary` instances are typically per-workload and long-lived)
+//   - a CCtx with the dictionary loaded by reference, behind a Mutex
+//   - a DCtx with the dictionary loaded by reference, behind a Mutex
+//
+// Multiple Ractors with separate Dictionary instances scale freely.
+// Multiple Ractors sharing one Dictionary serialize on its mutexes.
+#[magnus::wrap(class = "RZstd::Dictionary", free_immediately, size)]
+struct Dictionary {
+    bytes: &'static [u8],
+    id: u32,
+    cctx: Mutex<CCtx<'static>>,
+    dctx: Mutex<DCtx<'static>>,
+}
+
+// Safety: Dictionary's interior state lives behind Mutexes. The leaked
+// `bytes` slice is `'static`. CCtx/DCtx from zstd-safe own a unique
+// ZSTD_*Ctx pointer with no shared state, so wrapping them in Mutex
+// makes the whole struct Send + Sync.
+unsafe impl Send for Dictionary {}
+unsafe impl Sync for Dictionary {}
+
+fn dict_initialize(ruby: &Ruby, rb_dict: RString, id: u32, level: i32) -> Result<Dictionary, Error> {
+    // SAFETY: copy bytes into an owned Vec before any Ruby allocation.
+    let owned: Vec<u8> = unsafe { rb_dict.as_slice().to_vec() };
+    rb_dict.freeze();
+
+    // Leak the dict bytes so the CCtx/DCtx can hold a `'static` reference
+    // without self-referential lifetimes. Dictionaries are long-lived
+    // (typically one per workload) so this is fine in practice.
+    let bytes: &'static [u8] = Box::leak(owned.into_boxed_slice());
+
+    let mut cctx = CCtx::create();
+    cctx.set_parameter(CParameter::CompressionLevel(level))
+        .map_err(|code| {
+            Error::new(
+                ruby.exception_runtime_error(),
+                format!("zstd CCtx set_parameter failed: {code}"),
+            )
+        })?;
+    // Enable the content checksum so decoding with the wrong dictionary
+    // (or wrong bytes generally) fails fast at the trailing XXH64 check
+    // instead of silently returning garbage. Raw-content dictionaries
+    // always carry a frame `dictID` of 0 by spec, so the checksum is the
+    // only on-wire signal we have to detect dict mismatch.
+    cctx.set_parameter(CParameter::ContentSizeFlag(true))
+        .map_err(|code| {
+            Error::new(
+                ruby.exception_runtime_error(),
+                format!("zstd CCtx set_parameter ContentSizeFlag failed: {code}"),
+            )
+        })?;
+    cctx.set_parameter(CParameter::ChecksumFlag(true))
+        .map_err(|code| {
+            Error::new(
+                ruby.exception_runtime_error(),
+                format!("zstd CCtx set_parameter ChecksumFlag failed: {code}"),
+            )
+        })?;
+    cctx.load_dictionary(bytes).map_err(|code| {
+        Error::new(
+            ruby.exception_runtime_error(),
+            format!("zstd CCtx load_dictionary failed: {code}"),
+        )
+    })?;
+
+    let mut dctx = DCtx::create();
+    dctx.load_dictionary(bytes).map_err(|code| {
+        Error::new(
+            ruby.exception_runtime_error(),
+            format!("zstd DCtx load_dictionary failed: {code}"),
+        )
+    })?;
+
+    Ok(Dictionary {
+        bytes,
+        id,
+        cctx: Mutex::new(cctx),
+        dctx: Mutex::new(dctx),
+    })
+}
+
+fn dict_compress(ruby: &Ruby, rb_self: &Dictionary, rb_input: RString) -> Result<RString, Error> {
+    let input: Vec<u8> = unsafe { rb_input.as_slice().to_vec() };
+    let upper = zstd_safe::compress_bound(input.len());
+    let mut out = vec![0u8; upper];
+
+    let mut cctx = rb_self.cctx.lock().expect("Dictionary CCtx mutex poisoned");
+    let n = cctx.compress2(&mut out, &input).map_err(|code| {
+        Error::new(
+            ruby.exception_runtime_error(),
+            format!("zstd dict compress failed: {code}"),
+        )
+    })?;
+    out.truncate(n);
+    Ok(ruby.str_from_slice(&out))
+}
+
+fn dict_decompress(
+    ruby: &Ruby,
+    rb_self: &Dictionary,
+    rb_input: RString,
+) -> Result<RString, Error> {
+    let compressed: Vec<u8> = unsafe { rb_input.as_slice().to_vec() };
+    if compressed.len() < ZSTD_FRAME_MAGIC.len() || compressed[..4] != ZSTD_FRAME_MAGIC {
+        return Err(Error::new(
+            decompress_error(ruby),
+            "zstd dict frame decode failed: bad magic (input is not a Zstd frame)",
+        ));
+    }
+
+    // Note: raw-content zstd dictionaries always produce a frame `dictID`
+    // of 0, so we cannot use `get_dict_id_from_frame` for negotiation.
+    // The Dict_ID exposed by `Dictionary#id` is for out-of-band peer
+    // agreement (e.g. via the `dict:sha256:<hex>` profile string in the
+    // application protocol). On-wire mismatch is caught by the content
+    // checksum that the encoder enables — wrong dict bytes will produce
+    // a checksum failure here.
+
+    let upper = match zstd_safe::get_frame_content_size(&compressed) {
+        Ok(Some(n)) if n <= u64::from(u32::MAX) => n as usize,
+        _ => 1024 * 1024,
+    };
+    let mut out = vec![0u8; upper];
+
+    let mut dctx = rb_self.dctx.lock().expect("Dictionary DCtx mutex poisoned");
+    let n = dctx.decompress(&mut out, &compressed).map_err(|code| {
+        Error::new(
+            decompress_error(ruby),
+            format!("zstd dict frame decode failed: {code}"),
+        )
+    })?;
+    out.truncate(n);
+    Ok(ruby.str_from_slice(&out))
+}
+
+// ---------- dictionary training ----------
+//
+// Wraps `ZDICT_trainFromBuffer`. Caller passes a flat buffer of all
+// samples concatenated, plus a sizes array describing how to split
+// it back into per-sample slices. Returns the trained dictionary
+// bytes (truncated to actual dictionary size).
+//
+// `dict_capacity` is the upper bound on the produced dictionary size;
+// the C function may return less. ZDICT recommends ~100 KiB and at
+// least ~10 samples to converge — under-sized inputs raise an error.
+fn rzstd_train(
+    ruby: &Ruby,
+    rb_samples: RString,
+    rb_sample_sizes: magnus::RArray,
+    dict_capacity: usize,
+) -> Result<RString, Error> {
+    let samples: Vec<u8> = unsafe { rb_samples.as_slice().to_vec() };
+
+    let mut sizes: Vec<usize> = Vec::with_capacity(rb_sample_sizes.len());
+    for v in rb_sample_sizes.into_iter() {
+        let n: usize = magnus::TryConvert::try_convert(v)?;
+        sizes.push(n);
+    }
+
+    if sizes.iter().sum::<usize>() != samples.len() {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "sample sizes do not sum to samples buffer length",
+        ));
+    }
+
+    let mut dict_buf: Vec<u8> = vec![0u8; dict_capacity];
+    let written = zstd_safe::train_from_buffer(&mut dict_buf, &samples, &sizes).map_err(|code| {
+        Error::new(
+            ruby.exception_runtime_error(),
+            format!("zstd train_from_buffer failed: {code}"),
+        )
+    })?;
+    dict_buf.truncate(written);
+    Ok(ruby.str_from_slice(&dict_buf))
+}
+
+
+fn dict_size(rb_self: &Dictionary) -> usize {
+    rb_self.bytes.len()
+}
+
+fn dict_id(rb_self: &Dictionary) -> u32 {
+    rb_self.id
+}
+
+// ---------- module init ----------
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    // Mark this extension as Ractor-safe. Globals are OnceLock<Mutex<...>>;
+    // Dictionary state is Mutex-protected and Send+Sync; the leaked dict
+    // bytes are 'static.
+    unsafe { rb_sys::rb_ext_ractor_safe(true) };
+
+    let module = ruby.define_module("RZstd")?;
+
+    let decompress_error_class =
+        module.define_error("DecompressError", ruby.exception_standard_error())?;
+    DECOMPRESS_ERROR
+        .set(Opaque::from(decompress_error_class))
+        .unwrap_or_else(|_| panic!("init called more than once"));
+
+    // Bound as `_native_compress(bytes, level)`. Ruby's `RZstd.compress`
+    // wraps this with a `level:` kwarg default — see `lib/rzstd.rb`.
+    module.define_module_function("_native_compress", function!(rzstd_compress, 2))?;
+    module.define_module_function("decompress", function!(rzstd_decompress, 1))?;
+
+    let dict_class = module.define_class("Dictionary", ruby.class_object())?;
+    // Bound as `_native_new(bytes, id, level)`. Ruby's `RZstd::Dictionary.new(bytes)`
+    // computes the id and forwards — see `lib/rzstd.rb`.
+    dict_class.define_singleton_method("_native_new", function!(dict_initialize, 3))?;
+    dict_class.define_singleton_method("_native_train", function!(rzstd_train, 3))?;
+    dict_class.define_method("compress", method!(dict_compress, 1))?;
+    dict_class.define_method("decompress", method!(dict_decompress, 1))?;
+    dict_class.define_method("size", method!(dict_size, 0))?;
+    dict_class.define_method("id", method!(dict_id, 0))?;
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn frame_round_trip() {
+        let data = b"the quick brown fox jumps over the lazy dog ".repeat(100);
+        let upper = zstd_safe::compress_bound(data.len());
+        let mut out = vec![0u8; upper];
+        let mut cctx = CCtx::create();
+        cctx.set_parameter(CParameter::CompressionLevel(3)).unwrap();
+        let n = cctx.compress2(&mut out, &data).unwrap();
+        out.truncate(n);
+        assert!(out.len() < data.len());
+        assert_eq!(&out[..4], &ZSTD_FRAME_MAGIC);
+
+        let mut pt = vec![0u8; data.len()];
+        let mut dctx = DCtx::create();
+        let m = dctx.decompress(&mut pt, &out).unwrap();
+        pt.truncate(m);
+        assert_eq!(pt, data);
+    }
+
+    #[test]
+    fn dict_round_trip() {
+        let dict = b"JSON schema version 1 field ".repeat(8);
+        let bytes: &'static [u8] = Box::leak(dict.into_boxed_slice());
+        let msg = b"JSON schema version 1 field name=hello value=world".to_vec();
+
+        let mut cctx = CCtx::create();
+        cctx.set_parameter(CParameter::CompressionLevel(3)).unwrap();
+        cctx.load_dictionary(bytes).unwrap();
+        let mut ct = vec![0u8; zstd_safe::compress_bound(msg.len())];
+        let n = cctx.compress2(&mut ct, &msg).unwrap();
+        ct.truncate(n);
+        assert_eq!(&ct[..4], &ZSTD_FRAME_MAGIC);
+
+        // Raw-content dicts always carry frame dict id 0; that's expected.
+
+        let mut dctx = DCtx::create();
+        dctx.load_dictionary(bytes).unwrap();
+        let mut pt = vec![0u8; msg.len()];
+        let m = dctx.decompress(&mut pt, &ct).unwrap();
+        pt.truncate(m);
+        assert_eq!(pt, msg);
+    }
+}

data/lib/rzstd/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RZstd
+  VERSION = "0.1.0"
+end

data/lib/rzstd.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "rzstd/rzstd"
+require_relative "rzstd/version"
+
+module RZstd
+  DEFAULT_LEVEL = 3
+
+  # Wrap the native `_native_compress(bytes, level)` so callers get a
+  # `level:` kwarg with a sensible default. Defined as a real method
+  # (not a Proc-bound singleton method) so it remains Ractor-shareable.
+  def self.compress(bytes, level: DEFAULT_LEVEL)
+    _native_compress(bytes, Integer(level))
+  end
+
+  class Dictionary
+    # Public constructor. Derives the Zstd `Dict_ID` from the dictionary
+    # bytes (sha256 truncated to the first 4 bytes, little-endian) and
+    # forwards to the Rust extension. The id is for out-of-band peer
+    # negotiation (e.g. via the `dict:sha256:<hex>` profile string in
+    # the application protocol) — raw-content zstd dictionaries always
+    # write a frame `dictID` of 0, so the on-wire frame doesn't carry
+    # this id. Wrong-dict decoding is caught by the content checksum
+    # the encoder enables.
+    def self.new(bytes, level: DEFAULT_LEVEL)
+      id = Digest::SHA256.digest(bytes).byteslice(0, 4).unpack1("V")
+      _native_new(bytes, id, Integer(level))
+    end
+
+
+    # Trains a raw-content dictionary from a corpus of sample frames.
+    # Wraps `ZDICT_trainFromBuffer`. Returns the trained dictionary as
+    # a binary String, ready to feed back into `Dictionary.new`.
+    #
+    # ZDICT recommends roughly 100 KiB total samples and at least 10
+    # samples; under-provisioned inputs raise.
+    #
+    # @param samples [Array<String>] sample frames (any encoding)
+    # @param capacity [Integer] upper bound on the produced dict size
+    # @return [String] trained dictionary bytes (binary)
+    def self.train(samples, capacity: 64 * 1024)
+      sizes = samples.map { |s| s.bytesize }
+      buffer = String.new(capacity: sizes.sum, encoding: Encoding::BINARY)
+      samples.each { |s| buffer << s.b }
+      _native_train(buffer, sizes, Integer(capacity))
+    end
+  end
+end

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

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

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

@@ -0,0 +1,24 @@
+[package]
+name    = "rzstd"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+name       = "rzstd"
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+# Backend: gyscos/zstd-rs (libzstd via zstd-sys). Chosen because it exposes
+# persistent ZSTD_CCtx / ZSTD_DCtx contexts via `zstd-safe`, which is the
+# whole reason this gem exists — we need to reuse encoder/decoder state
+# across calls to compete fairly with rlz4 on small messages.
+#
+# The pure-Rust killingspark/zstd-rs option is the eventual goal; tracked
+# as a follow-up once it grows a persistent-context API.
+zstd-safe = { version = "7", default-features = false, features = ["std", "zdict_builder"] }
+magnus    = "0.8"
+rb-sys    = "0.9"
+sha2      = { version = "0.10", default-features = false }
+
+[build-dependencies]
+rb-sys = "0.9"

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: rzstd
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Patrik Wenger
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: |
+  Ruby bindings (via Rust/magnus) for the Zstandard compressor with
+  persistent ZSTD_CCtx / ZSTD_DCtx contexts that are reused across
+  calls. Provides Zstd frame compress/decompress at module level and
+  a stateful Dictionary class for dict-bound compression. Designed to
+  be safe to call from multiple Ractors and competitive with rlz4 on
+  small messages, where per-call context allocation in zstd-ruby
+  dominates the cost.
+email:
+- paddor@protonmail.ch
+executables: []
+extensions:
+- ext/rzstd/extconf.rb
+extra_rdoc_files: []
+files:
+- Cargo.lock
+- Cargo.toml
+- LICENSE
+- README.md
+- ext/rzstd/Cargo.toml
+- ext/rzstd/extconf.rb
+- ext/rzstd/src/lib.rs
+- lib/rzstd.rb
+- lib/rzstd/version.rb
+- tmp/x86_64-linux/stage/Cargo.toml
+- tmp/x86_64-linux/stage/ext/rzstd/Cargo.toml
+homepage: https://github.com/paddor/rzstd
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/paddor/rzstd
+  source_code_uri: https://github.com/paddor/rzstd
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ractor-safe Zstandard bindings for Ruby with persistent contexts
+test_files: []