mqtt-v5 0.0.1.ci.release

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a5e261413c2be4f3d16bbbd3ee4047b851617ce7316fa26860e16206369b23c
+  data.tar.gz: da4064437dc46ac32962b5df6353d4c5e25ec017ea0eda8a70e9eb11aa1afc8e
+SHA512:
+  metadata.gz: b012587302e73b990c2d8f4879ec1cc1f8de601bd2c272cdf4d44d39dbf73bc5215424edebdcea57e52acd00212f0926680be1a2619c92ec36c2e06b9e115f70
+  data.tar.gz: fd2bff72aac401f3dc37dfa86fa1498b4440771fffb5f7c681b9fe2d7369b175609eef3f325ee347673da0c5f6ecdb654f2cc4018c3eddcb8540514355ebd4df

data/lib/mqtt/v5/async/client.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'async'
+require_relative '../client'
+
+module MQTT
+  module V5
+    module Async
+      # An Async {MQTT::Core::Client} for MQTT 5.0
+      class Client < MQTT::V5::Client
+        class << self
+          # Create a new {Client}
+          def open(*io_args, **run_args, &)
+            raise FiberError, 'No async reactor' unless block_given? || ::Async::Task.current?
+
+            super
+          end
+
+          # @!visibility private
+          def mqtt_monitor
+            async_monitor
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mqtt/v5/client/authenticator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module MQTT
+  module V5
+    class Client < MQTT::Core::Client
+      # Enhanced authentication
+      # @abstract
+      class Authenticator
+        class << self
+          # @param [String] auth_method
+          # @param [Class|Authenticator] authenticator
+          def register(auth_method, authenticator)
+            @authenticators ||= {}
+            @authenticators[auth_method] = authenticator
+          end
+
+          #   @param [String<UTF8>|Class|Authenticator] auth_method
+          #     * String will lookup a registered authenticator (see #{register} )
+          #     * Class will be used to instantiate an Authenticator
+          #     * Authenticator (or something that quacks like one) will be used directly
+          #   @return [Authenticator]
+          #   @raise [Error] if authentication_method is not valid
+          def factory(auth_method)
+            return nil unless auth_method
+
+            if auth_method.is_a?(String)
+              auth_method = @authenticators.fetch do
+                raise ProtocolError, "Unknown authentication method #{auth_method}"
+              end
+            end
+
+            return auth_method.new if auth_method.is_a?(Class)
+            return auth_method if %i[start continue success failed].all? { |m| auth_method.respond_to?(m) }
+
+            raise Error, "Invalid Authenticator #{auth_method}"
+          end
+        end
+
+        # Start authentication
+        # @!method start(authentication_method:, authentication_data: nil, **connect_props)
+        #   @param [String] authentication_method
+        #   @param [String] authentication_data
+        #   @param [Hash<Symbol>] connect_props additional properties for connect packet
+        #   @return [Hash<Symbol>] properties to merge into the connect data
+        #      typically will include :authentication_data
+        #      can include other connect packet properties
+
+        # Initiate re-authentication
+        # @!method reauthenticate(authentication_method:, authentication_data: nil, **auth_props)
+        #   @param [String] authentication_method
+        #   @param [String,nil] authentication_data
+        #   @param [Hash<Symbol>] auth_props additional properties supplied to reauthenticate
+        #   @return [Hash<Symbol>] properties to merge into the auth data
+        #      typically will include :authentication_data
+        #      can include other auth packet properties
+        # @note this need not be implemented if re-authentication is not required
+
+        # Continue authentication
+        # @!method continue(authentication_method:, authentication_data: nil, **auth_props)
+        #   @param [String] authentication_method
+        #   @param [String] authentication_data
+        #   @param [Hash<Symbol>] auth_props additional auth properties (from auth packet)
+        #   @return [Hash<Symbol>] properties to merge into the auth packet
+        #      typically will include :authentication_data
+        #      can include other auth packet properties
+
+        # Completion of successful authentication
+        # @!method success(authentication_method:, authentication_data: nil, **auth_props)
+        #   @param [String] authentication_method
+        #   @param [String] authentication_data
+        #   @param [Hash<Symbol>] auth_props additional auth properties (from connack or auth completion packet)
+        #   @return [void]
+
+        # Notification of failed authentication
+        # @!method failed(reason_code:, **properties)
+        #   @param [Integer] reason_code
+        #   @param [Hash<Symbol>] properties of the failed connack or disconnect packet
+        #   @return [void]
+        # @note this is not guaranteed to be called
+      end
+    end
+  end
+end

data/lib/mqtt/v5/client/connection.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'mqtt/core/client'
+require_relative '../topic_alias'
+
+module MQTT
+  module V5
+    class Client < MQTT::Core::Client
+      # Client protocol for MQTT 5.0
+      class Connection < MQTT::Core::Client::Connection # rubocop:disable Metrics/ClassLength
+        def initialize(**)
+          super
+          @qos_send_condition = new_condition
+        end
+
+        def publish(qos: 0, topic_alias: true, **publish, &)
+          decrement_send_quota if qos.positive?
+          topic_alias = topic_alias.positive? if topic_alias.is_a?(Integer)
+          publish[:assign_alias] = topic_alias
+          begin
+            session.publish(qos:, **publish, &)
+          rescue StandardError
+            increment_send_quota if qos.positive?
+            raise
+          end
+        end
+
+        def send_packet(packet)
+          topic_aliases&.handle_outgoing(packet) if packet&.packet_name == :publish
+          super
+        end
+
+        def disconnect(exception = nil, **disconnect)
+          if exception
+            disconnect.merge!({ reason_code: 0x04, reason_string: "#{exception.class.name}: #{exception.message}" })
+          end
+
+          super(**disconnect)
+        end
+
+        def reauthenticate(**auth, &)
+          raise ProtocolError, 'Not connected with extended auth' unless @auth
+
+          # reauthenticate sets authentication_method/data in auth data
+          send_packet(auth_packet(reason_code: 0x19, **@auth.reauthenticate(**auth)), &)
+        end
+
+        private
+
+        def_delegators :session, :clean_start, :session_expiry_interval, :max_packet_id, :stored_packet?, :session_store
+        def_delegators :client, :topic_aliases, :auth_ack
+
+        def connect_packet(**connect)
+          super.tap do |p|
+            @qos_receive_quota = p.receive_maximum || max_packet_id
+            topic_aliases&.clear_incoming!(p)
+          end
+        end
+
+        def connect_data(**connect)
+          super.tap { |data| data.merge!(setup_authentication(**connect)) }
+        end
+
+        def setup_authentication(authentication_method: nil, **connect)
+          return {} unless authentication_method
+
+          @auth = Authenticator.factory(authentication_method)
+          @auth.start(authentication_method:, **connect)
+        end
+
+        def complete_connection(received_packet)
+          super(complete_authentication(received_packet))
+        end
+
+        def complete_authentication(packet)
+          while packet&.packet_name == :auth
+            raise ProtocolError, 'Unexpected auth packet' unless @auth
+
+            packet.continue!
+
+            send_packet(auth_packet(**@auth.continue(**packet.properties.dup)))
+            packet = receive_packet
+          end
+          packet
+        end
+
+        def handle_connack(packet)
+          super
+          @auth&.success(**packet.properties)
+          @qos_send_quota = packet.receive_maximum || max_packet_id
+          topic_aliases&.clear_outgoing!(packet)
+          self.keep_alive = [@keep_alive, packet.server_keep_alive || @keep_alive].min if packet.server_keep_alive
+          log.debug { "Connected: Keep alive: #{@keep_alive}, Send quota: #{@qos_send_quota}" }
+          true
+        rescue BadAuthenticationMethod, NotAuthorized => e
+          @auth&.failed(reason_code: e.code, **packet.properties)
+          raise
+        end
+
+        def handle_auth(packet)
+          raise ProtocolError, 'Unexpected auth packet' unless @auth
+
+          case packet.reason_code
+          when 0x18 # continue
+            push_packet(auth_packet(**@auth.continue(**packet.properties.dup)))
+          when 0x00 # success - we only see this on reauthenticate, otherwise it comes in connack
+            @auth.success(**packet.properties)
+            auth_ack(packet)
+          else
+            raise UnknownReasonCode, packet.reason_code, 'Unknown reason code for auth packet'
+          end
+        end
+
+        def auth_packet(reason_code: 0x18, **data)
+          # always a continuation from the client
+          build_packet(:auth, reason_code:, **data)
+        end
+
+        def handle_publish(packet)
+          topic_aliases&.handle_incoming(packet)
+          decrement_receive_quota if packet.qos.positive?
+
+          super
+        rescue ReceiveMaximumExceeded, TopicAliasInvalid => e
+          push_packet(disconnect_packet(reason_code: e.reason_code))
+        end
+
+        def handle_puback(packet)
+          increment_send_quota if stored_packet?(packet.id)
+          super
+        end
+
+        def handle_pubrec(packet)
+          increment_send_quota if packet.failed? && stored_packet?(packet.id)
+          super
+        end
+
+        def handle_pubcomp(packet)
+          increment_send_quota if stored_packet?(packet.id)
+          super
+        end
+
+        def handle_disconnect(packet)
+          super
+        rescue NotAuthorized => e
+          @auth&.failed(reason_code: e.code, **packet.properties)
+        rescue ServerMoved, UseAnotherServer
+          handle_server_redirect(packet)
+          raise
+        end
+
+        # @!visibility private
+        def handle_server_redirect(packet)
+          # moved temporarily,  moved permanently
+          # Followed by a UTF-8 Encoded String which can be used by the Client to identify another Server to use.
+          # It is a Protocol Error to include the Server Reference more than once.
+          # The Server sends DISCONNECT including a Server Reference and Reason Code 0x9C (Use another server) or 0x9D
+          # (Server moved) as described in section 4.13.
+          socket_factory.redirect(packet.server_redirect) if socket_factory.respond_to?(:redirect)
+        end
+
+        def decrement_receive_quota
+          synchronize do
+            raise RecieveMaximumExceeded if @qos_receive_quota.zero?
+
+            @qos_receive_quota -= 1
+          end
+        end
+
+        def increment_receive_quota
+          synchronize do
+            @qos_receive_quota += 1
+          end
+        end
+
+        def decrement_send_quota
+          synchronize do
+            @qos_send_condition.wait_until { @qos_send_quota.positive? }
+            @qos_send_quota -= 1
+          end
+        end
+
+        def increment_send_quota
+          synchronize do
+            @qos_send_quota += 1
+            @qos_send_condition.signal
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mqtt/v5/client/session.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'mqtt/core/client'
+require_relative '../packet'
+
+module MQTT
+  module V5
+    class Client < MQTT::Core::Client
+      # Client Session specialisation for MQTT 5.0
+      class Session < MQTT::Core::Client::Session
+        # If client id was set non-empty, then this is just used
+        # If not set, or explicitly empty or explicitly nil, then use server-assigned client id
+        def connect_data(**connect)
+          check_session_managed_fields(:connect, connect, :clean_start, :session_expiry_interval)
+          super.merge!(
+            {
+              clean_start: clean?,
+              session_expiry_interval: session_store.expiry_interval
+            }
+          )
+        end
+
+        # There seems to be no real use for updating the session_expiry_interval on disconnect,
+        # and there are potential issues because we don't get an ack to know if the broker ever received it.
+        def disconnect_data(**disconnect)
+          check_session_managed_fields(:disconnect, disconnect, :session_expiry_interval)
+          super
+        end
+
+        def connected!(connect, connack)
+          session_store.client_id = connack.assigned_client_identifier if connack.assigned_client_identifier
+          session_store.expiry_interval = connack.session_expiry_interval if connack.session_expiry_interval
+          super
+        end
+
+        private
+
+        def qos2_response(response_name, id, exists, **data)
+          # Use reason code instead of raise protocol error
+          super(response_name, id, true, reason_code: exists ? 0x00 : 0x92, **data)
+        end
+      end
+    end
+  end
+end

data/lib/mqtt/v5/client.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'mqtt/core/client'
+require_relative 'packets'
+require_relative 'client/authenticator'
+require_relative 'client/connection'
+require_relative 'client/session'
+
+module MQTT
+  module V5
+    # An MQTT::V5 Client
+    #
+    class Client < MQTT::Core::Client
+      # @!visibility private
+      def self.packet_module
+        Packet
+      end
+
+      # @!visibility private
+      def self.protocol_version
+        5
+      end
+
+      # @return [TopicAlias::Manager] the topic alias manager manages the bi-directional mapping of topic names to
+      #   topic aliases to limit bandwidth usage.
+      attr_reader :topic_aliases
+
+      # @!visibility private
+      def self.new_options(configure_opts)
+        { topic_aliases: configure_opts.delete(:topic_aliases) }
+      end
+
+      # @!visibility private
+      def initialize(topic_aliases: nil, **)
+        @topic_aliases = topic_aliases
+        super(**)
+      end
+
+      # V5 Authentication flow (untested)
+      def reauthenticate(**auth)
+        connection.reauthenticate(**auth) { |packet| send_and_wait(packet) { |ack| handle_ack(packet, ack) } }
+      end
+
+      # @!method publish(topic, message, **publish)
+      #   @param [String] topic
+      #   @param [String] message
+      #   @param [Hash<Symbol>] publish additional attributes for the `PUBLISH` packet.
+      #   @option publish [Boolean] topic_alias (true) whether to try to assign a topic alias. See {#topic_aliases}
+      #
+      #     This property is a hint to the {TopicAlias::Manager}. The primary use is to avoid aliasing
+      #     a topic that will only be used once, or to indicate that this is the last publish to a topic, and thus
+      #     leave room in the alias cache for other topics.
+      #
+      #     If you pass an Integer, it is treated as `true` if positive otherwise `false`.
+      #     The value is not used directly.
+      #   @return [self]
+      #   @see Packet::Publish
+      #   @see Core::Client#publish
+    end
+  end
+end

data/lib/mqtt/v5/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module MQTT
+  module V5
+    # V5 response error - with reason code
+    class ResponseError < MQTT::ResponseError
+      class << self
+        attr_reader :code
+      end
+
+      def initialize(message = nil)
+        code = self.class.code || 0xff
+        super(format '(0x%02<code>x) %<message>s', code:, message:)
+      end
+    end
+
+    class UnknownReasonCode < ResponseError; end
+  end
+end

data/lib/mqtt/v5/packet/auth.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 AUTH packet
+      #
+      # Sent by client or broker for extended authentication exchange.
+      #
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901217 MQTT 5.0 Spec §3.15
+      class Auth
+        include Packet
+
+        fixed(15)
+
+        # @!parse include ReasonCodeAck
+        # @!attribute [r] reason_code
+        #   authentication status
+        #
+        #   ✅ Success:
+        #
+        #   - `0x00` Success
+        #   - `0x18` Continue authentication
+        #   - `0x19` Re-authenticate
+        #
+        #   @return [ReasonCode]
+
+        # @!group Properties
+
+        # @!attribute [r] authentication_method
+        #   @return [String<UTF8>] authentication method name
+        # @!attribute [r] authentication_data
+        #   @return [String<Binary>] authentication data
+        # @!attribute [r] reason_string
+        #   @return [String<UTF8>] human-readable reason for the response
+        # @!attribute [r] user_properties
+        #   @return [Array<String, String>] user-defined properties as key-value pairs
+
+        # @!endgroup
+
+        variable(
+          reason_code:, # automatically includes ReasonCodeAck
+          properties:
+        )
+
+        # @return [self] if reason code is 0x18 (Continue authentication)
+        # @raise [ProtocolError] if reason code is not 0x18
+        def continue!
+          return self if reason_code == 0x18
+
+          raise ProtocolError, reason_code, 'expected reason code 0x18 (auth continue)'
+        end
+      end
+    end
+  end
+end

data/lib/mqtt/v5/packet/connack.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 CONNACK packet
+      #
+      # Connection acknowledgement sent by broker in response to a CONNECT packet.
+      #
+      # @see Core::Client#connect
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901074 MQTT 5.0 Spec §3.2
+      class Connack
+        include Packet
+
+        fixed(2)
+
+        # @!attribute [r] session_present
+        #   @return [Boolean] whether the broker has a stored session for this client
+
+        # @!parse include ReasonCodeAck
+        # @!attribute [r] reason_code
+        #   connection acknowledgement status
+        #
+        #   ✅ Success:
+        #
+        #   - `0x00` Success
+        #
+        #   ❌ Error:
+        #
+        #   - `0x80` Unspecified error
+        #   - `0x81` Malformed Packet
+        #   - `0x82` Protocol Error
+        #   - `0x83` Implementation specific error
+        #   - `0x84` Unsupported Protocol Version
+        #   - `0x85` Client Identifier not valid
+        #   - `0x86` Bad User Name or Password
+        #   - `0x87` Not authorized
+        #   - `0x88` Server unavailable
+        #   - `0x89` Server busy
+        #   - `0x8A` Banned
+        #   - `0x8C` Bad authentication method
+        #   - `0x90` Topic Name invalid
+        #   - `0x95` Packet too large
+        #   - `0x97` Quota exceeded
+        #   - `0x99` Payload format invalid
+        #   - `0x9A` Retain not supported
+        #   - `0x9B` QoS not supported
+        #   - `0x9C` Use another server
+        #   - `0x9F` Connection rate exceeded
+        #
+        #   @return [ReasonCode]
+
+        # @!group Properties
+
+        # @!attribute [r] session_expiry_interval
+        #   @return [Integer] session expiry interval in seconds
+        # @!attribute [r] receive_maximum
+        #   @return [Integer] maximum number of QoS 1 and 2 messages the server will process concurrently
+        # @!attribute [r] maximum_qos
+        #   @return [Integer] maximum QoS level supported by the server
+        # @!attribute [r] retain_available
+        #   @return [Boolean] whether the server supports retained messages
+        # @!attribute [r] maximum_packet_size
+        #   @return [Integer] maximum packet size the server is willing to accept
+        # @!attribute [r] assigned_client_identifier
+        #   @return [String<UTF8>] client identifier assigned by the server
+        # @!attribute [r] topic_alias_maximum
+        #   @return [Integer] maximum topic alias value supported by the server
+        # @!attribute [r] reason_string
+        #   @return [String<UTF8>] human-readable reason for the response
+        # @!attribute [r] user_properties
+        #   @return [Array<String, String>] user-defined properties as key-value pairs
+        # @!attribute [r] wildcard_subscription_available
+        #   @return [Boolean] whether the server supports wildcard subscriptions
+        # @!attribute [r] subscription_identifier_available
+        #   @return [Boolean] whether the server supports subscription identifiers
+        # @!attribute [r] shared_subscription_available
+        #   @return [Boolean] whether the server supports shared subscriptions
+        # @!attribute [r] server_keep_alive
+        #   @return [Integer] keep alive time in seconds assigned by the server
+        # @!attribute [r] response_information
+        #   @return [String<UTF8>] response information for request/response
+        # @!attribute [r] server_reference
+        #   @return [String<UTF8>] server reference for redirection
+        # @!attribute [r] authentication_method
+        #   @return [String<UTF8>] authentication method name
+        # @!attribute [r] authentication_data
+        #   @return [String<Binary>] authentication data
+
+        # @!endgroup
+
+        variable(
+          flags: flags([:reserved, 7], [:session_present, 1]),
+          reason_code:, # automatically includes ReasonCodeAck
+          properties:
+        )
+
+        alias connect_reason_code reason_code # align with spec naming
+        alias session_present? session_present
+
+        # @!visibility private
+        def defaults
+          super.merge!(session_present: false)
+        end
+      end
+    end
+  end
+end