nnq 0.2.0

data/lib/nnq/routing/req.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "async"
+require "securerandom"
+
+module NNQ
+  module Routing
+    # REQ: client side of req0/rep0.
+    #
+    # Wire format: each message body on the wire is `[4-byte BE
+    # request_id][user_payload]`. The request id has the high bit set
+    # (`0x80000000..0xFFFFFFFF`) — that's nng's marker for "this is the
+    # last (deepest) frame on the backtrace stack". Direct REQ→REP has
+    # exactly one id.
+    #
+    # Semantics (cooked mode, what this implements):
+    # - At most one in-flight request per socket. Issuing a new
+    #   send_request while a previous one is still waiting for its
+    #   reply cancels the previous one: the blocked caller wakes up
+    #   with a {NNQ::RequestCancelled} error and the late reply (if
+    #   any) is silently dropped. This matches nng cooked req0, where
+    #   a new nng_sendmsg abandons the prior request.
+    # - Reply is matched by id, NOT by pipe. Late or unmatched replies
+    #   are silently dropped.
+    # - Round-robin peer selection, but no retry timer (real nng resends
+    #   on a timer; we leave that to the user via timeouts).
+    # - Blocks waiting for a peer if no connection is currently up.
+    #
+    class Req
+      def initialize(engine)
+        @engine     = engine
+        @next_idx   = 0
+        @mutex      = Mutex.new
+        @outstanding = nil # [id, promise] or nil
+      end
+
+
+      # Sends +body+ as a request, blocks until the matching reply
+      # comes back. Returns the reply payload (without the id header).
+      #
+      # If another fiber issues a send_request while this call is
+      # waiting, this call raises {NNQ::RequestCancelled}.
+      #
+      # @param body [String]
+      # @return [String]
+      def send_request(body)
+        id      = SecureRandom.random_number(0x80000000) | 0x80000000
+        promise = Async::Promise.new
+
+        @mutex.synchronize do
+          # Cancel any in-flight request — new send supersedes it.
+          @outstanding&.last&.reject(RequestCancelled.new("cancelled by new send_request"))
+          @outstanding = [id, promise]
+        end
+
+        conn   = pick_peer
+        header = [id].pack("N")
+        conn.send_message(header + body)
+        promise.wait
+      ensure
+        @mutex.synchronize do
+          # Only clear the slot if it's still ours. If a concurrent
+          # send_request already replaced it, leave the new entry alone.
+          @outstanding = nil if @outstanding && @outstanding[0] == id
+        end
+      end
+
+
+      # Called by the engine recv loop with each received frame.
+      def enqueue(body, _conn)
+        return if body.bytesize < 4
+        id      = body.unpack1("N")
+        payload = body.byteslice(4..)
+
+        @mutex.synchronize do
+          if @outstanding && @outstanding[0] == id
+            @outstanding[1].resolve(payload)
+          end
+          # Mismatched id → late/spurious reply, silently dropped.
+        end
+      end
+
+
+      def close
+        @mutex.synchronize do
+          @outstanding&.last&.reject(NNQ::Error.new("REQ socket closed"))
+          @outstanding = nil
+        end
+      end
+
+
+      private
+
+      def pick_peer
+        loop do
+          conns = @engine.connections.keys
+          if conns.empty?
+            @engine.new_pipe.wait
+            next
+          end
+          @next_idx = (@next_idx + 1) % conns.size
+          return conns[@next_idx]
+        end
+      end
+    end
+  end
+end

data/lib/nnq/routing/send_pump.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/limited_queue"
+
+module NNQ
+  module Routing
+    # Mixin for routing strategies that drain a shared bounded send queue
+    # via per-connection work-stealing pumps. Used by PUSH (load-balance
+    # across N peers) and PAIR (single peer, but the same pump shape).
+    #
+    # See DESIGN.md "Per-socket HWM" for the rationale.
+    #
+    # The per-pump batch caps (BATCH_MSG_CAP / BATCH_BYTE_CAP) enforce
+    # fairness across the work-stealing pumps. Without them, the first
+    # pump that wakes up would drain the entire queue in one non-blocking
+    # burst before any other pump got a turn (TCP send buffers absorb
+    # bursts without forcing a fiber yield).
+    #
+    # Including classes must call {#init_send_pump} from #initialize and
+    # {#spawn_send_pump_for} from their #connection_added hook.
+    #
+    module SendPump
+      BATCH_MSG_CAP  = 256
+      BATCH_BYTE_CAP = 256 * 1024
+
+
+      # @return [Boolean] true once the shared queue is empty AND no
+      #   batch is mid-write across any pump.
+      def send_queue_drained?
+        @send_queue.empty? && @in_flight.zero?
+      end
+
+
+      # Removes a pump and stops its task (unless called from inside
+      # the pump itself, in which case the pump is already on its way
+      # out via the rescue/ensure path).
+      def remove_send_pump_for(conn)
+        task = @pumps.delete(conn)
+        return if task.nil? || task == Async::Task.current
+        task.stop
+      rescue IOError, Errno::EPIPE
+        # Pump was mid-flush when its conn was closed; cancel surfaced
+        # the same IOError. Already handled — pump is gone.
+      end
+
+
+      # Stops all send pump tasks. Each pump's ensure block calls
+      # engine.handle_connection_lost → routing.connection_removed
+      # which removes its own entry, so iterate over a snapshot.
+      def close
+        @pumps.values.each(&:stop)
+        @pumps.clear
+      end
+
+
+      private
+
+      # @param engine [Engine]
+      def init_send_pump(engine)
+        @engine     = engine
+        @send_queue = Async::LimitedQueue.new(engine.options.send_hwm)
+        @pumps      = {} # conn => pump task
+        @in_flight  = 0  # batches dequeued but not yet flushed
+      end
+
+
+      # Enqueues +body+ on the shared send queue. Blocks the caller when
+      # the queue is full (HWM backpressure).
+      #
+      # @param body [String]
+      def enqueue_for_send(body)
+        @send_queue.enqueue(body)
+      end
+
+
+      # Spawns a send pump fiber for +conn+ that races to drain the
+      # shared queue.
+      #
+      # @param conn [Connection]
+      def spawn_send_pump_for(conn)
+        task = @engine.spawn_task(annotation: "nnq send pump #{conn.endpoint}") do
+          loop do
+            first = @send_queue.dequeue
+            break if first.nil? # queue closed
+            @in_flight += 1
+            begin
+              batch = [first]
+              drain_capped(batch)
+              write_batch(conn, batch)
+            ensure
+              @in_flight -= 1
+            end
+          rescue EOFError, IOError, Errno::EPIPE, Errno::ECONNRESET
+            # Peer died mid-flush. In-flight batch dropped.
+            break
+          end
+        ensure
+          @engine.handle_connection_lost(conn)
+        end
+        @pumps[conn] = task
+      end
+
+
+      def drain_capped(batch)
+        bytes = batch[0].bytesize
+        while batch.size < BATCH_MSG_CAP && bytes < BATCH_BYTE_CAP
+          msg = @send_queue.dequeue(timeout: 0)
+          break unless msg
+          batch << msg
+          bytes += msg.bytesize
+        end
+      end
+
+
+      def write_batch(conn, batch)
+        if batch.size == 1
+          conn.write_message(batch[0])
+        else
+          # Single mutex acquisition for the whole batch (batches run
+          # up to BATCH_MSG_CAP messages). The per-message pump loop
+          # would otherwise lock/unlock the SP mutex N times.
+          conn.write_messages(batch)
+        end
+        conn.flush
+      end
+    end
+  end
+end

data/lib/nnq/routing/sub.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "async/queue"
+
+module NNQ
+  module Routing
+    # SUB side of the pub/sub pattern (nng sub0).
+    #
+    # All filtering happens locally — pub0 broadcasts blindly and sub0
+    # drops messages that don't match any subscription prefix. An empty
+    # subscription set means receive nothing (matching nng — unlike
+    # ZeroMQ's pre-4.x "no subscription = receive everything").
+    #
+    # Subscriptions are byte-prefix matches. A subscription to the
+    # empty string matches every message.
+    #
+    class Sub
+      def initialize
+        @queue         = Async::Queue.new
+        @subscriptions = [] # array of byte strings
+      end
+
+
+      def subscribe(prefix)
+        prefix = prefix.b
+        @subscriptions << prefix unless @subscriptions.include?(prefix)
+      end
+
+
+      def unsubscribe(prefix)
+        @subscriptions.delete(prefix.b)
+      end
+
+
+      def enqueue(body, _conn = nil)
+        return unless matches?(body)
+        @queue.enqueue(body)
+      end
+
+
+      # @return [String, nil]
+      def receive
+        @queue.dequeue
+      end
+
+
+      def close
+        @queue.enqueue(nil)
+      end
+
+      private
+
+      def matches?(body)
+        @subscriptions.any? { |prefix| body.start_with?(prefix) }
+      end
+    end
+  end
+end

data/lib/nnq/socket.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "options"
+require_relative "engine"
+require_relative "reactor"
+
+module NNQ
+  # Socket base class. Subclasses (PUSH, PULL, ...) wire up a routing
+  # strategy and the SP protocol id.
+  #
+  class Socket
+    # @return [Options]
+    attr_reader :options
+
+
+    def self.bind(endpoint, **opts)
+      sock = new(**opts)
+      sock.bind(endpoint)
+      sock
+    end
+
+
+    def self.connect(endpoint, **opts)
+      sock = new(**opts)
+      sock.connect(endpoint)
+      sock
+    end
+
+
+    def initialize(linger: nil, send_hwm: Options::DEFAULT_HWM)
+      @options = Options.new(linger: linger, send_hwm: send_hwm)
+      @engine  = Engine.new(protocol: protocol, options: @options) { |engine| build_routing(engine) }
+    end
+
+
+    def bind(endpoint)
+      ensure_parent_task
+      Reactor.run { @engine.bind(endpoint) }
+    end
+
+
+    def connect(endpoint)
+      ensure_parent_task
+      Reactor.run { @engine.connect(endpoint) }
+    end
+
+
+    def close
+      Reactor.run { @engine.close }
+      nil
+    end
+
+
+    def last_endpoint = @engine.last_endpoint
+
+
+    def connection_count = @engine.connections.size
+
+
+    private
+
+    def ensure_parent_task
+      # Must run OUTSIDE Reactor.run so that non-Async callers capture
+      # the IO thread's root task, not the ephemeral work-item task
+      # that Reactor wraps each dispatched block in. Inside an Async
+      # reactor, the current task is the right parent.
+      if Async::Task.current?
+        @engine.capture_parent_task(Async::Task.current)
+      else
+        @engine.capture_parent_task(Reactor.root_task)
+      end
+    end
+
+
+    # Subclass hooks.
+
+    def protocol
+      raise NotImplementedError
+    end
+
+
+    def build_routing(_engine)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/nnq/transport/inproc.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "socket"
+require "io/stream"
+
+module NNQ
+  module Transport
+    # In-process transport. Both peers live in the same process and
+    # exchange frames over a Unix socketpair — no network, no address.
+    #
+    # Unlike omq's DirectPipe, inproc here still runs through
+    # Protocol::SP: the socketpair just replaces TCP. Kernel buffering
+    # across the pair is plenty to avoid contention for typical
+    # in-process message sizes, and reusing the SP handshake + framing
+    # keeps the transport ~40 LOC instead of a parallel Connection
+    # implementation.
+    #
+    module Inproc
+      @registry = {}
+      @mutex    = Mutex.new
+
+
+      class << self
+        # Binds +engine+ to +endpoint+ in the process-global registry.
+        #
+        # @param endpoint [String] e.g. "inproc://my-endpoint"
+        # @param engine [Engine]
+        # @return [Listener]
+        def bind(endpoint, engine)
+          @mutex.synchronize do
+            raise Error, "inproc endpoint already bound: #{endpoint}" if @registry.key?(endpoint)
+            @registry[endpoint] = engine
+          end
+          Listener.new(endpoint)
+        end
+
+
+        # Connects +engine+ to a bound inproc endpoint. Creates a Unix
+        # socketpair, hands one side to the bound engine (accepted),
+        # the other to the connecting engine (connected). Both sides
+        # run the normal SP handshake concurrently.
+        #
+        # @param endpoint [String]
+        # @param engine [Engine]
+        # @return [void]
+        def connect(endpoint, engine)
+          bound = @mutex.synchronize { @registry[endpoint] }
+          raise Error, "inproc endpoint not bound: #{endpoint}" unless bound
+          a, b = UNIXSocket.pair
+          # Handshake on the bound side must run concurrently with
+          # ours — if we called bound.handle_accepted synchronously
+          # it would block on reading our greeting before we've had
+          # a chance to write it.
+          bound.spawn_task(annotation: "nnq inproc accept #{endpoint}") do
+            bound.handle_accepted(IO::Stream::Buffered.wrap(b), endpoint: endpoint)
+          end
+          engine.handle_connected(IO::Stream::Buffered.wrap(a), endpoint: endpoint)
+        end
+
+
+        # Removes +endpoint+ from the registry. Called by Listener#stop.
+        def unbind(endpoint)
+          @mutex.synchronize { @registry.delete(endpoint) }
+        end
+
+
+        # Clears the registry. For tests.
+        def reset!
+          @mutex.synchronize { @registry.clear }
+        end
+      end
+
+
+      # A bound inproc endpoint. Owns no fibers — just a registry entry.
+      class Listener
+        attr_reader :endpoint
+
+        def initialize(endpoint)
+          @endpoint = endpoint
+        end
+
+
+        # No accept loop: inproc connects synchronously.
+        def start_accept_loop(_parent_task, &_on_accepted)
+        end
+
+
+        def stop
+          Inproc.unbind(@endpoint)
+        end
+      end
+    end
+  end
+end

data/lib/nnq/transport/ipc.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "socket"
+require "io/stream"
+
+module NNQ
+  module Transport
+    # IPC transport using Unix domain sockets.
+    #
+    # Supports both file-based paths and Linux abstract namespace
+    # (paths starting with @). Wire format is identical to TCP: SP/TCP
+    # greeting followed by framed messages, so Protocol::SP handles it
+    # verbatim.
+    #
+    module IPC
+      class << self
+        # Binds an IPC server.
+        #
+        # @param endpoint [String] e.g. "ipc:///tmp/nnq.sock" or "ipc://@abstract"
+        # @param engine [Engine]
+        # @return [Listener]
+        def bind(endpoint, engine)
+          path      = parse_path(endpoint)
+          sock_path = to_socket_path(path)
+          File.delete(sock_path) if !abstract?(path) && File.exist?(sock_path)
+          server = UNIXServer.new(sock_path)
+          Listener.new(endpoint, server, path, engine)
+        end
+
+
+        # Connects to an IPC endpoint.
+        #
+        # @param endpoint [String]
+        # @param engine [Engine]
+        # @return [void]
+        def connect(endpoint, engine)
+          path      = parse_path(endpoint)
+          sock_path = to_socket_path(path)
+          sock      = UNIXSocket.new(sock_path)
+          engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: endpoint, framing: :ipc)
+        end
+
+
+        def parse_path(endpoint)
+          endpoint.sub(%r{\Aipc://}, "")
+        end
+
+
+        # Converts @ prefix to \0 for Linux abstract namespace.
+        def to_socket_path(path)
+          abstract?(path) ? "\0#{path[1..]}" : path
+        end
+
+
+        def abstract?(path)
+          path.start_with?("@")
+        end
+      end
+
+
+      # A bound IPC listener.
+      class Listener
+        attr_reader :endpoint
+
+        def initialize(endpoint, server, path, engine)
+          @endpoint = endpoint
+          @server   = server
+          @path     = path
+          @engine   = engine
+          @task     = nil
+        end
+
+
+        def start_accept_loop(parent_task, &on_accepted)
+          @task = parent_task.async(annotation: "nnq ipc accept #{@endpoint}") do
+            loop do
+              client = @server.accept
+              # Engine's per-listener block closes over +framing+ below.
+              on_accepted.call(IO::Stream::Buffered.wrap(client), :ipc)
+            rescue Async::Stop, IOError
+              break
+            end
+          ensure
+            @server.close rescue nil
+          end
+        end
+
+
+        def stop
+          @task&.stop
+          @server.close rescue nil
+          File.delete(@path) rescue nil unless IPC.abstract?(@path)
+        end
+      end
+    end
+  end
+end

data/lib/nnq/transport/tcp.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "socket"
+require "uri"
+require "io/stream"
+
+module NNQ
+  module Transport
+    # TCP transport. Smaller than omq's: no IPv6 dual-bind dance, no
+    # custom buffer-size sockopts (yet). One server per bind, blocking
+    # accept inside an Async fiber.
+    #
+    module TCP
+      class << self
+        # Binds a TCP server to +endpoint+.
+        #
+        # @param endpoint [String] e.g. "tcp://127.0.0.1:5570" or "tcp://127.0.0.1:0"
+        # @param engine [Engine]
+        # @return [Listener]
+        def bind(endpoint, engine)
+          host, port = parse_endpoint(endpoint)
+          host = "0.0.0.0" if host == "*"
+          server = TCPServer.new(host, port)
+          actual = server.local_address.ip_port
+          host_part = host.include?(":") ? "[#{host}]" : host
+          Listener.new("tcp://#{host_part}:#{actual}", server, actual, engine)
+        end
+
+
+        # Connects to +endpoint+ and registers the resulting pipe with
+        # the engine. Synchronous (errors propagate to the caller).
+        #
+        # @param endpoint [String]
+        # @param engine [Engine]
+        # @return [void]
+        def connect(endpoint, engine)
+          host, port = parse_endpoint(endpoint)
+          sock = TCPSocket.new(host, port)
+          engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: endpoint)
+        end
+
+
+        def parse_endpoint(endpoint)
+          uri = URI.parse(endpoint)
+          [uri.hostname, uri.port]
+        end
+      end
+
+
+      # A bound TCP listener.
+      #
+      class Listener
+        attr_reader :endpoint
+        attr_reader :port
+
+        def initialize(endpoint, server, port, engine)
+          @endpoint = endpoint
+          @server   = server
+          @port     = port
+          @engine   = engine
+          @task     = nil
+        end
+
+
+        # Spawns an accept loop fiber under +parent_task+ that yields
+        # IO::Stream::Buffered for each accepted connection.
+        def start_accept_loop(parent_task, &on_accepted)
+          @task = parent_task.async(annotation: "nnq tcp accept #{@endpoint}") do
+            loop do
+              client = @server.accept
+              on_accepted.call(IO::Stream::Buffered.wrap(client))
+            rescue Async::Stop
+              break
+            rescue IOError
+              break
+            end
+          ensure
+            @server.close rescue nil
+          end
+        end
+
+
+        def stop
+          @task&.stop
+          @server.close rescue nil
+        end
+      end
+    end
+  end
+end

data/lib/nnq/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module NNQ
+  VERSION = "0.2.0"
+end

data/lib/nnq.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "protocol/sp"
+
+module NNQ
+end
+
+require_relative "nnq/version"
+require_relative "nnq/error"
+require_relative "nnq/options"
+require_relative "nnq/connection"
+require_relative "nnq/engine"
+require_relative "nnq/socket"
+require_relative "nnq/push_pull"
+require_relative "nnq/pair"
+require_relative "nnq/req_rep"
+require_relative "nnq/pub_sub"