omq-draft 0.1.0

data/lib/omq/routing/peer.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module OMQ
+  module Routing
+    # PEER socket routing: bidirectional multi-peer with auto-generated
+    # 4-byte routing IDs.
+    #
+    # Prepends routing ID on receive. Strips routing ID on send and
+    # routes to the identified connection.
+    #
+    class Peer
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine                     = engine
+        @recv_queue                 = Routing.build_queue(engine.options.recv_hwm, :block)
+        @send_queue                 = Routing.build_queue(engine.options.send_hwm, :block)
+        @connections_by_routing_id  = {}
+        @routing_id_by_connection   = {}
+        @tasks                      = []
+        @send_pump_started          = false
+        @send_pump_idle             = true
+        @written                    = Set.new
+      end
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue, :send_queue
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        routing_id = SecureRandom.bytes(4)
+        @connections_by_routing_id[routing_id] = connection
+        @routing_id_by_connection[connection]  = routing_id
+
+        task = @engine.start_recv_pump(connection, @recv_queue) do |msg|
+          [routing_id, *msg]
+        end
+        @tasks << task if task
+
+        start_send_pump unless @send_pump_started
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        routing_id = @routing_id_by_connection.delete(connection)
+        @connections_by_routing_id.delete(routing_id) if routing_id
+      end
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        @send_queue.enqueue(parts)
+      end
+
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+
+      def send_pump_idle? = @send_pump_idle
+
+      private
+
+      def start_send_pump
+        @send_pump_started = true
+        @tasks << @engine.spawn_pump_task(annotation: "send pump") do
+          loop do
+            @send_pump_idle = true
+            batch = [@send_queue.dequeue]
+            @send_pump_idle = false
+            Routing.drain_send_queue(@send_queue, batch)
+
+            @written.clear
+            batch.each do |parts|
+              routing_id = parts.first
+              conn       = @connections_by_routing_id[routing_id]
+              next unless conn # silently drop if peer gone
+              begin
+                conn.write_message(parts[1..])
+                @written << conn
+              rescue *CONNECTION_LOST
+                # will be cleaned up
+              end
+            end
+
+            @written.each do |conn|
+              conn.flush
+            rescue *CONNECTION_LOST
+              # will be cleaned up
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omq/routing/radio.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # RADIO socket routing: group-based fan-out to DISH peers.
+    #
+    # Like PUB/FanOut but with exact group matching and JOIN/LEAVE
+    # commands instead of SUBSCRIBE/CANCEL.
+    #
+    # Messages are sent as two frames on the wire:
+    #   group (MORE=1) + body (MORE=0)
+    #
+    class Radio
+      # Sentinel used for UDP connections that have no group filter:
+      # any group is considered a match.
+      #
+      ANY_GROUPS = Object.new.tap { |o| o.define_singleton_method(:include?) { |_| true } }.freeze
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine            = engine
+        @connections       = []
+        @groups            = {} # connection => Set of joined groups (or ANY_GROUPS for UDP)
+        @send_queue        = Routing.build_queue(engine.options.send_hwm, :block)
+        @on_mute           = engine.options.on_mute
+        @send_pump_started = false
+        @conflate          = engine.options.conflate
+        @tasks             = []
+        @written           = Set.new
+        @latest            = {} if @conflate
+      end
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :send_queue
+
+      # RADIO is write-only.
+      #
+      def recv_queue
+        raise "RADIO sockets cannot receive"
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        @connections << connection
+        if connection.respond_to?(:read_frame)
+          @groups[connection] = Set.new
+          start_group_listener(connection)
+        else
+          @groups[connection] = ANY_GROUPS  # UDP: fan-out to all groups
+        end
+        start_send_pump unless @send_pump_started
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        @connections.delete(connection)
+        @groups.delete(connection)
+      end
+
+      # Enqueues a message for sending.
+      #
+      # @param parts [Array<String>] [group, body]
+      #
+      def enqueue(parts)
+        @send_queue.enqueue(parts)
+      end
+
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+
+      private
+
+      def muted?(conn)
+        return false if @on_mute == :block
+        q = conn.direct_recv_queue if conn.respond_to?(:direct_recv_queue)
+        q&.respond_to?(:limited?) && q.limited?
+      end
+
+      def start_send_pump
+        @send_pump_started = true
+        @tasks << @engine.spawn_pump_task(annotation: "send pump") do
+          loop do
+            @send_pump_idle = true
+            batch = [@send_queue.dequeue]
+            @send_pump_idle = false
+            Routing.drain_send_queue(@send_queue, batch)
+
+            @written.clear
+
+            if @conflate
+              # Keep only the last matching message per connection.
+              @latest.clear
+              batch.each do |parts|
+                group = parts[0]
+                body  = parts[1] || EMPTY_BINARY
+                @connections.each do |conn|
+                  next unless @groups[conn]&.include?(group)
+                  @latest[conn] = [group, body]
+                end
+              end
+              @latest.each do |conn, msg|
+                next if muted?(conn)
+                begin
+                  conn.write_message(msg)
+                  @written << conn
+                rescue *CONNECTION_LOST
+                end
+              end
+            else
+              batch.each do |parts|
+                group      = parts[0]
+                body       = parts[1] || EMPTY_BINARY
+                msg        = [group, body]
+                wire_bytes = nil
+
+                @connections.each do |conn|
+                  next unless @groups[conn]&.include?(group)
+                  next if muted?(conn)
+                  begin
+                    if conn.respond_to?(:curve?) && conn.curve?
+                      conn.write_message(msg)
+                    elsif conn.respond_to?(:write_wire)
+                      wire_bytes ||= Protocol::ZMTP::Codec::Frame.encode_message(msg)
+                      conn.write_wire(wire_bytes)
+                    else
+                      conn.write_message(msg)
+                    end
+                    @written << conn
+                  rescue *CONNECTION_LOST
+                  end
+                end
+              end
+            end
+
+            @written.each do |conn|
+              conn.flush
+            rescue *CONNECTION_LOST
+            end
+          end
+        end
+      end
+
+
+      def start_group_listener(conn)
+        @tasks << @engine.spawn_pump_task(annotation: "group listener") do
+          loop do
+            frame = conn.read_frame
+            next unless frame.command?
+            cmd = Protocol::ZMTP::Codec::Command.from_body(frame.body)
+            case cmd.name
+            when "JOIN"  then @groups[conn]&.add(cmd.data)
+            when "LEAVE" then @groups[conn]&.delete(cmd.data)
+            end
+          end
+        rescue *CONNECTION_LOST
+          @engine.connection_lost(conn)
+        end
+      end
+    end
+  end
+end

data/lib/omq/routing/scatter.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # SCATTER socket routing: round-robin send to GATHER peers.
+    #
+    class Scatter
+      include RoundRobin
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine = engine
+        @tasks  = []
+        init_round_robin(engine)
+      end
+
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :send_queue
+
+
+      # SCATTER is write-only.
+      #
+      def recv_queue
+        raise "SCATTER sockets cannot receive"
+      end
+
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        @connections << connection
+        signal_connection_available
+        update_direct_pipe
+        start_send_pump unless @send_pump_started
+        start_reaper(connection)
+      end
+
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        @connections.delete(connection)
+        update_direct_pipe
+      end
+
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        enqueue_round_robin(parts)
+      end
+
+
+      # Stops all background tasks (send pump, reapers).
+      #
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+
+      private
+
+
+      # Detects peer disconnection on write-only sockets by
+      # blocking on a receive that only returns on disconnect.
+      #
+      # @param conn [Connection]
+      #
+      def start_reaper(conn)
+        return if conn.is_a?(Transport::Inproc::DirectPipe)
+        @tasks << @engine.spawn_pump_task(annotation: "reaper") do
+          conn.receive_message
+        rescue *CONNECTION_LOST
+          @engine.connection_lost(conn)
+        end
+      end
+
+
+    end
+  end
+end

data/lib/omq/routing/server.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module OMQ
+  module Routing
+    # SERVER socket routing: identity-based routing with auto-generated
+    # 4-byte routing IDs.
+    #
+    # Prepends routing ID on receive. Strips routing ID on send and
+    # routes to the identified connection.
+    #
+    class Server
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine                     = engine
+        @recv_queue                 = Routing.build_queue(engine.options.recv_hwm, :block)
+        @send_queue                 = Routing.build_queue(engine.options.send_hwm, :block)
+        @connections_by_routing_id  = {}
+        @routing_id_by_connection   = {}
+        @tasks                      = []
+        @send_pump_started          = false
+        @send_pump_idle             = true
+        @written                    = Set.new
+      end
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue, :send_queue
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        routing_id = SecureRandom.bytes(4)
+        @connections_by_routing_id[routing_id] = connection
+        @routing_id_by_connection[connection]  = routing_id
+
+        task = @engine.start_recv_pump(connection, @recv_queue) do |msg|
+          [routing_id, *msg]
+        end
+        @tasks << task if task
+
+        start_send_pump unless @send_pump_started
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        routing_id = @routing_id_by_connection.delete(connection)
+        @connections_by_routing_id.delete(routing_id) if routing_id
+      end
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        @send_queue.enqueue(parts)
+      end
+
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+
+      def send_pump_idle? = @send_pump_idle
+
+      private
+
+      def start_send_pump
+        @send_pump_started = true
+        @tasks << @engine.spawn_pump_task(annotation: "send pump") do
+          loop do
+            @send_pump_idle = true
+            batch = [@send_queue.dequeue]
+            @send_pump_idle = false
+            Routing.drain_send_queue(@send_queue, batch)
+
+            @written.clear
+            batch.each do |parts|
+              routing_id = parts.first
+              conn       = @connections_by_routing_id[routing_id]
+              next unless conn # silently drop if peer gone
+              begin
+                conn.write_message(parts[1..])
+                @written << conn
+              rescue *CONNECTION_LOST
+                # will be cleaned up
+              end
+            end
+
+            @written.each do |conn|
+              conn.flush
+            rescue *CONNECTION_LOST
+              # will be cleaned up
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omq/scatter_gather.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OMQ
+  class SCATTER < Socket
+    include Writable
+    include SingleFrame
+
+    def initialize(endpoints = nil, linger: 0, send_hwm: nil, send_timeout: nil, backend: nil)
+      _init_engine(:SCATTER, linger: linger, send_hwm: send_hwm, send_timeout: send_timeout, backend: backend)
+      _attach(endpoints, default: :connect)
+    end
+  end
+
+  class GATHER < Socket
+    include Readable
+    include SingleFrame
+
+    def initialize(endpoints = nil, linger: 0, recv_hwm: nil, recv_timeout: nil, backend: nil)
+      _init_engine(:GATHER, linger: linger, recv_hwm: recv_hwm, recv_timeout: recv_timeout, backend: backend)
+      _attach(endpoints, default: :bind)
+    end
+  end
+end

data/lib/omq/single_frame.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module OMQ
+  # Mixin that rejects multipart messages.
+  #
+  # All draft socket types (CLIENT, SERVER, RADIO, DISH, SCATTER,
+  # GATHER, PEER, CHANNEL) require single-frame messages for
+  # thread-safe atomic operations.
+  #
+  module SingleFrame
+    def send(message)
+      if message.is_a?(Array) && message.size > 1
+        raise ArgumentError, "#{self.class} does not support multipart messages"
+      end
+      super
+    end
+  end
+end

data/lib/omq/transport/udp.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "socket"
+require "uri"
+require "set"
+
+module OMQ
+  module Transport
+    # UDP transport for RADIO/DISH sockets.
+    #
+    # Connectionless, datagram-based. No ZMTP handshake.
+    # DISH binds and receives; RADIO connects and sends.
+    #
+    # Wire format per datagram:
+    #   flags (1 byte = 0x01) | group_size (1 byte) | group (n bytes) | body
+    #
+    module UDP
+      MAX_DATAGRAM_SIZE = 65507
+
+      class << self
+        # Binds a UDP server for a DISH socket.
+        #
+        # @param endpoint [String] e.g. "udp://*:5555" or "udp://127.0.0.1:5555"
+        # @param engine [Engine]
+        # @return [Listener]
+        #
+        def bind(endpoint, engine)
+          host, port = parse_endpoint(endpoint)
+          host = "0.0.0.0" if host == "*"
+          socket = UDPSocket.new
+          socket.bind(host, port)
+          Listener.new(endpoint, socket, engine)
+        end
+
+        # Connects a UDP sender for a RADIO socket.
+        #
+        # @param endpoint [String] e.g. "udp://127.0.0.1:5555"
+        # @param engine [Engine]
+        # @return [void]
+        #
+        def connect(endpoint, engine)
+          host, port = parse_endpoint(endpoint)
+          socket = UDPSocket.new
+          conn = RadioConnection.new(socket, host, port)
+          engine.connection_ready(conn, endpoint: endpoint)
+        end
+
+        # @param endpoint [String]
+        # @return [Array(String, Integer)]
+        #
+        def parse_endpoint(endpoint)
+          uri = URI.parse(endpoint)
+          [uri.hostname, uri.port]
+        end
+
+        # Encodes a group + body into a UDP datagram.
+        #
+        # @param group [String]
+        # @param body [String]
+        # @return [String] binary datagram
+        #
+        def encode_datagram(group, body)
+          g = group.b
+          b = body.b
+          [0x01, g.bytesize].pack("CC") + g + b
+        end
+
+        # Decodes a UDP datagram into [group, body].
+        #
+        # @param data [String] raw datagram bytes
+        # @return [Array(String, String), nil] nil if malformed
+        #
+        def decode_datagram(data)
+          return nil if data.bytesize < 2
+          return nil unless data.getbyte(0) & 0x01 == 0x01
+          gs = data.getbyte(1)
+          return nil if data.bytesize < 2 + gs
+          group = data.byteslice(2, gs)
+          body  = data.byteslice(2 + gs, data.bytesize - 2 - gs)
+          [group, body]
+        end
+      end
+
+      # Outgoing UDP connection for RADIO sockets.
+      #
+      # Intentionally does not implement #read_frame — this signals
+      # Routing::Radio to skip the group listener and use ANY_GROUPS.
+      #
+      class RadioConnection
+        # @param socket [UDPSocket]
+        # @param host [String]
+        # @param port [Integer]
+        #
+        def initialize(socket, host, port)
+          @socket = socket
+          @host   = host
+          @port   = port
+        end
+
+        # Encodes and sends a datagram.
+        #
+        # @param parts [Array<String>] [group, body]
+        #
+        def write_message(parts)
+          group, body = parts
+          datagram = UDP.encode_datagram(group.to_s, body.to_s)
+          @socket.send(datagram, 0, @host, @port)
+        rescue Errno::ECONNREFUSED, Errno::ENETUNREACH
+          # UDP fire-and-forget — drop silently
+        end
+
+        alias send_message write_message
+
+        def flush; end
+        def curve?; false; end
+
+        def close
+          @socket.close rescue nil
+        end
+      end
+
+      # Incoming UDP connection for DISH sockets.
+      #
+      # Tracks joined groups locally. JOIN/LEAVE commands from the
+      # DISH routing strategy are intercepted via #send_command and
+      # never transmitted on the wire.
+      #
+      class DishConnection
+        # @param socket [UDPSocket] bound socket
+        #
+        def initialize(socket)
+          @socket = socket
+          @groups = Set.new
+        end
+
+        # Receives one matching datagram, blocking until available.
+        #
+        # Async-safe: rescues IO::WaitReadable and yields to the
+        # fiber scheduler via #wait_readable.
+        #
+        # @return [Array<String>] [group, body], both binary-frozen
+        #
+        def receive_message
+          loop do
+            data, = @socket.recvfrom_nonblock(MAX_DATAGRAM_SIZE)
+            parts = UDP.decode_datagram(data)
+            next unless parts
+            group, body = parts
+            next unless @groups.include?(group.b)
+            return [group.b.freeze, body.b.freeze]
+          rescue IO::WaitReadable
+            @socket.wait_readable
+            retry
+          end
+        end
+
+        # Handles JOIN/LEAVE commands locally; nothing is sent on the wire.
+        #
+        # @param cmd [Protocol::ZMTP::Codec::Command]
+        #
+        def send_command(cmd)
+          case cmd.name
+          when "JOIN"  then @groups << cmd.data.b.freeze
+          when "LEAVE" then @groups.delete(cmd.data.b)
+          end
+        end
+
+        def curve?; false; end
+
+        def close
+          @socket.close rescue nil
+        end
+      end
+
+      # Bound UDP listener for DISH sockets.
+      #
+      # Unlike TCP/IPC listeners, there is no accept loop — a single
+      # DishConnection is registered directly with the engine, bypassing
+      # the ZMTP handshake path.
+      #
+      class Listener
+        # @return [String] bound endpoint
+        #
+        attr_reader :endpoint
+
+        # @param endpoint [String]
+        # @param socket [UDPSocket]
+        # @param engine [Engine]
+        #
+        def initialize(endpoint, socket, engine)
+          @endpoint = endpoint
+          @socket   = socket
+          @engine   = engine
+        end
+
+        # Registers a DishConnection with the engine.
+        # The on_accepted block is intentionally ignored — no ZMTP handshake.
+        #
+        # @param parent_task [Async::Task] (unused)
+        #
+        def start_accept_loops(parent_task, &_on_accepted)
+          conn = DishConnection.new(@socket)
+          @engine.connection_ready(conn, endpoint: @endpoint)
+        end
+
+        # Stops the listener.
+        #
+        def stop
+          @socket.close rescue nil
+        end
+      end
+    end
+  end
+end