omq 0.9.0 → 0.11.0

data/lib/omq/zmtp/reactor.rb

@@ -1,131 +0,0 @@
-# frozen_string_literal: true
-
-require "async"
-
-module OMQ
-  module ZMTP
-    # Shared IO reactor for the Ruby backend.
-    #
-    # When user code runs inside an Async reactor, pump tasks are spawned
-    # as transient Async tasks directly. When no reactor is available
-    # (e.g. bare Thread.new), a single shared IO thread hosts all pump
-    # tasks — mirroring libzmq's IO thread architecture.
-    #
-    module Reactor
-      @work_queue = Async::Queue.new
-      @thread     = nil
-      @mutex      = Mutex.new
-
-      class << self
-        # Spawns a pump task (recv loop, send loop, accept loop).
-        #
-        # Inside an Async reactor: spawns as transient Async task.
-        # Outside: dispatches to the shared IO thread.
-        #
-        # @return [#stop] a stoppable handle
-        #
-        def spawn_pump(annotation: nil, &block)
-          if Async::Task.current?
-            Async(transient: true, annotation: annotation, &block)
-          else
-            handle = PumpHandle.new
-            ensure_started
-            @work_queue.push([:spawn, block, handle, annotation])
-            handle
-          end
-        end
-
-        # Runs a block synchronously within an Async context.
-        #
-        # Inside an Async reactor: runs directly.
-        # Outside: dispatches to the shared IO thread and waits.
-        #
-        # @return [Object] the block's return value
-        #
-        def run(&block)
-          if Async::Task.current?
-            yield
-          else
-            result_queue = Thread::Queue.new
-            ensure_started
-            @work_queue.push([:run, block, result_queue])
-            status, value = result_queue.pop
-            raise value if status == :error
-            value
-          end
-        end
-
-        # Ensures the shared IO thread is running.
-        #
-        # @return [void]
-        #
-        def ensure_started
-          @mutex.synchronize do
-            return if @thread&.alive?
-            ready = Thread::Queue.new
-            @thread = Thread.new { run_reactor(ready) }
-            @thread.name = "omq-io"
-            ready.pop
-          end
-        end
-
-        # Stops the shared IO thread. Used in tests.
-        #
-        # @return [void]
-        #
-        def stop!
-          @work_queue.push([:stop])
-          @thread&.join(2)
-          @thread = nil
-        end
-
-        private
-
-        # Runs the shared Async reactor loop, dispatching work items.
-        #
-        # @param ready [Thread::Queue] signaled once the reactor is accepting work
-        #
-        def run_reactor(ready)
-          Async do |task|
-            ready.push(true)
-            loop do
-              item = @work_queue.dequeue
-              case item[0]
-              when :spawn
-                _, block, handle, annotation = item
-                async_task = task.async(transient: true, annotation: annotation, &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
-        end
-      end
-
-      # A stoppable handle for a pump task running in the shared reactor.
-      #
-      class PumpHandle
-        # @return [Async::Task, nil]
-        #
-        attr_accessor :task
-
-
-        # Stops the pump task.
-        #
-        # @return [void]
-        #
-        def stop
-          @task&.stop
-        end
-      end
-    end
-  end
-end

data/lib/omq/zmtp/readable.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-require "timeout"
-
-module OMQ
-  module ZMTP
-    # Pure Ruby Readable mixin. Dequeues messages from the engine's recv queue.
-    #
-    module Readable
-      # Receives the next message.
-      #
-      # @return [Array<String>] message parts
-      # @raise [IO::TimeoutError] if read_timeout exceeded
-      #
-      def receive
-        with_timeout(@options.read_timeout) { @engine.dequeue_recv }
-      end
-
-      # Waits until the socket is readable.
-      #
-      # @param timeout [Numeric, nil] timeout in seconds
-      # @return [true]
-      #
-      def wait_readable(timeout = @options.read_timeout)
-        true
-      end
-    end
-  end
-end

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

@@ -1,81 +0,0 @@
-# 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          = []
-          @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)
-        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 send_pump_idle? = @send_pump_idle
-
-
-        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 *ZMTP::CONNECTION_LOST
-            @engine.connection_lost(conn)
-          end
-          @tasks << @send_pump
-        end
-      end
-    end
-  end
-end

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

@@ -1,56 +0,0 @@
-# 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/dealer.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-module OMQ
-  module ZMTP
-    module Routing
-      # DEALER socket routing: round-robin send, fair-queue receive.
-      #
-      # No envelope manipulation — messages pass through unchanged.
-      #
-      class Dealer
-        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

@@ -1,80 +0,0 @@
-# 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

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

@@ -1,131 +0,0 @@
-# frozen_string_literal: true
-
-module OMQ
-  module ZMTP
-    module Routing
-      # Mixin for routing strategies that fan-out to subscribers.
-      #
-      # Manages per-connection subscription sets, subscription command
-      # listeners, and a send pump that delivers to all matching peers.
-      #
-      # Including classes must call `init_fan_out(engine)` from
-      # their #initialize.
-      #
-      module FanOut
-        attr_reader :subscriber_joined
-
-        private
-
-        def init_fan_out(engine)
-          @connections        = []
-          @subscriptions      = {} # connection => Set of prefixes
-          @send_queue         = Async::LimitedQueue.new(engine.options.send_hwm)
-          @send_pump_started  = false
-          @send_pump_idle     = true
-          @conflate           = engine.options.conflate
-          @subscriber_joined  = Async::Promise.new
-        end
-
-        # @return [Boolean] whether the connection is subscribed to the topic
-        #
-        def subscribed?(conn, topic)
-          subs = @subscriptions[conn]
-          return false unless subs
-          subs.any? { |prefix| topic.b.start_with?(prefix.b) }
-        end
-
-        # Called when a subscription command is received from a peer.
-        # Override in subclasses to expose subscriptions to the
-        # application (e.g. XPUB enqueues to recv_queue).
-        #
-        # @param conn [Connection]
-        # @param prefix [String]
-        #
-        def on_subscribe(conn, prefix)
-          @subscriptions[conn] << prefix
-          @subscriber_joined.resolve(conn) unless @subscriber_joined.resolved?
-        end
-
-        # Called when a cancel command is received from a peer.
-        # Override in subclasses (e.g. XPUB enqueues to recv_queue).
-        #
-        # @param conn [Connection]
-        # @param prefix [String]
-        #
-        def on_cancel(conn, prefix)
-          @subscriptions[conn]&.delete(prefix)
-        end
-
-        # @return [Boolean] true when the send pump is idle (not sending a batch)
-        def send_pump_idle? = @send_pump_idle
-
-
-        def start_send_pump
-          @send_pump_started = true
-          @tasks << @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)
-
-              written = Set.new
-
-              if @conflate
-                # Keep only the last matching message per connection.
-                latest = {} # conn => parts
-                batch.each do |parts|
-                  topic = parts.first || "".b
-                  @connections.each do |conn|
-                    next unless subscribed?(conn, topic)
-                    latest[conn] = parts
-                  end
-                end
-                latest.each do |conn, parts|
-                  begin
-                    conn.write_message(parts)
-                    written << conn
-                  rescue *ZMTP::CONNECTION_LOST
-                  end
-                end
-              else
-                batch.each do |parts|
-                  topic = parts.first || "".b
-                  @connections.each do |conn|
-                    next unless subscribed?(conn, topic)
-                    begin
-                      conn.write_message(parts)
-                      written << conn
-                    rescue *ZMTP::CONNECTION_LOST
-                    end
-                  end
-                end
-              end
-
-              written.each do |conn|
-                conn.flush
-              rescue *ZMTP::CONNECTION_LOST
-              end
-            end
-          end
-        end
-
-        def start_subscription_listener(conn)
-          @tasks << Reactor.spawn_pump(annotation: "recv pump") do
-            loop do
-              frame = conn.read_frame
-              next unless frame.command?
-              cmd = Codec::Command.from_body(frame.body)
-              case cmd.name
-              when "SUBSCRIBE" then on_subscribe(conn, cmd.data)
-              when "CANCEL"    then on_cancel(conn, cmd.data)
-              end
-            end
-          rescue *ZMTP::CONNECTION_LOST
-            @engine.connection_lost(conn)
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-module OMQ
-  module ZMTP
-    module Routing
-      # GATHER socket routing: fair-queue receive from SCATTER peers.
-      #
-      class Gather
-        # @param engine [Engine]
-        #
-        def initialize(engine)
-          @engine     = engine
-          @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
-          @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
-end

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

@@ -1,84 +0,0 @@
-# frozen_string_literal: true
-
-module OMQ
-  module ZMTP
-    module Routing
-      # PAIR socket routing: exclusive 1-to-1 bidirectional.
-      #
-      # Only one peer connection is allowed. Messages flow through
-      # internal send/recv queues backed by Async::LimitedQueue.
-      #
-      class Pair
-
-        # @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          = []
-          @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 "PAIR 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 send_pump_idle? = @send_pump_idle
-
-
-        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 *ZMTP::CONNECTION_LOST
-            @engine.connection_lost(conn)
-          end
-          @tasks << @send_pump
-        end
-      end
-    end
-  end
-end