omq 0.4.2 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dc74658712882f8d0eb8f58b0c9a37c959d50c87116677d23be39904f7002e7
-  data.tar.gz: 1ba17796cac6b1cd594ebbee874428e0675153d461d168e0f69f07abab608ef8
+  metadata.gz: 76cecd3650f9fb73d699a027570421f589452a40cf6bbf207af02afb2bc6df08
+  data.tar.gz: 0252e01bacd5278defe46ed9ab4750b3e33ca71e928beb13f1092c23a7c2ce62
 SHA512:
-  metadata.gz: 3628a755a53010690ae407ac790eb83ef7592ac5cac34bddff8a62782c20cb6092c3dd300ae71a2dfff324eaf8457ba319305b6892ca259f8990ce63267c74e0
-  data.tar.gz: 76502cad1a484cf8224285fbf4259e9ba8e5daa396caa42ac3716b50ada2e72a4c31b8d256208ab7410f5e48727216fee526efbf6166e3a1a32bb7bc1701cacb
+  metadata.gz: de2508cbe4e22c6dc93bdeab4626fed0c5280cf74eaaf4c4f886f566719a3c732f5db9b766c201f7e9d6eb7bb00ee4ed2d2392eec232abe88c7847148b889fc5
+  data.tar.gz: 65e96cef70697abe90588e5e35f4563e55ef183bb0be44276c6cb62ec007f6accb4e482a08c14d89b15ec3f542d75c78bacc87c6174ca6f4e69b588ddb540730

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.5.1 — 2026-03-28
+
+### Improved
+
+- **3–4x throughput under burst load** — send pumps now batch writes
+  before flushing. `Connection#write_message` buffers without flushing;
+  `Connection#flush` triggers the syscall. Pumps drain all queued messages
+  per cycle, reducing flush count from `N_msgs × N_conns` to `N_conns`
+  per batch. PUB/SUB TCP with 10 subscribers: 2.3k → 9.2k msg/s (**4x**).
+  PUSH/PULL TCP: 24k → 83k msg/s (**3.4x**). Zero overhead under light
+  load (batch of 1 = same path as before).
+
+- **Simplified Reactor IO thread** — replaced `Thread::Queue` + `IO.pipe`
+  wake signal with a single `Async::Queue`. `Thread::Queue#pop` is
+  fiber-scheduler-aware in Ruby 4.0, so the pipe pair was unnecessary.
+
+### Fixed
+
+- **`router_mandatory` SocketError raised in send pump** — the error
+  killed the pump fiber instead of reaching the caller. Now checked
+  synchronously in `enqueue` before queuing.
+
+## 0.5.0 — 2026-03-28
+
+### Added
+
+- **Draft socket types** (RFCs 41, 48, 49, 51, 52):
+  - `CLIENT`/`SERVER` — thread-safe REQ/REP without envelope, 4-byte routing IDs
+  - `RADIO`/`DISH` — group-based pub/sub with exact match, JOIN/LEAVE commands.
+    `radio.publish(group, body)`, `radio.send(body, group:)`, `radio << [group, body]`
+  - `SCATTER`/`GATHER` — thread-safe PUSH/PULL
+  - `PEER` — bidirectional multi-peer with 4-byte routing IDs
+  - `CHANNEL` — thread-safe PAIR
+- All draft types enforce single-frame messages (no multipart)
+- Reconnect-after-restart tests for all 10 socket type pairings
+
+### Fixed
+
+- **PUSH/SCATTER silently wrote to dead peers** — write-only sockets had
+  no recv pump to detect peer disconnection. Writes succeeded because the
+  kernel send buffer absorbed the data, preventing reconnect from
+  triggering. Added background monitor task per connection.
+- **PAIR/CHANNEL stale send pump after reconnect** — old send pump kept
+  its captured connection reference and raced with the new send pump,
+  sending to the dead connection. Now stopped in `connection_removed`.
+
 ## 0.4.2 — 2026-03-27
 
 ### Fixed

data/README.md

@@ -18,7 +18,7 @@ Pure Ruby implementation of the [ZMTP 3.1](https://rfc.zeromq.org/spec/23/) wire
 ## Highlights
 
 - **Pure Ruby** — no C extensions, no FFI, no libzmq/libczmq dependency
-- **All socket types** — req/rep, pub/sub, push/pull, dealer/router, xpub/xsub, pair
+- **All socket types** — req/rep, pub/sub, push/pull, dealer/router, xpub/xsub, pair + draft types (client/server, radio/dish, scatter/gather, peer, channel)
 - **Async-native** — built on [Async](https://github.com/socketry/async) fibers, also works with plain threads
 - **Ruby-idiomatic API** — messages as `Array<String>`, errors as exceptions, timeouts as `IO::TimeoutError`
 - **All transports** — tcp, ipc, inproc
@@ -112,6 +112,11 @@ end
 | Pipeline | `PUSH`, `PULL` | unidirectional |
 | Routing | `DEALER`, `ROUTER` | bidirectional |
 | Exclusive pair | `PAIR` | bidirectional |
+| Client/Server | `CLIENT`, `SERVER` | bidirectional |
+| Group messaging | `RADIO`, `DISH` | unidirectional |
+| Pipeline (draft) | `SCATTER`, `GATHER` | unidirectional |
+| Peer-to-peer | `PEER` | bidirectional |
+| Channel (draft) | `CHANNEL` | bidirectional |
 
 All classes live under `OMQ::`. For the purists, `ØMQ` is an alias:
 

data/lib/omq/channel.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module OMQ
+  class CHANNEL < Socket
+    include ZMTP::Readable
+    include ZMTP::Writable
+    include ZMTP::SingleFrame
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:CHANNEL, linger: linger)
+      _attach(endpoints, default: :connect)
+    end
+  end
+end

data/lib/omq/client_server.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module OMQ
+  class CLIENT < Socket
+    include ZMTP::Readable
+    include ZMTP::Writable
+    include ZMTP::SingleFrame
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:CLIENT, linger: linger)
+      _attach(endpoints, default: :connect)
+    end
+  end
+
+  class SERVER < Socket
+    include ZMTP::Readable
+    include ZMTP::Writable
+    include ZMTP::SingleFrame
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:SERVER, linger: linger)
+      _attach(endpoints, default: :bind)
+    end
+
+    # Sends a message to a specific peer by routing ID.
+    #
+    # @param routing_id [String] 4-byte routing ID
+    # @param message [String] message body
+    # @return [self]
+    #
+    def send_to(routing_id, message)
+      parts = [routing_id.b.freeze, message.b.freeze]
+      with_timeout(@options.write_timeout) { @engine.enqueue_send(parts) }
+      self
+    end
+  end
+end

data/lib/omq/peer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module OMQ
+  class PEER < Socket
+    include ZMTP::Readable
+    include ZMTP::Writable
+    include ZMTP::SingleFrame
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:PEER, linger: linger)
+      _attach(endpoints, default: :connect)
+    end
+
+    # Sends a message to a specific peer by routing ID.
+    #
+    # @param routing_id [String] 4-byte routing ID
+    # @param message [String] message body
+    # @return [self]
+    #
+    def send_to(routing_id, message)
+      parts = [routing_id.b.freeze, message.b.freeze]
+      with_timeout(@options.write_timeout) { @engine.enqueue_send(parts) }
+      self
+    end
+  end
+end

data/lib/omq/radio_dish.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module OMQ
+  class RADIO < Socket
+    include ZMTP::Writable
+
+    def initialize(endpoints = nil, linger: 0)
+      _init_engine(:RADIO, linger: linger)
+      _attach(endpoints, default: :bind)
+    end
+
+    # Publishes a message to a group.
+    #
+    # @param group [String] group name
+    # @param body [String] message body
+    # @return [self]
+    #
+    def publish(group, body)
+      with_timeout(@options.write_timeout) do
+        @engine.enqueue_send([group.b.freeze, body.b.freeze])
+      end
+      self
+    end
+
+    # Sends a message to a group.
+    #
+    # @param message [String] message body (requires group: kwarg)
+    # @param group [String] group name
+    # @return [self]
+    #
+    def send(message, group: nil)
+      raise ArgumentError, "RADIO requires a group (use group: kwarg, publish, or << [group, body])" unless group
+      publish(group, message)
+    end
+
+    # Sends a message to a group via [group, body] array.
+    #
+    # @param message [Array<String>] [group, body]
+    # @return [self]
+    #
+    def <<(message)
+      raise ArgumentError, "RADIO requires [group, body] array" unless message.is_a?(Array) && message.size == 2
+      publish(message[0], message[1])
+    end
+  end
+
+  class DISH < Socket
+    include ZMTP::Readable
+
+    def initialize(endpoints = nil, linger: 0, group: nil)
+      _init_engine(:DISH, linger: linger)
+      _attach(endpoints, default: :connect)
+      join(group) if group
+    end
+
+    # Joins a group.
+    #
+    # @param group [String]
+    # @return [void]
+    #
+    def join(group)
+      @engine.routing.join(group)
+    end
+
+    # Leaves a group.
+    #
+    # @param group [String]
+    # @return [void]
+    #
+    def leave(group)
+      @engine.routing.leave(group)
+    end
+  end
+end

data/lib/omq/scatter_gather.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OMQ
+  class SCATTER < Socket
+    include ZMTP::Writable
+    include ZMTP::SingleFrame
+
+    def initialize(endpoints = nil, linger: 0, send_hwm: nil, send_timeout: nil)
+      _init_engine(:SCATTER, linger: linger, send_hwm: send_hwm, send_timeout: send_timeout)
+      _attach(endpoints, default: :connect)
+    end
+  end
+
+  class GATHER < Socket
+    include ZMTP::Readable
+    include ZMTP::SingleFrame
+
+    def initialize(endpoints = nil, linger: 0, recv_hwm: nil, recv_timeout: nil)
+      _init_engine(:GATHER, linger: linger, recv_hwm: recv_hwm, recv_timeout: recv_timeout)
+      _attach(endpoints, default: :bind)
+    end
+  end
+end

data/lib/omq/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OMQ
-  VERSION = "0.4.2"
+  VERSION = "0.5.1"
 end

data/lib/omq/zmtp/codec/command.rb

@@ -101,6 +101,24 @@ module OMQ
           new("CANCEL", prefix.b)
         end
 
+        # Builds a JOIN command (RADIO/DISH group subscription).
+        #
+        # @param group [String] group name
+        # @return [Command]
+        #
+        def self.join(group)
+          new("JOIN", group.b)
+        end
+
+        # Builds a LEAVE command (RADIO/DISH group unsubscription).
+        #
+        # @param group [String] group name
+        # @return [Command]
+        #
+        def self.leave(group)
+          new("LEAVE", group.b)
+        end
+
         # Builds a PING command.
         #
         # @param ttl [Numeric] time-to-live in seconds (sent as deciseconds)

data/lib/omq/zmtp/connection.rb

@@ -77,21 +77,36 @@ module OMQ
         end
       end
 
-      # Sends a multi-frame message.
+      # Sends a multi-frame message (write + flush).
       #
       # @param parts [Array<String>] message frames
       # @return [void]
       #
       def send_message(parts)
         @mutex.synchronize do
-          parts.each_with_index do |part, i|
-            more = i < parts.size - 1
-            if @mechanism.encrypted?
-              @io.write(@mechanism.encrypt(part.b, more: more))
-            else
-              @io.write(Codec::Frame.new(part, more: more).to_wire)
-            end
-          end
+          write_frames(parts)
+          @io.flush
+        end
+      end
+
+      # Writes a multi-frame message to the buffer without flushing.
+      # Call {#flush} after batching writes.
+      #
+      # @param parts [Array<String>] message frames
+      # @return [void]
+      #
+      def write_message(parts)
+        @mutex.synchronize do
+          write_frames(parts)
+        end
+      end
+
+      # Flushes the write buffer to the underlying IO.
+      #
+      # @return [void]
+      #
+      def flush
+        @mutex.synchronize do
           @io.flush
         end
       end
@@ -213,6 +228,17 @@ module OMQ
 
       private
 
+      def write_frames(parts)
+        parts.each_with_index do |part, i|
+          more = i < parts.size - 1
+          if @mechanism.encrypted?
+            @io.write(@mechanism.encrypt(part.b, more: more))
+          else
+            @io.write(Codec::Frame.new(part, more: more).to_wire)
+          end
+        end
+      end
+
       def touch_heartbeat
         @last_received_at = monotonic_now if @heartbeat_interval
       end

data/lib/omq/zmtp/reactor.rb

@@ -12,11 +12,9 @@ module OMQ
     # tasks — mirroring libzmq's IO thread architecture.
     #
     module Reactor
-      @work_queue = Thread::Queue.new
+      @work_queue = Async::Queue.new
       @thread     = nil
       @mutex      = Mutex.new
-      @wake_r     = nil
-      @wake_w     = nil
 
       class << self
         # Spawns a pump task (recv loop, send loop, accept loop).
@@ -33,7 +31,6 @@ module OMQ
             handle = PumpHandle.new
             ensure_started
             @work_queue.push([:spawn, block, handle])
-            @wake_w.write_nonblock(".") rescue nil
             handle
           end
         end
@@ -52,7 +49,6 @@ module OMQ
             result_queue = Thread::Queue.new
             ensure_started
             @work_queue.push([:run, block, result_queue])
-            @wake_w.write_nonblock(".") rescue nil
             status, value = result_queue.pop
             raise value if status == :error
             value
@@ -66,9 +62,8 @@ module OMQ
         def ensure_started
           @mutex.synchronize do
             return if @thread&.alive?
-            @wake_r, @wake_w = IO.pipe
             ready = Thread::Queue.new
-            @thread = Thread.new { run_reactor(ready, @wake_r) }
+            @thread = Thread.new { run_reactor(ready) }
             @thread.name = "omq-io"
             ready.pop
           end
@@ -80,42 +75,31 @@ module OMQ
         #
         def stop!
           @work_queue.push([:stop])
-          @wake_w&.write_nonblock(".") rescue nil
           @thread&.join(2)
           @thread = nil
-          @wake_r&.close rescue nil
-          @wake_w&.close rescue nil
-          @wake_r = nil
-          @wake_w = nil
         end
 
         private
 
-        def run_reactor(ready, wake_r)
+        def run_reactor(ready)
           Async do |task|
             ready.push(true)
             loop do
-              # Wait for wakeup signal (non-blocking for Async scheduler)
-              wake_r.wait_readable
-              wake_r.read_nonblock(256) rescue nil
-
-              # Drain all pending work items
-              while (item = @work_queue.pop(true) rescue nil)
-                case item[0]
-                when :spawn
-                  _, block, handle = item
-                  async_task = task.async(transient: true, &block)
-                  handle.task = async_task
-                when :run
-                  _, block, result_queue = item
-                  task.async do
-                    result_queue.push([:ok, block.call])
-                  rescue => e
-                    result_queue.push([:error, e])
-                  end
-                when :stop
-                  return
+              item = @work_queue.dequeue
+              case item[0]
+              when :spawn
+                _, block, handle = item
+                async_task = task.async(transient: true, &block)
+                handle.task = async_task
+              when :run
+                _, block, result_queue = item
+                task.async do
+                  result_queue.push([:ok, block.call])
+                rescue => e
+                  result_queue.push([:error, e])
                 end
+              when :stop
+                return
               end
             end
           end

data/lib/omq/zmtp/routing/channel.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # CHANNEL socket routing: exclusive 1-to-1 bidirectional.
+      #
+      class Channel
+
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine     = engine
+          @connection = nil
+          @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+          @send_queue = Async::LimitedQueue.new(engine.options.send_hwm)
+          @tasks      = []
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :recv_queue, :send_queue
+
+        # @param connection [Connection]
+        # @raise [RuntimeError] if a connection already exists
+        #
+        def connection_added(connection)
+          raise "CHANNEL allows only one peer" if @connection
+          @connection = connection
+          task = @engine.start_recv_pump(connection, @recv_queue)
+          @tasks << task if task
+          start_send_pump(connection)
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_removed(connection)
+          if @connection == connection
+            @connection = nil
+            @send_pump&.stop
+            @send_pump = nil
+          end
+        end
+
+        # @param parts [Array<String>]
+        #
+        def enqueue(parts)
+          @send_queue.enqueue(parts)
+        end
+
+        #
+        def stop
+          @tasks.each(&:stop)
+          @tasks.clear
+        end
+
+        private
+
+        def start_send_pump(conn)
+          @send_pump = Reactor.spawn_pump do
+            loop do
+              batch = [@send_queue.dequeue]
+              Routing.drain_send_queue(@send_queue, batch)
+              batch.each { |parts| conn.write_message(parts) }
+              conn.flush
+            end
+          rescue *ZMTP::CONNECTION_LOST
+            @engine.connection_lost(conn)
+          end
+          @tasks << @send_pump
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/routing/client.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # CLIENT socket routing: round-robin send, fair-queue receive.
+      #
+      # Same as DEALER — no envelope manipulation.
+      #
+      class Client
+        include RoundRobin
+
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine     = engine
+          @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+          @tasks      = []
+          init_round_robin(engine)
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :recv_queue, :send_queue
+
+        # @param connection [Connection]
+        #
+        def connection_added(connection)
+          @connections << connection
+          signal_connection_available
+          task = @engine.start_recv_pump(connection, @recv_queue)
+          @tasks << task if task
+          start_send_pump unless @send_pump_started
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_removed(connection)
+          @connections.delete(connection)
+        end
+
+        # @param parts [Array<String>]
+        #
+        def enqueue(parts)
+          @send_queue.enqueue(parts)
+        end
+
+        #
+        def stop
+          @tasks.each(&:stop)
+          @tasks.clear
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/routing/dish.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # DISH socket routing: group-based receive from RADIO peers.
+      #
+      # Sends JOIN/LEAVE commands to connected RADIO peers.
+      # Receives two-frame messages (group + body) from RADIO.
+      #
+      class Dish
+
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine      = engine
+          @connections = []
+          @recv_queue  = Async::LimitedQueue.new(engine.options.recv_hwm)
+          @groups      = Set.new
+          @tasks       = []
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :recv_queue
+
+        # @param connection [Connection]
+        #
+        def connection_added(connection)
+          @connections << connection
+          # Send existing group memberships to new peer
+          @groups.each do |group|
+            connection.send_command(Codec::Command.join(group))
+          end
+          task = @engine.start_recv_pump(connection, @recv_queue)
+          @tasks << task if task
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_removed(connection)
+          @connections.delete(connection)
+        end
+
+        # DISH is read-only.
+        #
+        def enqueue(_parts)
+          raise "DISH sockets cannot send"
+        end
+
+        # Joins a group.
+        #
+        # @param group [String]
+        #
+        def join(group)
+          @groups << group
+          @connections.each do |conn|
+            conn.send_command(Codec::Command.join(group))
+          end
+        end
+
+        # Leaves a group.
+        #
+        # @param group [String]
+        #
+        def leave(group)
+          @groups.delete(group)
+          @connections.each do |conn|
+            conn.send_command(Codec::Command.leave(group))
+          end
+        end
+
+        def stop
+          @tasks.each(&:stop)
+          @tasks.clear
+        end
+      end
+    end
+  end
+end