omq 0.13.0 → 0.14.1

data/lib/omq/routing/rep.rb

@@ -13,6 +13,7 @@ module OMQ
 
       EMPTY_FRAME = "".b.freeze
 
+
       # @param engine [Engine]
       #
       def initialize(engine)
@@ -24,6 +25,7 @@ module OMQ
         @tasks           = []
       end
 
+
       # @return [FairQueue]
       #
       attr_reader :recv_queue
@@ -44,6 +46,7 @@ module OMQ
         @conn_send_tasks[connection] = ConnSendPump.start(@engine, connection, q, @tasks)
       end
 
+
       # @param connection [Connection]
       #
       def connection_removed(connection)
@@ -53,6 +56,7 @@ module OMQ
         @conn_send_tasks.delete(connection)&.stop
       end
 
+
       # Enqueues a reply. Routes to the connection that sent the matching
       # request by consuming the next pending_reply entry.
       #
@@ -65,12 +69,18 @@ module OMQ
         @conn_queues[conn]&.enqueue([*reply_info[:envelope], EMPTY_FRAME, *parts])
       end
 
+
+      # Stops all background tasks.
+      #
+      # @return [void]
+      #
       def stop
         @tasks.each(&:stop)
         @tasks.clear
       end
 
-      # True when all per-connection send queues are empty.
+
+      # @return [Boolean] true when all per-connection send queues are empty
       #
       def send_queues_drained?
         @conn_queues.values.all?(&:empty?)

data/lib/omq/routing/req.rb

@@ -20,6 +20,7 @@ module OMQ
         init_round_robin(engine)
       end
 
+
       # @return [FairQueue]
       #
       attr_reader :recv_queue
@@ -36,6 +37,7 @@ module OMQ
         add_round_robin_send_connection(connection)
       end
 
+
       # @param connection [Connection]
       #
       def connection_removed(connection)
@@ -44,6 +46,7 @@ module OMQ
         remove_round_robin_send_connection(connection)
       end
 
+
       # @param parts [Array<String>]
       #
       def enqueue(parts)
@@ -52,6 +55,10 @@ module OMQ
         enqueue_round_robin(parts)
       end
 
+
+      # Stops all background tasks.
+      #
+      # @return [void]
       #
       def stop
         @tasks.each(&:stop)

data/lib/omq/routing/round_robin.rb

@@ -15,8 +15,8 @@ module OMQ
     # their #initialize.
     #
     module RoundRobin
-      # True when the staging queue and all per-connection send queues
-      # are empty. Used by Engine#drain_send_queues during linger.
+      # @return [Boolean] true when the staging queue and all per-connection
+      #   send queues are empty
       #
       def send_queues_drained?
         @staging_queue.empty? && @conn_queues.values.all?(&:empty?)
@@ -103,7 +103,7 @@ module OMQ
           @staging_queue.enqueue(parts)
         else
           conn = next_connection
-          @conn_queues[conn]&.enqueue(parts)
+          @conn_queues[conn].enqueue(parts)
         end
       end
 
@@ -165,6 +165,7 @@ module OMQ
         @tasks << task
       end
 
+
       def write_batch(conn, batch)
         if batch.size == 1
           conn.send_message(transform_send(batch[0]))

data/lib/omq/routing/router.rb

@@ -24,6 +24,7 @@ module OMQ
         @tasks                   = []
       end
 
+
       # @return [FairQueue]
       #
       attr_reader :recv_queue
@@ -43,6 +44,7 @@ module OMQ
         @conn_send_tasks[connection] = ConnSendPump.start(@engine, connection, q, @tasks)
       end
 
+
       # @param connection [Connection]
       #
       def connection_removed(connection)
@@ -53,6 +55,7 @@ module OMQ
         @conn_send_tasks.delete(connection)&.stop
       end
 
+
       # Enqueues a message for sending. The first frame is the routing identity.
       #
       # @param parts [Array<String>]
@@ -69,12 +72,18 @@ module OMQ
         @conn_queues[conn]&.enqueue(parts[1..])
       end
 
+
+      # Stops all background tasks.
+      #
+      # @return [void]
+      #
       def stop
         @tasks.each(&:stop)
         @tasks.clear
       end
 
-      # True when all per-connection send queues are empty.
+
+      # @return [Boolean] true when all per-connection send queues are empty
       #
       def send_queues_drained?
         @conn_queues.values.all?(&:empty?)

data/lib/omq/routing/sub.rb

@@ -18,6 +18,7 @@ module OMQ
         @tasks         = []
       end
 
+
       # @return [FairQueue]
       #
       attr_reader :recv_queue
@@ -36,6 +37,7 @@ module OMQ
         @tasks << task if task
       end
 
+
       # @param connection [Connection]
       #
       def connection_removed(connection)
@@ -43,12 +45,14 @@ module OMQ
         @recv_queue.remove_queue(connection)
       end
 
+
       # SUB is read-only.
       #
       def enqueue(_parts)
         raise "SUB sockets cannot send"
       end
 
+
       # Subscribes to a topic prefix.
       #
       # @param prefix [String]
@@ -60,6 +64,7 @@ module OMQ
         end
       end
 
+
       # Unsubscribes from a topic prefix.
       #
       # @param prefix [String]
@@ -71,6 +76,11 @@ module OMQ
         end
       end
 
+
+      # Stops all background tasks.
+      #
+      # @return [void]
+      #
       def stop
         @tasks.each(&:stop)
         @tasks.clear

data/lib/omq/routing/xpub.rb

@@ -23,6 +23,7 @@ module OMQ
         init_fan_out(engine)
       end
 
+
       # @return [Async::LimitedQueue]
       #
       attr_reader :recv_queue
@@ -36,6 +37,7 @@ module OMQ
         add_fan_out_send_connection(connection)
       end
 
+
       # @param connection [Connection]
       #
       def connection_removed(connection)
@@ -44,12 +46,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)
@@ -65,6 +72,7 @@ module OMQ
         @recv_queue.enqueue(["\x01#{prefix}".b])
       end
 
+
       # Expose unsubscription to application as data message.
       #
       def on_cancel(conn, prefix)

data/lib/omq/routing/xsub.rb

@@ -21,6 +21,7 @@ module OMQ
         @tasks           = []
       end
 
+
       # @return [FairQueue]
       #
       attr_reader :recv_queue
@@ -41,6 +42,7 @@ module OMQ
         start_conn_send_pump(connection, q)
       end
 
+
       # @param connection [Connection]
       #
       def connection_removed(connection)
@@ -50,6 +52,7 @@ module OMQ
         @conn_send_tasks.delete(connection)&.stop
       end
 
+
       # Enqueues a subscription command (fan-out to all connected PUBs).
       #
       # @param parts [Array<String>]
@@ -58,13 +61,18 @@ module OMQ
         @connections.each { |conn| @conn_queues[conn]&.enqueue(parts) }
       end
 
+
+      # Stops all background tasks.
+      #
+      # @return [void]
       #
       def stop
         @tasks.each(&:stop)
         @tasks.clear
       end
 
-      # True when all per-connection send queues are empty.
+
+      # @return [Boolean] true when all per-connection send queues are empty
       #
       def send_queues_drained?
         @conn_queues.values.all?(&:empty?)
@@ -82,8 +90,10 @@ module OMQ
             prefix = frame.byteslice(1..) || "".b
             begin
               case flag
-              when 0x01 then conn.send_command(Protocol::ZMTP::Codec::Command.subscribe(prefix))
-              when 0x00 then conn.send_command(Protocol::ZMTP::Codec::Command.cancel(prefix))
+              when 0x01
+                conn.send_command(Protocol::ZMTP::Codec::Command.subscribe(prefix))
+              when 0x00
+                conn.send_command(Protocol::ZMTP::Codec::Command.cancel(prefix))
               end
             rescue Protocol::ZMTP::Error, *CONNECTION_LOST
               @engine.connection_lost(conn)

data/lib/omq/routing.rb

@@ -18,6 +18,7 @@ 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+.
     #
@@ -35,6 +36,7 @@ module OMQ
       end
     end
 
+
     # Builds a send or recv queue based on the mute strategy.
     #
     # @param hwm [Integer] high water mark
@@ -54,6 +56,7 @@ module OMQ
       end
     end
 
+
     # Drains all available messages from +queue+ into +batch+ without
     # blocking. Call after the initial blocking dequeue.
     #
@@ -73,6 +76,7 @@ module OMQ
       end
     end
 
+
     # Returns the routing strategy class for a socket type.
     #
     # @param socket_type [Symbol] e.g. :PAIR, :REQ
@@ -80,17 +84,28 @@ module OMQ
     #
     def self.for(socket_type)
       case socket_type
-      when :PAIR   then Pair
-      when :REQ    then Req
-      when :REP    then Rep
-      when :DEALER then Dealer
-      when :ROUTER then Router
-      when :PUB    then Pub
-      when :SUB    then Sub
-      when :XPUB   then XPub
-      when :XSUB   then XSub
-      when :PUSH   then Push
-      when :PULL   then Pull
+      when :PAIR
+        Pair
+      when :REQ
+        Req
+      when :REP
+        Rep
+      when :DEALER
+        Dealer
+      when :ROUTER
+        Router
+      when :PUB
+        Pub
+      when :SUB
+        Sub
+      when :XPUB
+        XPub
+      when :XSUB
+        XSub
+      when :PUSH
+        Push
+      when :PULL
+        Pull
       else
         @registry[socket_type] or raise ArgumentError, "unknown socket type: #{socket_type.inspect}"
       end

data/lib/omq/socket.rb

@@ -62,7 +62,12 @@ module OMQ
     end
 
 
-    def initialize(endpoints = nil, linger: 0); end
+    # @param endpoints [String, nil] optional endpoint with prefix convention
+    #   (+@+ for bind, +>+ for connect, plain uses subclass default)
+    # @param linger [Integer] linger period in seconds (default 0)
+    #
+    def initialize(endpoints = nil, linger: 0)
+    end
 
 
     # Binds to an endpoint.
@@ -136,6 +141,8 @@ module OMQ
     # Signals end-of-stream on the receive side. A subsequent
     # +#receive+ call that would otherwise block returns +nil+.
     #
+    # @return [void]
+    #
     def close_read
       @engine.dequeue_recv_sentinel
     end
@@ -182,12 +189,18 @@ module OMQ
 
 
     # Disable auto-reconnect for connected endpoints.
+    #
+    # @param val [Boolean]
+    # @return [void]
+    #
     def reconnect_enabled=(val)
       @engine.reconnect_enabled = val
     end
 
 
-    # Closes the socket.
+    # Closes the socket and releases all resources.
+    #
+    # @return [nil]
     #
     def close
       Reactor.run { @engine.close }
@@ -197,6 +210,8 @@ module OMQ
 
     # Set socket to use unbounded pipes (HWM=0).
     #
+    # @return [nil]
+    #
     def set_unbounded
       @options.send_hwm = 0
       @options.recv_hwm = 0
@@ -277,9 +292,12 @@ module OMQ
       @recv_buffer = []
       @recv_mutex  = Mutex.new
       @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}"
+                     when nil, :ruby
+                       Engine.new(socket_type, @options)
+                     when :ffi
+                       FFI::Engine.new(socket_type, @options)
+                     else
+                       raise ArgumentError, "unknown backend: #{backend}"
                      end
     end
   end

data/lib/omq/transport/inproc/direct_pipe.rb

@@ -64,6 +64,9 @@ module OMQ
         # Sets the direct recv queue. Drains any messages that were
         # buffered before the queue was available.
         #
+        # @param queue [Async::LimitedQueue, nil]
+        # @return [void]
+        #
         def direct_recv_queue=(queue)
           @direct_recv_queue = queue
           if queue && @pending_direct
@@ -93,8 +96,14 @@ module OMQ
         alias write_message send_message
 
 
+        # @return [Boolean] always false; inproc pipes are never encrypted
+        #
+        def encrypted? = false
+
         # No-op — inproc has no IO buffer to flush.
         #
+        # @return [nil]
+        #
         def flush = nil
 
 
@@ -143,7 +152,9 @@ module OMQ
         end
 
 
-        # Closes this pipe end.
+        # Closes this pipe end and sends a nil sentinel to the peer.
+        #
+        # @return [void]
         #
         def close
           return if @closed

data/lib/omq/transport/inproc.rb

@@ -19,6 +19,7 @@ module OMQ
       #
       COMMAND_TYPES = %i[PUB SUB XPUB XSUB RADIO DISH].freeze
 
+
       # Global registry of bound inproc endpoints.
       #
       @registry = {}
@@ -105,11 +106,13 @@ module OMQ
           server_engine.connection_ready(server_pipe, endpoint: endpoint)
         end
 
+
         def needs_commands?(ce, se, ct, st)
           COMMAND_TYPES.include?(ct) || COMMAND_TYPES.include?(st) ||
             ce.options.qos >= 1 || se.options.qos >= 1
         end
 
+
         def make_pipe_pair(ce, se, ct, st, needs_cmds)
           if needs_cmds
             a_to_b = Async::Queue.new
@@ -126,6 +129,7 @@ module OMQ
           [client, server]
         end
 
+
         def await_bind(endpoint, engine)
           # Endpoint not bound yet — wait briefly then start background retry.
           # Matches ZMQ 4.x: connect to unbound inproc succeeds silently.
@@ -163,6 +167,7 @@ module OMQ
         end
       end
 
+
       # A bound inproc endpoint handle.
       #
       class Listener

data/lib/omq/transport/ipc.rb

@@ -30,6 +30,7 @@ module OMQ
           Listener.new(endpoint, server, path)
         end
 
+
         # Connects to an IPC endpoint.
         #
         # @param endpoint [String]
@@ -51,6 +52,7 @@ module OMQ
           endpoint.sub(%r{\Aipc://}, "")
         end
 
+
         # Converts @ prefix to \0 for abstract namespace.
         #
         def to_socket_path(path)
@@ -61,6 +63,7 @@ module OMQ
           end
         end
 
+
         # @return [Boolean] true if abstract namespace path
         #
         def abstract?(path)
@@ -68,6 +71,7 @@ module OMQ
         end
       end
 
+
       # A bound IPC listener.
       #
       class Listener
@@ -113,7 +117,9 @@ module OMQ
         end
 
 
-        # Stops the listener.
+        # Stops the listener and removes the socket file.
+        #
+        # @return [void]
         #
         def stop
           @task&.stop

data/lib/omq/transport/tcp.rb

@@ -37,12 +37,7 @@ module OMQ
           Listener.new(resolved, servers, actual_port)
         end
 
-        # Connects to a TCP endpoint.
-        #
-        # @param endpoint [String] e.g. "tcp://127.0.0.1:5555"
-        # @param engine [Engine]
-        # @return [void]
-        #
+
         # Validates that the endpoint's host can be resolved.
         #
         # @param endpoint [String]
@@ -54,12 +49,19 @@ module OMQ
         end
 
 
+        # Connects to a TCP endpoint.
+        #
+        # @param endpoint [String] e.g. "tcp://127.0.0.1:5555"
+        # @param engine [Engine]
+        # @return [void]
+        #
         def connect(endpoint, engine)
           host, port = self.parse_endpoint(endpoint)
           sock = TCPSocket.new(host, port)
           engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: endpoint)
         end
 
+
         # Parses a TCP endpoint URI into host and port.
         #
         # @param endpoint [String]
@@ -71,6 +73,7 @@ module OMQ
         end
       end
 
+
       # A bound TCP listener.
       #
       class Listener
@@ -122,7 +125,9 @@ module OMQ
         end
 
 
-        # Stops the listener.
+        # Stops the listener and closes all server sockets.
+        #
+        # @return [void]
         #
         def stop
           @tasks.each(&:stop)

data/lib/omq/version.rb

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

data/lib/omq/writable.rb

@@ -19,6 +19,7 @@ module OMQ
       self
     end
 
+
     # Sends a message (chainable).
     #
     # @param message [String, Array<String>]
@@ -46,6 +47,7 @@ module OMQ
       parts.freeze
     end
 
+
     def frozen_binary(str)
       s = str.to_str
       return s if s.frozen? && s.encoding == Encoding::BINARY

data/lib/omq.rb

@@ -16,7 +16,9 @@ module OMQ
   # Raised when an internal pump task crashes unexpectedly.
   # The socket is no longer usable; the original error is available via #cause.
   #
-  class SocketDeadError < RuntimeError; end
+  class SocketDeadError < RuntimeError
+  end
+
 
   # Errors raised when a peer disconnects or resets the connection.
   # Not frozen at load time — transport plugins append to this before
@@ -42,6 +44,7 @@ module OMQ
   ]
 end
 
+
 # Transport
 require_relative "omq/transport/inproc"
 require_relative "omq/transport/tcp"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omq
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.1
 platform: ruby
 authors:
 - Patrik Wenger
@@ -13,16 +13,16 @@ dependencies:
   name: protocol-zmtp
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: async
   requirement: !ruby/object:Gem::Requirement
@@ -69,6 +69,7 @@ files:
 - lib/omq/engine.rb
 - lib/omq/engine/connection_setup.rb
 - lib/omq/engine/heartbeat.rb
+- lib/omq/engine/maintenance.rb
 - lib/omq/engine/reconnect.rb
 - lib/omq/engine/recv_pump.rb
 - lib/omq/monitor_event.rb