omq 0.1.0

data/lib/omq/zmtp/routing/sub.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # SUB socket routing: subscription-based receive from PUB peers.
+      #
+      # Sends SUBSCRIBE/CANCEL commands to connected PUB peers.
+      #
+      class Sub
+
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine        = engine
+          @connections   = []
+          @recv_queue    = Async::LimitedQueue.new(engine.options.recv_hwm)
+          @subscriptions = Set.new
+          @tasks         = []
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :recv_queue
+
+        # @param connection [Connection]
+        #
+        def connection_added(connection)
+          @connections << connection
+          # Send existing subscriptions to new peer
+          @subscriptions.each do |prefix|
+            connection.send_command(Codec::Command.subscribe(prefix))
+          end
+          task = @engine.start_recv_pump(connection, @recv_queue)
+          @tasks << task if task
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_removed(connection)
+          @connections.delete(connection)
+        end
+
+        # SUB is read-only.
+        #
+        def enqueue(_parts)
+          raise "SUB sockets cannot send"
+        end
+
+        # Subscribes to a topic prefix.
+        #
+        # @param prefix [String]
+        #
+        def subscribe(prefix)
+          @subscriptions << prefix
+          @connections.each do |conn|
+            conn.send_command(Codec::Command.subscribe(prefix))
+          end
+        end
+
+        # Unsubscribes from a topic prefix.
+        #
+        # @param prefix [String]
+        #
+        def unsubscribe(prefix)
+          @subscriptions.delete(prefix)
+          @connections.each do |conn|
+            conn.send_command(Codec::Command.cancel(prefix))
+          end
+        end
+
+        def stop
+          @tasks.each(&:stop)
+          @tasks.clear
+        end
+
+      end
+    end
+  end
+end

data/lib/omq/zmtp/routing/xpub.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # XPUB socket routing: like PUB but exposes subscription messages.
+      #
+      # Subscription/unsubscription messages from peers are delivered to
+      # the application as data frames: \x01 + prefix for subscribe,
+      # \x00 + prefix for unsubscribe.
+      #
+      class XPub
+        include FanOut
+
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine     = engine
+          @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+          @tasks      = []
+          init_fan_out(engine)
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :recv_queue, :send_queue
+
+        # @param connection [Connection]
+        #
+        def connection_added(connection)
+          @connections << connection
+          @subscriptions[connection] = Set.new
+          start_subscription_listener(connection)
+          start_send_pump unless @send_pump_started
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_removed(connection)
+          @connections.delete(connection)
+          @subscriptions.delete(connection)
+        end
+
+        # @param parts [Array<String>]
+        #
+        def enqueue(parts)
+          @send_queue.enqueue(parts)
+        end
+
+        #
+        def stop
+          @tasks.each(&:stop)
+          @tasks.clear
+        end
+
+        private
+
+        # Expose subscription to application as data message.
+        #
+        def on_subscribe(conn, prefix)
+          super
+          @recv_queue.enqueue(["\x01#{prefix}".b])
+        end
+
+        # Expose unsubscription to application as data message.
+        #
+        def on_cancel(conn, prefix)
+          super
+          @recv_queue.enqueue(["\x00#{prefix}".b])
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/routing/xsub.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # XSUB socket routing: like SUB but subscriptions sent as data messages.
+      #
+      # Subscriptions are sent as data frames: \x01 + prefix for subscribe,
+      # \x00 + prefix for unsubscribe.
+      #
+      class XSub
+
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine            = engine
+          @connections       = []
+          @recv_queue        = Async::LimitedQueue.new(engine.options.recv_hwm)
+          @send_queue        = Async::LimitedQueue.new(engine.options.send_hwm)
+          @tasks             = []
+          @send_pump_started = false
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :recv_queue, :send_queue
+
+        # @param connection [Connection]
+        #
+        def connection_added(connection)
+          @connections << connection
+          task = @engine.start_recv_pump(connection, @recv_queue)
+          @tasks << task if task
+          start_send_pump unless @send_pump_started
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_removed(connection)
+          @connections.delete(connection)
+        end
+
+        # @param parts [Array<String>]
+        #
+        def enqueue(parts)
+          @send_queue.enqueue(parts)
+        end
+
+        #
+        def stop
+          @tasks.each(&:stop)
+          @tasks.clear
+        end
+
+        private
+
+        def start_send_pump
+          @send_pump_started = true
+          @tasks << Reactor.spawn_pump do
+            loop do
+              parts = @send_queue.dequeue
+              frame = parts.first&.b
+              next if frame.nil? || frame.empty?
+
+              flag   = frame.getbyte(0)
+              prefix = frame.byteslice(1..) || "".b
+
+              case flag
+              when 0x01
+                @connections.each { |c| c.send_command(Codec::Command.subscribe(prefix)) }
+              when 0x00
+                @connections.each { |c| c.send_command(Codec::Command.cancel(prefix)) }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/routing.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/queue"
+require "async/limited_queue"
+
+module OMQ
+  module ZMTP
+    # Routing strategies for each ZMQ socket type.
+    #
+    # Each strategy manages how messages flow between connections and
+    # the socket's send/recv queues.
+    #
+    module Routing
+      # Returns the routing strategy class for a socket type.
+      #
+      # @param socket_type [Symbol] e.g. :PAIR, :REQ
+      # @return [Class]
+      #
+      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
+        else raise ArgumentError, "unknown socket type: #{socket_type}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/queue"
+
+module OMQ
+  module ZMTP
+    module Transport
+      # In-process transport.
+      #
+      # Both peers are Ruby backend sockets in the same process (native
+      # ZMQ's inproc registry is separate and unreachable). Messages are
+      # transferred as Ruby arrays — no ZMTP framing, no byte
+      # serialization. String parts are frozen by Writable#send to
+      # prevent shared mutable state without copying.
+      #
+      module Inproc
+        # Socket types that exchange commands (SUBSCRIBE/CANCEL) over inproc.
+        #
+        COMMAND_TYPES = %i[PUB SUB XPUB XSUB].freeze
+
+        # Global registry of bound inproc endpoints.
+        #
+        @registry = {}
+        @mutex    = Mutex.new
+        @waiters  = Hash.new { |h, k| h[k] = [] }
+
+
+        class << self
+          # Binds an engine to an inproc endpoint.
+          #
+          # @param endpoint [String] e.g. "inproc://my-endpoint"
+          # @param engine [Engine] the owning engine
+          # @return [Listener]
+          # @raise [ArgumentError] if endpoint is already bound
+          #
+          def bind(endpoint, engine)
+            @mutex.synchronize do
+              raise ArgumentError, "endpoint already bound: #{endpoint}" if @registry.key?(endpoint)
+              @registry[endpoint] = engine
+
+              # Wake any pending connects
+              @waiters[endpoint].each { |p| p.resolve(true) }
+              @waiters.delete(endpoint)
+            end
+            Listener.new(endpoint)
+          end
+
+          # Connects to a bound inproc endpoint.
+          #
+          # @param endpoint [String] e.g. "inproc://my-endpoint"
+          # @param engine [Engine] the connecting engine
+          # @return [void]
+          #
+          def connect(endpoint, engine)
+            bound_engine = @mutex.synchronize { @registry[endpoint] }
+
+            unless bound_engine
+              # Endpoint not bound yet. Wait with timeout derived from
+              # reconnect_interval. If it doesn't appear, silently return —
+              # matching ZMQ 4.x behavior where inproc connect to an
+              # unbound endpoint succeeds but messages go nowhere.
+              # A background task retries periodically.
+              ri      = engine.options.reconnect_interval
+              timeout = ri.is_a?(Range) ? ri.begin : ri
+              promise = Async::Promise.new
+              @mutex.synchronize { @waiters[endpoint] << promise }
+              unless promise.wait?(timeout: timeout)
+                @mutex.synchronize { @waiters[endpoint].delete(promise) }
+                start_connect_retry(endpoint, engine)
+                return
+              end
+              bound_engine = @mutex.synchronize { @registry[endpoint] }
+            end
+
+            establish_link(engine, bound_engine, endpoint)
+          end
+
+          # Removes a bound endpoint from the registry.
+          #
+          # @param endpoint [String]
+          # @return [void]
+          #
+          def unbind(endpoint)
+            @mutex.synchronize { @registry.delete(endpoint) }
+          end
+
+          # Resets the registry. Used in tests.
+          #
+          # @return [void]
+          #
+          def reset!
+            @mutex.synchronize do
+              @registry.clear
+              @waiters.clear
+            end
+          end
+
+          private
+
+          def establish_link(client_engine, server_engine, endpoint)
+            client_type = client_engine.socket_type
+            server_type = server_engine.socket_type
+
+            unless ZMTP::VALID_PEERS[client_type]&.include?(server_type)
+              raise ProtocolError,
+                    "incompatible socket types: #{client_type} cannot connect to #{server_type}"
+            end
+
+            # Only PUB/SUB-family types exchange commands (SUBSCRIBE/CANCEL)
+            # over inproc. All other types use only the direct recv queue
+            # bypass for data, so no internal queues are needed.
+            needs_commands = COMMAND_TYPES.include?(client_type) ||
+                             COMMAND_TYPES.include?(server_type)
+
+            if needs_commands
+              a_to_b = Async::Queue.new
+              b_to_a = Async::Queue.new
+            end
+
+            client_pipe = DirectPipe.new(
+              send_queue:    needs_commands ? a_to_b : nil,
+              receive_queue: needs_commands ? b_to_a : nil,
+              peer_identity: server_engine.options.identity,
+              peer_type:     server_type.to_s,
+            )
+            server_pipe = DirectPipe.new(
+              send_queue:    needs_commands ? b_to_a : nil,
+              receive_queue: needs_commands ? a_to_b : nil,
+              peer_identity: client_engine.options.identity,
+              peer_type:     client_type.to_s,
+            )
+
+            client_pipe.peer = server_pipe
+            server_pipe.peer = client_pipe
+
+            client_engine.connection_ready(client_pipe, endpoint: endpoint)
+            server_engine.connection_ready(server_pipe, endpoint: endpoint)
+          end
+
+          def start_connect_retry(endpoint, engine)
+            Reactor.spawn_pump do
+              ri  = engine.options.reconnect_interval
+              ivl = ri.is_a?(Range) ? ri.begin : ri
+              loop do
+                sleep ivl
+                bound_engine = @mutex.synchronize { @registry[endpoint] }
+                if bound_engine
+                  establish_link(engine, bound_engine, endpoint)
+                  break
+                end
+              end
+            end
+          end
+        end
+
+        # A bound inproc endpoint handle.
+        #
+        class Listener
+          # @return [String] the bound endpoint
+          #
+          attr_reader :endpoint
+
+          # @param endpoint [String]
+          #
+          def initialize(endpoint)
+            @endpoint = endpoint
+          end
+
+          # Stops the listener by removing it from the registry.
+          #
+          # @return [void]
+          #
+          def stop
+            Inproc.unbind(@endpoint)
+          end
+        end
+
+        # A direct in-process pipe that transfers Ruby arrays through queues.
+        #
+        # Implements the same interface as Connection so routing strategies
+        # can use it transparently.
+        #
+        # When a routing strategy sets {#direct_recv_queue} on a pipe,
+        # {#send_message} enqueues directly into the peer's recv queue,
+        # bypassing the intermediate internal queues and the recv pump
+        # task entirely.  This reduces inproc from 3 queue hops to 1.
+        #
+        class DirectPipe
+          # @return [String] peer's socket type
+          #
+          attr_reader :peer_socket_type
+
+          # @return [String] peer's identity
+          #
+          attr_reader :peer_identity
+
+          # @return [DirectPipe, nil] the other end of this pipe pair
+          #
+          attr_accessor :peer
+
+          # @return [Async::LimitedQueue, nil] when set, {#send_message}
+          #   enqueues directly here instead of using the internal queue
+          #
+          attr_accessor :direct_recv_queue
+
+          # @return [Proc, nil] optional transform applied before
+          #   enqueuing into {#direct_recv_queue}
+          #
+          attr_accessor :direct_recv_transform
+
+          # @param send_queue [Async::Queue, nil] outgoing command queue
+          #   (nil for non-PUB/SUB types that don't exchange commands)
+          # @param receive_queue [Async::Queue, nil] incoming command queue
+          # @param peer_identity [String]
+          # @param peer_type [String]
+          #
+          def initialize(send_queue: nil, receive_queue: nil, peer_identity:, peer_type:)
+            @send_queue            = send_queue
+            @receive_queue         = receive_queue
+            @peer_identity         = peer_identity || "".b
+            @peer_socket_type      = peer_type
+            @closed                = false
+            @peer                  = nil
+            @direct_recv_queue     = nil
+            @direct_recv_transform = nil
+          end
+
+          # Sends a multi-frame message.
+          #
+          # When {#direct_recv_queue} is set (inproc fast path), the
+          # message is delivered directly to the peer's recv queue,
+          # skipping the internal pipe queues and the recv pump.
+          #
+          # @param parts [Array<String>]
+          # @return [void]
+          #
+          def send_message(parts)
+            raise IOError, "closed" if @closed
+            if @direct_recv_queue
+              msg = @direct_recv_transform ? @direct_recv_transform.call(parts) : parts
+              @direct_recv_queue.enqueue(msg)
+            else
+              @send_queue.enqueue(parts)
+            end
+          end
+
+          # Receives a multi-frame message.
+          #
+          # @return [Array<String>]
+          # @raise [EOFError] if closed
+          #
+          def receive_message
+            msg = @receive_queue.dequeue
+            raise EOFError, "connection closed" if msg.nil?
+            msg
+          end
+
+          # Sends a command via the internal command queue.
+          # Only available for PUB/SUB-family pipes.
+          #
+          # @param command [Codec::Command]
+          # @return [void]
+          #
+          def send_command(command)
+            raise IOError, "closed" if @closed
+            @send_queue.enqueue([:command, command])
+          end
+
+          # Reads one command frame from the internal command queue.
+          # Used by PUB/XPUB subscription listeners.
+          #
+          # @return [Codec::Frame]
+          #
+          def read_frame
+            loop do
+              item = @receive_queue.dequeue
+              raise EOFError, "connection closed" if item.nil?
+              if item.is_a?(Array) && item.first == :command
+                cmd = item[1]
+                return Codec::Frame.new(cmd.to_body, command: true)
+              end
+            end
+          end
+
+          # Closes this pipe end.
+          #
+          # @return [void]
+          #
+          def close
+            return if @closed
+            @closed = true
+            @send_queue&.enqueue(nil) # close sentinel
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/transport/ipc.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "socket"
+require "io/stream"
+
+module OMQ
+  module ZMTP
+    module Transport
+      # IPC transport using Unix domain sockets.
+      #
+      # Supports both file-based paths and Linux abstract namespace
+      # (paths starting with @).
+      #
+      module IPC
+        class << self
+          # Binds an IPC server.
+          #
+          # @param endpoint [String] e.g. "ipc:///tmp/my.sock" or "ipc://@abstract"
+          # @param engine [Engine]
+          # @return [Listener]
+          #
+          def bind(endpoint, engine)
+            path = parse_path(endpoint)
+            sock_path = to_socket_path(path)
+
+            # Remove stale socket file for file-based paths
+            File.delete(sock_path) if !abstract?(path) && File.exist?(sock_path)
+
+            server = UNIXServer.new(sock_path)
+
+            accept_task = Reactor.spawn_pump do
+              loop do
+                client = server.accept
+                Reactor.run do
+                  engine.handle_accepted(IO::Stream::Buffered.wrap(client, minimum_write_size: 0), endpoint: endpoint)
+                rescue => e
+                  client.close rescue nil
+                  raise if !e.is_a?(ProtocolError) && !e.is_a?(EOFError)
+                end
+              end
+            rescue IOError
+              # server closed
+            end
+
+            Listener.new(endpoint, server, accept_task, path)
+          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, minimum_write_size: 0), endpoint: endpoint)
+          end
+
+          private
+
+          # Extracts path from "ipc://path".
+          #
+          def parse_path(endpoint)
+            endpoint.sub(%r{\Aipc://}, "")
+          end
+
+          # Converts @ prefix to \0 for abstract namespace.
+          #
+          def to_socket_path(path)
+            if abstract?(path)
+              "\0#{path[1..]}"
+            else
+              path
+            end
+          end
+
+          # @return [Boolean] true if abstract namespace path
+          #
+          def abstract?(path)
+            path.start_with?("@")
+          end
+        end
+
+        # A bound IPC listener.
+        #
+        class Listener
+          # @return [String] the endpoint
+          #
+          attr_reader :endpoint
+
+          def initialize(endpoint, server, accept_task, path)
+            @endpoint = endpoint
+            @server = server
+            @accept_task = accept_task
+            @path = path
+          end
+
+          # Stops the listener.
+          #
+          def stop
+            @accept_task.stop
+            @server.close rescue nil
+            # Clean up socket file for file-based paths
+            unless @path.start_with?("@")
+              File.delete(@path) rescue nil
+            end
+          end
+        end
+      end
+    end
+  end
+end