omq-rs 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: deaed5d4439c9c15105ab96ca99b1589052d80bdf0730d07aff19f7b146cdc47
-  data.tar.gz: 116dc7537c497dc57a59a5348966dc6c5f82bf3dea038ddc488eef7aa6efb470
+  metadata.gz: ace7dd4c9d05f6cba6ed58941ed30038c131c3de0a246395baf2b932ac76fa25
+  data.tar.gz: 4c6fdc8bd3543f98c01979ba2cabe4460a6c435d92c91b969b7a6bc0e6b7fdd0
 SHA512:
-  metadata.gz: c82ec7acb65d986cdc8f0d6289ac8fd952b256cbe8b02276d0b1a84e4ff06fbb9f00dafa2373091bdcd17daeaffc53c4fff6a69d713a68d4b9aa9446e0c5bbbe
-  data.tar.gz: e8b55702563c7849a521545c387ef91fbf632b329efad536105af4306d67f6fae31d914f3755c7be71639cd864241843d358417570c0451f5003a441f4b35f56
+  metadata.gz: ff6a09ddfa0c2c1cddad4a369509ed59085143cd5abb208e506a216f5d6c6977db2a4c77384db602f0cd193be1ab4b69b17f4f0b25f31b9a88d236093e415918
+  data.tar.gz: a0e77ee6fc098846c4e8e40035ebed72d059cbcbb249c4f264954407cc5fde6ba7f1b3b0294752ad33069e261235269e2c0a87c889636b5b8b04374e31b73f7e

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-09-01
+
+- Route `Socket#try_recv` directly through the native nonblocking receive path.
+- Avoid Ruby-side batch array churn in hot polling loops.
+
+## [0.1.1] - 2026-08-23
+
+- Document the full public API and publish the RubyDoc documentation link.
+- Reject unknown socket options instead of silently ignoring misspellings.
+- Make peer, subscriber, and monitor waits stop cleanly when a socket closes.
+- Release the CURVE auth-worker mutex before joining its thread during close.
+- Add mixed transport, protocol, lifecycle, and resource soak coverage.
+- Require `omq-proto` 0.26.1 and `omq-tokio` 0.21.4.
+
+## [0.1.0] - 2026-08-20
+
 - 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.

data/DEVELOPMENT.md

@@ -0,0 +1,170 @@
+# omq-rs development
+
+Run commands from the repository root unless a section changes directory.
+
+## Prerequisites
+
+- Ruby 3.3 or newer with Bundler.
+- Rust 1.93 or newer with Cargo, rustfmt, and Clippy.
+- Python with pyzmq for the Python interoperability tests.
+- CZMQ and libzmq development files for cztop interoperability and both
+  benchmark baselines.
+
+Install the Ruby dependencies:
+
+```sh
+cd bindings/ruby
+bundle install
+```
+
+## Build and test
+
+Run the normal binding test pass from the repository root:
+
+```sh
+./scripts/test-ruby.sh
+```
+
+Select a Ruby executable explicitly with `OMQ_RUBY`:
+
+```sh
+OMQ_RUBY=/path/to/ruby ./scripts/test-ruby.sh
+```
+
+The equivalent commands from the binding directory are:
+
+```sh
+cd bindings/ruby
+bundle exec rake
+```
+
+Compile once, then run one test file:
+
+```sh
+bundle exec rake compile
+bundle exec ruby -Ilib:test test/test_features.rb
+```
+
+The suite covers socket patterns, options, transports, CURVE, PLAIN,
+compression, monitors, Fiber schedulers, Ractors, lifecycle behavior, and
+pyzmq interoperability. pyzmq tests skip when pyzmq is unavailable. cztop
+tests skip when CZMQ or cztop is unavailable. Ractor tests require Ruby 4.
+
+## Soak tests
+
+Run the mixed transport, security, compression, churn, and resource soak:
+
+```sh
+bindings/ruby/scripts/soak.sh 1h
+```
+
+The duration accepts `s`, `m`, `h`, or `d`. The test reports progress, RSS,
+file descriptors, and Ruby thread counts. It fails on message corruption,
+stalls, or sustained resource growth.
+
+`scripts/test-all.sh` includes the Ruby pass in the full repository test run.
+
+## Static checks
+
+Run the same native checks as CI:
+
+```sh
+cargo fmt --manifest-path bindings/ruby/Cargo.toml --all --check
+cargo clippy --manifest-path bindings/ruby/Cargo.toml \
+  --all-targets --all-features -- -D warnings
+```
+
+Check Ruby syntax:
+
+```sh
+find bindings/ruby/lib bindings/ruby/test bindings/ruby/scripts \
+  -name '*.rb' -print0 | xargs -0 -n1 ruby -cw
+ruby -cw bindings/ruby/Rakefile
+ruby -cw bindings/ruby/omq-rs.gemspec
+```
+
+Check public YARD coverage from `bindings/ruby` after installing YARD:
+
+```sh
+yard stats --no-save --no-cache --list-undoc --no-private \
+  'lib/**/*.rb' 'lib/*.rb'
+```
+
+## Benchmarks
+
+Run benchmarks on an otherwise idle machine. The harness starts separate Ruby
+processes over TCP. PUSH/PULL throughput covers 16 B through 32 KiB. REQ/REP
+mean latency covers 16 B through 4 KiB. The default run keeps the median of three
+rounds for each implementation, pattern, and message size. Throughput uses a
+0.5 second warmup and 2.5 second measurement window. Latency uses a 0.5 second
+warmup and 1.5 second measurement window.
+
+From the binding directory:
+
+```sh
+cd bindings/ruby
+bundle exec rake compile
+bundle exec ruby -Ilib scripts/update_perf.rb
+```
+
+The default run benchmarks `omq-rs`. It includes cztop when CZMQ is available
+and ffi-rzmq when libzmq is available. Missing baselines are skipped.
+
+Useful controls:
+
+```sh
+bundle exec ruby -Ilib scripts/update_perf.rb --quick
+bundle exec ruby -Ilib scripts/update_perf.rb --impl omq-rs,cztop,ffi-rzmq
+bundle exec ruby -Ilib scripts/update_perf.rb --patterns pushpull,reqrep
+bundle exec ruby -Ilib scripts/update_perf.rb --sizes 16,128,1024,4096
+bundle exec ruby -Ilib scripts/update_perf.rb --rounds 5
+bundle exec ruby -Ilib scripts/update_perf.rb --duration 2.5 --warmup-duration 0.5
+bundle exec ruby -Ilib scripts/update_perf.rb --latency-duration 1.5 --latency-warmup-duration 0.5
+bundle exec ruby -Ilib scripts/update_perf.rb --no-record
+```
+
+`--quick` runs one round at 128 B and 1 KiB without recording results or
+rewriting the chart.
+
+## Chart generation
+
+Benchmark rows append to:
+
+```text
+~/.cache/omq-rs/bindings.jsonl
+```
+
+Regenerate the SVG from the latest cached row for each implementation,
+pattern, and message size:
+
+```sh
+cd bindings/ruby
+bundle exec ruby -Ilib scripts/update_perf.rb --chart-only
+```
+
+The output is `bindings/ruby/doc/charts/bindings.svg`. Its hardware subtitle
+comes from the repository-root `.chart_hw` file:
+
+```text
+prefix=Linux VM on a 2018 Mac Mini
+postfix=6 cores, performance governor, turbo off
+```
+
+`.chart_hw` is local-only and gitignored.
+
+## Packaging and release
+
+Build the source gem from the binding directory:
+
+```sh
+cd bindings/ruby
+bundle exec rake build
+```
+
+The gem is written to `bindings/ruby/pkg/`. Publication runs only through
+`.github/workflows/release-rubygems.yml` using RubyGems trusted publishing.
+The release tag must match the gem version:
+
+```text
+ruby-v<VERSION>
+```

data/README.md

@@ -7,6 +7,16 @@ 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.
 
+## 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. See [DEVELOPMENT.md](DEVELOPMENT.md)
+for methodology and regeneration commands.
+
 ## Install
 
 ```sh
@@ -131,30 +141,7 @@ 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.
+Build, test, benchmark, and release instructions: [DEVELOPMENT.md](DEVELOPMENT.md).
 
 ## License
 

data/ext/omq_rs_native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "omq_rs_native"
-version = "0.1.0"
+version = "0.1.2"
 edition = "2024"
 rust-version = "1.93"
 license = "ISC"
@@ -20,8 +20,8 @@ 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 }
+omq-proto = { version = ">=0.26.1, <0.28.0", default-features = false }
+omq-tokio = { version = ">=0.21.4, <0.23.0", default-features = false }
 yring = { version = "=0.3.14", features = ["async"] }
 
 bytes = "1.12.0"

data/ext/omq_rs_native/src/socket.rs

@@ -198,7 +198,8 @@ fn set_curve_authenticator(
     }
     drop(options_guard);
 
-    if let Some(previous) = rb_self.auth_worker.lock().unwrap().take() {
+    let previous = rb_self.auth_worker.lock().unwrap().take();
+    if let Some(previous) = previous {
         previous.stop();
     }
     *rb_self.auth_worker.lock().unwrap() = worker;
@@ -774,7 +775,8 @@ unsafe extern "C" fn rust_socket_leave(rb_self: VALUE, group: VALUE) -> VALUE {
 fn rust_socket_close_impl(rb_self: &RustSocket, wait_for_auth_worker: bool) {
     rb_self.closed.store(true, Ordering::Relaxed);
     #[cfg(feature = "curve")]
-    if let Some(worker) = rb_self.auth_worker.lock().unwrap().take() {
+    let worker = rb_self.auth_worker.lock().unwrap().take();
+    if let Some(worker) = worker {
         if wait_for_auth_worker {
             worker.stop();
         } else {

data/lib/omq/rs/socket.rb

@@ -18,6 +18,69 @@ module OMQ
     # @api private
     SINGLE_FRAME_TYPES = %i[client server scatter gather channel].freeze
 
+    # @api private
+    SOCKET_OPTIONS = %w[
+      workload_profile
+      send_hwm
+      recv_hwm
+      recv_rate_limit
+      recv_ip_rate_limit
+
+      linger
+      identity
+      router_mandatory
+      conflate
+
+      heartbeat_interval
+      heartbeat_ttl
+      heartbeat_timeout
+      handshake_timeout
+      max_pending_handshakes
+
+      max_message_size
+      sndbuf
+      rcvbuf
+      large_message_threshold
+      arena_threshold
+      transmit_slot_cap
+
+      xpub_nodrop
+      reconnect_stop_conn_refused
+      on_mute
+      reconnect_interval
+      reconnect_interval_min
+      reconnect_interval_max
+
+      compression_dict
+      compression_auto_train
+      compression_threshold
+      compression_level
+      compression_dict_capacity
+      max_recv_dict_size
+      compression_offload_threshold
+
+      mechanism_type
+      mechanism_server
+      mechanism_public_key
+      mechanism_secret_key
+      mechanism_server_key
+      mechanism_username
+      mechanism_password
+
+      curve_server
+      curve_publickey
+      curve_public_key
+      curve_secretkey
+      curve_secret_key
+      curve_serverkey
+      curve_server_key
+
+      plain_server
+      plain_username
+      plain_password
+    ].freeze
+    private_constant :ROUTED_TYPES, :SINGLE_FRAME_TYPES, :SOCKET_OPTIONS
+
     # CURVE peer metadata passed to callable authenticators.
     #
     # @!attribute [r] public_key
@@ -34,11 +97,13 @@ module OMQ
         Native.io_threads
       end
 
-      # Sets number of OMQ.rs IO threads used by subsequently created sockets.
+      # Sets number of OMQ.rs IO threads before the shared runtime starts.
       #
       # @param count [Integer] positive IO thread count
       # @return [Integer] assigned count
       # @raise [ArgumentError] if +count+ is not positive
+      # @note Set this before materializing any socket. It does not resize a
+      #   running runtime.
       def io_threads=(count)
         count = Integer(count)
         raise ArgumentError, "io_threads must be positive" unless count.positive?
@@ -139,7 +204,9 @@ module OMQ
       def each
         return enum_for(__method__) unless block_given?
 
-        loop { yield recv }
+        while (event = recv)
+          yield event
+        end
       rescue IOError
         raise unless @socket.closed?
       end
@@ -156,8 +223,53 @@ module OMQ
       # @param send_timeout [Numeric, nil] send timeout in seconds
       # @param curve_auth [Array<String>, #call, nil] CURVE allowlist or authenticator
       # @param options [Hash] native OMQ.rs socket options
+      # @option options [Symbol] :workload_profile +:throughput+ or +:latency+
+      # @option options [Integer] :send_hwm outbound message capacity
+      # @option options [Integer] :recv_hwm inbound message capacity
+      # @option options [Hash] :recv_rate_limit per-connection
+      #   +:messages_per_second+ (or +:rate+) and +:burst+
+      # @option options [Hash] :recv_ip_rate_limit per-IP
+      #   +:messages_per_second+ (or +:rate+) and +:burst+
+      # @option options [Numeric] :linger close linger in seconds; positive
+      #   infinity waits forever
+      # @option options [String] :identity ZMTP socket identity
+      # @option options [Boolean] :router_mandatory reject unroutable sends
+      # @option options [Boolean] :conflate retain only latest received message
+      # @option options [Numeric] :heartbeat_interval heartbeat period in seconds
+      # @option options [Numeric] :heartbeat_ttl remote heartbeat TTL in seconds
+      # @option options [Numeric] :heartbeat_timeout peer timeout in seconds
+      # @option options [Numeric] :handshake_timeout handshake timeout in seconds
+      # @option options [Integer] :max_pending_handshakes inbound handshake limit
+      # @option options [Integer] :max_message_size maximum received message bytes
+      # @option options [Integer] :sndbuf kernel send buffer bytes
+      # @option options [Integer] :rcvbuf kernel receive buffer bytes
+      # @option options [Integer] :large_message_threshold receive buffer threshold
+      # @option options [Integer] :arena_threshold contiguous frame arena threshold
+      # @option options [Integer] :transmit_slot_cap per-peer transmit bytes
+      # @option options [Boolean] :xpub_nodrop block instead of dropping on mute
+      # @option options [Boolean] :reconnect_stop_conn_refused stop refused reconnects
+      # @option options [Symbol] :on_mute +:block+, +:drop_newest+, or +:drop_oldest+
+      # @option options [Numeric] :reconnect_interval fixed reconnect delay in seconds
+      # @option options [Numeric] :reconnect_interval_min minimum backoff in seconds
+      # @option options [Numeric] :reconnect_interval_max maximum backoff in seconds
+      # @option options [String] :compression_dict compression dictionary bytes
+      # @option options [Boolean] :compression_auto_train train a zstd dictionary
+      # @option options [Integer] :compression_threshold minimum bytes to compress
+      # @option options [Integer] :compression_level zstd compression level
+      # @option options [Integer] :compression_dict_capacity trained dictionary bytes
+      # @option options [Integer] :max_recv_dict_size received dictionary byte limit
+      # @option options [Integer] :compression_offload_threshold offload threshold;
+      #   negative disables offloading
+      # @option options [Symbol] :mechanism_type +:null+, +:plain+, or +:curve+
+      # @option options [Boolean] :plain_server enable PLAIN server mode
+      # @option options [String] :plain_username PLAIN client username
+      # @option options [String] :plain_password PLAIN client password
+      # @option options [Boolean] :curve_server enable CURVE server mode
+      # @option options [String] :curve_publickey local raw or Z85 public key
+      # @option options [String] :curve_secretkey local raw or Z85 secret key
+      # @option options [String] :curve_serverkey CURVE server raw or Z85 public key
       # @return [Socket]
-      # @raise [ArgumentError] if an option is invalid
+      # @raise [ArgumentError] if an option is unknown or invalid
       def initialize(recv_timeout: nil, send_timeout: nil, curve_auth: nil, **options)
         socket_type = self.class.const_get(:SOCKET_TYPE, false)
         @socket_type = socket_type.to_s.downcase.to_sym
@@ -167,7 +279,6 @@ module OMQ
 
         @recv_timeout = recv_timeout
         @send_timeout = send_timeout
-        @recv_batch   = []
         @request_waiting = false
         @reply_ready     = false
         @native       = Native::Socket.new(@socket_type.to_s.upcase)
@@ -176,6 +287,8 @@ module OMQ
         @materialized = false
         @recv_io = nil
         @send_io = nil
+        @peer_connected = false
+        @subscriber_joined = false
         set_curve_auth(curve_auth) unless curve_auth.nil?
       end
 
@@ -228,7 +341,7 @@ module OMQ
         @native.peer_info(routing_id)
       end
 
-      # Configures CURVE client authentication before socket materialization.
+      # Configures CURVE client authorization on a server before materialization.
       #
       # @param authenticator [Array<String>, #call, nil] public-key allowlist,
       #   callable receiving {MechanismPeerInfo}, or +nil+ to allow valid clients
@@ -326,18 +439,11 @@ module OMQ
       # @return [Array<String, Integer>, nil] next message, or +nil+ if none is ready
       def try_recv
         ensure_materialized
-        unless @recv_batch.empty?
-          message = @recv_batch.shift
-          received!
-          return message
-        end
 
         message = if ROUTED_TYPES.include?(@socket_type)
           @native.try_recv_routed
-        elsif (batch = @native.try_recv_batch)
-          first = batch.shift
-          @recv_batch = batch
-          first
+        else
+          @native.try_recv
         end
         received! if message
         message
@@ -430,9 +536,16 @@ module OMQ
       # @param timeout [Numeric, nil] maximum wait in seconds
       # @return [Socket] self
       # @raise [IO::TimeoutError] if timeout expires
+      # @raise [IOError] if socket closes first
       def wait_for_peer(timeout: nil)
+        raise IOError, "socket closed" if closed?
+        return self if @peer_connected
+
         ensure_materialized
         wait_for_native_fd(@native.peer_connected_fd, timeout, "peer connection timed out")
+        raise IOError, "socket closed" if closed?
+
+        @peer_connected = true
         self
       end
 
@@ -441,9 +554,16 @@ module OMQ
       # @param timeout [Numeric, nil] maximum wait in seconds
       # @return [Socket] self
       # @raise [IO::TimeoutError] if timeout expires
+      # @raise [IOError] if socket closes first
       def wait_for_subscriber(timeout: nil)
+        raise IOError, "socket closed" if closed?
+        return self if @subscriber_joined
+
         ensure_materialized
         wait_for_native_fd(@native.subscriber_joined_fd, timeout, "subscriber timed out")
+        raise IOError, "socket closed" if closed?
+
+        @subscriber_joined = true
         self
       end
 
@@ -471,6 +591,8 @@ module OMQ
       # @return [Hash, nil]
       # @raise [IO::TimeoutError] if timeout expires
       def monitor_event(timeout: @recv_timeout)
+        return if closed?
+
         ensure_materialized
         event = @native.try_recv_monitor
         return event if event
@@ -483,6 +605,8 @@ module OMQ
       #
       # @return [Hash, nil]
       def try_monitor_event
+        return if closed?
+
         ensure_materialized
         @native.try_recv_monitor
       end
@@ -532,11 +656,17 @@ module OMQ
       end
 
       def normalize_options(options)
-        options.to_h do |key, value|
+        normalized = options.to_h do |key, value|
           value = value.to_s if value.is_a?(Symbol)
           value = value.transform_keys(&:to_s) if value.is_a?(Hash)
           [key.to_s, value]
         end
+        unknown = normalized.keys - SOCKET_OPTIONS
+        unless unknown.empty?
+          raise ArgumentError, "unknown socket option#{"s" if unknown.length > 1}: #{unknown.sort.join(", ")}"
+        end
+
+        normalized
       end
 
       def validate_send_parts!(parts)

data/lib/omq/rs/version.rb

@@ -5,6 +5,6 @@ module OMQ
   module Rust
     # Ruby binding version.
     # @return [String]
-    VERSION = "0.1.0"
+    VERSION = "0.1.2"
   end
 end

data/lib/omq/rs.rb

@@ -4,6 +4,7 @@ require_relative "rs/version"
 require_relative "rs/omq_rs_native"
 require_relative "rs/socket"
 
+# Brokerless messaging APIs and language backends.
 module OMQ
   class << self
     # Returns the OMQ.rs namespace or creates an OMQ.rs-backed socket.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omq-rs
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Patrik Wenger
@@ -33,6 +33,7 @@ extensions:
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- DEVELOPMENT.md
 - LICENSE
 - README.md
 - ext/omq_rs_native/Cargo.toml
@@ -56,6 +57,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/paddor/omq.rs/tree/main/bindings/ruby
   changelog_uri: https://github.com/paddor/omq.rs/tree/main/bindings/ruby/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/omq-rs
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: