omq 0.1.0

data/lib/omq/zmtp/engine.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+require "async"
+
+module OMQ
+  module ZMTP
+    # Per-socket orchestrator.
+    #
+    # Manages connections, transports, and the routing strategy for one
+    # OMQ::Socket instance. Each socket type creates one Engine.
+    #
+    class Engine
+      # @return [Symbol] socket type (e.g. :REQ, :PAIR)
+      #
+      attr_reader :socket_type
+
+      # @return [Options] socket options
+      #
+      attr_reader :options
+
+      # @return [Routing] routing strategy
+      #
+      attr_reader :routing
+
+      # @return [String, nil] last bound endpoint
+      #
+      attr_reader :last_endpoint
+
+      # @return [Integer, nil] last auto-selected TCP port
+      #
+      attr_reader :last_tcp_port
+
+      # @param socket_type [Symbol] e.g. :REQ, :REP, :PAIR
+      # @param options [Options]
+      #
+      def initialize(socket_type, options)
+        @socket_type          = socket_type
+        @options              = options
+        @routing              = Routing.for(socket_type).new(self)
+        @connections          = []
+        @connection_endpoints = {} # connection => endpoint (for reconnection)
+        @connected_endpoints  = [] # endpoints we connected to (not bound)
+        @listeners            = []
+        @tasks                = []
+        @closed               = false
+        @last_endpoint        = nil
+        @last_tcp_port        = nil
+      end
+
+      # Binds to an endpoint.
+      #
+      # @param endpoint [String] e.g. "tcp://127.0.0.1:5555", "inproc://foo"
+      # @return [void]
+      # @raise [ArgumentError] on unsupported transport
+      #
+      def bind(endpoint)
+        transport = transport_for(endpoint)
+        listener = transport.bind(endpoint, self)
+        @listeners << listener
+        @last_endpoint = listener.endpoint
+        @last_tcp_port = extract_tcp_port(listener.endpoint)
+      end
+
+      # Connects to an endpoint.
+      #
+      # @param endpoint [String]
+      # @return [void]
+      #
+      def connect(endpoint)
+        @connected_endpoints << endpoint
+        transport = transport_for(endpoint)
+        transport.connect(endpoint, self)
+      rescue Errno::ECONNREFUSED, Errno::ENOENT, Errno::ETIMEDOUT, IOError, ProtocolError
+        # Server not up yet — schedule background reconnect
+        schedule_reconnect(endpoint)
+      end
+
+      # Disconnects from an endpoint. Closes connections to that endpoint
+      # and stops auto-reconnection for it.
+      #
+      # @param endpoint [String]
+      # @return [void]
+      #
+      def disconnect(endpoint)
+        @connected_endpoints.delete(endpoint)
+        conns = @connection_endpoints.select { |_, ep| ep == endpoint }.keys
+        conns.each do |conn|
+          @connection_endpoints.delete(conn)
+          @connections.delete(conn)
+          @routing.connection_removed(conn)
+          conn.close
+        end
+      end
+
+      # Unbinds from an endpoint. Stops the listener and closes all
+      # connections that were accepted on it.
+      #
+      # @param endpoint [String]
+      # @return [void]
+      #
+      def unbind(endpoint)
+        listener = @listeners.find { |l| l.endpoint == endpoint }
+        return unless listener
+        listener.stop
+        @listeners.delete(listener)
+
+        # Close connections accepted on this endpoint
+        conns = @connection_endpoints.select { |_, ep| ep == endpoint }.keys
+        conns.each do |conn|
+          @connection_endpoints.delete(conn)
+          @connections.delete(conn)
+          @routing.connection_removed(conn)
+          conn.close
+        end
+      end
+
+      # Called by a transport when an incoming connection is accepted.
+      #
+      # @param io [#read, #write, #close]
+      # @param endpoint [String, nil] the endpoint this was accepted on
+      # @return [void]
+      #
+      def handle_accepted(io, endpoint: nil)
+        setup_connection(io, as_server: true, endpoint: endpoint)
+      end
+
+      # Called by a transport when an outgoing connection is established.
+      #
+      # @param io [#read, #write, #close]
+      # @return [void]
+      #
+      def handle_connected(io, endpoint: nil)
+        setup_connection(io, as_server: false, endpoint: endpoint)
+      end
+
+      # Called by inproc transport with a pre-validated DirectPipe.
+      # Skips ZMTP handshake — just registers with routing strategy.
+      #
+      # @param pipe [Transport::Inproc::DirectPipe]
+      # @return [void]
+      #
+      def connection_ready(pipe, endpoint: nil)
+        @connections << pipe
+        @connection_endpoints[pipe] = endpoint if endpoint
+        @routing.connection_added(pipe)
+      end
+
+      # Dequeues the next received message. Blocks until available.
+      #
+      # @return [Array<String>] message parts
+      #
+      def dequeue_recv
+        @routing.recv_queue.dequeue
+      end
+
+      # Enqueues a message for sending. Blocks at HWM.
+      #
+      # @param parts [Array<String>]
+      # @return [void]
+      #
+      def enqueue_send(parts)
+        @routing.enqueue(parts)
+      end
+
+      # Starts a recv pump for a connection, or wires the inproc
+      # fast path when the connection is a DirectPipe.
+      #
+      # @param conn [Connection, Transport::Inproc::DirectPipe]
+      # @param recv_queue [Async::LimitedQueue] routing strategy's recv queue
+      # @param transform [#call, nil] optional message transform
+      # @return [#stop, nil] pump task handle, or nil for DirectPipe bypass
+      #
+      def start_recv_pump(conn, recv_queue, transform: nil)
+        if conn.is_a?(Transport::Inproc::DirectPipe) && conn.peer
+          conn.peer.direct_recv_queue = recv_queue
+          conn.peer.direct_recv_transform = transform
+          return nil
+        end
+
+        Reactor.spawn_pump do
+          loop do
+            msg = conn.receive_message
+            msg = transform ? transform.call(msg) : msg
+            recv_queue.enqueue(msg)
+          end
+        rescue EOFError, IOError
+          connection_lost(conn)
+        end
+      end
+
+      # Called when a connection is lost.
+      #
+      # @param connection [Connection]
+      # @return [void]
+      #
+      def connection_lost(connection)
+        endpoint = @connection_endpoints.delete(connection)
+        @connections.delete(connection)
+        @routing.connection_removed(connection)
+        connection.close
+
+        # Auto-reconnect if this was a connected (not bound) endpoint
+        if endpoint && @connected_endpoints.include?(endpoint) && !@closed
+          schedule_reconnect(endpoint)
+        end
+      end
+
+      # Closes all connections and listeners.
+      #
+      # @return [void]
+      #
+      def close
+        return if @closed
+        @closed = true
+
+        # Linger: wait for send queues to drain before closing.
+        # linger=0 → close immediately, linger=nil → wait forever.
+        linger = @options.linger
+        if linger.nil? || linger > 0
+          drain_timeout = linger # nil = wait forever, >0 = seconds
+          drain_send_queues(drain_timeout)
+        end
+
+        # Close connections — causes pump tasks to get EOFError/IOError
+        @connections.each(&:close)
+        @connections.clear
+        @listeners.each(&:stop)
+        @listeners.clear
+        # Stop any remaining pump tasks
+        @routing.stop rescue nil
+        @tasks.each { |t| t.stop rescue nil }
+        @tasks.clear
+      end
+
+      private
+
+      # Waits for the send queue to drain.
+      #
+      # @param timeout [Numeric, nil] max seconds to wait (nil = forever)
+      #
+      def drain_send_queues(timeout)
+        return unless @routing.respond_to?(:send_queue)
+        deadline = timeout ? Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout : nil
+
+        until @routing.send_queue.empty?
+          if deadline
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            break if remaining <= 0
+          end
+          sleep 0.001
+        end
+      end
+
+      def setup_connection(io, as_server:, endpoint: nil)
+        conn = Connection.new(
+          io,
+          socket_type:       @socket_type.to_s,
+          identity:          @options.identity,
+          as_server:         as_server,
+          mechanism:          build_mechanism,
+          heartbeat_interval: @options.heartbeat_interval,
+          heartbeat_ttl:      @options.heartbeat_ttl,
+          heartbeat_timeout:  @options.heartbeat_timeout,
+          max_message_size:   @options.max_message_size,
+        )
+        conn.handshake!
+        conn.start_heartbeat
+        @connections << conn
+        @connection_endpoints[conn] = endpoint if endpoint
+        @routing.connection_added(conn)
+      rescue ProtocolError, EOFError
+        conn&.close
+        raise
+      end
+
+      def schedule_reconnect(endpoint)
+        ri = @options.reconnect_interval
+        if ri.is_a?(Range)
+          delay   = ri.begin
+          max_delay = ri.end
+        else
+          delay     = ri
+          max_delay = nil
+        end
+
+        @tasks << Reactor.spawn_pump do
+          loop do
+            break if @closed
+            sleep delay
+            break if @closed
+            begin
+              transport = transport_for(endpoint)
+              transport.connect(endpoint, self)
+              break # reconnected successfully
+            rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, IOError, ProtocolError
+              delay = [delay * 2, max_delay].min if max_delay
+            end
+          end
+        end
+      end
+
+
+      def build_mechanism
+        case @options.mechanism
+        when :null
+          Mechanism::Null.new
+        when :curve
+          unless defined?(Mechanism::Curve)
+            raise LoadError, "require 'omq-curve' to use CURVE security"
+          end
+          Mechanism::Curve.new(
+            server_key:    @options.curve_server_key,
+            public_key:    @options.curve_public_key,
+            secret_key:    @options.curve_secret_key,
+            as_server:     @options.curve_server,
+            authenticator: @options.curve_authenticator,
+          )
+        else
+          raise ArgumentError, "unknown mechanism: #{@options.mechanism}"
+        end
+      end
+
+      def transport_for(endpoint)
+        case endpoint
+        when /\Atcp:\/\//    then Transport::TCP
+        when /\Aipc:\/\//    then Transport::IPC
+        when /\Ainproc:\/\// then Transport::Inproc
+        else raise ArgumentError, "unsupported transport: #{endpoint}"
+        end
+      end
+
+      def extract_tcp_port(endpoint)
+        return nil unless endpoint&.start_with?("tcp://")
+        port = endpoint.split(":").last.to_i
+        port.positive? ? port : nil
+      end
+    end
+  end
+end

data/lib/omq/zmtp/mechanism/null.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Mechanism
+      # NULL security mechanism — no encryption, no authentication.
+      #
+      # Performs the ZMTP 3.1 greeting exchange and READY command handshake.
+      #
+      class Null
+        MECHANISM_NAME = "NULL"
+
+        # Performs the full NULL handshake over +io+.
+        #
+        # 1. Exchange 64-byte greetings
+        # 2. Validate peer greeting (version, mechanism)
+        # 3. Exchange READY commands (socket type + identity)
+        #
+        # @param io [#read, #write] transport IO
+        # @param as_server [Boolean]
+        # @param socket_type [String]
+        # @param identity [String]
+        # @return [Hash] { peer_socket_type:, peer_identity: }
+        # @raise [ProtocolError]
+        #
+        def handshake!(io, as_server:, socket_type:, identity:)
+          # Send our greeting
+          io.write(Codec::Greeting.encode(mechanism: MECHANISM_NAME, as_server: as_server))
+
+          # Read peer greeting
+          greeting_data = io.read_exactly(Codec::Greeting::SIZE)
+          peer_greeting = Codec::Greeting.decode(greeting_data)
+
+          unless peer_greeting[:mechanism] == MECHANISM_NAME
+            raise ProtocolError, "unsupported mechanism: #{peer_greeting[:mechanism]}"
+          end
+
+          # Send our READY command
+          ready_cmd = Codec::Command.ready(socket_type: socket_type, identity: identity)
+          io.write(ready_cmd.to_frame.to_wire)
+
+          # Read peer READY command
+          frame = Codec::Frame.read_from(io)
+          unless frame.command?
+            raise ProtocolError, "expected command frame, got data frame"
+          end
+
+          peer_cmd = Codec::Command.from_body(frame.body)
+          unless peer_cmd.name == "READY"
+            raise ProtocolError, "expected READY command, got #{peer_cmd.name}"
+          end
+
+          props = peer_cmd.properties
+          peer_socket_type = props["Socket-Type"]
+          peer_identity    = props["Identity"] || ""
+
+          unless peer_socket_type
+            raise ProtocolError, "peer READY missing Socket-Type"
+          end
+
+          { peer_socket_type: peer_socket_type, peer_identity: peer_identity }
+        end
+
+        # @return [Boolean] false — NULL does not encrypt frames
+        #
+        def encrypted? = false
+      end
+    end
+  end
+end

data/lib/omq/zmtp/options.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    # Pure Ruby socket options.
+    #
+    # All timeouts are in seconds (Numeric) or nil (no timeout).
+    # HWM values are integers.
+    #
+    class Options
+      DEFAULT_HWM = 1000
+
+      # @param linger [Integer] linger period in seconds (default 0)
+      #
+      def initialize(linger: 0)
+        @send_hwm              = DEFAULT_HWM
+        @recv_hwm              = DEFAULT_HWM
+        @linger                = linger
+        @identity              = "".b
+        @router_mandatory      = false
+        @read_timeout          = nil   # seconds, nil = no timeout
+        @write_timeout         = nil
+        @reconnect_interval    = 0.1   # seconds, or Range for backoff (e.g. 0.1..5.0)
+        @heartbeat_interval    = nil   # seconds, nil = disabled
+        @heartbeat_ttl         = nil   # seconds, nil = use heartbeat_interval
+        @heartbeat_timeout     = nil   # seconds, nil = use heartbeat_interval
+        @max_message_size       = nil  # bytes, nil = unlimited
+        @connect_timeout        = 60   # seconds, nil = OS default
+        @mechanism              = :null # :null or :curve
+        @curve_server           = false
+        @curve_server_key       = nil  # 32-byte binary (server's permanent public key)
+        @curve_public_key       = nil  # 32-byte binary (our permanent public key)
+        @curve_secret_key       = nil  # 32-byte binary (our permanent secret key)
+        @curve_authenticator    = nil  # nil = allow all, Set = allowlist, #call = custom
+      end
+
+      attr_accessor :send_hwm,  :recv_hwm,
+                    :linger,    :identity,
+                    :router_mandatory,
+                    :read_timeout,          :write_timeout,
+                    :reconnect_interval,
+                    :heartbeat_interval,    :heartbeat_ttl,    :heartbeat_timeout,
+                    :max_message_size,
+                    :connect_timeout,
+                    :mechanism,
+                    :curve_server,          :curve_server_key,
+                    :curve_public_key,      :curve_secret_key,
+                    :curve_authenticator
+
+      alias_method :router_mandatory?, :router_mandatory
+      alias_method :recv_timeout,      :read_timeout
+      alias_method :recv_timeout=,     :read_timeout=
+      alias_method :send_timeout,      :write_timeout
+      alias_method :send_timeout=,     :write_timeout=
+    end
+  end
+end

data/lib/omq/zmtp/reactor.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "async"
+
+module OMQ
+  module ZMTP
+    # Shared IO reactor for the Ruby backend.
+    #
+    # When user code runs inside an Async reactor, pump tasks are spawned
+    # as transient Async tasks directly. When no reactor is available
+    # (e.g. bare Thread.new), a single shared IO thread hosts all pump
+    # tasks — mirroring libzmq's IO thread architecture.
+    #
+    module Reactor
+      @work_queue = Thread::Queue.new
+      @thread     = nil
+      @mutex      = Mutex.new
+      @wake_r     = nil
+      @wake_w     = nil
+
+      class << self
+        # Spawns a pump task (recv loop, send loop, accept loop).
+        #
+        # Inside an Async reactor: spawns as transient Async task.
+        # Outside: dispatches to the shared IO thread.
+        #
+        # @return [#stop] a stoppable handle
+        #
+        def spawn_pump(&block)
+          if Async::Task.current?
+            Async(transient: true, &block)
+          else
+            handle = PumpHandle.new
+            ensure_started
+            @work_queue.push([:spawn, block, handle])
+            @wake_w.write_nonblock(".") rescue nil
+            handle
+          end
+        end
+
+        # Runs a block synchronously within an Async context.
+        #
+        # Inside an Async reactor: runs directly.
+        # Outside: dispatches to the shared IO thread and waits.
+        #
+        # @return [Object] the block's return value
+        #
+        def run(&block)
+          if Async::Task.current?
+            yield
+          else
+            result_queue = Thread::Queue.new
+            ensure_started
+            @work_queue.push([:run, block, result_queue])
+            @wake_w.write_nonblock(".") rescue nil
+            status, value = result_queue.pop
+            raise value if status == :error
+            value
+          end
+        end
+
+        # Ensures the shared IO thread is running.
+        #
+        # @return [void]
+        #
+        def ensure_started
+          @mutex.synchronize do
+            return if @thread&.alive?
+            @wake_r, @wake_w = IO.pipe
+            ready = Thread::Queue.new
+            @thread = Thread.new { run_reactor(ready, @wake_r) }
+            @thread.name = "omq-io"
+            ready.pop
+          end
+        end
+
+        # Stops the shared IO thread. Used in tests.
+        #
+        # @return [void]
+        #
+        def stop!
+          @work_queue.push([:stop])
+          @wake_w&.write_nonblock(".") rescue nil
+          @thread&.join(2)
+          @thread = nil
+          @wake_r&.close rescue nil
+          @wake_w&.close rescue nil
+          @wake_r = nil
+          @wake_w = nil
+        end
+
+        private
+
+        def run_reactor(ready, wake_r)
+          Async do |task|
+            ready.push(true)
+            loop do
+              # Wait for wakeup signal (non-blocking for Async scheduler)
+              wake_r.wait_readable
+              wake_r.read_nonblock(256) rescue nil
+
+              # Drain all pending work items
+              while (item = @work_queue.pop(true) rescue nil)
+                case item[0]
+                when :spawn
+                  _, block, handle = item
+                  async_task = task.async(transient: true, &block)
+                  handle.task = async_task
+                when :run
+                  _, block, result_queue = item
+                  task.async do
+                    result_queue.push([:ok, block.call])
+                  rescue => e
+                    result_queue.push([:error, e])
+                  end
+                when :stop
+                  return
+                end
+              end
+            end
+          end
+        end
+      end
+
+      # A stoppable handle for a pump task running in the shared reactor.
+      #
+      class PumpHandle
+        # @return [Async::Task, nil]
+        #
+        attr_accessor :task
+
+        # Stops the pump task.
+        #
+        # @return [void]
+        #
+        def stop
+          @task&.stop
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/readable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module OMQ
+  module ZMTP
+    # Pure Ruby Readable mixin. Dequeues messages from the engine's recv queue.
+    #
+    module Readable
+      # Receives the next message.
+      #
+      # @return [Array<String>] message parts
+      # @raise [IO::TimeoutError] if read_timeout exceeded
+      #
+      def receive
+        with_timeout(@options.read_timeout) { @engine.dequeue_recv }
+      end
+
+      # Waits until the socket is readable.
+      #
+      # @param timeout [Numeric, nil] timeout in seconds
+      # @return [true]
+      #
+      def wait_readable(timeout = @options.read_timeout)
+        true
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # DEALER socket routing: round-robin send, fair-queue receive.
+      #
+      # No envelope manipulation — messages pass through unchanged.
+      #
+      class Dealer
+        include RoundRobin
+
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine     = engine
+          @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+          @tasks      = []
+          init_round_robin(engine)
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :recv_queue, :send_queue
+
+        # @param connection [Connection]
+        #
+        def connection_added(connection)
+          @connections << connection
+          signal_connection_available
+          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
+
+      end
+    end
+  end
+end