omq-backend-rust 0.3.0-java

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9895c2e753f379324c116f3082c76ab5d562e9d5b7e00539073bdfdd90fa2ac9
+  data.tar.gz: 11cdd6699b6e7efa69a2e8e84a65641406732d3fffb33326311925c009b98c24
+SHA512:
+  metadata.gz: 58c0e0103fe6cffd7d73373045cdce94f113f9c7d520e7a7de909e7a311618318790e5bf7c01685efb83f7bea927b5af7588474189942c29f1f38a4f2ea36d3b
+  data.tar.gz: 95dc600672be8c9ee8a5341b79ce090856ed8129053437fb4ca340d70e039cea9f980cc751ebffb1504f035ac827a1aee4ac837fc0da909e30db379e1c487a41

data/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.3.0] - 2026-08-26
+
+### Added
+
+- Added JRuby support through OMQ.java Maven artifacts for Linux x86_64,
+  macOS aarch64, macOS x86_64, and Windows x86_64.
+
+### Changed
+
+- Replaced the private MRI/TruffleRuby native extension with the first-class
+  `omq-rs` binding.
+
+## [0.2.0] - 2026-08-08
+
+### Added
+
+- Added TruffleRuby support for the Rust backend.
+- Added a shared fallback file descriptor watcher for Rubies without a
+  native `Fiber.scheduler`.
+- Added TruffleRuby CI coverage for the Rust backend.
+
+### Changed
+
+- Updated to `omq-tokio` 0.21.1 and `omq-proto` 0.25.1.
+- Replaced Magnus with a small `rb-sys` helper layer that uses public
+  Ruby C API calls.
+
+### Fixed
+
+- Raised Ruby exceptions through public C API entry points for
+  TruffleRuby compatibility.
+- Rejected invalid negative numeric options before they can overflow Rust
+  sizes or panic on invalid durations.
+
+## [0.1.7] - 2026-08-02
+
+### Added
+
+- Restored Rust/Ruby backend interop coverage.
+
+### Changed
+
+- Updated to `omq-tokio` 0.21.0.
+
+### Fixed
+
+- Drained the Ruby-to-Tokio send pump before native socket close.
+- Released Rust send ring slots before awaiting native sends, avoiding
+  high-throughput stalls under `omq-tokio` 0.21.0 backpressure.
+- Waited for Rust peer registration before resolving `peer_connected`.
+
+## [0.1.6] - 2026-08-01
+
+### Added
+
+- Updated to `omq-tokio` 0.20.3 and `omq-proto` 0.25.0.
+- Enabled OMQ.rs `zstd+tcp://` by default.
+- Forwarded compression bind/connect kwargs to current OMQ.rs options:
+  `dict:`, `auto_dict:`, `compression_threshold:`, `max_recv_dict_size:`,
+  `compression_offload_threshold:`, and zstd `level:`.
+
+## [0.1.5] - 2026-07-31
+
+### Fixed
+
+- Used `IO#wait_readable` for Rust backend receive waits and routed
+  `close_read` wakeups through the native receive notifier.
+- Updated to `omq-tokio` 0.20.2, fixing large byte-stream `PUB` fan-out
+  delivery over IPC and TCP.
+
+## [0.1.4] - 2026-07-30
+
+### Fixed
+
+- Accepted Ruby string identities when materializing Rust sockets.
+
+## [0.1.3] - 2026-07-30
+
+### Added
+
+- Added `require "omq/backend/rust"` as the canonical backend load path.
+
+### Removed
+
+- Removed the old `require "omq/rust"` load path.
+
+## 0.1.2 - 2026-07-28
+
+### Changed
+
+- Updated to `omq-tokio` 0.20.1 and `omq-proto` 0.24.1.
+- Marked the native extension Ractor-safe for Ruby 4 Ractors.
+- Adapted CURVE server setup to `CurveServerOptions`.
+
+## 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/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,86 @@
+# 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 through the first-class
+[omq-rs](https://github.com/paddor/omq.rs/tree/main/bindings/ruby) binding on
+MRI and TruffleRuby, or through OMQ.java on JRuby.
+
+## Install
+
+The `omq-rs` dependency compiles OMQ.rs during installation on MRI and
+TruffleRuby. JRuby uses OMQ.java on Java 25 or newer. The Java gem selects the
+matching OMQ.java artifact on Linux x86_64, macOS aarch64, macOS x86_64, and
+Windows x86_64.
+
+```ruby
+# Gemfile
+gem "omq-backend-rust"
+```
+
+```sh
+gem install omq-backend-rust
+```
+
+## Usage
+
+```ruby
+require "omq"
+require "omq/backend/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))
+
+## Compressed transports
+
+The Rust backend supports `lz4+tcp://` and `zstd+tcp://`. Compression
+configuration uses the same bind/connect kwargs as the Ruby transports:
+`level:` for zstd compression level (`-8..4`), `dict:` for a static
+send-side dictionary, and `auto_dict: true` for automatic dictionary
+training.
+
+Automatic dictionary training is off by default.
+OMQ.rs stores compression configuration per socket, so pass these kwargs on
+the first `bind` or `connect` for a Rust-backed socket.
+
+## Development
+
+```sh
+OMQ_RS_PATH=/path/to/omq.rs/bindings/ruby bundle install
+OMQ_RS_PATH=/path/to/omq.rs/bindings/ruby bundle exec rake
+```
+
+## License
+
+[ISC](LICENSE)

data/lib/omq/backend/rust.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "omq"
+require_relative "../rust/version"
+
+if RUBY_ENGINE == "jruby"
+  require_relative "../rust/java/engine"
+else
+  require "omq/rs"
+  require_relative "../rust/engine"
+end
+
+if RUBY_ENGINE == "jruby"
+  module OMQ
+    module Rust
+      @io_threads = 1
+
+      class << self
+        attr_accessor :io_threads
+      end
+    end
+  end
+end
+
+OMQ::Backend.register(:rust, OMQ::Rust::Engine)

data/lib/omq/rust/java/engine.rb

@@ -0,0 +1,642 @@
+# frozen_string_literal: true
+
+require "jar_dependencies"
+require "thread"
+require "uri"
+require "java"
+
+require_relative "../version"
+require_relative "platform"
+
+require_jar "io.github.paddor", "omq-java",
+            OMQ::Rust::Java.classifier, OMQ::Rust::OMQ_JAVA_VERSION
+
+module OMQ
+  module Rust
+    module Java
+      Duration = ::Java::JavaTime::Duration
+      JavaOMQ = ::Java::IoOmq::OMQ
+      SocketOptions = ::Java::IoOmq::SocketOptions
+      SocketType = ::Java::IoOmq::SocketType
+      Message = ::Java::IoOmq::Message
+      CurveKeypair = ::Java::IoOmq::CurveKeypair
+      OnMute = ::Java::IoOmq::OnMute
+      @context_mutex = Mutex.new
+
+      class << self
+        def context
+          @context_mutex.synchronize do
+            @context ||= JavaOMQ.context(OMQ::Rust.io_threads.to_i).tap do
+              at_exit { @context&.close rescue nil } unless @context_at_exit
+              @context_at_exit = true
+            end
+          end
+        end
+      end
+
+      class Promise
+        def initialize(&resolver)
+          @mutex    = Mutex.new
+          @cv       = ConditionVariable.new
+          @resolved = false
+          @value    = nil
+          @resolver = resolver
+        end
+
+
+        def resolved?
+          @mutex.synchronize { @resolved }
+        end
+
+
+        def resolve(value = nil)
+          @mutex.synchronize do
+            return @value if @resolved
+
+            @resolved = true
+            @value    = value
+            @cv.broadcast
+          end
+        end
+
+
+        def wait
+          until resolved?
+            if @resolver
+              @resolver.call(self)
+            else
+              @mutex.synchronize { @cv.wait(@mutex, 0.05) unless @resolved }
+            end
+          end
+
+          @value
+        end
+      end
+
+      class Engine
+        POLL_SECONDS = 0.005
+        POLL_DURATION = Duration.ofMillis((POLL_SECONDS * 1000).to_i)
+
+        attr_reader :options, :connections, :routing, :socket_type
+        attr_reader :peer_connected, :all_peers_gone, :parent_task
+        attr_reader :on_io_thread
+        alias on_io_thread? on_io_thread
+        attr_writer :reconnect_enabled
+        attr_accessor :subscriber_joined
+
+
+        def initialize(socket_type, options)
+          @socket_type         = socket_type
+          @options             = options
+          @connections         = {}
+          @closed              = false
+          @parent_task         = nil
+          @on_io_thread        = false
+          @materialized        = false
+          @recv_sentinels      = 0
+          @compression_options = {}
+
+          @peer_connected = Promise.new do |promise|
+            wait_connected(1)
+            promise.resolve(true) unless @closed
+          end
+          @all_peers_gone = Promise.new do |promise|
+            wait_all_peers_gone
+            promise.resolve(true) unless @closed
+          end
+          @subscriber_joined = Promise.new do |promise|
+            wait_subscribed(1)
+            promise.resolve(true) unless @closed
+          end
+
+          @routing = RoutingStub.new(self)
+        end
+
+
+        def capture_parent_task(parent: nil)
+          @parent_task ||= parent
+        end
+
+
+        def bind(endpoint, parent: nil, **opts)
+          capture_parent_task(parent: parent)
+          apply_endpoint_options!(opts)
+          ensure_materialized
+          URI.parse(with_java_errors { @native.bind(endpoint) })
+        end
+
+
+        def connect(endpoint, parent: nil, **opts)
+          capture_parent_task(parent: parent)
+          apply_endpoint_options!(opts)
+          ensure_materialized
+          with_java_errors { @native.connect(endpoint) }
+          resolve_peer_connected if endpoint.start_with?("inproc://")
+          URI.parse(endpoint)
+        end
+
+
+        def disconnect(endpoint)
+          ensure_materialized
+          with_java_errors { @native.disconnect(endpoint) }
+        end
+
+
+        def unbind(endpoint)
+          ensure_materialized
+          with_java_errors { @native.unbind(endpoint) }
+        end
+
+
+        def enqueue_send(parts)
+          ensure_materialized
+          msg = java_message(parts)
+
+          if (timeout = @options.write_timeout)
+            ok = with_java_errors { @native.send(msg, duration_from_seconds("write_timeout", timeout)) }
+            raise IO::TimeoutError, "operation timed out" unless ok
+          else
+            with_java_errors { @native.send(msg) }
+          end
+
+          nil
+        end
+
+
+        def dequeue_recv
+          ensure_materialized
+          @recv_deadline = monotonic_time + @options.read_timeout.to_f if @options.read_timeout
+
+          loop do
+            return take_recv_sentinel if @recv_sentinels.positive?
+
+            optional = with_java_errors { @native.tryReceive }
+            return ruby_parts(optional.get) if optional.isPresent
+
+            raise IO::TimeoutError, "operation timed out" if recv_deadline_expired?
+
+            sleep recv_poll_seconds
+          end
+        ensure
+          @recv_deadline = nil
+        end
+
+
+        def dequeue_recv_sentinel
+          @recv_sentinels += 1
+          nil
+        end
+
+
+        def close
+          return if @closed
+
+          @closed = true
+          @peer_connected.resolve(nil)
+          @all_peers_gone.resolve(nil)
+          @subscriber_joined.resolve(nil)
+          with_java_errors { @native&.close }
+          @connections.clear
+          nil
+        end
+
+
+        alias stop close
+
+
+        def closed?
+          @closed
+        end
+
+
+        def subscribe(prefix)
+          @routing.subscribe(prefix)
+        end
+
+
+        def unsubscribe(prefix)
+          @routing.unsubscribe(prefix)
+        end
+
+
+        def emit_monitor_event(_type, endpoint: nil, detail: nil)
+        end
+
+
+        def monitor_queue=(queue)
+          @monitor_queue = queue
+        end
+
+
+        def verbose_monitor=(val)
+          @verbose_monitor = val
+        end
+
+
+        private
+
+
+        def ensure_materialized
+          return if @materialized
+
+          @native = Java.context.socket(SocketType.valueOf(@socket_type.to_s), java_options)
+          @materialized = true
+          @routing.replay_pending(@native)
+        end
+
+
+        def java_message(parts)
+          frames = parts.map { |part| part.to_java_bytes }
+          return Message.of(frames.first) if frames.size == 1
+
+          Message.multipart(*frames)
+        end
+
+
+        def ruby_parts(message)
+          parts = []
+          message.partCount.times do |index|
+            parts << String.from_java_bytes(message.part(index)).b.freeze
+          end
+          parts.freeze
+        end
+
+
+        def take_recv_sentinel
+          @recv_sentinels -= 1
+          nil
+        end
+
+
+        def recv_deadline_expired?
+          return false unless @options.read_timeout
+
+          monotonic_time >= @recv_deadline
+        end
+
+
+        def recv_poll_seconds
+          return POLL_SECONDS unless @options.read_timeout
+
+          [[@recv_deadline - monotonic_time, POLL_SECONDS].min, 0].max
+        end
+
+
+        def monotonic_time
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+
+
+        def wait_connected(count)
+          ensure_materialized
+
+          loop do
+            result = @native.waitConnected(count, POLL_DURATION)
+            resolve_peer_connected if result.to_i.positive?
+            return result
+          rescue ::Java::IoOmq::TimeoutException
+            return nil if @closed
+          rescue ::Java::IoOmq::ClosedException
+            return nil
+          end
+        end
+
+
+        def resolve_peer_connected
+          @connections[:peer] = true
+          @peer_connected.resolve(true) unless @peer_connected.resolved?
+        end
+
+
+        def wait_subscribed(count)
+          ensure_materialized
+
+          loop do
+            result = @native.waitSubscribed(count, POLL_DURATION)
+            return result
+          rescue ::Java::IoOmq::TimeoutException
+            return nil if @closed
+          rescue ::Java::IoOmq::ClosedException
+            return nil
+          end
+        end
+
+
+        def wait_all_peers_gone
+          @peer_connected.wait
+
+          loop do
+            @native.waitConnected(1, POLL_DURATION)
+            sleep POLL_SECONDS
+          rescue ::Java::IoOmq::TimeoutException
+            @connections.clear
+            return true
+          rescue ::Java::IoOmq::ClosedException
+            return nil
+          end
+        end
+
+
+        def java_options
+          builder = SocketOptions.builder
+          apply_socket_options(builder)
+          apply_compression_options(builder)
+          apply_mechanism(builder)
+          builder.build
+        end
+
+
+        def apply_socket_options(builder)
+          builder.sendHighWaterMark([integer_option("send_hwm", @options.send_hwm), 0].max)
+          builder.receiveHighWaterMark([integer_option("recv_hwm", @options.recv_hwm), 0].max)
+
+          if @options.linger == Float::INFINITY
+            builder.lingerForever
+          else
+            builder.linger(duration_from_seconds("linger", @options.linger))
+          end
+
+          builder.identity(bytes(@options.identity)) if @options.identity && !@options.identity.empty?
+          builder.routerMandatory(!!@options.router_mandatory)
+          builder.conflate(!!@options.conflate)
+          builder.maxMessageSize(nonnegative_integer("max_message_size", @options.max_message_size)) if @options.max_message_size
+          builder.sendBufferSize(nonnegative_integer("sndbuf", @options.sndbuf)) if @options.sndbuf
+          builder.receiveBufferSize(nonnegative_integer("rcvbuf", @options.rcvbuf)) if @options.rcvbuf
+          builder.onMute(on_mute)
+
+          apply_duration_option(builder, :heartbeatInterval, "heartbeat_interval", @options.heartbeat_interval)
+          apply_duration_option(builder, :heartbeatTtl, "heartbeat_ttl", @options.heartbeat_ttl)
+          apply_duration_option(builder, :heartbeatTimeout, "heartbeat_timeout", @options.heartbeat_timeout)
+          apply_reconnect_option(builder)
+        end
+
+
+        def apply_reconnect_option(builder)
+          reconnect = @options.reconnect_interval
+
+          case reconnect
+          when Range
+            builder.reconnectExponential(
+              duration_from_seconds("reconnect_interval min", reconnect.begin),
+              duration_from_seconds("reconnect_interval max", reconnect.end),
+            )
+          when nil, false
+            builder.reconnectDisabled
+          else
+            builder.reconnectInterval(duration_from_seconds("reconnect_interval", reconnect))
+          end
+        end
+
+
+        def apply_duration_option(builder, method, label, value)
+          builder.public_send(method, duration_from_seconds(label, value)) if value
+        end
+
+
+        def apply_compression_options(builder)
+          if @compression_options.key?("compression_auto_train")
+            builder.compressionAutoTrain(!!@compression_options["compression_auto_train"])
+          end
+          if (value = @compression_options["compression_threshold"])
+            builder.compressionThreshold(nonnegative_integer("compression_threshold", value))
+          end
+          if (value = @compression_options["compression_level"])
+            builder.compressionLevel(integer_option("compression_level", value))
+          end
+          if (value = @compression_options["compression_dict"])
+            builder.compressionDict(bytes(value))
+          end
+          if (value = @compression_options["compression_dict_capacity"])
+            builder.compressionDictCapacity(nonnegative_integer("compression_dict_capacity", value))
+          end
+          if (value = @compression_options["max_recv_dict_size"])
+            builder.maxReceiveDictSize(nonnegative_integer("max_recv_dict_size", value))
+          end
+
+          return unless @compression_options.key?("compression_offload_threshold")
+
+          value = @compression_options["compression_offload_threshold"]
+          if value.nil? || value.to_i.negative?
+            builder.noCompressionOffload
+          else
+            builder.compressionOffloadThreshold(nonnegative_integer("compression_offload_threshold", value))
+          end
+        end
+
+
+        def apply_mechanism(builder)
+          mech = @options.mechanism
+          klass = mech.class.name
+          return unless klass&.include?("Curve")
+
+          require "protocol/zmtp/z85"
+
+          keypair = CurveKeypair.new(
+            z85_key(mech.instance_variable_get(:@permanent_public), "public key"),
+            z85_key(mech.instance_variable_get(:@permanent_secret), "secret key"),
+          )
+
+          if mech.instance_variable_get(:@as_server)
+            builder.curveServer(keypair)
+          else
+            builder.curveClient(keypair, z85_key(mech.instance_variable_get(:@server_public), "server key"))
+          end
+        end
+
+
+        def z85_key(key, label)
+          raw = key&.to_s&.b
+          raise ArgumentError, "#{label} must be exactly 32 bytes" unless raw&.bytesize == 32
+
+          Protocol::ZMTP::Z85.encode(raw)
+        end
+
+
+        def on_mute
+          case @options.on_mute&.to_sym
+          when :drop_newest, :drop
+            OnMute::DROP_NEWEST
+          when :drop_oldest
+            OnMute::DROP_OLDEST
+          else
+            OnMute::BLOCK
+          end
+        end
+
+
+        def duration_from_seconds(label, value)
+          seconds = Float(value)
+          raise ArgumentError, "#{label} must be finite and non-negative" unless seconds.finite? && !seconds.negative?
+
+          Duration.ofNanos((seconds * 1_000_000_000).round)
+        end
+
+
+        def nonnegative_integer(label, value)
+          value = integer_option(label, value)
+          raise ArgumentError, "#{label} must be non-negative" if value.negative?
+
+          value
+        end
+
+
+        def integer_option(label, value)
+          Integer(value)
+        rescue ArgumentError, TypeError
+          raise ArgumentError, "#{label} must be an Integer"
+        end
+
+
+        def bytes(value)
+          value.to_s.b.to_java_bytes
+        end
+
+
+        def apply_endpoint_options!(opts)
+          compression = extract_endpoint_compression_options(opts)
+          return if compression.empty?
+
+          if @materialized
+            existing = compression.keys.to_h do |key|
+              [key, @compression_options.fetch(key, default_compression_option(key))]
+            end
+            return if compression == existing
+
+            raise ArgumentError,
+              "Rust backend compression options must be set before first bind/connect"
+          end
+
+          @compression_options.merge!(compression)
+        end
+
+
+        def extract_endpoint_compression_options(opts)
+          out = {}
+
+          if opts.key?(:level)
+            validate_zstd_level!(opts[:level])
+            out["compression_level"] = opts[:level]
+          end
+          out["compression_dict"] = opts[:dict].b if opts.key?(:dict) && opts[:dict]
+
+          if opts.key?(:auto_dict)
+            auto_dict = opts[:auto_dict]
+            if auto_dict && opts[:dict]
+              raise ArgumentError, "cannot combine auto_dict: and dict:"
+            end
+
+            case auto_dict
+            when nil, false
+              out["compression_auto_train"] = false
+            when true
+              out["compression_auto_train"] = true
+            when Hash
+              if auto_dict.key?(:trigger)
+                raise ArgumentError,
+                  "Rust backend does not support auto_dict: trigger"
+              end
+              validate_positive!("auto_dict capacity", auto_dict[:capacity]) if auto_dict[:capacity]
+              out["compression_auto_train"] = true
+              out["compression_dict_capacity"] = auto_dict[:capacity] if auto_dict[:capacity]
+            else
+              raise TypeError, "auto_dict: must be true, false, or a Hash; got #{auto_dict.class}"
+            end
+          end
+
+          out["compression_threshold"] = opts[:compression_threshold] if opts.key?(:compression_threshold)
+          out["max_recv_dict_size"] = opts[:max_recv_dict_size] if opts.key?(:max_recv_dict_size)
+          if opts.key?(:compression_offload_threshold)
+            out["compression_offload_threshold"] = opts[:compression_offload_threshold] || -1
+          end
+
+          out
+        end
+
+
+        def default_compression_option(key)
+          key == "compression_auto_train" ? false : nil
+        end
+
+
+        def validate_positive!(label, value)
+          return if value.respond_to?(:positive?) && value.positive?
+
+          raise ArgumentError, "#{label} must be positive"
+        end
+
+
+        def validate_zstd_level!(level)
+          return if level.is_a?(Integer) && (-8..4).cover?(level)
+
+          raise ArgumentError, "zstd compression level must be -8..4, got #{level.inspect}"
+        end
+
+
+        def with_java_errors
+          yield
+        rescue ::Java::IoOmq::TimeoutException => error
+          raise IO::TimeoutError, error.message
+        rescue ::Java::IoOmq::ClosedException => error
+          raise IOError, error.message
+        rescue ::Java::IoOmq::InvalidEndpointException => error
+          raise ArgumentError, error.message
+        rescue ::Java::IoOmq::OMQException => error
+          raise RuntimeError, error.message
+        end
+
+        class RoutingStub
+          def initialize(engine)
+            @engine            = engine
+            @pending_subscribe = []
+            @pending_join      = []
+          end
+
+
+          def subscriber_joined
+            @engine.subscriber_joined
+          end
+
+
+          def subscribe(prefix)
+            native = @engine.instance_variable_get(:@native)
+            if @engine.instance_variable_get(:@materialized)
+              native.subscribe(prefix.b.to_java_bytes)
+            else
+              @pending_subscribe << prefix.b
+            end
+          end
+
+
+          def unsubscribe(prefix)
+            @engine.instance_variable_get(:@native).unsubscribe(prefix.b.to_java_bytes)
+          end
+
+
+          def join(group)
+            native = @engine.instance_variable_get(:@native)
+            if @engine.instance_variable_get(:@materialized)
+              native.join(group.b.to_java_bytes)
+            else
+              @pending_join << group.b
+            end
+          end
+
+
+          def leave(group)
+            @engine.instance_variable_get(:@native).leave(group.b.to_java_bytes)
+          end
+
+
+          def replay_pending(native)
+            @pending_subscribe.each { |prefix| native.subscribe(prefix.to_java_bytes) }
+            @pending_subscribe.clear
+            @pending_join.each { |group| native.join(group.to_java_bytes) }
+            @pending_join.clear
+          end
+        end
+      end
+    end
+
+    Engine = Java::Engine
+  end
+end

data/lib/omq/rust/java/platform.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+require_relative "../version"
+
+module OMQ
+  module Rust
+    module Java
+      class UnsupportedPlatformError < LoadError; end
+
+      class << self
+        def classifier
+          override = ENV.fetch("OMQ_JAVA_CLASSIFIER", "").strip
+          return validate_classifier(override) unless override.empty?
+
+          classifier_for(os_name: host_os_name, os_arch: host_os_arch)
+        end
+
+
+        def classifier_for(os_name:, os_arch:)
+          os   = normalize_os(os_name)
+          arch = normalize_arch(os_arch)
+
+          classifier = "#{os}-#{arch}" if os && arch
+          return classifier if OMQ::Rust::OMQ_JAVA_CLASSIFIERS.include?(classifier)
+
+          raise UnsupportedPlatformError,
+                "unsupported OMQ.java platform: #{os_name.inspect}/#{os_arch.inspect} " \
+                "(supported: #{OMQ::Rust::OMQ_JAVA_CLASSIFIERS.join(", ")})"
+        end
+
+
+        private
+
+
+        def validate_classifier(classifier)
+          return classifier if OMQ::Rust::OMQ_JAVA_CLASSIFIERS.include?(classifier)
+
+          raise UnsupportedPlatformError,
+                "unsupported OMQ.java classifier: #{classifier.inspect} " \
+                "(supported: #{OMQ::Rust::OMQ_JAVA_CLASSIFIERS.join(", ")})"
+        end
+
+
+        def host_os_name
+          java_system_property("os.name") ||
+            RbConfig::CONFIG["host_os"] ||
+            RbConfig::CONFIG["target_os"] ||
+            RUBY_PLATFORM
+        end
+
+
+        def host_os_arch
+          java_system_property("os.arch") ||
+            RbConfig::CONFIG["host_cpu"] ||
+            RbConfig::CONFIG["target_cpu"] ||
+            RUBY_PLATFORM
+        end
+
+
+        def java_system_property(name)
+          return unless RUBY_ENGINE == "jruby"
+
+          require "java"
+          ::Java::JavaLang::System.get_property(name)
+        rescue LoadError, NameError
+          nil
+        end
+
+
+        def normalize_os(value)
+          case value.to_s.downcase
+          when /linux/
+            "linux"
+          when /darwin|mac\s*os|macos/
+            "macos"
+          when /windows|mswin|mingw|cygwin/
+            "windows"
+          end
+        end
+
+
+        def normalize_arch(value)
+          case value.to_s.downcase
+          when "amd64", "x64", "x86-64", "x86_64"
+            "x86_64"
+          when "aarch64", "arm64"
+            "aarch64"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omq/rust/version.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Backend
+    module Rust
+      VERSION = "0.3.0"
+    end
+  end
+
+  module Rust
+    OMQ_JAVA_VERSION = "0.3.0"
+    OMQ_JAVA_CLASSIFIERS = [
+      "linux-x86_64",
+      "macos-aarch64",
+      "macos-x86_64",
+      "windows-x86_64",
+    ].freeze
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: omq-backend-rust
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: java
+authors:
+- Patrik Wenger
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: omq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.28'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.28'
+- !ruby/object:Gem::Dependency
+  name: jar-dependencies
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.7
+description: Drop-in Rust backend for OMQ on JRuby. Same socket API (REQ/REP, PUB/SUB,
+  PUSH/PULL, DEALER/ROUTER, and all draft types), but networking runs through the
+  OMQ.java Maven artifact.
+email:
+- paddor@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/omq/backend/rust.rb
+- lib/omq/rust/java/engine.rb
+- lib/omq/rust/java/platform.rb
+- lib/omq/rust/version.rb
+homepage: https://github.com/zeromq/omq.rb/tree/main/gems/omq-backend-rust
+licenses:
+- ISC
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- jar io.github.paddor:omq-java:linux-x86_64, 0.3.0
+- jar io.github.paddor:omq-java:macos-aarch64, 0.3.0
+- jar io.github.paddor:omq-java:macos-x86_64, 0.3.0
+- jar io.github.paddor:omq-java:windows-x86_64, 0.3.0
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Rust-backed engine for OMQ using OMQ.java on JRuby
+test_files: []