omq-rs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: deaed5d4439c9c15105ab96ca99b1589052d80bdf0730d07aff19f7b146cdc47
+  data.tar.gz: 116dc7537c497dc57a59a5348966dc6c5f82bf3dea038ddc488eef7aa6efb470
+SHA512:
+  metadata.gz: c82ec7acb65d986cdc8f0d6289ac8fd952b256cbe8b02276d0b1a84e4ff06fbb9f00dafa2373091bdcd17daeaffc53c4fff6a69d713a68d4b9aa9446e0c5bbbe
+  data.tar.gz: e8b55702563c7849a521545c387ef91fbf632b329efad536105af4306d67f6fae31d914f3755c7be71639cd864241843d358417570c0451f5003a441f4b35f56

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+
+- Add standalone `omq-rs` Ruby binding with all 20 OMQ socket types.
+- Add PLAIN and CURVE sockets, Z85 key generation, CURVE client authentication,
+  and pyzmq CURVE interoperability.
+- Add LZ4/zstd transports and compression options.
+- Add socket lifecycle monitoring with Fiber-aware waits.
+- Add receive wake and monitor-fd hooks for backend adapters.
+- Support Ractor-owned sockets and cross-Ractor inproc/TCP messaging on Ruby 4.
+- Support synchronous sockets on TruffleRuby and test them in CI.

data/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Patrik Wenger
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,161 @@
+# omq-rs
+
+Fast Ruby binding for [OMQ.rs](https://github.com/paddor/omq.rs). No libzmq,
+FFI, or broker. Networking runs on OMQ-owned Tokio threads. The Ruby API is
+synchronous; its waits cooperate with an installed `Fiber.scheduler`.
+
+MRI 3.3+, MRI 4.0+, and TruffleRuby are supported. TruffleRuby 34 does not
+provide Ruby's `Fiber.scheduler` API, so waits block the calling thread there.
+
+## Install
+
+```sh
+gem install omq-rs
+```
+
+Source installs require Rust 1.93 or newer.
+
+## Usage
+
+```ruby
+require "omq/rs"
+
+pull = OMQ.rs(:pull)
+push = OMQ.rs(:push)
+
+endpoint = pull.bind("tcp://127.0.0.1:0")
+push.connect(endpoint).wait_for_peer(timeout: 2)
+
+push << "hello"
+p pull.recv # => ["hello"]
+
+push.close
+pull.close
+```
+
+Socket classes are also available directly:
+
+```ruby
+push = OMQ::Rust::PUSH.new
+pull = OMQ.rs::PULL.new
+```
+
+`#send` accepts one frame, multiple arguments, or an Array. `#recv` always
+returns an Array of frozen binary Strings. SERVER messages prepend a numeric
+routing ID: `[routing_id, body]`. ROUTER, STREAM, and PEER use their normal
+identity frame. RADIO/DISH messages use `[group, body]`.
+
+`SERVER#peer_info(routing_id)` returns connection metadata for a live route,
+including `:peer_address` and `:peer_identity`, or `nil` for a stale route.
+
+All 20 socket types are available: REQ, REP, PUB, SUB, XPUB, XSUB, PUSH,
+PULL, DEALER, ROUTER, PAIR, STREAM, CLIENT, SERVER, RADIO, DISH, SCATTER,
+GATHER, CHANNEL, and PEER.
+
+Published gems include PLAIN, CURVE, LZ4, zstd, and WebSocket support. Check
+features with `OMQ::Rust.has(:curve)`.
+
+## CURVE
+
+Keys use the standard 40-byte Z85 representation.
+
+```ruby
+server_public, server_secret = OMQ::Rust.curve_keypair
+client_public, client_secret = OMQ::Rust.curve_keypair
+
+pull = OMQ.rs(
+  :pull,
+  curve_server: true,
+  curve_publickey: server_public,
+  curve_secretkey: server_secret,
+)
+pull.set_curve_auth([client_public])
+
+push = OMQ.rs(
+  :push,
+  curve_serverkey: server_public,
+  curve_publickey: client_public,
+  curve_secretkey: client_secret,
+)
+```
+
+`#set_curve_auth` accepts an Array of allowed public keys, a callable receiving
+an `OMQ::Rust::MechanismPeerInfo`, or `nil` to accept every valid CURVE client.
+Configure it before the first bind, connect, send, receive, or monitor call.
+`OMQ::Rust.curve_public(secret_key)` derives a public key.
+
+PLAIN uses `plain_server: true` on the server and `plain_username` plus
+`plain_password` on clients. PLAIN authenticates without encryption; use it
+only on trusted transports.
+
+## Compression
+
+Use `lz4+tcp://` or `zstd+tcp://` endpoints on both peers. zstd senders accept
+`compression_level`, `compression_dict`, and `compression_auto_train` socket
+options.
+
+## Monitoring
+
+`socket.monitor` returns an Enumerable monitor. `#recv(timeout:)` blocks for
+the next event; `#recv_nowait` returns an event Hash or `nil`. Event hashes
+contain `:event` and event-specific fields such as `:endpoint`,
+`:connection_id`, and `:peer_identity`.
+
+## Fiber Schedulers
+
+There is no separate async API and omq-rs does not install a scheduler.
+`#send`, `#recv`, and connection waits use Ruby IO readiness. When the caller
+installs a `Fiber.scheduler`, such as Async, waits suspend only the current
+fiber.
+
+TruffleRuby currently has no `Fiber.scheduler` API. Use threads when concurrent
+blocking waits are needed there.
+
+```ruby
+require "async"
+require "omq/rs"
+
+Async do
+  OMQ.rs(:pull) do |pull|
+    pull.bind("tcp://127.0.0.1:5555")
+    p pull.recv
+  end
+end
+```
+
+## Ractors
+
+Ruby 4 Ractors can create and use omq-rs sockets. Each socket must remain owned
+by the Ractor that created it. Ractors can communicate through inproc, IPC, or
+TCP endpoints; no preparation call is required.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+```
+
+## Performance
+
+![Ruby binding benchmark](doc/charts/bindings.svg)
+
+The binding benchmark uses separate Ruby processes over TCP and compares
+`omq-rs` with [cztop](https://github.com/paddor/cztop), which calls CZMQ and
+libzmq through FFI, and [ffi-rzmq](https://github.com/chuckremes/ffi-rzmq),
+which calls libzmq directly through FFI. Install CZMQ and libzmq to include
+both baselines.
+
+```sh
+ruby -Ilib scripts/update_perf.rb
+ruby -Ilib scripts/update_perf.rb --quick
+ruby -Ilib scripts/update_perf.rb --chart-only
+```
+
+Rows append to `~/.cache/omq-rs/bindings.jsonl`. The generated chart is
+`doc/charts/bindings.svg`. `--quick` only runs a smoke benchmark and does not
+write results or a chart.
+
+## License
+
+[ISC](LICENSE)

data/ext/omq_rs_native/Cargo.toml

@@ -0,0 +1,50 @@
+[package]
+name = "omq_rs_native"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.93"
+license = "ISC"
+authors = ["Patrik Wenger <paddor@gmail.com>"]
+publish = false
+
+[lib]
+name = "omq_rs_native"
+crate-type = ["cdylib"]
+
+[features]
+default = ["plain", "curve", "lz4", "zstd", "ws"]
+plain = ["omq-tokio/plain"]
+curve = ["omq-tokio/curve"]
+lz4 = ["omq-tokio/lz4"]
+zstd = ["omq-tokio/zstd"]
+ws = ["omq-tokio/ws"]
+
+[dependencies]
+omq-proto = { version = ">=0.26.0, <0.28.0", default-features = false }
+omq-tokio = { version = ">=0.21.3, <0.23.0", default-features = false }
+yring = { version = "=0.3.14", features = ["async"] }
+
+bytes = "1.12.0"
+flume = { version = "0.12", default-features = false, features = ["async"] }
+futures = { version = "0.3", default-features = false, features = ["std", "async-await"] }
+libc = "0.2"
+rb-sys = "0.9"
+tokio = { version = "1.52.0", features = ["rt", "rt-multi-thread", "time", "sync", "io-util", "net"] }
+
+[build-dependencies]
+rb-sys = "0.9"
+
+[lints.rust]
+missing_debug_implementations = "deny"
+unsafe_op_in_unsafe_fn = "deny"
+rust_2018_idioms = { level = "warn", priority = -1 }
+
+[lints.clippy]
+all = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+module_name_repetitions = "allow"
+missing_errors_doc = "allow"
+missing_panics_doc = "allow"
+must_use_candidate = "allow"
+cast_possible_truncation = "allow"
+cast_sign_loss = "allow"

data/ext/omq_rs_native/build.rs

@@ -0,0 +1,24 @@
+use std::process::Command;
+
+fn main() {
+    println!("cargo:rerun-if-env-changed=RUBY");
+    println!("cargo:rustc-check-cfg=cfg(ruby_engine, values(\"mri\", \"truffleruby\"))");
+
+    let ruby = std::env::var("RUBY").unwrap_or_else(|_| "ruby".to_string());
+    let output = Command::new(&ruby)
+        .arg("-rrbconfig")
+        .arg("-e")
+        .arg("print RbConfig::CONFIG.fetch('ruby_install_name')")
+        .output()
+        .unwrap_or_else(|err| panic!("failed to run {ruby}: {err}"));
+
+    assert!(
+        output.status.success(),
+        "failed to query Ruby engine with {ruby}"
+    );
+
+    match String::from_utf8_lossy(&output.stdout).trim() {
+        "truffleruby" => println!("cargo:rustc-cfg=ruby_engine=\"truffleruby\""),
+        _ => println!("cargo:rustc-cfg=ruby_engine=\"mri\""),
+    }
+}

data/ext/omq_rs_native/extconf.rb

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

data/ext/omq_rs_native/src/auth.rs

@@ -0,0 +1,182 @@
+use std::ffi::c_void;
+use std::panic::{AssertUnwindSafe, catch_unwind};
+use std::sync::Arc;
+
+use bytes::Bytes;
+use rb_sys::VALUE;
+
+use crate::notify::PipeNotify;
+use crate::options::parse_curve_public_key;
+use crate::rb::{self, RbResult};
+
+enum AuthRequest {
+    Check {
+        public_key: [u8; 32],
+        identity: Option<Bytes>,
+        reply: flume::Sender<bool>,
+    },
+    Stop,
+}
+
+pub struct AuthWorker {
+    sender: flume::Sender<AuthRequest>,
+    notify: Arc<PipeNotify>,
+    callback: VALUE,
+    thread: VALUE,
+}
+
+impl AuthWorker {
+    pub fn stop(self) {
+        let _ = self.sender.send(AuthRequest::Stop);
+        self.notify.notify();
+        let _ = rb::call_method_0(self.thread, c"join");
+    }
+
+    pub fn request_stop(self) {
+        let _ = self.sender.send(AuthRequest::Stop);
+        self.notify.notify();
+    }
+
+    pub fn callback(&self) -> VALUE {
+        self.callback
+    }
+
+    pub fn thread(&self) -> VALUE {
+        self.thread
+    }
+}
+
+struct WorkerData {
+    callback: VALUE,
+    receiver: flume::Receiver<AuthRequest>,
+    notify: Arc<PipeNotify>,
+}
+
+fn wait_for_request(data: &WorkerData) -> Option<AuthRequest> {
+    loop {
+        match data.receiver.try_recv() {
+            Ok(request) => return Some(request),
+            Err(flume::TryRecvError::Disconnected) => return None,
+            Err(flume::TryRecvError::Empty) => {}
+        }
+
+        data.notify.park_begin();
+        match data.receiver.try_recv() {
+            Ok(request) => {
+                data.notify.cancel_park();
+                return Some(request);
+            }
+            Err(flume::TryRecvError::Disconnected) => {
+                data.notify.cancel_park();
+                return None;
+            }
+            Err(flume::TryRecvError::Empty) => unsafe {
+                rb_sys::rb_thread_wait_fd(data.notify.read_fd());
+            },
+        }
+        data.notify.clear();
+    }
+}
+
+unsafe extern "C" fn auth_worker_main(data: *mut c_void) -> VALUE {
+    let data = unsafe { Box::from_raw(data.cast::<WorkerData>()) };
+    let _ = catch_unwind(AssertUnwindSafe(|| {
+        while let Some(AuthRequest::Check {
+            public_key,
+            identity,
+            reply,
+        }) = wait_for_request(&data)
+        {
+            let accepted = invoke_callback(data.callback, public_key, identity.as_ref());
+            let _ = reply.send(accepted);
+        }
+    }));
+    rb::qnil()
+}
+
+fn invoke_callback(callback: VALUE, public_key: [u8; 32], identity: Option<&Bytes>) -> bool {
+    let result = (|| -> RbResult<VALUE> {
+        let peer = rb::hash_new()?;
+        let key = omq_proto::CurvePublicKey::from_bytes(public_key)
+            .to_z85()
+            .into_bytes();
+        rb::hash_aset(
+            peer,
+            rb::symbol("public_key")?,
+            rb::new_binary_string(&key)?,
+        )?;
+        let identity = match identity {
+            Some(value) => rb::new_binary_string(value)?,
+            None => rb::qnil(),
+        };
+        rb::hash_aset(peer, rb::symbol("identity")?, identity)?;
+        rb::call_method_1(callback, c"call", peer)
+    })();
+
+    if let Ok(value) = result {
+        value != rb::qfalse() && value != rb::qnil()
+    } else {
+        unsafe { rb_sys::rb_set_errinfo(rb::qnil()) };
+        false
+    }
+}
+
+pub fn allowed_keys(value: VALUE) -> RbResult<omq_proto::Authenticator> {
+    let count = rb::array_len(value)?;
+    let mut keys = std::collections::HashSet::with_capacity(count);
+    for index in 0..count {
+        let value = rb::array_entry(value, index)?;
+        let bytes = rb::value_to_bytes(value)?;
+        let key = parse_curve_public_key(&bytes, "CURVE allowlist key")?;
+        keys.insert(*key.as_bytes());
+    }
+    Ok(omq_proto::Authenticator::new(move |peer| {
+        keys.contains(&peer.public_key)
+    }))
+}
+
+pub fn callback(callback: VALUE) -> RbResult<(omq_proto::Authenticator, AuthWorker)> {
+    let (sender, receiver) = flume::unbounded();
+    let notify = Arc::new(PipeNotify::new());
+    let data = Box::new(WorkerData {
+        callback,
+        receiver,
+        notify: Arc::clone(&notify),
+    });
+    let raw = Box::into_raw(data);
+    let thread = rb::protect_value(|| unsafe {
+        rb_sys::rb_thread_create(Some(auth_worker_main), raw.cast::<c_void>())
+    });
+    let thread = match thread {
+        Ok(thread) => thread,
+        Err(error) => {
+            unsafe { drop(Box::from_raw(raw)) };
+            return Err(error);
+        }
+    };
+
+    let auth_sender = sender.clone();
+    let auth_notify = Arc::clone(&notify);
+    let authenticator = omq_proto::Authenticator::new(move |peer| {
+        let (reply, result) = flume::bounded(1);
+        let request = AuthRequest::Check {
+            public_key: peer.public_key,
+            identity: peer.identity.clone(),
+            reply,
+        };
+        if auth_sender.send(request).is_err() {
+            return false;
+        }
+        auth_notify.notify();
+        result.recv().unwrap_or(false)
+    });
+    Ok((
+        authenticator,
+        AuthWorker {
+            sender,
+            notify,
+            callback,
+            thread,
+        },
+    ))
+}

data/ext/omq_rs_native/src/error.rs

@@ -0,0 +1,15 @@
+use omq_proto::error::Error as OmqError;
+
+use crate::rb::RubyErr;
+
+pub fn map_err(e: OmqError) -> RubyErr {
+    match e {
+        OmqError::Closed => RubyErr::io("socket closed"),
+        OmqError::Timeout => RubyErr::runtime("operation timed out"),
+        OmqError::Unroutable => RubyErr::runtime("no route to peer"),
+        OmqError::InvalidEndpoint(msg) => RubyErr::arg(msg),
+        OmqError::Protocol(msg) | OmqError::HandshakeFailed(msg) => RubyErr::runtime(msg),
+        OmqError::Io(e) => RubyErr::runtime(e.to_string()),
+        _ => RubyErr::runtime(format!("{e}")),
+    }
+}

data/ext/omq_rs_native/src/lib.rs

@@ -0,0 +1,126 @@
+#[cfg(feature = "curve")]
+mod auth;
+mod error;
+mod notify;
+mod options;
+mod rb;
+mod runtime;
+mod socket;
+
+use rb_sys::VALUE;
+
+use crate::rb::{RbResult, RubyErr};
+
+fn has_impl(name: VALUE) -> RbResult<VALUE> {
+    let name = rb::value_to_string(name)?;
+    let available = match name.as_str() {
+        "ipc" | "inproc" => true,
+        #[cfg(feature = "curve")]
+        "curve" => true,
+        #[cfg(feature = "plain")]
+        "plain" => true,
+        #[cfg(feature = "lz4")]
+        "lz4" => true,
+        #[cfg(feature = "zstd")]
+        "zstd" => true,
+        #[cfg(feature = "ws")]
+        "ws" => true,
+        _ => false,
+    };
+    Ok(rb::bool_value(available))
+}
+
+unsafe extern "C" fn has(_module: VALUE, name: VALUE) -> VALUE {
+    rb::wrap(|| has_impl(name))
+}
+
+#[cfg(feature = "curve")]
+fn curve_keypair_impl() -> RbResult<VALUE> {
+    let keypair = omq_proto::CurveKeypair::generate();
+    let pair = rb::array_new_capa(2)?;
+    rb::array_push(
+        pair,
+        rb::new_binary_string(keypair.public.to_z85().as_bytes())?,
+    )?;
+    rb::array_push(
+        pair,
+        rb::new_binary_string(keypair.secret.to_z85().as_bytes())?,
+    )?;
+    Ok(pair)
+}
+
+#[cfg(feature = "curve")]
+unsafe extern "C" fn curve_keypair(_module: VALUE) -> VALUE {
+    rb::wrap(curve_keypair_impl)
+}
+
+#[cfg(feature = "curve")]
+fn curve_public_impl(secret: VALUE) -> RbResult<VALUE> {
+    let secret = rb::value_to_string(secret)?;
+    let secret = omq_proto::CurveSecretKey::from_z85(&secret)
+        .map_err(|error| RubyErr::arg(error.to_string()))?;
+    rb::new_binary_string(secret.derive_public().to_z85().as_bytes())
+}
+
+#[cfg(feature = "curve")]
+unsafe extern "C" fn curve_public(_module: VALUE, secret: VALUE) -> VALUE {
+    rb::wrap(|| curve_public_impl(secret))
+}
+
+fn set_io_threads_impl(n: VALUE) -> RbResult<VALUE> {
+    let n = rb::value_to_i64(n)?;
+    if n < 0 {
+        return Err(RubyErr::arg("io_threads must be non-negative"));
+    }
+    let n = usize::try_from(n).map_err(|_| RubyErr::arg("io_threads too large"))?;
+    socket::set_io_threads(n);
+    Ok(rb::qnil())
+}
+
+fn io_threads_impl() -> RbResult<VALUE> {
+    let n = u64::try_from(socket::io_threads())
+        .map_err(|_| RubyErr::runtime("io_threads too large"))?;
+    Ok(rb::u64_value(n))
+}
+
+unsafe extern "C" fn io_threads(_module: VALUE) -> VALUE {
+    rb::wrap(io_threads_impl)
+}
+
+unsafe extern "C" fn set_io_threads(_module: VALUE, n: VALUE) -> VALUE {
+    rb::wrap(|| set_io_threads_impl(n))
+}
+
+#[unsafe(no_mangle)]
+/// # Safety
+///
+/// Ruby calls this once while loading the native extension.
+pub unsafe extern "C" fn Init_omq_rs_native() {
+    rb::wrap_init(init);
+}
+
+fn init() -> RbResult<()> {
+    #[cfg(ruby_engine = "mri")]
+    unsafe {
+        rb_sys::rb_ext_ractor_safe(true);
+    }
+
+    let omq = unsafe { rb::define_module(c"OMQ")? };
+    let rust = unsafe { rb::define_module_under(omq, c"Rust")? };
+    let native = unsafe { rb::define_module_under(rust, c"Native")? };
+
+    unsafe {
+        rb::define_module_function_0(native, c"io_threads", io_threads)?;
+        rb::define_module_function_1(native, c"io_threads=", set_io_threads)?;
+        rb::define_module_function_1(native, c"has", has)?;
+        #[cfg(feature = "curve")]
+        {
+            rb::define_module_function_0(native, c"curve_keypair", curve_keypair)?;
+            rb::define_module_function_1(native, c"curve_public", curve_public)?;
+        }
+    }
+
+    socket::register(native)?;
+
+    Ok(())
+}