omq-draft 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 227c70413e95a09337fe74eff2c92393a218456aa16c75cb45bd2312cedf08af
+  data.tar.gz: 14345eedca4ea644f478fb3c2538a06f93eb8bf387f7a9f3a2664aace0022aad
+SHA512:
+  metadata.gz: 75cea8ecb3cd08f469897a0ceeef2bac1bc6c087b0cf3b5f60b77bc2ce53891338f62fcddb3cf024077565b30383badfe8b8ecfb1950fb8d9d740a39c4040b7f
+  data.tar.gz: 5f691e089cdaa0010955948bd722f844768a1e678dce56d5fd75da7b795a6b6fdadd782b84c751647979a68f0b7b1969fff39aad7e2fc9c8dd88bbded1314ff9

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,58 @@
+# omq-draft
+
+Draft ZMQ socket types for [OMQ](https://github.com/zeromq/omq) — the pure Ruby ZeroMQ library.
+
+Implements the ZeroMQ draft RFCs as opt-in, separately loadable modules:
+
+| Require | Socket types | Transport |
+|---|---|---|
+| `omq/draft/radiodish` | `OMQ::RADIO`, `OMQ::DISH` | TCP, IPC, inproc, **UDP** |
+| `omq/draft/clientserver` | `OMQ::CLIENT`, `OMQ::SERVER` | TCP, IPC, inproc |
+| `omq/draft/scattergather` | `OMQ::SCATTER`, `OMQ::GATHER` | TCP, IPC, inproc |
+| `omq/draft/channel` | `OMQ::CHANNEL` | TCP, IPC, inproc |
+| `omq/draft/p2p` | `OMQ::PEER` | TCP, IPC, inproc |
+
+## Installation
+
+```ruby
+gem "omq-draft"
+```
+
+## Usage
+
+Load only the socket types you need:
+
+```ruby
+require "omq/draft/radiodish"
+
+radio = OMQ::RADIO.connect("udp://127.0.0.1:5555")
+dish  = OMQ::DISH.bind("udp://127.0.0.1:5555")
+dish.join("weather")
+
+radio.publish("weather", "sunny")
+puts dish.receive.inspect   # => ["weather", "sunny"]
+```
+
+```ruby
+require "omq/draft/clientserver"
+
+server = OMQ::SERVER.bind("tcp://127.0.0.1:5555")
+client = OMQ::CLIENT.connect("tcp://127.0.0.1:5555")
+
+client.send("hello")
+routing_id, body = server.receive
+server.send_to(routing_id, "world")
+puts client.receive.inspect   # => ["world"]
+```
+
+## Development
+
+```sh
+export OMQ_DEV=1    # use ../omq from source
+bundle install
+bundle exec rake
+```
+
+## License
+
+ISC

data/lib/omq/channel.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module OMQ
+  class CHANNEL < Socket
+    include Readable
+    include Writable
+    include SingleFrame
+
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:CHANNEL, linger: linger, backend: backend)
+      _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 Readable
+    include Writable
+    include SingleFrame
+
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:CLIENT, linger: linger, backend: backend)
+      _attach(endpoints, default: :connect)
+    end
+  end
+
+  class SERVER < Socket
+    include Readable
+    include Writable
+    include SingleFrame
+
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:SERVER, linger: linger, backend: backend)
+      _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/draft/channel.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# OMQ draft CHANNEL socket type.
+#
+# Usage:
+#   require "omq/draft/channel"
+#
+#   a = OMQ::CHANNEL.bind("tcp://127.0.0.1:5555")
+#   b = OMQ::CHANNEL.connect("tcp://127.0.0.1:5555")
+
+require "omq"
+
+require_relative "../single_frame"
+require_relative "../routing/channel"
+require_relative "../channel"
+
+OMQ::Routing.register(:CHANNEL, OMQ::Routing::Channel)

data/lib/omq/draft/clientserver.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# OMQ draft CLIENT/SERVER socket types.
+#
+# Usage:
+#   require "omq/draft/clientserver"
+#
+#   server = OMQ::SERVER.bind("tcp://127.0.0.1:5555")
+#   client = OMQ::CLIENT.connect("tcp://127.0.0.1:5555")
+
+require "omq"
+
+require_relative "../single_frame"
+require_relative "../routing/client"
+require_relative "../routing/server"
+require_relative "../client_server"
+
+OMQ::Routing.register(:CLIENT, OMQ::Routing::Client)
+OMQ::Routing.register(:SERVER, OMQ::Routing::Server)

data/lib/omq/draft/p2p.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# OMQ draft PEER socket type.
+#
+# Usage:
+#   require "omq/draft/p2p"
+#
+#   a = OMQ::PEER.bind("tcp://127.0.0.1:5555")
+#   b = OMQ::PEER.connect("tcp://127.0.0.1:5555")
+
+require "omq"
+
+require_relative "../single_frame"
+require_relative "../routing/peer"
+require_relative "../peer"
+
+OMQ::Routing.register(:PEER, OMQ::Routing::Peer)

data/lib/omq/draft/radiodish.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# OMQ draft RADIO/DISH socket types with UDP transport.
+#
+# Usage:
+#   require "omq/draft/radiodish"
+#
+#   radio = OMQ::RADIO.connect("udp://127.0.0.1:5555")
+#   dish  = OMQ::DISH.bind("udp://127.0.0.1:5555")
+#   dish.join("weather")
+#   radio.publish("weather", "sunny")
+
+require "omq"
+
+require_relative "../single_frame"
+require_relative "../routing/radio"
+require_relative "../routing/dish"
+require_relative "../transport/udp"
+require_relative "../radio_dish"
+
+OMQ::Routing.register(:RADIO, OMQ::Routing::Radio)
+OMQ::Routing.register(:DISH,  OMQ::Routing::Dish)
+OMQ::Engine.transports["udp"] = OMQ::Transport::UDP

data/lib/omq/draft/scattergather.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# OMQ draft SCATTER/GATHER socket types.
+#
+# Usage:
+#   require "omq/draft/scattergather"
+#
+#   gather  = OMQ::GATHER.bind("tcp://127.0.0.1:5555")
+#   scatter = OMQ::SCATTER.connect("tcp://127.0.0.1:5555")
+
+require "omq"
+
+require_relative "../single_frame"
+require_relative "../routing/scatter"
+require_relative "../routing/gather"
+require_relative "../scatter_gather"
+
+OMQ::Routing.register(:SCATTER, OMQ::Routing::Scatter)
+OMQ::Routing.register(:GATHER,  OMQ::Routing::Gather)

data/lib/omq/draft/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Draft
+    VERSION = "0.1.0"
+  end
+end

data/lib/omq/peer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module OMQ
+  class PEER < Socket
+    include Readable
+    include Writable
+    include SingleFrame
+
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:PEER, linger: linger, backend: backend)
+      _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 Writable
+
+    def initialize(endpoints = nil, linger: 0, on_mute: :drop_newest, conflate: false, backend: nil)
+      _init_engine(:RADIO, linger: linger, on_mute: on_mute, conflate: conflate, backend: backend)
+      _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 Readable
+
+    def initialize(endpoints = nil, linger: 0, group: nil, on_mute: :block, backend: nil)
+      _init_engine(:DISH, linger: linger, on_mute: on_mute, backend: backend)
+      _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/routing/channel.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # CHANNEL socket routing: exclusive 1-to-1 bidirectional.
+    #
+    class Channel
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine     = engine
+        @connection = nil
+        @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
+        @send_queue = Routing.build_queue(engine.options.send_hwm, :block)
+        @tasks          = []
+        @send_pump_idle = true
+      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) unless connection.is_a?(Transport::Inproc::DirectPipe)
+      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)
+        conn = @connection
+        if conn.is_a?(Transport::Inproc::DirectPipe) && conn.direct_recv_queue
+          conn.send_message(parts)
+        else
+          @send_queue.enqueue(parts)
+        end
+      end
+
+      #
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+
+      def send_pump_idle? = @send_pump_idle
+
+      private
+
+      def start_send_pump(conn)
+        @send_pump = @engine.spawn_pump_task(annotation: "send pump") do
+          loop do
+            @send_pump_idle = true
+            batch = [@send_queue.dequeue]
+            @send_pump_idle = false
+            Routing.drain_send_queue(@send_queue, batch)
+            batch.each { |parts| conn.write_message(parts) }
+            conn.flush
+          end
+        rescue *CONNECTION_LOST
+          @engine.connection_lost(conn)
+        end
+        @tasks << @send_pump
+      end
+    end
+  end
+end

data/lib/omq/routing/client.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module OMQ
+  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 = Routing.build_queue(engine.options.recv_hwm, :block)
+        @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
+        update_direct_pipe
+        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)
+        update_direct_pipe
+      end
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        enqueue_round_robin(parts)
+      end
+
+      #
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+    end
+  end
+end

data/lib/omq/routing/dish.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module OMQ
+  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  = Routing.build_queue(engine.options.recv_hwm, engine.options.on_mute)
+        @groups      = Set.new
+        @tasks       = []
+      end
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        @connections << connection
+        @groups.each do |group|
+          connection.send_command(Protocol::ZMTP::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(Protocol::ZMTP::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(Protocol::ZMTP::Codec::Command.leave(group))
+        end
+      end
+
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+    end
+  end
+end

data/lib/omq/routing/gather.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # GATHER socket routing: fair-queue receive from SCATTER peers.
+    #
+    class Gather
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine     = engine
+        @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
+        @tasks      = []
+      end
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        task = @engine.start_recv_pump(connection, @recv_queue)
+        @tasks << task if task
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        # recv pump stops on CONNECTION_LOST
+      end
+
+      # GATHER is read-only.
+      #
+      def enqueue(_parts)
+        raise "GATHER sockets cannot send"
+      end
+
+      #
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+    end
+  end
+end