mqtt-core 0.0.1.ci.release

data/lib/mqtt/core/client/socket_factory.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require_relative 'uri'
+require_relative '../../options'
+
+module MQTT
+  module Core
+    class Client
+      # A Factory for creating the underlying connection to an MQTT server/broker from a URI
+      # @see https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme
+      # @api public
+      class SocketFactory
+        extend Options
+        include Options
+
+        # Option keys for constructing a URI
+        URI_OPTIONS = %i[uri host port local_addr local_port scheme password_file].freeze
+
+        # Option keys for constructing an IO object.
+        # @see new_io
+        IO_OPTIONS = (%i[connect_timeout resolv_timeout tcp_nodelay] + [:ssl_context, /ssl_(.*)/]).freeze
+
+        # All option keys owned by SocketFactory
+        OPTIONS = (%i[ignore_uri_params] + URI_OPTIONS + IO_OPTIONS).freeze
+
+        # Removes {OPTIONS} from an options Hash.
+        def self.extract_io_options(options)
+          slice_opts!(options, *OPTIONS)
+        end
+
+        # Create a SocketFactory for establishing MQTT connections
+        #
+        # @overload create(uri = ENV['MQTT_SERVER'], **opts)
+        #   Create from a URI
+        #   @param [String, URI] uri an mqtt://, mqtts:// or unix:// URI
+        #   @param [Hash<Symbol>] **opts
+        #   @option opts [Boolean] ignore_uri_params (false)
+        #     URI query parameters are merged into the opts Hash unless this is set. Use where uri input is untrusted.
+        #   @option opts [String] password_file Provide authentication password from a file
+        #   @option opts [Hash<Symbol>] **io_opts connection timeouts and socket options see {#new_io}
+        #   @option opts [OpenSSL::SSL::SSLContext] ssl_context SSL context for `mqtts://` scheme
+        #
+        #     - A default (secure) context is created if this option is absent and the mqtts:// scheme is used.
+        #   @option opts [Hash<Symbol>] **ssl Additional `ssl_(.*)` options passed to
+        #     OpenSSL::SSL::SSLContext#set_params
+        #
+        #     - `min_version`, `ca_file`, `ciphers`, etc...
+        #   @option opts [Hash<Symbol>] **client_certificate options for client authentication certificate
+        #
+        #     - `ssl_cert`, `ssl_key` - can take native `OpenSSL` objects, or construct them from a `String`
+        #     - `ssl_cert_file`, `ssl_key_file` - options to construct certificate objects from files
+        #     - `ssl_passphrase`, `ssl_passphrase_file` - options to set the passphrase for the private key if required
+        #   @return [SocketFactory]
+        #   @example MQTT URI
+        #     uri = URI('mqtt://localhost:1883')
+        #     factory = MQTT::Core::Client::SocketFactory.create(uri)
+        #     factory.new_io # => #<TCPSocket:0x00007f9920002000>
+        #   @example MQTTS URI with minimum TLS version
+        #     uri = URI('mqtts://localhost:8883')
+        #     factory = MQTT::Core::Client::SocketFactory.create(uri, ssl_min_version: :TLSv1_2)
+        #     factory.new_io # => #<OpenSSL::SSL::SSLSocket:0x00007f9920002000>
+        #   @example MQTTS URI with client certificate files
+        #     uri = 'mqtts://localhost:8883?ssl_cert_file=client.crt&ssl_key_file=client.key'
+        #     factory = MQTT::Core::Client::SocketFactory.create(uri)
+        #   @see URI::MQTT
+        #   @see URI::MQTTS
+        #
+        # @overload create(host, port = nil, local_addr = nil, local_port = nil, scheme: nil, **opts)
+        #   Build URI from TCP-style arguments
+        #   @param [String] host Hostname or IP address
+        #   @param [Integer, nil] port Port number
+        #   @param [String, nil] local_addr Local address for the TCPSocket
+        #   @param [Integer, nil] local_port Local port for the TCPSocket
+        #   @param [String, nil] scheme 'mqtt', 'mqtts', or nil to auto-detect from ssl options
+        #   @param [Hash<Symbol>] **opts Additional options (see first overload)
+        #   @return [SocketFactory]
+        #
+        # @overload create(**opts)
+        #   Create from keyword options only
+        #   @param [Hash<Symbol>] opts Options including uri, host, port, local_addr, local_port (see first overload)
+        #   @return [SocketFactory]
+        #
+        # @overload create(klass, *rest, **opts)
+        #   Create a custom IO builder
+        #   @param [Class] klass Class to instantiate
+        #   @param [Array] *rest Arguments passed to klass.new
+        #   @param [Hash<Symbol>] **opts Keyword arguments passed to klass.new
+        #   @return [:new_io] New instance that implements `#new_io`
+        #
+        # @overload create(obj, options: {})
+        #   Pass through an existing SocketFactory or compatible object
+        #   @param [:new_io] obj Object that implements `#new_io`
+        #   @param [Hash<Symbol>] options SocketFactory related options are extracted from this hash
+        #   @return [:new_io] The obj parameter unchanged
+        #   @see extract_io_options
+        def self.create(*io_args, options: {}, **opts)
+          opts.merge!(extract_io_options(options))
+          return io_args.first if io_args.first.respond_to?(:new_io)
+
+          (io_args.first.is_a?(Class) ? io_args.shift : self).new(*io_args, **opts)
+        end
+
+        # @!visibility private
+        # rubocop:disable Metrics/AbcSize
+        def initialize(*io_args, ignore_uri_params: false, **opts)
+          extract_io_args(io_args, opts)
+
+          @uri, @io_args = parse_uri(*io_args, default_scheme: default_scheme(opts))
+          unless %w[mqtt mqtts unix].include?(@uri.scheme)
+            raise URI::InvalidURIError, "Invalid scheme for MQTT: #{@uri.scheme}"
+          end
+
+          @uri.require_deps
+
+          opts.merge!(URI.decode_www_form(@uri.query || '').to_h.transform_keys(&:to_sym)) unless ignore_uri_params
+          @uri.query = nil
+
+          @io_opts = slice_opts!(opts, :connect_timeout, :resolv_timeout, :tcp_nodelay) do |k, v|
+            k == :tcp_nodelay ? coerce_boolean(k, v) : coerce_float(k, v)
+          end
+
+          @auth = build_auth(opts)
+          @ssl_context = build_ssl_context(**slice_ssl_opts!(opts))
+
+          # Remaining unused opts
+          @query_params = opts.freeze
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        # @return [URI] The URI that will be used for the next connection.
+        attr_reader :uri
+        alias sanitized_uri uri
+
+        # @return [Hash<Symbol>] io_opts default options for #new_io
+        attr_reader :io_opts
+
+        # @return [Hash<Symbol>] username and password from URI
+        attr_reader :auth
+
+        # @return [Hash<Symbol>] Unused options and uri query parameters. This hash is frozen.
+        attr_reader :query_params
+
+        # @param [Hash<Symbol>] io_opts Options passed to the underlying IO object
+        #
+        #    Available options depend on the URI scheme
+        # @option io_opts [Boolean] tcp_nodelay (true) (MQTT/S) Enable TCP_NODELAY to avoid trying to coalesce packets.
+        # @option io_opts [Numeric] connect_timeout (nil) (MQTT/S) Timeout in seconds to establish a connection
+        # @option io_opts [Numeric] resolv_timeout (connect_timeout) (MQTT/S) Timeout in seconds for name resolution
+        # @return [IO] -a connection to the URI
+        def new_io(**io_opts)
+          @uri.to_io(*@io_args, **@io_opts, **io_opts, **(@ssl_context && { ssl_context: @ssl_context }))
+        end
+
+        private
+
+        def default_scheme(io_params)
+          return io_params.delete(:scheme) if io_params.key?(:scheme)
+
+          io_params.keys.any? { |k| k.to_s.start_with?('ssl_') } ? 'mqtts' : 'mqtt'
+        end
+
+        # Pull non-SSL args out of the hash
+        # amazonq-ignore-next-line
+        def extract_io_args(io_args, io_params)
+          %i[uri host port local_addr local_port].each { |k| io_args << io_params.delete(k) }
+          io_args.compact!
+        end
+
+        def parse_uri(host = nil, *io_args, default_scheme:)
+          host ||= ENV.fetch('MQTT_SERVER', nil)
+          return [host, io_args.freeze] if host.is_a?(URI)
+          return [URI.parse(host), io_args.freeze] if host.is_a?(String) && host =~ %r{^[a-z]+://}
+
+          port = io_args.shift if io_args.any?
+          [URI.parse(["#{default_scheme}://#{host}", port].compact.join(':')), io_args.freeze]
+        end
+
+        def build_auth(io_params)
+          # agents review - file path traversal
+          password = File.read(io_params.delete(:password_file)).chomp if io_params.key?(:password_file)
+          password ||= URI.decode_www_form_component(@uri.password) if @uri.password
+          username = URI.decode_www_form_component(@uri.user) if @uri.user
+          # amazonq-ignore-next-line
+          @uri.password = '********' if password
+          { username: username, password: password }.compact
+        end
+
+        def slice_ssl_opts!(opts, *_keys)
+          slice_opts!(opts, :ssl_context, /^ssl_(.*)$/) do |k, v|
+            case k
+            when :verify_mode
+              coerce_ssl_verify_mode(v)
+            when :verify_hostname
+              coerce_boolean(k, v)
+            when :verify_depth
+              coerce_integer(k, v)
+            else
+              v
+            end
+          end
+        end
+
+        def build_ssl_context(ssl_context: nil, **ssl_params)
+          return unless @uri.scheme == 'mqtts'
+
+          (ssl_context || OpenSSL::SSL::SSLContext.new).tap do |ctx|
+            build_client_certificate_params(ssl_params)
+            ctx.set_params(ssl_params)
+          end
+        end
+
+        def coerce_ssl_verify_mode(value)
+          return value if value.is_a?(Integer)
+          return value unless value
+
+          case value.to_s.downcase
+          when 'none', '0' then OpenSSL::SSL::VERIFY_NONE
+          when 'peer', '1' then OpenSSL::SSL::VERIFY_PEER
+          when 'fail_if_no_peer_cert', '2' then OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT
+          when 'client_once', '4' then OpenSSL::SSL::VERIFY_CLIENT_ONCE
+          else
+            raise ArgumentError, "Invalid ssl_verify_mode: #{value}. Use 'none', 'peer', (See OpenSSL::SSL::VERIFY_*)"
+          end
+        end
+
+        # rubocop:disable Metrics/AbcSize
+        def build_client_certificate_params(ssl_params)
+          passphrase = File.read(ssl_params.delete(:passphrase_file)).chomp if ssl_params.key?(:passphrase_file)
+          passphrase = ssl_params.delete(:passphrase) if ssl_params.key?(:passphrase)
+
+          ssl_params[:cert] = load_certificate(ssl_params[:cert]) if ssl_params[:cert].is_a?(String)
+          ssl_params[:cert] = load_certificate_file(ssl_params.delete(:cert_file)) if ssl_params.key?(:cert_file)
+
+          ssl_params[:key] = load_private_key(ssl_params[:key], passphrase) if ssl_params[:key].is_a?(String)
+          return unless ssl_params.key?(:key_file)
+
+          ssl_params[:key] =
+            load_private_key_file(ssl_params.delete(:key_file), passphrase)
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        def load_certificate_file(cert_file)
+          return load_certificate(cert_file.binread) if cert_file.respond_to?(:binread)
+
+          load_certificate(File.binread(cert_file))
+        end
+
+        def load_certificate(cert)
+          return cert if cert.is_a?(OpenSSL::X509::Certificate)
+
+          OpenSSL::X509::Certificate.new(cert)
+        end
+
+        def load_private_key_file(key_file, passphrase = nil)
+          return load_private_key(key_file.binread, passphrase) if key_file.respond_to?(:binread)
+
+          load_private_key(File.binread(key_file), passphrase)
+        end
+
+        def load_private_key(key, pwd = nil)
+          return key if key.is_a?(OpenSSL::PKey::PKey)
+
+          OpenSSL::PKey.read(key, pwd)
+        end
+      end
+    end
+  end
+end

data/lib/mqtt/core/client/subscription.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative '../../errors'
+module MQTT
+  module Core
+    # Base subscription error
+    class SubscriptionError < ResponseError
+      # @!attribute [r] errors
+      #   @return [Hash<String,ReasonCode|ResultCode] Map of topic_filter to failure code
+      def initialize(failed_filters)
+        msg = ["#{self::NAME} failed for #{failed_filters.size} topics"] +
+              failed_filters.map { |topic_filter, status| "#{topic_filter}(#{status})" }
+        super(msg.join("\n\t"))
+      end
+    end
+
+    class SubscribeError < SubscriptionError
+      NAME = 'Subscribe'
+    end
+
+    class UnsubscribeError < SubscriptionError
+      NAME = 'Unsubscribe'
+    end
+
+    class Client
+      Subscription = Data.define(:sub_packet, :ack_packet, :handler, :client)
+
+      # Base subscription for handling received messages
+      class Subscription < Data
+        # @!attribute [r] sub_packet
+        #   @return [Packet] the `SUBSCRIBE` packet
+
+        # @!attribute [r] ack_packet
+        #  @return [Packet] the `SUBACK` packet
+
+        # Classify `SUBACK` results
+        # @return [Hash<String,Symbol>]
+        #   Map pf filter to acknowledged status. version-specific.
+        #
+        # @see Packet::Subscribe#filter_status
+        def filter_status
+          sub_packet.filter_status(ack_packet)
+        end
+
+        # Deregister this Subscription from its client and unsubscribe its topics from the server.
+        # @param [Hash<Symbol>] unsubscribe additional properties for the `UNSUBSCRIBE` packet
+        # @note this will also terminate the current enumeration.
+        def unsubscribe(**unsubscribe)
+          client.delete_subscription(self, **unsubscribe, **unsubscribe_params)
+        end
+
+        # Yield self, ensuring {#unsubscribe}
+        # @return [Object] the result of the block
+        def with!
+          yield self
+        ensure
+          unsubscribe
+        end
+
+        # Yield self, returning self, ensuring {#unsubscribe}
+        # @yieldreturn [void]
+        # @return [self]
+        def tap!(&)
+          tap { with!(&) }
+        end
+
+        # @!visibility private
+        # Match messages
+        def ===(other)
+          sub_packet === other # rubocop:disable Style/CaseEquality
+        end
+
+        # @!visibility private
+        def resubscribe_topic_filters
+          sub_packet.resubscribe_topic_filters(ack_packet)
+        end
+
+        # Successfully subscribed topic filters
+        # @return [Array<String>]
+        def subscribed_topic_filters
+          sub_packet.subscribed_topic_filters(ack_packet)
+        end
+
+        # @!visibility private
+        # called from a client when a message has arrived
+        def put(packet)
+          handle(packet, &handler) unless packet.is_a?(StandardError)
+        end
+
+        # @!visibility private
+        def match?(publish_packet)
+          sub_packet.match?(publish_packet)
+        end
+
+        private
+
+        def unsubscribe_params
+          sub_packet.unsubscribe_params(ack_packet)
+        end
+
+        def handle(packet)
+          raise packet if packet.is_a?(StandardError)
+
+          (block_given? ? yield(packet) : packet).tap { client.handled!(packet) if packet&.qos&.positive? }
+        end
+      end
+    end
+  end
+end

data/lib/mqtt/core/client/uri.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module URI
+  # MQTT over TCP
+  # @see https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme
+  class MQTT < ::URI::Generic
+    DEFAULT_PORT = 1883
+
+    # Options for MQTT URI new_io method
+    IO_OPTS = %i[connect_timeout resolv_timeout tcp_nodelay].freeze
+
+    def require_deps
+      require 'socket'
+    end
+
+    # Create a TCP socket connection to the MQTT broker
+    # @param local_args [Array] Optional local_host and local_port for binding
+    # @param connect_timeout [Numeric, nil] Timeout in seconds for connection establishment
+    # @param resolv_timeout [Numeric, nil] Timeout in seconds for DNS resolution (defaults to connect_timeout)
+    # @param tcp_nodelay [Boolean] Enable TCP_NODELAY to avoid waiting to coalesce packets (default: true)
+    # @return [TCPSocket]
+    def to_io(*local_args, connect_timeout: nil, resolv_timeout: connect_timeout, tcp_nodelay: true)
+      TCPSocket.new(host, port, *local_args, connect_timeout:, resolv_timeout:).tap do |socket|
+        socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1) if tcp_nodelay
+      end
+    end
+  end
+
+  # MQTT over TLS
+  # @see https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme
+  class MQTTS < MQTT
+    DEFAULT_PORT = 8883
+
+    def require_deps
+      require_relative '../../../patches/openssl'
+    end
+
+    # Create a TLS-encrypted socket connection to the MQTT broker
+    # @param local_args [Array] Optional local_host and local_port for binding
+    # @param ssl_context [OpenSSL::SSL::SSLContext] Pre-configured SSL context (required)
+    # @param connect_timeout [Numeric, nil] Timeout in seconds for connection establishment and SSL handshake
+    # @param tcp_args [Hash] Additional TCP options (see {MQTT#to_io})
+    # @return [OpenSSL::SSL::SSLSocket]
+    def to_io(*local_args, ssl_context:, connect_timeout: nil, **tcp_args)
+      tcp = super(*local_args, connect_timeout:, **tcp_args)
+      tcp.timeout = connect_timeout if connect_timeout
+      OpenSSL::SSL::SSLSocket.new(tcp, ssl_context).tap do |ssl_socket|
+        ssl_socket.sync_close = true
+        ssl_socket.hostname = host # For SNI validation if requested
+        ssl_socket.connect
+      end
+    end
+  end
+
+  # MQTT over Unix domain socket
+  # @example
+  #   URI('unix:///var/run/mosquitto.sock')
+  class Unix < ::URI::Generic
+    DEFAULT_PORT = nil
+
+    def require_deps
+      require 'socket'
+    end
+
+    # Create a Unix domain socket connection
+    # @return [UNIXSocket]
+    def to_io(...)
+      UNIXSocket.new(path)
+    end
+  end
+end
+
+URI.register_scheme 'mqtt', URI::MQTT
+URI.register_scheme 'mqtts', URI::MQTTS
+URI.register_scheme 'unix', URI::Unix