omq 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91e6db2b4fd881530030f63c0c47a534c3f6361497d0f55ad1d28c7dbb85a669
-  data.tar.gz: 1af1d5692333586b650f7d0f14118ae04f64a65ab3d127d8ea3a3781e0eaae34
+  metadata.gz: 997f3d83d6ddc56d44341f69743f4f30b9e122f046718246de78da75969ec6fa
+  data.tar.gz: 65f4f071d952c477630bfae4c25f136abfa79350099b58b1be4ca79ec500f2e3
 SHA512:
-  metadata.gz: 4a724ddc29600b8d101046ca82869e4598f733564be4022fc8eb287084a80319a1586d5e0ced449f3eea3a26127add8f962fc3914177cc95f4f495e98f87e7d4
-  data.tar.gz: '08935cd0ad4548af6a526984d84514b242ab1d29bfd14fb8933f7b84b9f906f1197588f6bc0fec95332d2dbac6e016308cbdb5bf5efe9e2cba7b2bbf7d695d58'
+  metadata.gz: d92503d56e3106987bda522497f42630d7999bca8ba1ddd5190129d0dc567c5dac1714a8f8566601ac1fa309d0e142f87936342667b36588f81e39f785a2b502
+  data.tar.gz: bed4e86b9404a7ecc175c50ba85a2b7ad8daaea1490c8f39a449c8f92c197b039326d73708279838c1678a29235c7a5ff30c1bf36903306d452dccd743059b76

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.14.0 — 2026-04-07
+
+- **Fix recv pump crash with connection wrappers** — `start_direct` called
+  `msg.sum(&:bytesize)` unconditionally, crashing when a `connection_wrapper`
+  (e.g. omq-ractor's `MarshalConnection`) returns deserialized Ruby objects.
+  Byte counting now uses `conn.instance_of?(Protocol::ZMTP::Connection)` to
+  skip non-ZMTP connections (inproc, Ractor bridges).
+- Remove TLS transport dependency from Gemfile.
+- YARD documentation on all public methods and classes.
+- Code style: expand `else X` one-liners, enforce two blank lines between
+  methods and constants.
+- Benchmarks: add per-run timeout (default 30s, `OMQ_BENCH_TIMEOUT` env var)
+  and abort if a group produces no results.
+
+- Add `Engine::Maintenance` — spawns a periodic `Async::Loop.quantized` timer
+  that calls the mechanism's `#maintenance` callback (if defined). Enables
+  automatic cookie key rotation for CurveZMQ and BLAKE3ZMQ server mechanisms.
+- **YJIT: remove redundant `is_a?` guards in recv pump** — the non-transform
+  branch no longer type-checks every message; `conn.receive_message` always
+  returns `Array<String>`.
+- **YJIT: `FanOut#subscribed?` fast path for subscribe-all** — connections
+  subscribed to `""` are tracked in a `@subscribe_all` Set, short-circuiting
+  the per-message prefix scan with an O(1) lookup.
+- **YJIT: remove safe navigation in hot enqueue paths** — `&.enqueue` calls
+  in `FanOut#fan_out_enqueue` and `RoundRobin#enqueue_round_robin` replaced
+  with direct calls; queues are guaranteed to exist for live connections.
+- **Fix PUB/SUB fan-out over inproc and IPC** — restore `respond_to?(:write_wire)`
+  guard in `FanOut#start_conn_send_pump` so DirectPipe connections use
+  `#write_message` instead of the wire-optimized path. Add `DirectPipe#encrypted?`
+  (returns `false`) for the mechanism query.
+- **Code audit: never-instantiated classes** — `RecvPump`, `ConnectionSetup`,
+  and `Reconnect` refactored from class-method namespaces to proper instances
+  that capture shared state. `Heartbeat`, `Maintenance`, and `ConnSendPump`
+  changed from classes to modules (single `self.` method, never instantiated).
+
 ## 0.13.0
 
 ### Changed

data/README.md

@@ -197,6 +197,33 @@ bundle install
 bundle exec rake
 ```
 
+### Full development setup
+
+Set `OMQ_DEV=1` to tell Bundler to load sibling projects from source
+(protocol-zmtp, nuckle, omq-rfc-\*, etc.) instead of released gems.
+This is required for running benchmarks and for testing changes across
+the stack.
+
+```sh
+# clone OMQ and its sibling repos into the same parent directory
+git clone https://github.com/paddor/omq.git
+git clone https://github.com/paddor/protocol-zmtp.git
+git clone https://github.com/paddor/nuckle.git
+git clone https://github.com/paddor/omq-rfc-blake3zmq.git
+git clone https://github.com/paddor/omq-rfc-channel.git
+git clone https://github.com/paddor/omq-rfc-clientserver.git
+git clone https://github.com/paddor/omq-rfc-p2p.git
+git clone https://github.com/paddor/omq-rfc-qos.git
+git clone https://github.com/paddor/omq-rfc-radiodish.git
+git clone https://github.com/paddor/omq-rfc-scattergather.git
+git clone https://github.com/paddor/omq-ffi.git
+git clone https://github.com/paddor/omq-ractor.git
+
+cd omq
+OMQ_DEV=1 bundle install
+OMQ_DEV=1 bundle exec rake
+```
+
 ## License
 
 [ISC](LICENSE)

data/lib/omq/drop_queue.rb

@@ -18,6 +18,7 @@ module OMQ
       @strategy = strategy
     end
 
+
     # Enqueues an item. Drops according to the configured strategy if full.
     #
     # @param item [Object]
@@ -33,6 +34,7 @@ module OMQ
       retry
     end
 
+
     # Removes and returns the next item, blocking if empty.
     #
     # @return [Object]
@@ -45,6 +47,7 @@ module OMQ
       end
     end
 
+
     # @return [Boolean]
     #
     def empty?

data/lib/omq/engine/connection_setup.rb

@@ -13,34 +13,57 @@ module OMQ
       # @return [Connection]
       #
       def self.run(io, engine, as_server:, endpoint: nil, done: nil)
-        conn = build_connection(io, engine, as_server)
+        new(engine).run(io, as_server: as_server, endpoint: endpoint, done: done)
+      end
+
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine = engine
+      end
+
+
+      # Performs the ZMTP handshake, starts heartbeat, and registers the connection.
+      #
+      # @param io [#read, #write, #close]
+      # @param as_server [Boolean]
+      # @param endpoint [String, nil]
+      # @param done [Async::Promise, nil] resolved when connection is lost
+      # @return [Connection]
+      #
+      def run(io, as_server:, endpoint: nil, done: nil)
+        conn = build_connection(io, as_server)
         conn.handshake!
-        Heartbeat.start(engine.parent_task, conn, engine.options, engine.tasks)
-        conn = engine.connection_wrapper.call(conn) if engine.connection_wrapper
-        register(conn, engine, endpoint, done)
-        engine.emit_monitor_event(:handshake_succeeded, endpoint: endpoint)
+        Heartbeat.start(@engine.parent_task, conn, @engine.options, @engine.tasks)
+        conn = @engine.connection_wrapper.call(conn) if @engine.connection_wrapper
+        register(conn, endpoint, done)
+        @engine.emit_monitor_event(:handshake_succeeded, endpoint: endpoint)
         conn
       rescue Protocol::ZMTP::Error, *CONNECTION_LOST => error
-        engine.emit_monitor_event(:handshake_failed, endpoint: endpoint, detail: { error: error })
+        @engine.emit_monitor_event(:handshake_failed, endpoint: endpoint, detail: { error: error })
         conn&.close
         raise
       end
 
-      def self.build_connection(io, engine, as_server)
+      private
+
+      def build_connection(io, as_server)
         Protocol::ZMTP::Connection.new(
           io,
-          socket_type:      engine.socket_type.to_s,
-          identity:         engine.options.identity,
+          socket_type:      @engine.socket_type.to_s,
+          identity:         @engine.options.identity,
           as_server:        as_server,
-          mechanism:        engine.options.mechanism&.dup,
-          max_message_size: engine.options.max_message_size,
+          mechanism:        @engine.options.mechanism&.dup,
+          max_message_size: @engine.options.max_message_size,
         )
       end
 
-      def self.register(conn, engine, endpoint, done)
-        engine.connections[conn] = Engine::ConnectionRecord.new(endpoint: endpoint, done: done)
-        engine.routing.connection_added(conn)
-        engine.peer_connected.resolve(conn)
+
+      def register(conn, endpoint, done)
+        @engine.connections[conn] = Engine::ConnectionRecord.new(endpoint: endpoint, done: done)
+        @engine.routing.connection_added(conn)
+        @engine.peer_connected.resolve(conn)
       end
     end
   end

data/lib/omq/engine/heartbeat.rb

@@ -7,7 +7,7 @@ module OMQ
     # Sends PING frames at +interval+ seconds and closes the connection
     # if no traffic is seen within +timeout+ seconds.
     #
-    class Heartbeat
+    module Heartbeat
       # @param parent_task [Async::Task]
       # @param conn [Connection]
       # @param options [Options]

data/lib/omq/engine/maintenance.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "async/loop"
+
+module OMQ
+  class Engine
+    # Spawns a periodic maintenance task for the parent mechanism.
+    #
+    # The mechanism declares maintenance needs via +#maintenance+,
+    # which returns +{ interval:, task: }+ or nil.
+    #
+    module Maintenance
+      # @param parent_task [Async::Task]
+      # @param mechanism [#maintenance, nil]
+      # @param tasks [Array<Async::Task>]
+      #
+      def self.start(parent_task, mechanism, tasks)
+        return unless mechanism.respond_to?(:maintenance)
+        spec = mechanism.maintenance
+        return unless spec
+
+        interval = spec[:interval]
+        callable = spec[:task]
+
+        tasks << parent_task.async(transient: true, annotation: "mechanism maintenance") do
+          Async::Loop.quantized(interval: interval) do
+            callable.call
+          end
+        rescue Async::Stop
+          # clean shutdown
+        end
+      end
+    end
+  end
+end

data/lib/omq/engine/reconnect.rb

@@ -11,33 +11,57 @@ module OMQ
       # @param endpoint [String]
       # @param options [Options]
       # @param parent_task [Async::Task]
-      # @param engine [Engine] for transport_for / emit_monitor_event / signal_fatal_error / closed?
+      # @param engine [Engine]
       # @param delay [Numeric, nil] initial delay (defaults to reconnect_interval)
       #
       def self.schedule(endpoint, options, parent_task, engine, delay: nil)
-        ri = options.reconnect_interval
-        delay, max_delay = init_delay(ri, delay)
+        new(engine, endpoint, options).run(parent_task, delay: delay)
+      end
+
+
+      # @param engine [Engine]
+      # @param endpoint [String]
+      # @param options [Options]
+      #
+      def initialize(engine, endpoint, options)
+        @engine   = engine
+        @endpoint = endpoint
+        @options  = options
+      end
 
-        engine.tasks << parent_task.async(transient: true, annotation: "reconnect #{endpoint}") do
+
+      # Spawns a background task that retries the connection with exponential backoff.
+      #
+      # @param parent_task [Async::Task]
+      # @param delay [Numeric, nil] initial delay override
+      # @return [void]
+      #
+      def run(parent_task, delay: nil)
+        delay, max_delay = init_delay(delay)
+
+        @engine.tasks << parent_task.async(transient: true, annotation: "reconnect #{@endpoint}") do
           loop do
-            break if engine.closed?
+            break if @engine.closed?
             sleep delay if delay > 0
-            break if engine.closed?
+            break if @engine.closed?
             begin
-              engine.transport_for(endpoint).connect(endpoint, engine)
+              @engine.transport_for(@endpoint).connect(@endpoint, @engine)
               break
             rescue *CONNECTION_LOST, *CONNECTION_FAILED, Protocol::ZMTP::Error
-              delay = next_delay(delay, max_delay, ri)
-              engine.emit_monitor_event(:connect_retried, endpoint: endpoint, detail: { interval: delay })
+              delay = next_delay(delay, max_delay)
+              @engine.emit_monitor_event(:connect_retried, endpoint: @endpoint, detail: { interval: delay })
             end
           end
         rescue Async::Stop
         rescue => error
-          engine.signal_fatal_error(error)
+          @engine.signal_fatal_error(error)
         end
       end
 
-      def self.init_delay(ri, delay)
+      private
+
+      def init_delay(delay)
+        ri = @options.reconnect_interval
         if ri.is_a?(Range)
           [delay || ri.begin, ri.end]
         else
@@ -45,7 +69,9 @@ module OMQ
         end
       end
 
-      def self.next_delay(delay, max_delay, ri)
+
+      def next_delay(delay, max_delay)
+        ri    = @options.reconnect_interval
         delay = delay * 2
         delay = [delay, max_delay].min if max_delay
         delay = (ri.is_a?(Range) ? ri.begin : ri) if delay == 0

data/lib/omq/engine/recv_pump.rb

@@ -2,73 +2,116 @@
 
 module OMQ
   class Engine
-    # Starts a recv pump for a connection.
+    # Recv pump for a connection.
     #
     # For inproc DirectPipe: wires the direct recv path (no fiber spawned).
     # For TCP/IPC: spawns a transient task that reads messages from the
     # connection and enqueues them into +recv_queue+.
     #
-    # The two-branch structure (with/without transform) is intentional for
+    # The two-method structure (with/without transform) is intentional for
     # YJIT: it gives the JIT a monomorphic call per routing strategy instead
     # of a megamorphic `transform.call` dispatch inside a shared loop.
     #
-    # @param parent_task [Async::Task]
-    # @param conn [Connection, Transport::Inproc::DirectPipe]
-    # @param recv_queue [SignalingQueue]
-    # @param engine [Engine] for connection_lost / signal_fatal_error callbacks
-    # @param transform [Proc, nil]
-    # @return [Async::Task, nil]
-    #
     class RecvPump
       FAIRNESS_MESSAGES = 64
       FAIRNESS_BYTES    = 1 << 20 # 1 MB
 
+
+      # Public entry point — callers use the class method.
+      #
+      # @param parent_task [Async::Task]
+      # @param conn [Connection, Transport::Inproc::DirectPipe]
+      # @param recv_queue [SignalingQueue]
+      # @param engine [Engine]
+      # @param transform [Proc, nil]
+      # @return [Async::Task, nil]
+      #
       def self.start(parent_task, conn, recv_queue, engine, transform)
-        if conn.is_a?(Transport::Inproc::DirectPipe) && conn.peer
-          conn.peer.direct_recv_queue     = recv_queue
-          conn.peer.direct_recv_transform = transform
+        new(conn, recv_queue, engine).start(parent_task, transform)
+      end
+
+
+      # @param conn [Connection, Transport::Inproc::DirectPipe]
+      # @param recv_queue [Routing::SignalingQueue]
+      # @param engine [Engine]
+      #
+      def initialize(conn, recv_queue, engine)
+        @conn        = conn
+        @recv_queue  = recv_queue
+        @engine      = engine
+        @count_bytes = conn.instance_of?(Protocol::ZMTP::Connection)
+      end
+
+
+      # Starts the recv pump. For inproc DirectPipe, wires the direct path
+      # (no task spawned). For TCP/IPC, spawns a fiber that reads messages.
+      #
+      # @param parent_task [Async::Task]
+      # @param transform [Proc, nil] optional per-message transform
+      # @return [Async::Task, nil]
+      #
+      def start(parent_task, transform)
+        if @conn.is_a?(Transport::Inproc::DirectPipe) && @conn.peer
+          @conn.peer.direct_recv_queue     = @recv_queue
+          @conn.peer.direct_recv_transform = transform
           return nil
         end
 
         if transform
-          parent_task.async(transient: true, annotation: "recv pump") do |task|
-            loop do
-              count = 0
-              bytes = 0
-              while count < FAIRNESS_MESSAGES && bytes < FAIRNESS_BYTES
-                msg = conn.receive_message
-                msg = transform.call(msg).freeze
-                recv_queue.enqueue(msg)
-                count += 1
-                bytes += msg.is_a?(Array) && msg.first.is_a?(String) ? msg.sum(&:bytesize) : 0
-              end
-              task.yield
+          start_with_transform(parent_task, transform)
+        else
+          start_direct(parent_task)
+        end
+      end
+
+      private
+
+
+      def start_with_transform(parent_task, transform)
+        conn, recv_queue, count_bytes = @conn, @recv_queue, @count_bytes
+
+        parent_task.async(transient: true, annotation: "recv pump") do |task|
+          loop do
+            count = 0
+            bytes = 0
+            while count < FAIRNESS_MESSAGES && bytes < FAIRNESS_BYTES
+              msg = conn.receive_message
+              msg = transform.call(msg).freeze
+              recv_queue.enqueue(msg)
+              count += 1
+              bytes += msg.sum(&:bytesize) if count_bytes
             end
-          rescue Async::Stop
-          rescue Protocol::ZMTP::Error, *CONNECTION_LOST
-            engine.connection_lost(conn)
-          rescue => error
-            engine.signal_fatal_error(error)
+            task.yield
           end
-        else
-          parent_task.async(transient: true, annotation: "recv pump") do |task|
-            loop do
-              count = 0
-              bytes = 0
-              while count < FAIRNESS_MESSAGES && bytes < FAIRNESS_BYTES
-                msg = conn.receive_message
-                recv_queue.enqueue(msg)
-                count += 1
-                bytes += msg.is_a?(Array) && msg.first.is_a?(String) ? msg.sum(&:bytesize) : 0
-              end
-              task.yield
+        rescue Async::Stop
+        rescue Protocol::ZMTP::Error, *CONNECTION_LOST
+          @engine.connection_lost(conn)
+        rescue => error
+          @engine.signal_fatal_error(error)
+        end
+      end
+
+
+      def start_direct(parent_task)
+        conn, recv_queue, count_bytes = @conn, @recv_queue, @count_bytes
+
+        parent_task.async(transient: true, annotation: "recv pump") do |task|
+          loop do
+            count = 0
+            bytes = 0
+            while count < FAIRNESS_MESSAGES && bytes < FAIRNESS_BYTES
+              msg = conn.receive_message
+              recv_queue.enqueue(msg)
+              count += 1
+              bytes += msg.sum(&:bytesize) if count_bytes
             end
-          rescue Async::Stop
-          rescue Protocol::ZMTP::Error, *CONNECTION_LOST
-            engine.connection_lost(conn)
-          rescue => error
-            engine.signal_fatal_error(error)
+            task.yield
           end
+        rescue Async::Stop
+        rescue Protocol::ZMTP::Error, *CONNECTION_LOST
+          @engine.connection_lost(conn)
+        rescue => error
+          @engine.signal_fatal_error(error)
         end
       end
     end

data/lib/omq/engine.rb

@@ -5,6 +5,7 @@ require_relative "engine/recv_pump"
 require_relative "engine/heartbeat"
 require_relative "engine/reconnect"
 require_relative "engine/connection_setup"
+require_relative "engine/maintenance"
 
 module OMQ
   # Per-socket orchestrator.
@@ -23,6 +24,7 @@ module OMQ
       attr_reader :transports
     end
 
+
     # Per-connection metadata: the endpoint it was established on and an
     # optional Promise resolved when the connection is lost (used by
     # {#spawn_connection} to await connection teardown).
@@ -79,10 +81,23 @@ module OMQ
     end
 
 
+    # @return [Async::Promise] resolves when first peer completes handshake
+    # @return [Async::Promise] resolves when all peers disconnect (after having had peers)
+    # @return [Hash{Connection => ConnectionRecord}] active connections
+    # @return [Async::Task, nil] root task for spawning subtrees
+    # @return [Array<Async::Task>] background tasks (pumps, heartbeat, reconnect)
+    #
     attr_reader :peer_connected, :all_peers_gone, :connections, :parent_task, :tasks
 
+    # @!attribute [w] reconnect_enabled
+    #   @param value [Boolean] enable or disable auto-reconnect
+    # @!attribute [w] monitor_queue
+    #   @param value [Async::Queue, nil] queue for monitor events
+    #
     attr_writer :reconnect_enabled, :monitor_queue
 
+    # @return [Boolean] true if the engine has been closed
+    #
     def closed? = @state == :closed
 
     # Optional proc that wraps new connections (e.g. for serialization).
@@ -371,15 +386,30 @@ module OMQ
         @on_io_thread = true
         Reactor.track_linger(@options.linger)
       end
+      Maintenance.start(@parent_task, @options.mechanism, @tasks)
     end
 
 
+    # Emits a lifecycle event to the monitor queue, if one is attached.
+    #
+    # @param type [Symbol] event type (e.g. :listening, :connected, :disconnected)
+    # @param endpoint [String, nil] the endpoint involved
+    # @param detail [Hash, nil] extra context
+    # @return [void]
+    #
     def emit_monitor_event(type, endpoint: nil, detail: nil)
       return unless @monitor_queue
       @monitor_queue.push(MonitorEvent.new(type: type, endpoint: endpoint, detail: detail))
     rescue Async::Stop, ClosedQueueError
     end
 
+
+    # Looks up the transport module for an endpoint URI.
+    #
+    # @param endpoint [String] endpoint URI (e.g. "tcp://...", "inproc://...")
+    # @return [Module] the transport module
+    # @raise [ArgumentError] if the scheme is not registered
+    #
     def transport_for(endpoint)
       scheme = endpoint[/\A([^:]+):\/\//, 1]
       self.class.transports[scheme] or
@@ -401,6 +431,7 @@ module OMQ
       @tasks << task if task
     end
 
+
     def drain_send_queues(timeout)
       return unless @routing.respond_to?(:send_queues_drained?)
       deadline = timeout ? Async::Clock.now + timeout : nil
@@ -410,21 +441,25 @@ module OMQ
       end
     end
 
+
     def maybe_reconnect(endpoint)
       return unless endpoint && @dialed.include?(endpoint)
       return unless @state == :open && @reconnect_enabled
       Reconnect.schedule(endpoint, @options, @parent_task, self)
     end
 
+
     def schedule_reconnect(endpoint, delay: nil)
       Reconnect.schedule(endpoint, @options, @parent_task, self, delay: delay)
     end
 
+
     def validate_endpoint!(endpoint)
       transport = transport_for(endpoint)
       transport.validate_endpoint!(endpoint) if transport.respond_to?(:validate_endpoint!)
     end
 
+
     def start_accept_loops(listener)
       return unless listener.respond_to?(:start_accept_loops)
       listener.start_accept_loops(@parent_task) do |io|
@@ -432,16 +467,19 @@ module OMQ
       end
     end
 
+
     def stop_listeners
       @listeners.each(&:stop)
       @listeners.clear
     end
 
+
     def close_connections
       @connections.each_key(&:close)
       @connections.clear
     end
 
+
     def close_connections_at(endpoint)
       conns = @connections.filter_map { |conn, e| conn if e.endpoint == endpoint }
       conns.each do |conn|
@@ -451,24 +489,28 @@ module OMQ
       end
     end
 
+
     def stop_tasks
       @routing.stop rescue nil
       @tasks.each { |t| t.stop rescue nil }
       @tasks.clear
     end
 
+
     def freeze_error_lists!
       return if OMQ::CONNECTION_LOST.frozen?
       OMQ::CONNECTION_LOST.freeze
       OMQ::CONNECTION_FAILED.freeze
     end
 
+
     def close_monitor_queue
       return unless @monitor_queue
       @monitor_queue.push(nil)
     end
   end
 
+
   # Register built-in transports.
   Engine.transports["tcp"]    = Transport::TCP
   Engine.transports["ipc"]    = Transport::IPC