omq 0.13.0 → 0.14.0

data/lib/omq/options.rb

@@ -9,6 +9,7 @@ module OMQ
   class Options
     DEFAULT_HWM = 1000
 
+
     # @param linger [Integer] linger period in seconds (default 0)
     #
     def initialize(linger: 0)
@@ -30,6 +31,40 @@ module OMQ
       @qos                   = 0       # 0 = fire-and-forget, 1 = at-least-once (see omq-qos gem)
     end
 
+
+    # @!attribute send_hwm
+    #   @return [Integer] send high water mark (default 1000, 0 = unbounded)
+    # @!attribute recv_hwm
+    #   @return [Integer] receive high water mark (default 1000, 0 = unbounded)
+    # @!attribute linger
+    #   @return [Integer, nil] linger period in seconds (nil = wait forever, 0 = immediate)
+    # @!attribute identity
+    #   @return [String] socket identity for ROUTER addressing (default "")
+    # @!attribute router_mandatory
+    #   @return [Boolean] raise on unroutable messages (default false)
+    # @!attribute conflate
+    #   @return [Boolean] keep only the latest message per topic (default false)
+    # @!attribute read_timeout
+    #   @return [Numeric, nil] read timeout in seconds (nil = no timeout)
+    # @!attribute write_timeout
+    #   @return [Numeric, nil] write timeout in seconds (nil = no timeout)
+    # @!attribute reconnect_interval
+    #   @return [Numeric, Range] reconnect interval in seconds, or Range for exponential backoff
+    # @!attribute heartbeat_interval
+    #   @return [Numeric, nil] PING interval in seconds (nil = disabled)
+    # @!attribute heartbeat_ttl
+    #   @return [Numeric, nil] TTL advertised in PING (nil = use heartbeat_interval)
+    # @!attribute heartbeat_timeout
+    #   @return [Numeric, nil] time without traffic before closing (nil = use heartbeat_interval)
+    # @!attribute max_message_size
+    #   @return [Integer, nil] maximum message size in bytes
+    # @!attribute on_mute
+    #   @return [Symbol] mute strategy (:block, :drop_newest, :drop_oldest)
+    # @!attribute mechanism
+    #   @return [Protocol::ZMTP::Mechanism::Null, Protocol::ZMTP::Mechanism::Curve] security mechanism
+    # @!attribute qos
+    #   @return [Integer] quality of service level (0 = fire-and-forget)
+    #
     attr_accessor :send_hwm,  :recv_hwm,
                   :linger,    :identity,
                   :router_mandatory,  :conflate,
@@ -41,10 +76,19 @@ module OMQ
                   :mechanism,
                   :qos
 
+    # @return [Boolean] true if router_mandatory is set
     alias_method :router_mandatory?, :router_mandatory
+
+    # @return [Numeric, nil] alias for #read_timeout
     alias_method :recv_timeout,      :read_timeout
+
+    # @param val [Numeric, nil] alias for #read_timeout=
     alias_method :recv_timeout=,     :read_timeout=
+
+    # @return [Numeric, nil] alias for #write_timeout
     alias_method :send_timeout,      :write_timeout
+
+    # @param val [Numeric, nil] alias for #write_timeout=
     alias_method :send_timeout=,     :write_timeout=
   end
 end

data/lib/omq/pair.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
 module OMQ
+  # PAIR socket — exclusive 1-to-1 bidirectional communication.
+  #
   class PAIR < Socket
     include Readable
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     def initialize(endpoints = nil, linger: 0, backend: nil)
       _init_engine(:PAIR, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)

data/lib/omq/pub_sub.rb

@@ -1,15 +1,24 @@
 # frozen_string_literal: true
 
 module OMQ
+  # PUB socket — publish messages to all matching subscribers.
+  #
   class PUB < Socket
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param on_mute [Symbol] mute strategy for slow subscribers
+    # @param conflate [Boolean] keep only latest message per topic
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     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
 
+
   # SUB socket.
   #
   class SUB < Socket
@@ -19,6 +28,7 @@ module OMQ
     #
     EVERYTHING = ''
 
+
     # @param endpoints [String, nil]
     # @param linger [Integer]
     # @param subscribe [String, nil] subscription prefix; +nil+ (default)
@@ -31,6 +41,7 @@ module OMQ
       self.subscribe(subscribe) unless subscribe.nil?
     end
 
+
     # Subscribes to a topic prefix.
     #
     # @param prefix [String]
@@ -40,6 +51,7 @@ module OMQ
       @engine.routing.subscribe(prefix)
     end
 
+
     # Unsubscribes from a topic prefix.
     #
     # @param prefix [String]
@@ -50,16 +62,27 @@ module OMQ
     end
   end
 
+
+  # XPUB socket — like PUB but exposes subscription events to the application.
+  #
   class XPUB < Socket
     include Readable
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param on_mute [Symbol] mute strategy for slow subscribers
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     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
 
+
+  # XSUB socket — like SUB but subscriptions are sent as data frames.
+  #
   class XSUB < Socket
     include Readable
     include Writable
@@ -68,6 +91,8 @@ module OMQ
     # @param linger [Integer]
     # @param subscribe [String, nil] subscription prefix; +nil+ (default)
     #   means no subscription — send a subscribe frame explicitly.
+    # @param on_mute [Symbol] mute strategy (:block, :drop_newest, :drop_oldest)
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
     #
     def initialize(endpoints = nil, linger: 0, subscribe: nil, on_mute: :block, backend: nil)
       _init_engine(:XSUB, linger: linger, on_mute: on_mute, backend: backend)

data/lib/omq/push_pull.rb

@@ -1,18 +1,35 @@
 # frozen_string_literal: true
 
 module OMQ
+  # PUSH socket — push messages to connected PULL peers via round-robin.
+  #
   class PUSH < Socket
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param send_hwm [Integer, nil] send high water mark (nil uses default)
+    # @param send_timeout [Numeric, nil] send timeout in seconds
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     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
 
+
+  # PULL socket — receive messages from PUSH peers via fair-queue.
+  #
   class PULL < Socket
     include Readable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param recv_hwm [Integer, nil] receive high water mark (nil uses default)
+    # @param recv_timeout [Numeric, nil] receive timeout in seconds
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     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)

data/lib/omq/queue_interface.rb

@@ -35,6 +35,7 @@ module OMQ
       dequeue(timeout: nil)
     end
 
+
     # Yields each received message until the socket is closed or
     # a receive timeout expires.
     #

data/lib/omq/readable.rb

@@ -11,6 +11,7 @@ module OMQ
     # Maximum messages to prefetch from the recv queue per drain.
     RECV_BATCH_SIZE = 64
 
+
     # Receives the next message. Returns from a local prefetch
     # buffer when available, otherwise drains up to
     # {RECV_BATCH_SIZE} messages from the recv queue in one
@@ -23,6 +24,7 @@ module OMQ
       @recv_mutex.synchronize { @recv_buffer.shift } || fill_recv_buffer
     end
 
+
     # Waits until the socket is readable.
     #
     # @param timeout [Numeric, nil] timeout in seconds

data/lib/omq/req_rep.rb

@@ -1,20 +1,33 @@
 # frozen_string_literal: true
 
 module OMQ
+  # REQ socket — send a request, then receive one reply (strict alternation).
+  #
   class REQ < Socket
     include Readable
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     def initialize(endpoints = nil, linger: 0, backend: nil)
       _init_engine(:REQ, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)
     end
   end
 
+
+  # REP socket — receive a request, then send one reply (strict alternation).
+  #
   class REP < Socket
     include Readable
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     def initialize(endpoints = nil, linger: 0, backend: nil)
       _init_engine(:REP, linger: linger, backend: backend)
       _attach(endpoints, default: :bind)

data/lib/omq/router_dealer.rb

@@ -1,27 +1,39 @@
 # frozen_string_literal: true
 
 module OMQ
+  # DEALER socket — asynchronous round-robin send, fair-queue receive.
+  #
   class DEALER < Socket
     include Readable
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     def initialize(endpoints = nil, linger: 0, backend: nil)
       _init_engine(:DEALER, linger: linger, backend: backend)
       _attach(endpoints, default: :connect)
     end
   end
 
+
   # ROUTER socket.
   #
   class ROUTER < Socket
     include Readable
     include Writable
 
+    # @param endpoints [String, nil] endpoint to bind/connect
+    # @param linger [Integer] linger period in seconds
+    # @param backend [Symbol, nil] :ruby (default) or :ffi
+    #
     def initialize(endpoints = nil, linger: 0, backend: nil)
       _init_engine(:ROUTER, linger: linger, backend: backend)
       _attach(endpoints, default: :bind)
     end
 
+
     # Sends a message to a specific peer by identity.
     #
     # @param receiver [String] peer identity

data/lib/omq/routing/conn_send_pump.rb

@@ -7,7 +7,7 @@ module OMQ
     # Used by Router and Rep, which have per-connection queues but do not
     # include the RoundRobin mixin.
     #
-    class ConnSendPump
+    module ConnSendPump
       # Spawns the pump task and registers it in +tasks+.
       #
       # @param engine [Engine]

data/lib/omq/routing/dealer.rb

@@ -19,6 +19,7 @@ module OMQ
         init_round_robin(engine)
       end
 
+
       # @return [FairQueue]
       #
       attr_reader :recv_queue
@@ -31,6 +32,7 @@ module OMQ
         add_round_robin_send_connection(connection)
       end
 
+
       # @param connection [Connection]
       #
       def connection_removed(connection)
@@ -39,12 +41,17 @@ module OMQ
         remove_round_robin_send_connection(connection)
       end
 
+
       # @param parts [Array<String>]
       #
       def enqueue(parts)
         enqueue_round_robin(parts)
       end
 
+
+      # Stops all background tasks.
+      #
+      # @return [void]
       #
       def stop
         @tasks.each(&:stop)

data/lib/omq/routing/fair_queue.rb

@@ -12,6 +12,8 @@ module OMQ
     # SignalingQueue wrapper, which also wakes a blocked #dequeue.
     #
     class FairQueue
+      # Creates an empty fair queue with no per-connection queues.
+      #
       def initialize
         @queues    = []              # ordered list of per-connection inner queues
         @mapping   = {}              # connection => inner queue
@@ -21,6 +23,7 @@ module OMQ
         @closed    = false
       end
 
+
       # Registers a per-connection queue. Called when a connection is added.
       #
       # @param conn [Connection]
@@ -31,6 +34,7 @@ module OMQ
         @queues << q
       end
 
+
       # Removes the per-connection queue for a disconnected peer.
       #
       # If the queue is empty it is removed immediately. If it still has
@@ -47,6 +51,7 @@ module OMQ
         # Non-empty orphaned queues stay in @queues until drained
       end
 
+
       # Wakes a blocked #dequeue. Called by SignalingQueue after each enqueue.
       #
       def signal
@@ -54,6 +59,7 @@ module OMQ
         @condition.signal
       end
 
+
       # Returns the next message from any per-connection queue, in fair
       # round-robin order. Blocks until a message is available.
       #
@@ -81,6 +87,7 @@ module OMQ
         end
       end
 
+
       # Injects a nil sentinel to unblock a waiting #dequeue.
       # Called by Engine on close or fatal error.
       #
@@ -89,6 +96,7 @@ module OMQ
         @condition.signal
       end
 
+
       # @return [Boolean]
       #
       def empty?
@@ -126,18 +134,38 @@ module OMQ
     # signals the FairQueue to wake a blocked #dequeue.
     #
     class SignalingQueue
+      # @param inner [Async::LimitedQueue] the per-connection bounded queue
+      # @param fair_queue [FairQueue] the parent fair queue to signal on enqueue
+      #
       def initialize(inner, fair_queue)
         @inner = inner
         @fair  = fair_queue
       end
 
+
+      # Enqueues a message and signals the fair queue.
+      #
+      # @param msg [Array<String>]
+      # @return [void]
+      #
       def enqueue(msg)
         @inner.enqueue(msg)
         @fair.signal
       end
 
+
+      # @param timeout [Numeric, nil] dequeue timeout
+      # @return [Array<String>, nil]
+      #
       def dequeue(timeout: nil) = @inner.dequeue(timeout: timeout)
+
+      # @return [Boolean]
+      #
       def empty?                = @inner.empty?
+
+      # @param item [Object, nil]
+      # @return [void]
+      #
       def push(item)            = @inner.push(item)
     end
   end

data/lib/omq/routing/fan_out.rb

@@ -17,10 +17,11 @@ module OMQ
     # their #initialize.
     #
     module FanOut
+      # @return [Async::Promise] resolves when the first subscriber joins
+      #
       attr_reader :subscriber_joined
 
-      # True when all per-connection send queues are empty.
-      # Used by Engine#drain_send_queues during linger.
+      # @return [Boolean] true when all per-connection send queues are empty
       #
       def send_queues_drained?
         @conn_queues.values.all?(&:empty?)
@@ -31,6 +32,7 @@ module OMQ
       def init_fan_out(engine)
         @connections        = Set.new
         @subscriptions      = {} # connection => Set of prefixes
+        @subscribe_all      = Set.new # connections subscribed to "" (match-all fast path)
         @conn_queues        = {} # connection => per-connection send queue
         @conn_send_tasks    = {} # connection => send pump task
         @conflate           = engine.options.conflate
@@ -42,11 +44,13 @@ module OMQ
       # @return [Boolean] whether the connection is subscribed to the topic
       #
       def subscribed?(conn, topic)
+        return true if @subscribe_all.include?(conn)
         subs = @subscriptions[conn]
         return false unless subs
         subs.any? { |prefix| topic.start_with?(prefix) }
       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).
@@ -56,9 +60,11 @@ module OMQ
       #
       def on_subscribe(conn, prefix)
         @subscriptions[conn] << prefix.b.freeze
+        @subscribe_all.add(conn) if prefix.empty?
         @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).
       #
@@ -67,6 +73,7 @@ module OMQ
       #
       def on_cancel(conn, prefix)
         @subscriptions[conn]&.delete(prefix)
+        @subscribe_all.delete(conn) if prefix.empty?
       end
 
 
@@ -88,6 +95,7 @@ module OMQ
       # @param conn [Connection]
       #
       def remove_fan_out_send_connection(conn)
+        @subscribe_all.delete(conn)
         @conn_queues.delete(conn)
         @conn_send_tasks.delete(conn)&.stop
       end
@@ -108,7 +116,7 @@ module OMQ
       #
       def fan_out_enqueue(parts)
         @connections.each do |conn|
-          @conn_queues[conn]&.enqueue(parts)
+          @conn_queues[conn].enqueue(parts)
         end
       end
 
@@ -120,8 +128,10 @@ module OMQ
             next unless frame.command?
             cmd = Protocol::ZMTP::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)
+            when "SUBSCRIBE"
+              on_subscribe(conn, cmd.data)
+            when "CANCEL"
+              on_cancel(conn, cmd.data)
             end
           end
         rescue *CONNECTION_LOST
@@ -131,7 +141,7 @@ module OMQ
 
 
       # Starts a dedicated send pump for one subscriber connection.
-      # Uses write_wire (pre-encoded bytes) for non-CURVE TCP connections
+      # Uses write_wire (pre-encoded bytes) for non-encrypted TCP connections
       # to avoid re-encoding the same message N times during fan-out.
       # In conflate mode, drains the batch and keeps only the latest
       # message per topic before writing.
@@ -140,12 +150,13 @@ module OMQ
       # @param q [Async::LimitedQueue, DropQueue]
       #
       def start_conn_send_pump(conn, q)
-        use_wire = conn.respond_to?(:write_wire) && !(conn.respond_to?(:curve?) && conn.curve?)
+        use_wire = conn.respond_to?(:write_wire) && !conn.encrypted?
         task     = @conflate ? start_conn_send_pump_conflate(conn, q) : start_conn_send_pump_normal(conn, q, use_wire)
         @conn_send_tasks[conn] = task
         @tasks << task
       end
 
+
       def start_conn_send_pump_normal(conn, q, use_wire)
         @engine.spawn_pump_task(annotation: "send pump") do
           loop do
@@ -159,6 +170,7 @@ module OMQ
         end
       end
 
+
       def write_matching_batch(conn, batch, use_wire)
         sent = false
         batch.each do |parts|

data/lib/omq/routing/pair.rb

@@ -23,6 +23,7 @@ module OMQ
         @tasks          = []
       end
 
+
       # @return [FairQueue]
       #
       attr_reader :recv_queue
@@ -45,6 +46,7 @@ module OMQ
         end
       end
 
+
       # @param connection [Connection]
       #
       def connection_removed(connection)
@@ -57,6 +59,7 @@ module OMQ
         end
       end
 
+
       # @param parts [Array<String>]
       #
       def enqueue(parts)
@@ -70,13 +73,18 @@ module OMQ
         end
       end
 
+
+      # Stops all background tasks.
+      #
+      # @return [void]
       #
       def stop
         @tasks.each(&:stop)
         @tasks.clear
       end
 
-      # True when the staging and send queues are empty.
+
+      # @return [Boolean] true when the staging and send queues are empty
       #
       def send_queues_drained?
         @staging_queue.empty? && (@send_queue.nil? || @send_queue.empty?)

data/lib/omq/routing/pub.rb

@@ -19,12 +19,14 @@ module OMQ
         init_fan_out(engine)
       end
 
+
       # PUB is write-only.
       #
       def recv_queue
         raise "PUB sockets cannot receive"
       end
 
+
       # @param connection [Connection]
       #
       def connection_added(connection)
@@ -34,6 +36,7 @@ module OMQ
         add_fan_out_send_connection(connection)
       end
 
+
       # @param connection [Connection]
       #
       def connection_removed(connection)
@@ -42,12 +45,17 @@ module OMQ
         remove_fan_out_send_connection(connection)
       end
 
+
       # @param parts [Array<String>]
       #
       def enqueue(parts)
         fan_out_enqueue(parts)
       end
 
+
+      # Stops all background tasks.
+      #
+      # @return [void]
       #
       def stop
         @tasks.each(&:stop)

data/lib/omq/routing/pull.rb

@@ -14,6 +14,7 @@ module OMQ
         @tasks      = []
       end
 
+
       # @return [FairQueue]
       #
       attr_reader :recv_queue
@@ -24,6 +25,7 @@ module OMQ
         add_fair_recv_connection(connection)
       end
 
+
       # @param connection [Connection]
       #
       def connection_removed(connection)
@@ -31,12 +33,17 @@ module OMQ
         # recv pump stops on EOFError
       end
 
+
       # PULL is read-only.
       #
       def enqueue(_parts)
         raise "PULL sockets cannot send"
       end
 
+
+      # Stops all background tasks.
+      #
+      # @return [void]
       #
       def stop
         @tasks.each(&:stop)