omq 0.10.0 → 0.12.0

data/lib/omq/pub_sub.rb

@@ -4,8 +4,8 @@ module OMQ
   class PUB < Socket
     include Writable
 
-    def initialize(endpoints = nil, linger: 0, conflate: false)
-      _init_engine(:PUB, linger: linger, conflate: conflate)
+    def initialize(endpoints = nil, linger: 0, on_mute: :drop_newest, conflate: false, backend: nil)
+      _init_engine(:PUB, linger: linger, on_mute: on_mute, conflate: conflate, backend: backend)
       _attach(endpoints, default: :bind)
     end
   end
@@ -21,13 +21,14 @@ module OMQ
 
     # @param endpoints [String, nil]
     # @param linger [Integer]
-    # @param prefix [String, nil] subscription prefix; +nil+ (default)
+    # @param subscribe [String, nil] subscription prefix; +nil+ (default)
     #   means no subscription — call {#subscribe} explicitly.
+    # @param on_mute [Symbol] :block (default), :drop_newest, or :drop_oldest
     #
-    def initialize(endpoints = nil, linger: 0, prefix: nil)
-      _init_engine(:SUB, linger: linger)
+    def initialize(endpoints = nil, linger: 0, subscribe: nil, on_mute: :block, backend: nil)
+      _init_engine(:SUB, linger: linger, on_mute: on_mute, backend: backend)
       _attach(endpoints, default: :connect)
-      subscribe(prefix) unless prefix.nil?
+      self.subscribe(subscribe) unless subscribe.nil?
     end
 
     # Subscribes to a topic prefix.
@@ -53,8 +54,8 @@ module OMQ
     include Readable
     include Writable
 
-    def initialize(endpoints = nil, linger: 0)
-      _init_engine(:XPUB, linger: linger)
+    def initialize(endpoints = nil, linger: 0, on_mute: :drop_newest, backend: nil)
+      _init_engine(:XPUB, linger: linger, on_mute: on_mute, backend: backend)
       _attach(endpoints, default: :bind)
     end
   end
@@ -65,13 +66,13 @@ module OMQ
 
     # @param endpoints [String, nil]
     # @param linger [Integer]
-    # @param prefix [String, nil] subscription prefix; +nil+ (default)
+    # @param subscribe [String, nil] subscription prefix; +nil+ (default)
     #   means no subscription — send a subscribe frame explicitly.
     #
-    def initialize(endpoints = nil, linger: 0, prefix: nil)
-      _init_engine(:XSUB, linger: linger)
+    def initialize(endpoints = nil, linger: 0, subscribe: nil, on_mute: :block, backend: nil)
+      _init_engine(:XSUB, linger: linger, on_mute: on_mute, backend: backend)
       _attach(endpoints, default: :connect)
-      send("\x01#{prefix}".b) unless prefix.nil?
+      send("\x01#{subscribe}".b) unless subscribe.nil?
     end
   end
 end

data/lib/omq/push_pull.rb

@@ -4,8 +4,8 @@ module OMQ
   class PUSH < Socket
     include Writable
 
-    def initialize(endpoints = nil, linger: 0, send_hwm: nil, send_timeout: nil)
-      _init_engine(:PUSH, linger: linger, send_hwm: send_hwm, send_timeout: send_timeout)
+    def initialize(endpoints = nil, linger: 0, send_hwm: nil, send_timeout: nil, backend: nil)
+      _init_engine(:PUSH, linger: linger, send_hwm: send_hwm, send_timeout: send_timeout, backend: backend)
       _attach(endpoints, default: :connect)
     end
   end
@@ -13,8 +13,8 @@ module OMQ
   class PULL < Socket
     include Readable
 
-    def initialize(endpoints = nil, linger: 0, recv_hwm: nil, recv_timeout: nil)
-      _init_engine(:PULL, linger: linger, recv_hwm: recv_hwm, recv_timeout: recv_timeout)
+    def initialize(endpoints = nil, linger: 0, recv_hwm: nil, recv_timeout: nil, backend: nil)
+      _init_engine(:PULL, linger: linger, recv_hwm: recv_hwm, recv_timeout: recv_timeout, backend: backend)
       _attach(endpoints, default: :bind)
     end
   end

data/lib/omq/queue_interface.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module OMQ
+  # Async::Queue-compatible read interface.
+  #
+  # Automatically included by {Readable}. Provides #dequeue, #pop,
+  # #wait, and #each so sockets can be used where an Async::Queue
+  # is expected.
+  #
+  module QueueReadable
+    # Dequeues the next message.
+    #
+    # @param timeout [Numeric, nil] timeout in seconds (overrides
+    #   the socket's +read_timeout+ for this call)
+    # @return [Array<String>] message parts
+    # @raise [IO::TimeoutError] if timeout exceeded
+    #
+    def dequeue(timeout: @options.read_timeout)
+      msg = @recv_mutex.synchronize { @recv_buffer.shift }
+      return msg if msg
+
+      batch = Reactor.run { with_timeout(timeout) { @engine.dequeue_recv_batch(Readable::RECV_BATCH_SIZE) } }
+      msg = batch.shift
+      @recv_mutex.synchronize { @recv_buffer.concat(batch) } unless batch.empty?
+      msg
+    end
+
+    alias_method :pop, :dequeue
+
+    # Waits for the next message indefinitely (ignores read_timeout).
+    #
+    # @return [Array<String>] message parts
+    #
+    def wait
+      dequeue(timeout: nil)
+    end
+
+    # Yields each received message until the socket is closed or
+    # a receive timeout expires.
+    #
+    # @yield [Array<String>] message parts
+    # @return [void]
+    #
+    def each
+      while (msg = receive)
+        yield msg
+      end
+    rescue IO::TimeoutError
+      nil
+    end
+  end
+
+
+  # Async::Queue-compatible write interface.
+  #
+  # Automatically included by {Writable}. Provides #enqueue, #push,
+  # and #signal so sockets can be used where an Async::Queue is
+  # expected.
+  #
+  module QueueWritable
+    # Enqueues one or more messages for sending.
+    #
+    # @param messages [String, Array<String>]
+    # @return [self]
+    #
+    def enqueue(*messages)
+      messages.each { |msg| send(msg) }
+      self
+    end
+
+    alias_method :push, :enqueue
+  end
+end

data/lib/omq/readable.rb

@@ -6,6 +6,8 @@ module OMQ
   # Pure Ruby Readable mixin. Dequeues messages from the engine's recv queue.
   #
   module Readable
+    include QueueReadable
+
     # Maximum messages to prefetch from the recv queue per drain.
     RECV_BATCH_SIZE = 64
 

data/lib/omq/req_rep.rb

@@ -5,8 +5,8 @@ module OMQ
     include Readable
     include Writable
 
-    def initialize(endpoints = nil, linger: 0)
-      _init_engine(:REQ, linger: linger)
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:REQ, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)
     end
   end
@@ -15,8 +15,8 @@ module OMQ
     include Readable
     include Writable
 
-    def initialize(endpoints = nil, linger: 0)
-      _init_engine(:REP, linger: linger)
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:REP, linger: linger, backend: backend)
       _attach(endpoints, default: :bind)
     end
   end

data/lib/omq/router_dealer.rb

@@ -5,8 +5,8 @@ module OMQ
     include Readable
     include Writable
 
-    def initialize(endpoints = nil, linger: 0)
-      _init_engine(:DEALER, linger: linger)
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:DEALER, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)
     end
   end
@@ -17,8 +17,8 @@ module OMQ
     include Readable
     include Writable
 
-    def initialize(endpoints = nil, linger: 0)
-      _init_engine(:ROUTER, linger: linger)
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:ROUTER, linger: linger, backend: backend)
       _attach(endpoints, default: :bind)
     end
 

data/lib/omq/routing/dealer.rb

@@ -13,7 +13,7 @@ module OMQ
       #
       def initialize(engine)
         @engine     = engine
-        @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+        @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
         @tasks      = []
         init_round_robin(engine)
       end

data/lib/omq/routing/fan_out.rb

@@ -13,12 +13,16 @@ module OMQ
     module FanOut
       attr_reader :subscriber_joined
 
+      # @return [Boolean] true when the send pump is idle (not sending a batch)
+      def send_pump_idle? = @send_pump_idle
+
       private
 
       def init_fan_out(engine)
         @connections        = []
         @subscriptions      = {} # connection => Set of prefixes
-        @send_queue         = Async::LimitedQueue.new(engine.options.send_hwm)
+        @send_queue         = Routing.build_queue(engine.options.send_hwm, :block)
+        @on_mute            = engine.options.on_mute
         @send_pump_started  = false
         @send_pump_idle     = true
         @conflate           = engine.options.conflate
@@ -57,8 +61,14 @@ module OMQ
         @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
+      # Returns true if the connection is muted (recv queue full) and
+      # the on_mute strategy says to drop rather than block.
+      #
+      def muted?(conn)
+        return false if @on_mute == :block
+        q = conn.direct_recv_queue if conn.respond_to?(:direct_recv_queue)
+        q&.respond_to?(:limited?) && q.limited?
+      end
 
 
       def start_send_pump
@@ -83,6 +93,7 @@ module OMQ
                 end
               end
               @latest.each do |conn, parts|
+                next if muted?(conn)
                 begin
                   conn.write_message(parts)
                   @written << conn
@@ -91,11 +102,21 @@ module OMQ
               end
             else
               batch.each do |parts|
-                topic = parts.first || EMPTY_BINARY
+                topic      = parts.first || EMPTY_BINARY
+                wire_bytes = nil
+
                 @connections.each do |conn|
                   next unless subscribed?(conn, topic)
+                  next if muted?(conn)
                   begin
-                    conn.write_message(parts)
+                    if conn.respond_to?(:curve?) && conn.curve?
+                      conn.write_message(parts)
+                    elsif conn.respond_to?(:write_wire)
+                      wire_bytes ||= Protocol::ZMTP::Codec::Frame.encode_message(parts)
+                      conn.write_wire(wire_bytes)
+                    else
+                      conn.write_message(parts)
+                    end
                     @written << conn
                   rescue *CONNECTION_LOST
                   end

data/lib/omq/routing/pair.rb

@@ -14,8 +14,8 @@ module OMQ
       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)
+        @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

data/lib/omq/routing/pull.rb

@@ -9,7 +9,7 @@ module OMQ
       #
       def initialize(engine)
         @engine     = engine
-        @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+        @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
         @tasks      = []
       end
 

data/lib/omq/routing/push.rb

@@ -76,6 +76,8 @@ module OMQ
           @engine.connection_lost(conn)
         end
       end
+
+
     end
   end
 end

data/lib/omq/routing/rep.rb

@@ -15,8 +15,8 @@ module OMQ
 
       def initialize(engine)
         @engine            = engine
-        @recv_queue        = Async::LimitedQueue.new(engine.options.recv_hwm)
-        @send_queue        = Async::LimitedQueue.new(engine.options.send_hwm)
+        @recv_queue        = Routing.build_queue(engine.options.recv_hwm, :block)
+        @send_queue        = Routing.build_queue(engine.options.send_hwm, :block)
         @pending_replies   = []
         @tasks             = []
         @send_pump_started = false

data/lib/omq/routing/req.rb

@@ -12,9 +12,10 @@ module OMQ
       # @param engine [Engine]
       #
       def initialize(engine)
-        @engine     = engine
-        @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
-        @tasks      = []
+        @engine          = engine
+        @recv_queue      = Routing.build_queue(engine.options.recv_hwm, :block)
+        @tasks           = []
+        @state           = :ready        # :ready or :waiting_reply
         init_round_robin(engine)
       end
 
@@ -22,6 +23,7 @@ module OMQ
       #
       attr_reader :recv_queue, :send_queue
 
+
       # @param connection [Connection]
       #
       def connection_added(connection)
@@ -29,6 +31,7 @@ module OMQ
         signal_connection_available
         update_direct_pipe
         task = @engine.start_recv_pump(connection, @recv_queue) do |msg|
+          @state = :ready
           msg.first&.empty? ? msg[1..] : msg
         end
         @tasks << task if task
@@ -45,6 +48,8 @@ module OMQ
       # @param parts [Array<String>]
       #
       def enqueue(parts)
+        raise SocketError, "REQ socket expects send/recv/send/recv order" unless @state == :ready
+        @state = :waiting_reply
         enqueue_round_robin(parts)
       end
 

data/lib/omq/routing/round_robin.rb

@@ -12,6 +12,9 @@ module OMQ
     # their #initialize.
     #
     module RoundRobin
+      # @return [Boolean] true when the send pump is idle (not sending a batch)
+      def send_pump_idle? = @send_pump_idle
+
       private
 
 
@@ -23,7 +26,7 @@ module OMQ
         @connections          = []
         @cycle                = @connections.cycle
         @connection_available = Async::Promise.new
-        @send_queue           = Async::LimitedQueue.new(engine.options.send_hwm)
+        @send_queue           = Routing.build_queue(engine.options.send_hwm, :block)
         @send_pump_started    = false
         @send_pump_idle       = true
         @direct_pipe          = nil
@@ -90,13 +93,6 @@ module OMQ
       def transform_send(parts) = parts
 
 
-      # Starts the background send pump that dequeues messages
-      # and dispatches them round-robin across connections.
-      #
-      # @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
@@ -144,14 +140,11 @@ module OMQ
             @written << conn
           rescue *CONNECTION_LOST
             @engine.connection_lost(conn)
-            # Flush what we've written so far
             @written.each do |c|
               c.flush
             rescue *CONNECTION_LOST
-              # will be cleaned up
             end
             @written.clear
-            # Fall back to send_with_retry for this and remaining
             send_with_retry(parts)
             batch[(i + 1)..].each { |p| send_with_retry(p) }
             return
@@ -160,7 +153,6 @@ module OMQ
         @written.each do |conn|
           conn.flush
         rescue *CONNECTION_LOST
-          # will be cleaned up
         end
       end
     end

data/lib/omq/routing/router.rb

@@ -15,8 +15,8 @@ module OMQ
       #
       def initialize(engine)
         @engine                  = engine
-        @recv_queue              = Async::LimitedQueue.new(engine.options.recv_hwm)
-        @send_queue              = Async::LimitedQueue.new(engine.options.send_hwm)
+        @recv_queue              = Routing.build_queue(engine.options.recv_hwm, :block)
+        @send_queue              = Routing.build_queue(engine.options.send_hwm, :block)
         @connections_by_identity = {}
         @identity_by_connection  = {}
         @tasks                   = []

data/lib/omq/routing/sub.rb

@@ -13,7 +13,7 @@ module OMQ
       def initialize(engine)
         @engine        = engine
         @connections   = []
-        @recv_queue    = Async::LimitedQueue.new(engine.options.recv_hwm)
+        @recv_queue    = Routing.build_queue(engine.options.recv_hwm, engine.options.on_mute)
         @subscriptions = Set.new
         @tasks         = []
       end
@@ -26,7 +26,6 @@ module OMQ
       #
       def connection_added(connection)
         @connections << connection
-        # Send existing subscriptions to new peer
         @subscriptions.each do |prefix|
           connection.send_command(Protocol::ZMTP::Codec::Command.subscribe(prefix))
         end

data/lib/omq/routing/xpub.rb

@@ -15,7 +15,7 @@ module OMQ
       #
       def initialize(engine)
         @engine     = engine
-        @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+        @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
         @tasks      = []
         init_fan_out(engine)
       end

data/lib/omq/routing/xsub.rb

@@ -14,8 +14,8 @@ module OMQ
       def initialize(engine)
         @engine            = engine
         @connections       = []
-        @recv_queue        = Async::LimitedQueue.new(engine.options.recv_hwm)
-        @send_queue        = Async::LimitedQueue.new(engine.options.send_hwm)
+        @recv_queue        = Routing.build_queue(engine.options.recv_hwm, engine.options.on_mute)
+        @send_queue        = Routing.build_queue(engine.options.send_hwm, :block)
         @tasks             = []
         @send_pump_started = false
         @send_pump_idle    = true

data/lib/omq/routing.rb

@@ -3,6 +3,7 @@
 require "async"
 require "async/queue"
 require "async/limited_queue"
+require_relative "drop_queue"
 
 module OMQ
   # Routing strategies for each ZMQ socket type.
@@ -14,6 +15,42 @@ module OMQ
     # Shared frozen empty binary string to avoid repeated allocations.
     EMPTY_BINARY = "".b.freeze
 
+    # Plugin registry for socket types not built into omq.
+    # Populated by sister gems via +Routing.register+.
+    #
+    @registry = {}
+
+    class << self
+      # Registers a routing strategy class for a socket type.
+      # Called by omq-draft (and other plugins) at require time.
+      #
+      # @param socket_type [Symbol] e.g. :RADIO, :CLIENT
+      # @param strategy_class [Class]
+      #
+      def register(socket_type, strategy_class)
+        @registry[socket_type] = strategy_class
+      end
+    end
+
+    # Builds a send or recv queue based on the mute strategy.
+    #
+    # @param hwm [Integer] high water mark
+    # @param on_mute [Symbol] :block, :drop_newest, or :drop_oldest
+    # @return [Async::LimitedQueue, DropQueue]
+    #
+    def self.build_queue(hwm, on_mute)
+      return Async::Queue.new if hwm.nil? || hwm == 0
+
+      case on_mute
+      when :block
+        Async::LimitedQueue.new(hwm)
+      when :drop_newest, :drop_oldest
+        DropQueue.new(hwm, strategy: on_mute)
+      else
+        raise ArgumentError, "unknown on_mute strategy: #{on_mute.inspect}"
+      end
+    end
+
     # Drains all available messages from +queue+ into +batch+ without
     # blocking. Call after the initial blocking dequeue.
     #
@@ -49,17 +86,10 @@ module OMQ
       when :SUB    then Sub
       when :XPUB   then XPub
       when :XSUB   then XSub
-      when :PUSH    then Push
-      when :PULL    then Pull
-      when :CLIENT  then Client
-      when :SERVER  then Server
-      when :RADIO   then Radio
-      when :DISH    then Dish
-      when :SCATTER then Scatter
-      when :GATHER  then Gather
-      when :PEER    then Peer
-      when :CHANNEL then Channel
-      else raise ArgumentError, "unknown socket type: #{socket_type}"
+      when :PUSH   then Push
+      when :PULL   then Pull
+      else
+        @registry[socket_type] or raise ArgumentError, "unknown socket type: #{socket_type.inspect}"
       end
     end
   end

data/lib/omq/socket.rb

@@ -36,6 +36,7 @@ module OMQ
       :heartbeat_ttl,         :heartbeat_ttl=,
       :heartbeat_timeout,     :heartbeat_timeout=,
       :max_message_size,      :max_message_size=,
+      :on_mute,               :on_mute=,
       :mechanism,             :mechanism=
 
 
@@ -140,6 +141,46 @@ module OMQ
     end
 
 
+    # Yields lifecycle events for this socket.
+    #
+    # Spawns a background fiber that reads from an internal event queue.
+    # The block receives {MonitorEvent} instances until the socket is
+    # closed or the returned task is stopped.
+    #
+    # @yield [event] called for each lifecycle event
+    # @yieldparam event [MonitorEvent]
+    # @return [Async::Task] the monitor task (call +#stop+ to end early)
+    #
+    # @example
+    #   task = socket.monitor do |event|
+    #     case event
+    #     in type: :connected, endpoint:
+    #       puts "peer up: #{endpoint}"
+    #     in type: :disconnected, endpoint:
+    #       puts "peer down: #{endpoint}"
+    #     end
+    #   end
+    #   # later:
+    #   task.stop
+    #
+    def monitor(&block)
+      ensure_parent_task
+      queue = Async::Queue.new
+      @engine.monitor_queue = queue
+      Reactor.run do
+        @engine.parent_task.async(transient: true, annotation: "monitor") do
+          while (event = queue.dequeue)
+            block.call(event)
+          end
+        rescue Async::Stop
+        ensure
+          @engine.monitor_queue = nil
+          block.call(MonitorEvent.new(type: :monitor_stopped))
+        end
+      end
+    end
+
+
     # Disable auto-reconnect for connected endpoints.
     def reconnect_enabled=(val)
       @engine.reconnect_enabled = val
@@ -224,16 +265,22 @@ module OMQ
     # @param linger [Integer]
     #
     def _init_engine(socket_type, linger:, send_hwm: nil, recv_hwm: nil,
-                     send_timeout: nil, recv_timeout: nil, conflate: false)
+                     send_timeout: nil, recv_timeout: nil, conflate: false,
+                     on_mute: nil, backend: nil)
       @options = Options.new(linger: linger)
       @options.send_hwm      = send_hwm     if send_hwm
       @options.recv_hwm      = recv_hwm     if recv_hwm
       @options.send_timeout   = send_timeout if send_timeout
       @options.recv_timeout   = recv_timeout if recv_timeout
       @options.conflate       = conflate
+      @options.on_mute        = on_mute      if on_mute
       @recv_buffer = []
       @recv_mutex  = Mutex.new
-      @engine      = Engine.new(socket_type, @options)
+      @engine      = case backend
+                     when nil, :ruby then Engine.new(socket_type, @options)
+                     when :ffi       then FFI::Engine.new(socket_type, @options)
+                     else raise ArgumentError, "unknown backend: #{backend}"
+                     end
     end
   end
 end