omq-backend-rust 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d3204e074915dc804b56b3b5b713cbd08c11b84dec67732f3f0f7d12e02b5b87
+  data.tar.gz: c46c4dbebce74f3b164c3d8d4c5eb10a92ab4cc730c25198ef66edee7e50330b
+SHA512:
+  metadata.gz: 47c78d4a47f5f3494a90325065ac4e7adf8361d30b37ea0d8ff46cb7b96d47709d8021e5448fd3fef8fa85c0e4f1516e8ce6c7fa5465d435ae5c669499c0427e
+  data.tar.gz: 66a1f72298ea9e30cec1c729a76f77cd6551abdff58edfbd31cdc826d54bf66764dd01889d59da9cd098b1cef01367d50c6eac94aca0c39559689ff0621c7b6b

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [Unreleased]
+
+## 0.1.1 - 2026-07-23
+
+### Changed
+
+- Updated to `omq-tokio` 0.19.3 and `omq-proto` 0.23.2.
+- Removed obsolete Blake3ZMQ support.
+- Moved release source to the `zeromq/omq.rb` monorepo.
+
+## v0.1.0 — 2026-06-24
+
+Initial release.
+
+### Added
+
+- **`OMQ::Rust::Engine`** — drop-in OMQ engine backed by omq-tokio. Pass
+  `backend: :rust` to any OMQ socket constructor.
+- All standard socket types: REQ/REP, PUB/SUB, PUSH/PULL, DEALER/ROUTER,
+  XPUB/XSUB, PAIR.
+- All draft socket types: CLIENT/SERVER, RADIO/DISH, SCATTER/GATHER, CHANNEL.
+- TCP and IPC transports.
+- CURVE (CurveZMQ) and BLAKE3ZMQ security mechanisms.
+- Full cross-backend interop with the default Ruby engine.
+- Lifecycle promises: `peer_connected`, `all_peers_gone`, `subscriber_joined`.
+- Monitor event forwarding from the Tokio runtime.
+- Configurable IO thread count via `OMQ::Rust.io_threads`.

data/Cargo.toml

@@ -0,0 +1,3 @@
+[workspace]
+members = ["ext/omq_backend_rust"]
+resolver = "3"

data/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-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,70 @@
+# omq-backend-rust
+
+[![CI](https://github.com/zeromq/omq.rb/actions/workflows/ci.yml/badge.svg)](https://github.com/zeromq/omq.rb/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/omq-backend-rust?color=e9573f)](https://rubygems.org/gems/omq-backend-rust)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.3-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
+
+Rust-backed engine for [OMQ](https://github.com/zeromq/omq.rb). Same socket API,
+but networking runs on a [Tokio](https://tokio.rs/) runtime inside a native
+extension compiled via [rb_sys](https://github.com/oxidize-rb/rb-sys).
+
+## Install
+
+Requires a Rust toolchain (stable) at gem install time.
+
+```ruby
+# Gemfile
+gem "omq-backend-rust"
+```
+
+```sh
+gem install omq-backend-rust
+```
+
+## Usage
+
+```ruby
+require "omq"
+require "omq/rust"
+
+Async do
+  push = OMQ::PUSH.new(backend: :rust)
+  pull = OMQ::PULL.new(backend: :rust)
+
+  port = pull.bind("tcp://127.0.0.1:0").port
+  push.connect("tcp://127.0.0.1:#{port}")
+  push.peer_connected.wait
+
+  push << "hello from Rust"
+  p pull.receive  # => ["hello from Rust"]
+ensure
+  push&.close
+  pull&.close
+end
+```
+
+The `:rust` backend is fully interoperable with the default `:ruby` backend.
+Mix backends freely within the same process.
+
+## Supported socket types
+
+All standard and draft ZMTP socket types: REQ/REP, PUB/SUB, PUSH/PULL,
+DEALER/ROUTER, XPUB/XSUB, PAIR, CLIENT/SERVER, RADIO/DISH,
+SCATTER/GATHER, CHANNEL.
+
+## Security mechanisms
+
+- **NULL** (default)
+- **CURVE** (CurveZMQ, via [Nuckle](https://github.com/paddor/nuckle))
+
+## Development
+
+```sh
+OMQ_DEV=1 bundle install
+OMQ_DEV=1 bundle exec rake
+```
+
+## License
+
+[ISC](LICENSE)

data/ext/omq_backend_rust/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name    = "omq_backend_rust"
+version = "0.1.0"
+edition = "2024"
+license = "ISC"
+authors = ["Patrik Wenger <paddor@gmail.com>"]
+publish = false
+
+[lib]
+name       = "omq_backend_rust"
+crate-type = ["cdylib"]
+
+[features]
+default = ["plain", "curve", "lz4"]
+plain   = ["omq-tokio/plain"]
+curve   = ["omq-tokio/curve"]
+lz4     = ["omq-tokio/lz4"]
+
+[dependencies]
+omq-proto = { version = "=0.23.2", default-features = false }
+omq-tokio = { version = "=0.19.3", default-features = false }
+tokio     = { version = "1.52.0", features = ["rt", "rt-multi-thread", "time", "sync", "io-util", "net"] }
+yring     = { version = "0.3.8", 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"] }
+magnus  = "0.8"
+rb-sys  = "0.9"
+libc    = "0.2"
+
+[build-dependencies]
+rb-sys = "0.9"

data/ext/omq_backend_rust/extconf.rb

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

data/ext/omq_backend_rust/src/error.rs

@@ -0,0 +1,15 @@
+use magnus::{Error, Ruby};
+use omq_proto::error::Error as OmqError;
+
+pub fn map_err(ruby: &Ruby, e: OmqError) -> Error {
+    match e {
+        OmqError::Closed => Error::new(ruby.exception_io_error(), "socket closed"),
+        OmqError::Timeout => Error::new(ruby.exception_runtime_error(), "operation timed out"),
+        OmqError::Unroutable => Error::new(ruby.exception_runtime_error(), "no route to peer"),
+        OmqError::InvalidEndpoint(msg) => Error::new(ruby.exception_arg_error(), msg),
+        OmqError::Protocol(msg) => Error::new(ruby.exception_runtime_error(), msg),
+        OmqError::Io(e) => Error::new(ruby.exception_runtime_error(), e.to_string()),
+        OmqError::HandshakeFailed(msg) => Error::new(ruby.exception_runtime_error(), msg),
+        _ => Error::new(ruby.exception_runtime_error(), format!("{e}")),
+    }
+}

data/ext/omq_backend_rust/src/lib.rs

@@ -0,0 +1,24 @@
+mod error;
+mod notify;
+mod options;
+mod runtime;
+mod socket;
+
+use magnus::{Error, Ruby, function, prelude::*};
+
+fn set_io_threads(n: usize) {
+    socket::set_io_threads(n);
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let omq = ruby.define_module("OMQ")?;
+    let rust = omq.define_module("Rust")?;
+    let native = rust.define_module("Native")?;
+
+    native.define_module_function("io_threads=", function!(set_io_threads, 1))?;
+
+    socket::register(ruby)?;
+
+    Ok(())
+}

data/ext/omq_backend_rust/src/notify.rs

@@ -0,0 +1,69 @@
+use std::os::fd::RawFd;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+pub struct PipeNotify {
+    read_fd: RawFd,
+    write_fd: RawFd,
+    parking: AtomicBool,
+}
+
+unsafe impl Send for PipeNotify {}
+unsafe impl Sync for PipeNotify {}
+
+impl PipeNotify {
+    pub fn new() -> Self {
+        let mut fds = [0i32; 2];
+        let ret = unsafe { libc::pipe2(fds.as_mut_ptr(), libc::O_NONBLOCK | libc::O_CLOEXEC) };
+        assert!(
+            ret == 0,
+            "pipe2 failed: {}",
+            std::io::Error::last_os_error()
+        );
+        Self {
+            read_fd: fds[0],
+            write_fd: fds[1],
+            parking: AtomicBool::new(false),
+        }
+    }
+
+    pub fn notify(&self) {
+        if self.parking.load(Ordering::Acquire) {
+            self.write_byte();
+        }
+    }
+
+    pub fn force_wake(&self) {
+        self.write_byte();
+    }
+
+    pub fn read_fd(&self) -> RawFd {
+        self.read_fd
+    }
+
+    pub fn park_begin(&self) {
+        self.parking.store(true, Ordering::Release);
+    }
+
+    fn write_byte(&self) {
+        let val: u8 = 1;
+        loop {
+            let ret =
+                unsafe { libc::write(self.write_fd, &val as *const u8 as *const libc::c_void, 1) };
+            if ret >= 0 {
+                break;
+            }
+            if std::io::Error::last_os_error().raw_os_error() != Some(libc::EINTR) {
+                break;
+            }
+        }
+    }
+}
+
+impl Drop for PipeNotify {
+    fn drop(&mut self) {
+        unsafe {
+            libc::close(self.read_fd);
+            libc::close(self.write_fd);
+        }
+    }
+}

data/ext/omq_backend_rust/src/options.rs

@@ -0,0 +1,185 @@
+use std::time::Duration;
+
+use bytes::Bytes;
+use magnus::{Error, Ruby, TryConvert, r_hash::RHash, value::ReprValue};
+
+pub fn build_options(ruby: &Ruby, hash: RHash) -> Result<omq_tokio::Options, Error> {
+    let mut opts = omq_tokio::Options::default();
+
+    if let Some(v) = get_opt::<i64>(ruby, hash, "send_hwm")? {
+        opts.send_hwm = v.max(0) as u32;
+    }
+    if let Some(v) = get_opt::<i64>(ruby, hash, "recv_hwm")? {
+        opts.recv_hwm = v.max(0) as u32;
+    }
+    if let Some(v) = get_opt::<f64>(ruby, hash, "linger")? {
+        opts.linger = if v.is_infinite() {
+            None
+        } else {
+            Some(Duration::from_secs_f64(v))
+        };
+    }
+    if let Some(v) = get_opt::<Vec<u8>>(ruby, hash, "identity")? {
+        if !v.is_empty() {
+            opts.identity = Bytes::from(v);
+        }
+    }
+    if let Some(v) = get_opt::<bool>(ruby, hash, "router_mandatory")? {
+        opts.router_mandatory = v;
+    }
+    if let Some(v) = get_opt::<bool>(ruby, hash, "conflate")? {
+        opts.conflate = v;
+    }
+    if let Some(v) = get_opt_duration(ruby, hash, "heartbeat_interval")? {
+        opts.heartbeat_interval = Some(v);
+    }
+    if let Some(v) = get_opt_duration(ruby, hash, "heartbeat_ttl")? {
+        opts.heartbeat_ttl = Some(v);
+    }
+    if let Some(v) = get_opt_duration(ruby, hash, "heartbeat_timeout")? {
+        opts.heartbeat_timeout = Some(v);
+    }
+    if let Some(v) = get_opt::<i64>(ruby, hash, "max_message_size")? {
+        opts.max_message_size = Some(v as usize);
+    }
+    if let Some(v) = get_opt::<i64>(ruby, hash, "sndbuf")? {
+        opts.send_buffer_size = Some(v as usize);
+    }
+    if let Some(v) = get_opt::<i64>(ruby, hash, "rcvbuf")? {
+        opts.recv_buffer_size = Some(v as usize);
+    }
+    if let Some(v) = get_opt::<String>(ruby, hash, "on_mute")? {
+        opts.on_mute = match v.as_str() {
+            "drop_newest" | "drop" => omq_tokio::OnMute::DropNewest,
+            _ => omq_tokio::OnMute::Block,
+        };
+    }
+
+    if let Some(v) = get_opt::<f64>(ruby, hash, "reconnect_interval")? {
+        opts.reconnect = omq_proto::options::ReconnectPolicy::Fixed(Duration::from_secs_f64(v));
+    }
+    if let Some(min) = get_opt::<f64>(ruby, hash, "reconnect_interval_min")? {
+        let max = get_opt::<f64>(ruby, hash, "reconnect_interval_max")?.unwrap_or(min * 16.0);
+        opts.reconnect = omq_proto::options::ReconnectPolicy::Exponential {
+            min: Duration::from_secs_f64(min),
+            max: Duration::from_secs_f64(max),
+        };
+    }
+
+    if let Some(mech_type) = get_opt::<String>(ruby, hash, "mechanism_type")? {
+        apply_mechanism(ruby, hash, &mech_type, &mut opts)?;
+    }
+
+    Ok(opts)
+}
+
+fn apply_mechanism(
+    ruby: &Ruby,
+    hash: RHash,
+    mech_type: &str,
+    opts: &mut omq_tokio::Options,
+) -> Result<(), Error> {
+    match mech_type {
+        "null" => {}
+
+        #[cfg(feature = "curve")]
+        "curve" => {
+            let is_server = get_opt::<bool>(ruby, hash, "mechanism_server")?.unwrap_or(false);
+            let pub_key = get_opt_bytes(ruby, hash, "mechanism_public_key")?;
+            let sec_key = get_opt_bytes(ruby, hash, "mechanism_secret_key")?;
+
+            if is_server {
+                if let (Some(pk), Some(sk)) = (pub_key, sec_key) {
+                    let keypair = omq_proto::CurveKeypair {
+                        public: omq_proto::CurvePublicKey::from_bytes(to_32(
+                            ruby,
+                            &pk,
+                            "public key",
+                        )?),
+                        secret: omq_proto::CurveSecretKey::from_bytes(to_32(
+                            ruby,
+                            &sk,
+                            "secret key",
+                        )?),
+                    };
+                    opts.mechanism = omq_proto::MechanismSetup::CurveServer {
+                        our_keypair: keypair,
+                        cookie_keyring: std::sync::Arc::new(omq_proto::CurveCookieKeyring::new()),
+                        authenticator: None,
+                    };
+                }
+            } else {
+                let srv_key = get_opt_bytes(ruby, hash, "mechanism_server_key")?;
+                if let (Some(pk), Some(sk), Some(svk)) = (pub_key, sec_key, srv_key) {
+                    let keypair = omq_proto::CurveKeypair {
+                        public: omq_proto::CurvePublicKey::from_bytes(to_32(
+                            ruby,
+                            &pk,
+                            "public key",
+                        )?),
+                        secret: omq_proto::CurveSecretKey::from_bytes(to_32(
+                            ruby,
+                            &sk,
+                            "secret key",
+                        )?),
+                    };
+                    opts.mechanism = omq_proto::MechanismSetup::CurveClient {
+                        our_keypair: keypair,
+                        server_public: omq_proto::CurvePublicKey::from_bytes(to_32(
+                            ruby,
+                            &svk,
+                            "server key",
+                        )?),
+                    };
+                }
+            }
+        }
+
+        _ => {}
+    }
+    Ok(())
+}
+
+fn to_32(ruby: &Ruby, bytes: &[u8], label: &str) -> Result<[u8; 32], Error> {
+    bytes.try_into().map_err(|_| {
+        Error::new(
+            ruby.exception_arg_error(),
+            format!("{label} must be exactly 32 bytes, got {}", bytes.len()),
+        )
+    })
+}
+
+fn get_opt_bytes(ruby: &Ruby, hash: RHash, key: &str) -> Result<Option<Vec<u8>>, Error> {
+    let k = ruby.str_new(key);
+    match hash.get(k) {
+        Some(v) => {
+            if v.is_nil() {
+                return Ok(None);
+            }
+            let s = magnus::r_string::RString::try_convert(v)?;
+            Ok(Some(unsafe { s.as_slice() }.to_vec()))
+        }
+        None => Ok(None),
+    }
+}
+
+fn get_opt<T: TryConvert>(ruby: &Ruby, hash: RHash, key: &str) -> Result<Option<T>, Error> {
+    let k = ruby.str_new(key);
+    match hash.get(k) {
+        Some(v) => {
+            if v.is_nil() {
+                Ok(None)
+            } else {
+                Ok(Some(T::try_convert(v)?))
+            }
+        }
+        None => Ok(None),
+    }
+}
+
+fn get_opt_duration(ruby: &Ruby, hash: RHash, key: &str) -> Result<Option<Duration>, Error> {
+    match get_opt::<f64>(ruby, hash, key)? {
+        Some(v) => Ok(Some(Duration::from_secs_f64(v))),
+        None => Ok(None),
+    }
+}