nnq 0.2.0

data/lib/nnq/pub_sub.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "socket"
+require_relative "routing/pub"
+require_relative "routing/sub"
+
+module NNQ
+  # PUB side of the pub/sub pattern (nng pub0). Broadcasts every
+  # message to every connected SUB. Per-peer bounded send queues —
+  # a slow peer drops messages instead of blocking fast peers.
+  # Defaults to listening.
+  #
+  class PUB < Socket
+    def send(body)
+      Reactor.run { @engine.routing.send(body) }
+    end
+
+
+    private
+
+    def protocol
+      Protocol::SP::Protocols::PUB_V0
+    end
+
+
+    def build_routing(engine)
+      Routing::Pub.new(engine)
+    end
+  end
+
+
+  # SUB side of the pub/sub pattern (nng sub0). Applies local
+  # byte-prefix filtering. Empty subscription set means no messages
+  # are delivered — matching nng (unlike pre-4.x ZeroMQ). Defaults
+  # to dialing.
+  #
+  class SUB < Socket
+    # Subscribes to +prefix+. Bytes-level match. The empty string
+    # matches everything.
+    #
+    # @param prefix [String]
+    def subscribe(prefix)
+      Reactor.run { @engine.routing.subscribe(prefix) }
+    end
+
+
+    # Removes a previously-added subscription. No-op if not present.
+    #
+    # @param prefix [String]
+    def unsubscribe(prefix)
+      Reactor.run { @engine.routing.unsubscribe(prefix) }
+    end
+
+
+    # @return [String, nil]
+    def receive
+      Reactor.run { @engine.routing.receive }
+    end
+
+
+    private
+
+    def protocol
+      Protocol::SP::Protocols::SUB_V0
+    end
+
+
+    def build_routing(_engine)
+      Routing::Sub.new
+    end
+  end
+end

data/lib/nnq/push_pull.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "socket"
+require_relative "routing/push"
+require_relative "routing/pull"
+
+module NNQ
+  # PUSH side of the pipeline pattern (nng push0). Enqueues onto a single
+  # bounded send queue (`send_hwm`); per-peer send pumps work-steal from
+  # it. Defaults to dialing.
+  #
+  class PUSH < Socket
+    def send(body)
+      Reactor.run { @engine.routing.send(body) }
+    end
+
+
+    private
+
+    def protocol
+      Protocol::SP::Protocols::PUSH_V0
+    end
+
+
+    def build_routing(engine)
+      Routing::Push.new(engine)
+    end
+  end
+
+
+  # PULL side of the pipeline pattern (nng pull0). Fair-queues messages
+  # from all live PUSH peers into one unbounded receive queue. Defaults
+  # to listening.
+  #
+  class PULL < Socket
+    def receive
+      Reactor.run { @engine.routing.receive }
+    end
+
+
+    private
+
+    def protocol
+      Protocol::SP::Protocols::PULL_V0
+    end
+
+
+    def build_routing(_engine)
+      Routing::Pull.new
+    end
+  end
+end

data/lib/nnq/reactor.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "async"
+
+module NNQ
+  # Per-process fallback IO thread for non-Async callers.
+  #
+  # When user code already runs inside an Async reactor, NNQ tasks attach
+  # directly to the caller's task tree. When the caller is bare (e.g. a
+  # plain `Thread.new` or the main thread of a script), NNQ::Reactor lazily
+  # spawns one shared background thread that hosts an Async reactor and
+  # processes work items dispatched via {.run}.
+  #
+  # This is *not* an Async scheduler — it is a fallback thread for an
+  # Async reactor. NNQ and OMQ each have their own private fallback for
+  # bare-thread callers; both can coexist with the user's own reactor with
+  # no extraction or sharing required.
+  #
+  module Reactor
+    @mutex      = Mutex.new
+    @thread     = nil
+    @root_task  = nil
+    @work_queue = nil
+
+    class << self
+      def root_task
+        return @root_task if @root_task
+        @mutex.synchronize do
+          return @root_task if @root_task
+          ready       = Thread::Queue.new
+          @work_queue = Async::Queue.new
+          @thread     = Thread.new { run_reactor(ready) }
+          @thread.name = "nnq-io"
+          @root_task  = ready.pop
+          at_exit { stop! }
+        end
+        @root_task
+      end
+
+
+      def run(&block)
+        if Async::Task.current?
+          yield
+        else
+          result = Thread::Queue.new
+          root_task # ensure started
+          @work_queue.push([block, result])
+          status, value = result.pop
+          raise value if status == :error
+          value
+        end
+      end
+
+
+      def stop!
+        return unless @thread&.alive?
+        @work_queue&.push(nil)
+        @thread&.join(2)
+        @thread     = nil
+        @root_task  = nil
+        @work_queue = nil
+      end
+
+      private
+
+      def run_reactor(ready)
+        Async do |task|
+          ready.push(task)
+          loop do
+            item = @work_queue.dequeue
+            break if item.nil?
+            block, result = item
+            task.async do
+              result.push([:ok, block.call])
+            rescue => e
+              result.push([:error, e])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nnq/req_rep.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "socket"
+require_relative "routing/req"
+require_relative "routing/rep"
+
+module NNQ
+  # REQ (nng req0): client side of request/reply. Single in-flight
+  # request per socket. #send_request blocks until the matching reply
+  # comes back.
+  #
+  class REQ < Socket
+    # Sends +body+ as a request, blocks until the matching reply
+    # arrives. Returns the reply body (without the id header).
+    def send_request(body)
+      Reactor.run { @engine.routing.send_request(body) }
+    end
+
+
+    private
+
+    def protocol
+      Protocol::SP::Protocols::REQ_V0
+    end
+
+
+    def build_routing(engine)
+      Routing::Req.new(engine)
+    end
+  end
+
+
+  # REP (nng rep0): server side of request/reply. Strict alternation
+  # of #receive then #send_reply, per request.
+  #
+  class REP < Socket
+    # Blocks until the next request arrives. Returns the request body.
+    def receive
+      Reactor.run { @engine.routing.receive }
+    end
+
+
+    # Routes +body+ back to the pipe the most recent #receive came from.
+    def send_reply(body)
+      Reactor.run { @engine.routing.send_reply(body) }
+    end
+
+
+    private
+
+    def protocol
+      Protocol::SP::Protocols::REP_V0
+    end
+
+
+    def build_routing(engine)
+      Routing::Rep.new(engine)
+    end
+  end
+end

data/lib/nnq/routing/pair.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "async/queue"
+require_relative "send_pump"
+
+module NNQ
+  module Routing
+    # PAIR0: exclusive bidirectional channel with a single peer.
+    #
+    # Wire format: no SP header. Body on the wire is exactly the user
+    # payload (same as push0/pull0). Per nng's pair0, when a second peer
+    # tries to connect while one is already paired, the new pipe is
+    # rejected — first peer wins.
+    #
+    # Send side: shared send queue + 1 pump (reuses {SendPump}). The
+    # pump infrastructure is identical to PUSH; PAIR just never has
+    # more than one pump because it never has more than one peer.
+    #
+    # Recv side: messages fed by the engine's recv loop into a local
+    # Async::Queue. Unbounded — TCP throttles the peer.
+    #
+    class Pair
+      include SendPump
+
+      def initialize(engine)
+        init_send_pump(engine)
+        @recv_queue = Async::Queue.new
+        @peer       = nil
+      end
+
+
+      # @param body [String]
+      def send(body)
+        enqueue_for_send(body)
+      end
+
+
+      # @return [String, nil] message body, or nil once the socket is closed
+      def receive
+        @recv_queue.dequeue
+      end
+
+
+      # Called by the recv loop with each frame off the wire.
+      def enqueue(body, _conn = nil)
+        @recv_queue.enqueue(body)
+      end
+
+
+      # First-pipe-wins. Raising {ConnectionRejected} tells the
+      # ConnectionLifecycle to tear down the just-registered connection
+      # without ever exposing it to pumps.
+      def connection_added(conn)
+        raise ConnectionRejected, "PAIR socket already has a peer" if @peer
+        @peer = conn
+        spawn_send_pump_for(conn)
+      end
+
+
+      def connection_removed(conn)
+        remove_send_pump_for(conn)
+        @peer = nil if @peer == conn
+      end
+
+
+      def close
+        super
+        @recv_queue.enqueue(nil) # wake any waiter
+      end
+    end
+  end
+end

data/lib/nnq/routing/pub.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/limited_queue"
+
+module NNQ
+  module Routing
+    # PUB side of the pub/sub pattern (nng pub0).
+    #
+    # Broadcasts every message to every connected SUB. Each peer gets
+    # its own bounded send queue (`send_hwm`) and its own send pump
+    # fiber — a slow subscriber cannot block fast ones. When a peer's
+    # queue is full, new messages are dropped for that peer (matching
+    # nng's non-blocking fan-out semantics).
+    #
+    # Pub0 has no subscription state on the sender side: SUBs filter
+    # locally. Pub0 is strictly one-directional; nothing is read from
+    # SUB peers.
+    #
+    class Pub
+      def initialize(engine)
+        @engine     = engine
+        @queues     = {} # conn => Async::LimitedQueue
+        @pump_tasks = {} # conn => Async::Task
+      end
+
+
+      # Broadcasts +body+ to every connected peer. Non-blocking per
+      # peer: drops when a peer's queue is at HWM.
+      #
+      # @param body [String]
+      def send(body)
+        @queues.each_value do |queue|
+          queue.enqueue(body) unless queue.limited?
+        end
+      end
+
+
+      def connection_added(conn)
+        queue = Async::LimitedQueue.new(@engine.options.send_hwm)
+        # Register queue BEFORE spawning the pump. spawn_task yields
+        # control into the new task body, which parks on queue.dequeue;
+        # at that park the publisher fiber can run and must already see
+        # this peer's queue.
+        @queues[conn]     = queue
+        @pump_tasks[conn] = spawn_pump(conn, queue)
+      end
+
+
+      def connection_removed(conn)
+        @queues.delete(conn)
+        task = @pump_tasks.delete(conn)
+        return unless task
+        return if task == Async::Task.current
+        task.stop
+      rescue IOError, Errno::EPIPE
+        # pump was mid-flush; already unwinding
+      end
+
+
+      # True once every peer's queue is empty. Engine linger polls this.
+      def send_queue_drained?
+        @queues.each_value.all?(&:empty?)
+      end
+
+
+      def close
+        @pump_tasks.each_value(&:stop)
+        @pump_tasks.clear
+        @queues.clear
+      end
+
+      private
+
+      def spawn_pump(conn, queue)
+        @engine.spawn_task(annotation: "nnq pub pump #{conn.endpoint}") do
+          loop do
+            body = queue.dequeue
+            conn.send_message(body)
+          rescue EOFError, IOError, Errno::EPIPE, Errno::ECONNRESET
+            break
+          end
+        ensure
+          @engine.handle_connection_lost(conn)
+        end
+      end
+    end
+  end
+end

data/lib/nnq/routing/pull.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "async/queue"
+
+module NNQ
+  module Routing
+    # PULL side: an unbounded queue of received messages. Per-connection
+    # recv fibers (spawned by the Engine when each pipe is established)
+    # call {#enqueue} on each frame; user code calls {#receive}.
+    #
+    # No HWM, no prefetch buffer — TCP throttles the senders directly
+    # via the kernel buffer.
+    #
+    class Pull
+      def initialize
+        @queue = Async::Queue.new
+      end
+
+
+      def enqueue(body, _conn = nil)
+        @queue.enqueue(body)
+      end
+
+
+      # @return [String, nil] message body, or nil if the queue was closed
+      def receive
+        @queue.dequeue
+      end
+
+
+      # Wakes any waiters with nil so receive returns from a closed
+      # socket.
+      def close
+        @queue.enqueue(nil)
+      end
+    end
+  end
+end

data/lib/nnq/routing/push.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "send_pump"
+
+module NNQ
+  module Routing
+    # PUSH side of the pipeline pattern.
+    #
+    # Architecture: ONE shared bounded send queue per socket. Each peer
+    # connection gets its own send pump fiber that races to dequeue from
+    # the shared queue and write to its peer (work-stealing). A slow
+    # peer's pump just stops pulling (blocked on its own TCP flush);
+    # fast peers' pumps keep draining. Strictly better than per-pipe
+    # round-robin for PUSH semantics — load naturally biases to whoever
+    # is keeping up.
+    #
+    class Push
+      include SendPump
+
+      def initialize(engine)
+        init_send_pump(engine)
+      end
+
+
+      # User-facing send: enqueue onto the shared send queue.
+      #
+      # @param body [String]
+      def send(body)
+        enqueue_for_send(body)
+      end
+
+
+      def connection_added(conn)
+        spawn_send_pump_for(conn)
+      end
+
+
+      def connection_removed(conn)
+        remove_send_pump_for(conn)
+      end
+    end
+  end
+end

data/lib/nnq/routing/rep.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "async/queue"
+
+module NNQ
+  module Routing
+    # REP: server side of req0/rep0.
+    #
+    # Wire format: incoming bodies are `[backtrace stack][user_payload]`.
+    # The backtrace is one or more 4-byte BE words; we keep reading words
+    # off the front until we hit one whose top byte has its high bit set
+    # (the original REQ's request id terminates the stack). The whole
+    # backtrace is stashed and echoed verbatim on reply, prepended to the
+    # reply body. REP never reorders or rewrites the stack — it's pure
+    # echo back to the originating pipe.
+    #
+    # Semantics (cooked mode):
+    # - At most one pending request at a time. Calling #receive while a
+    #   previous request is pending silently discards that request — its
+    #   backtrace is forgotten and any later #send_reply will target the
+    #   *new* request. This matches nng cooked rep0, where nng_recvmsg
+    #   after nng_recvmsg drops the earlier message.
+    # - Calling #send_reply with no pending request raises.
+    # - The reply must be routed back to the same pipe the request came
+    #   from. If that pipe died in the meantime, #send_reply silently
+    #   drops the reply (matches nng's pipe_terminated behavior).
+    # - TTL cap on the backtrace stack: 8 hops, matching nng's default.
+    #
+    class Rep
+      MAX_HOPS = 8 # nng's default ttl
+
+      def initialize(engine)
+        @engine     = engine
+        @recv_queue = Async::Queue.new   # holds [conn, btrace, body]
+        @pending    = nil                # [conn, btrace] or nil
+        @mutex      = Mutex.new
+      end
+
+
+      # Receives one request body. Stashes the backtrace + originating
+      # connection so the next #send_reply can route the reply back.
+      #
+      # @return [String, nil] body, or nil if the socket was closed
+      def receive
+        # Any prior pending request is discarded — calling receive
+        # again without replying is how users drop unwanted requests.
+        @mutex.synchronize { @pending = nil }
+        item = @recv_queue.dequeue
+        return nil if item.nil?
+        conn, btrace, body = item
+        @mutex.synchronize { @pending = [conn, btrace] }
+        body
+      end
+
+
+      # Sends +body+ as the reply to the most recently received request.
+      #
+      # @param body [String]
+      def send_reply(body)
+        conn, btrace = @mutex.synchronize do
+          raise Error, "REP socket has no pending request to reply to" unless @pending
+          taken    = @pending
+          @pending = nil
+          taken
+        end
+
+        return if conn.closed?
+        conn.send_message(btrace + body)
+      end
+
+
+      # Called by the engine recv loop with each received frame.
+      def enqueue(body, conn)
+        btrace, payload = parse_backtrace(body)
+        return unless btrace # malformed/over-TTL — drop
+        @recv_queue.enqueue([conn, btrace, payload])
+      end
+
+
+      def connection_removed(conn)
+        @mutex.synchronize do
+          @pending = nil if @pending && @pending[0] == conn
+        end
+      end
+
+
+      def close
+        @recv_queue.enqueue(nil)
+      end
+
+
+      private
+
+      # Reads 4-byte BE words off the front of +body+, stopping at the
+      # first one whose top byte has its high bit set. Returns
+      # [backtrace_bytes, remaining_payload] or nil on malformed input.
+      def parse_backtrace(body)
+        offset = 0
+        hops   = 0
+        while hops < MAX_HOPS
+          return nil if body.bytesize - offset < 4
+          word = body.byteslice(offset, 4)
+          offset += 4
+          hops   += 1
+          if word.getbyte(0) & 0x80 != 0
+            return [body.byteslice(0, offset), body.byteslice(offset..)]
+          end
+        end
+        nil # exceeded TTL without finding terminator
+      end
+    end
+  end
+end