omq 0.6.5 → 0.8.0

data/lib/omq/zmtp/connection.rb

@@ -1,282 +0,0 @@
-# frozen_string_literal: true
-
-module OMQ
-  module ZMTP
-    # Manages one ZMTP peer connection over any transport IO.
-    #
-    # Delegates the security handshake to a Mechanism object (Null, Curve, etc.),
-    # then provides message send/receive and command send/receive on top of the
-    # framing codec.
-    #
-    class Connection
-      # @return [String] peer's socket type (from READY handshake)
-      #
-      attr_reader :peer_socket_type
-
-
-      # @return [String] peer's identity (from READY handshake)
-      #
-      attr_reader :peer_identity
-
-
-      # @return [Object] transport IO (#read, #write, #close)
-      #
-      attr_reader :io
-
-
-      # @param io [#read, #write, #close] transport IO
-      # @param socket_type [String] our socket type name (e.g. "REQ")
-      # @param identity [String] our identity
-      # @param as_server [Boolean] whether we are the server side
-      # @param mechanism [Mechanism::Null, Mechanism::Curve] security mechanism
-      # @param heartbeat_interval [Numeric, nil] heartbeat interval in seconds
-      # @param heartbeat_ttl [Numeric, nil] TTL to send in PING
-      # @param heartbeat_timeout [Numeric, nil] timeout for PONG
-      # @param max_message_size [Integer, nil] max frame size in bytes, nil = unlimited
-      #
-      def initialize(io, socket_type:, identity: "", as_server: false,
-                     mechanism: nil,
-                     heartbeat_interval: nil, heartbeat_ttl: nil, heartbeat_timeout: nil,
-                     max_message_size: nil)
-        @io                  = io
-        @socket_type         = socket_type
-        @identity            = identity
-        @as_server           = as_server
-        @mechanism           = mechanism || Mechanism::Null.new
-        @peer_socket_type    = nil
-        @peer_identity       = nil
-        @mutex               = Mutex.new
-        @heartbeat_interval  = heartbeat_interval
-        @heartbeat_ttl       = heartbeat_ttl || heartbeat_interval
-        @heartbeat_timeout   = heartbeat_timeout || heartbeat_interval
-        @last_received_at    = nil
-        @heartbeat_task      = nil
-        @max_message_size    = max_message_size
-      end
-
-
-      # Performs the full ZMTP handshake via the configured mechanism.
-      #
-      # @return [void]
-      # @raise [ProtocolError] on handshake failure
-      #
-      def handshake!
-        result = @mechanism.handshake!(
-          @io,
-          as_server:   @as_server,
-          socket_type: @socket_type,
-          identity:    @identity,
-        )
-
-        @peer_socket_type = result[:peer_socket_type]
-        @peer_identity    = result[:peer_identity]
-
-        unless @peer_socket_type
-          raise ProtocolError, "peer READY missing Socket-Type"
-        end
-
-        unless ZMTP::VALID_PEERS[@socket_type.to_sym]&.include?(@peer_socket_type.to_sym)
-          raise ProtocolError,
-                "incompatible socket types: #{@socket_type} cannot connect to #{@peer_socket_type}"
-        end
-      end
-
-
-      # Sends a multi-frame message (write + flush).
-      #
-      # @param parts [Array<String>] message frames
-      # @return [void]
-      #
-      def send_message(parts)
-        @mutex.synchronize do
-          write_frames(parts)
-          @io.flush
-        end
-      end
-
-
-      # Writes a multi-frame message to the buffer without flushing.
-      # Call {#flush} after batching writes.
-      #
-      # @param parts [Array<String>] message frames
-      # @return [void]
-      #
-      def write_message(parts)
-        @mutex.synchronize do
-          write_frames(parts)
-        end
-      end
-
-
-      # Flushes the write buffer to the underlying IO.
-      #
-      # @return [void]
-      #
-      def flush
-        @mutex.synchronize do
-          @io.flush
-        end
-      end
-
-
-      # Receives a multi-frame message.
-      # PING/PONG commands are handled automatically by #read_frame.
-      #
-      # @return [Array<String>] message frames
-      # @raise [EOFError] if connection is closed
-      #
-      def receive_message
-        frames = []
-        loop do
-          frame = read_frame
-          if frame.command?
-            yield frame if block_given?
-            next
-          end
-          frames << frame.body.freeze
-          break unless frame.more?
-        end
-        frames.freeze
-      end
-
-
-      # Starts the heartbeat sender task. Call after handshake.
-      #
-      # @return [#stop, nil] the heartbeat task, or nil if disabled
-      #
-      def start_heartbeat
-        return nil unless @heartbeat_interval
-        @last_received_at = monotonic_now
-        @heartbeat_task = Reactor.spawn_pump(annotation: "heartbeat") do
-          loop do
-            sleep @heartbeat_interval
-            # Send PING with TTL
-            send_command(Codec::Command.ping(
-              ttl:     @heartbeat_ttl || 0,
-              context: "".b,
-            ))
-            # Check if peer has gone silent
-            if @heartbeat_timeout && @last_received_at
-              elapsed = monotonic_now - @last_received_at
-              if elapsed > @heartbeat_timeout
-                close
-                break
-              end
-            end
-          end
-        rescue *ZMTP::CONNECTION_LOST
-          # connection closed
-        end
-      end
-
-
-      # Sends a command.
-      #
-      # @param command [Codec::Command]
-      # @return [void]
-      #
-      def send_command(command)
-        @mutex.synchronize do
-          if @mechanism.encrypted?
-            @io.write(@mechanism.encrypt(command.to_body, command: true))
-          else
-            @io.write(command.to_frame.to_wire)
-          end
-          @io.flush
-        end
-      end
-
-
-      # Reads one frame from the wire. Handles PING/PONG automatically.
-      # When using an encrypted mechanism, MESSAGE commands are decrypted
-      # back to ZMTP frames transparently.
-      #
-      # @return [Codec::Frame]
-      # @raise [EOFError] if connection is closed
-      #
-      def read_frame
-        loop do
-          frame = Codec::Frame.read_from(@io)
-          touch_heartbeat
-
-          # When CURVE is active, every wire frame is a MESSAGE envelope
-          # (data frame with "\x07MESSAGE" prefix). Decrypt to recover the
-          # inner ZMTP frame. This check only runs when encrypted? is true,
-          # so user data frames are never misdetected.
-          if @mechanism.encrypted? && frame.body.bytesize > 8 && frame.body.byteslice(0, 8) == "\x07MESSAGE".b
-            frame = @mechanism.decrypt(frame)
-          end
-
-          if @max_message_size && !frame.command? && frame.body.bytesize > @max_message_size
-            close
-            raise ProtocolError, "frame size #{frame.body.bytesize} exceeds max_message_size #{@max_message_size}"
-          end
-          if frame.command?
-            cmd = Codec::Command.from_body(frame.body)
-            case cmd.name
-            when "PING"
-              _, context = cmd.ping_ttl_and_context
-              send_command(Codec::Command.pong(context: context))
-              next
-            when "PONG"
-              next
-            end
-          end
-          return frame
-        end
-      end
-
-
-      # Closes the connection.
-      #
-      # @return [void]
-      #
-      def close
-        @heartbeat_task&.stop rescue nil
-        @io.close
-      rescue IOError
-        # already closed
-      end
-
-
-      private
-
-
-      # Writes message parts as ZMTP frames, encrypting if needed.
-      #
-      # @param parts [Array<String>] message frames
-      #
-      def write_frames(parts)
-        parts.each_with_index do |part, i|
-          more = i < parts.size - 1
-          if @mechanism.encrypted?
-            @io.write(@mechanism.encrypt(part.b, more: more))
-          else
-            @io.write(Codec::Frame.new(part, more: more).to_wire)
-          end
-        end
-      end
-
-
-      def touch_heartbeat
-        @last_received_at = monotonic_now if @heartbeat_interval
-      end
-
-
-      def monotonic_now
-        Async::Clock.now
-      end
-
-
-      # Sends one frame to the wire.
-      #
-      # @param frame [Codec::Frame]
-      # @return [void]
-      #
-      def send_frame(frame)
-        @mutex.synchronize { @io.write(frame.to_wire) }
-      end
-
-    end
-  end
-end

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

@@ -1,72 +0,0 @@
-# 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))
-          io.flush
-
-          # 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)
-          io.flush
-
-          # 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/valid_peers.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module OMQ
-  module ZMTP
-    # Valid socket type peer combinations per ZMTP spec.
-    #
-    VALID_PEERS = {
-      PAIR:   %i[PAIR].freeze,
-      REQ:    %i[REP ROUTER].freeze,
-      REP:    %i[REQ DEALER].freeze,
-      DEALER: %i[REP DEALER ROUTER].freeze,
-      ROUTER: %i[REQ DEALER ROUTER].freeze,
-      PUB:    %i[SUB XSUB].freeze,
-      SUB:    %i[PUB XPUB].freeze,
-      XPUB:   %i[SUB XSUB].freeze,
-      XSUB:   %i[PUB XPUB].freeze,
-      PUSH:    %i[PULL].freeze,
-      PULL:    %i[PUSH].freeze,
-      CLIENT:  %i[SERVER].freeze,
-      SERVER:  %i[CLIENT].freeze,
-      RADIO:   %i[DISH].freeze,
-      DISH:    %i[RADIO].freeze,
-      SCATTER: %i[GATHER].freeze,
-      GATHER:  %i[SCATTER].freeze,
-      PEER:    %i[PEER].freeze,
-      CHANNEL: %i[CHANNEL].freeze,
-    }.freeze
-  end
-end