mqtt-v5 0.0.1.ci.release

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module MQTT
+  module V5
+    module Packet
+      ReasonCode = Data.define(:code, :name, :error)
+
+      # Encapsulates reason codes
+      class ReasonCode < Data
+        # @!attribute [r] code
+        #   @return [Integer] the reason code value
+        # @!attribute [r] name
+        #   @return [String] the reason code name
+        # @!attribute [r] error
+        #   @return [Class,nil] the error class for failed reason codes
+
+        class << self
+          # rubocop:disable Style/OptionalBooleanParameter
+          def register(code, name, packet_types, retriable = false)
+            @reason_codes ||= Hash.new { |h, k| h[k] = {} }
+            rc = create(code, name, retriable)
+            packet_types.each { |packet_type| @reason_codes[packet_type][code] = rc }
+          end
+          # rubocop:enable Style/OptionalBooleanParameter
+
+          def find(packet_name, reason_code)
+            @reason_codes.dig(packet_name, reason_code) || unknown_reason_code(packet_name, reason_code)
+          end
+
+          def failed?(reason_code)
+            reason_code >= 0x80
+            # define readers
+          end
+
+          private
+
+          def create(code, name, retriable)
+            error = define_error_class(code, name, retriable) if code >= 0x80
+            new(code, name, error)
+          end
+
+          def unknown_reason_code(packet_name, reason_code)
+            new(reason_code, "Unknown ReasonCode for #{packet_name}", UnknownReasonCode)
+          end
+
+          def define_error_class(code, name, retriable)
+            klass = Class.new(ResponseError)
+            klass.include(Error::Retriable) if retriable
+            klass.instance_variable_set(:@code, code)
+            MQTT::V5.const_set(name.split(/\s+/).map(&:capitalize).join, klass)
+          end
+        end
+
+        def failed?
+          self.class.failed?(code)
+        end
+
+        def success!(reason_string)
+          return self unless failed?
+
+          raise error, reason_string || name
+        end
+
+        def to_s
+          format '%<name>s(0x%02<code>x)', name:, code:
+        end
+      end
+
+      # Success/Failed for packets with a single reason_code field
+      module ReasonCodeAck
+        def defaults
+          super.merge!({ reason_code: 0x00 })
+        end
+
+        def success?
+          !failed?
+        end
+
+        # @return [self]
+        # @raise [ResponseError]
+        def success!
+          reason_code_data.success!(reason_string) && self
+        end
+
+        def failed?
+          ReasonCode.failed?(reason_code)
+        end
+
+        def to_s
+          "#{super}: #{reason_code_data}"
+        end
+
+        def reason_code_data
+          ReasonCode.find(packet_name, reason_code)
+        end
+      end
+
+      # Module for packets with a :reason_codes field
+      module ReasonCodeListAck
+        def reason_codes_data
+          reason_codes.map { |rc| ReasonCode.find(packet_name, rc) }
+        end
+
+        def to_s
+          "#{super}: #{reason_codes_data.map { |rc| format('0x%02<code>x', code: rc.code) }.tally}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 SUBACK packet
+      #
+      # Subscription acknowledgement sent by broker in response to a SUBSCRIBE packet.
+      #
+      # @see Core::Client#subscribe
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901171 MQTT 5.0 Spec §3.9
+      class SubAck
+        include Packet
+
+        fixed(9)
+
+        # @!attribute [r] packet_identifier
+        #   @return [Integer] packet identifier matching the SUBSCRIBE packet (receive only)
+
+        # @!group Properties
+
+        # @!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
+
+        # @!parse include ReasonCodeListAck
+        # @!attribute [r] reason_codes
+        #   acknowledgement status for each subscription
+        #
+        #   ✅ Success:
+        #
+        #   - `0x00` Granted QoS 0
+        #   - `0x01` Granted QoS 1
+        #   - `0x02` Granted QoS 2
+        #
+        #   ❌ Error:
+        #
+        #   - `0x80` Unspecified error
+        #   - `0x83` Implementation specific error
+        #   - `0x87` Not authorized
+        #   - `0x8F` Topic Filter invalid
+        #   - `0x91` Packet Identifier in use
+        #   - `0x97` Quota exceeded
+        #   - `0xA1` Subscription Identifiers not supported
+        #   - `0xA2` Wildcard Subscriptions not supported
+        #
+        #   @return [Array<ReasonCode>]
+
+        variable(
+          packet_identifier: :int16,
+          properties:
+        )
+        payload(
+          reason_codes: # automatically includes ReasonCodeListAck
+        )
+
+        alias return_codes reason_codes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+require 'mqtt/core/packet/subscribe'
+
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 SUBSCRIBE packet
+      #
+      # Sent by client to subscribe to one or more topic filters.
+      #
+      # @see Core::Client#subscribe
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901161 MQTT 5.0 Spec §3.8
+      class Subscribe
+        include Packet
+
+        fixed(8, [:reserved, 4, 0b0010])
+
+        # @!attribute [r] packet_identifier
+        #   @return [Integer] packet identifier for matching with SUBACK (managed automatically by session)
+
+        # @!group Properties
+
+        # @!attribute [r] subscription_identifier
+        #   @return [Integer] identifier for this subscription
+        # @!attribute [r] user_properties
+        #   @return [Array<String, String>] user-defined properties as key-value pairs
+
+        # @!endgroup
+
+        # @!parse
+        #   class TopicFilter
+        #     # @!attribute [r] topic_filter
+        #     #   @return [String<UTF8>] topic filter pattern
+        #     # @!attribute [r] max_qos
+        #     #   @return [Integer] maximum QoS level accepted by the client: 0, 1, or 2
+        #     # @!attribute [r] no_local
+        #     #   @return [Boolean] do not forward messages back to same client id
+        #     # @!attribute [r] retain_as_published
+        #     #   @return [Boolean] retain flag from PUBLISH should be preserved
+        #     # @!attribute [r] retain
+        #     #   @return [Integer]
+        #     #   retained message handling
+        #     #
+        #     #   - `0` Send retained messages at the time of subscribe
+        #     #   - `1` Send retained messages only if subscription does not currently exist
+        #     #   - `2` Do not send retained messages at the time of subscribe
+        #   end
+
+        # @!attribute [r] topic_filters
+        #   @return [Array<TopicFilter>] list of topic filters to subscribe to
+
+        variable(
+          packet_identifier: :int16,
+          properties:
+        )
+        payload(
+          topic_filters: list(
+            :topic_filter,
+            topic_filter: :utf8string,
+            subscription_options: flags(
+              [:reserved, 2],
+              [:retain, 2],
+              :retain_as_published,
+              :no_local,
+              [:max_qos, 2]
+            )
+          ) do
+            alias_method :requested_qos, :max_qos
+          end
+        )
+
+        MAX_QOS_FIELD = :max_qos
+        include MQTT::Core::Packet::Subscribe
+
+        def match?(publish_packet)
+          if subscription_identifier&.positive?
+            publish_packet.match_subscription_identifier?(subscription_identifier)
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 UNSUBACK packet
+      #
+      # Unsubscribe acknowledgement sent by broker in response to an UNSUBSCRIBE packet.
+      #
+      # @see Core::Client::Subscription#unsubscribe
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901187 MQTT 5.0 Spec §3.11
+      class UnsubAck
+        include Packet
+
+        fixed(11)
+
+        # @!attribute [r] packet_identifier
+        #   @return [Integer] packet identifier matching the UNSUBSCRIBE packet (receive only)
+
+        # @!group Properties
+
+        # @!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
+
+        # @!parse include ReasonCodeListAck
+        # @!attribute [r] reason_codes
+        #   acknowledgement status for each topic filter
+        #
+        #   ✅ Success:
+        #
+        #   - `0x00` Success
+        #   - `0x11` No subscription existed
+        #
+        #   ❌ Error:
+        #
+        #   - `0x80` Unspecified error
+        #   - `0x83` Implementation specific error
+        #   - `0x87` Not authorized
+        #   - `0x8F` Topic Filter invalid
+        #   - `0x91` Packet Identifier in use
+        #
+        #   @return [Array<ReasonCode>]
+
+        variable(
+          packet_identifier: :int16,
+          properties:
+        )
+        payload(
+          reason_codes: # automatically includes ReasonCodeListAck
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+require 'mqtt/core/packet/unsubscribe'
+
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 UNSUBSCRIBE packet
+      #
+      # Sent by client to unsubscribe from one or more topic filters.
+      #
+      # @see Core::Client::Subscription#unsubscribe
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901179 MQTT 5.0 Spec §3.10
+      class Unsubscribe
+        include Packet
+        include Core::Packet::Unsubscribe
+
+        fixed(10, [:reserved, 4, 0b0010])
+
+        # @!attribute [r] packet_identifier
+        #   @return [Integer] packet identifier for matching with UNSUBACK (managed automatically by session)
+
+        # @!group Properties
+
+        # @!attribute [r] user_properties
+        #   @return [Array<String, String>] user-defined properties as key-value pairs
+
+        # @!endgroup
+
+        # @!attribute [r] topic_filters
+        #   @return [Array<String<UTF8>>] list of topic filters to unsubscribe from
+
+        variable(
+          packet_identifier: :int16,
+          properties:
+        )
+        payload(
+          topic_filters: list(:utf8string)
+        )
+
+        def apply_data(data)
+          @ignore_failed = data.delete(:ignore_failed) { false }
+          @ignore_no_subscription = data.delete(:ignore_no_subscription) { true }
+          super
+        end
+
+        # @return [Hash<String,Symbol>]
+        #   Map of topic_filter to ack status
+        #   * :success - subscription existed and was unsubscribed from the server
+        #   * :no_subscription - subscription did not exist on the server
+        #   * :failed - subscription failed to unsubscribe
+        def filter_status(unsuback)
+          topic_filters.zip(unsuback.reason_codes).to_h { |tf, rc| [tf, classify(rc)] }
+        end
+
+        # @return [Array<String>]
+        def unsubscribed_topic_filters(unsuback = nil)
+          return topic_filters unless unsuback
+
+          topic_filters.zip(unsuback.reason_codes).filter_map { |tf, rc| tf unless failed?(rc) }
+        end
+
+        # Version dependent partition topic_filters into success and failures
+        #
+        # Attributes @ignore_no_subscription and @ignore_failed can control whether these statuses are considered
+        # successful or not.
+        # @return [Array<Hash<String,Symbol>>] pair of Maps as per #filter_status
+        def partition_success(unsuback)
+          filter_status(unsuback).partition { |(_tf, ack_status)| ack_success?(ack_status) }.map(&:to_h)
+        end
+
+        def success!(unsuback)
+          _, failed = partition_success(unsuback)
+
+          raise UnsubscribeError, failed unless failed.empty?
+
+          self
+        end
+
+        private
+
+        def failed?(reason_code)
+          ReasonCode.failed?(reason_code)
+        end
+
+        def classify(reason_code)
+          if failed?(reason_code)
+            :failed
+          elsif reason_code == 0x17
+            :no_subscription
+          else
+            :success
+          end
+        end
+
+        def ack_success?(ack_status)
+          case ack_status
+          when :success
+            true
+          when :no_subscription
+            @ignore_no_subscription
+          when :failed
+            @ignore_failed
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mqtt/v5/packet.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'mqtt/core/packet'
+require_relative 'version'
+require_relative 'errors'
+require_relative 'packet/reason_code'
+
+module MQTT
+  module V5
+    # MQTT 5.0 base packet definition
+    #
+    # Inherited constants (referenced via self:: in {MQTT::Core::Packet}
+    module Packet
+      VALUE_TYPES = {
+        utf8string: MQTT::Core::Type::UTF8String,
+        binary: MQTT::Core::Type::Binary,
+        remaining: MQTT::Core::Type::Remaining,
+        utf8pair: MQTT::Core::Type::UTF8StringPair,
+        int8: MQTT::Core::Type::Int8,
+        int16: MQTT::Core::Type::Int16,
+        int32: MQTT::Core::Type::Int32,
+        intvar: MQTT::Core::Type::VarInt,
+        varint: MQTT::Core::Type::VarInt,
+        boolean: MQTT::Core::Type::BooleanByte
+      }.freeze
+
+      # Available property types for MQTT version 5.0
+      # @note :user_properties
+      #   The spec uses the singular 'user_property' - but it is the only property that can occur more than once
+      #   and it the key in the pair can itself appear more than once, so we represent it as Array<String,String>
+      #   and give it the plural name
+
+      # Attributes stored as a list of properties
+      PROPERTY_TYPES = [
+        [0x01, :payload_format_indicator, :int8, %i[publish will]],
+        [0x02, :message_expiry_interval, :int32, %i[publish will]],
+        [0x03, :content_type, :utf8string, %i[publish will]],
+        [0x08, :response_topic, :utf8string, %i[publish will]],
+        [0x09, :correlation_data, :binary, %i[publish will]],
+        # @!attribute [r] subscription_identifier
+        #   @return [Integer] (publish)
+        #   @return [Array<Integer>] (subscribe)
+        [0x0B, :subscription_identifier, :varint, %i[subscribe]],
+        [0x08, :subscription_identifiers, [:varint], %i[publish]], # this is only sent by servers
+        [0x11, :session_expiry_interval, :int32, %i[connect connack disconnect]],
+        [0x12, :assigned_client_identifier, :utf8string, [:connack]],
+        [0x13, :server_keep_alive, :int16, [:connack]],
+        [0x15, :authentication_method, :utf8string, %i[connect connack auth]],
+        [0x16, :authentication_data, :binary, %i[connect connack auth]],
+        [0x17, :request_problem_information, :boolean, [:connect]],
+        [0x18, :will_delay_interval, :int32, [:will]],
+        [0x19, :request_response_information, :boolean, [:connect]],
+        [0x1A, :response_information, :utf8string, [:connack]],
+        [0x1C, :server_reference, :utf8string, %i[connack disconnect]],
+        [0x1F, :reason_string, :utf8string, %i[connack puback pubrec pubrel pubcomp suback unsuback disconnect auth]],
+        [0x21, :receive_maximum, :int16, %i[connect connack]],
+        [0x22, :topic_alias_maximum, :int16, %i[connect connack]],
+        [0x23, :topic_alias, :int16, [:publish]],
+        [0x24, :maximum_qos, :int8, [:connack]],
+        [0x25, :retain_available, :boolean, [:connack]],
+        # @!attribute [r] user_properties
+        #   @return [Array<String,String>] list of key,value pairs, same key may appear more than once
+        [0x26, :user_properties, [:utf8pair], :all],
+        [0x27, :maximum_packet_size, :int32, %i[connect connack]],
+        [0x28, :wildcard_subscription_available, :boolean, [:connack]],
+        [0x29, :subscription_identifier_available, :boolean, [:connack]],
+        [0x2A, :shared_subscription_available, :boolean, [:connack]]
+      ].map { |data| MQTT::Core::Type::Properties::PropertyType.create(*data, types: VALUE_TYPES) }.freeze
+
+      # If the sender is compliant with this specification it will not send Malformed Packets or cause Protocol Errors
+
+      # Reason codes
+      REASON_CODES = [
+        [0x00, 'Success', %i[connack puback pubrec pubrel pubcomp unsuback auth]],
+        [0x00, 'Normal disconnection', %i[disconnect]],
+        [0x00, 'Granted QoS 0', %i[suback]],
+        [0x01, 'Granted QoS 1', %i[suback]],
+        [0x02, 'Granted QoS 2', %i[suback]],
+        [0x04, 'Disconnect with Will Message', %i[disconnect]],
+        [0x10, 'No matching subscribers', %i[puback pubrec]],
+        [0x11, 'No subscription existed', %i[unsuback]],
+        [0x18, 'Continue authentication', %i[auth]],
+        [0x19, 'Re-authenticate', %i[auth]],
+        [0x80, 'Unspecified error', %i[connack puback pubrec suback unsuback disconnect], true],
+        [0x81, 'Malformed Packet', %i[connack disconnect]],
+        [0x82, 'Protocol Error', %i[connack disconnect]],
+        [0x83, 'Implementation specific error', %i[connack puback pubrec suback unsuback disconnect], true],
+        [0x84, 'Unsupported Protocol Version', %i[connack]],
+        [0x85, 'Client Identifier not valid', %i[connack]],
+        [0x86, 'Bad User Name or Password', %i[connack]],
+        [0x87, 'Not authorized', %i[connack puback pubrec suback unsuback disconnect]],
+        [0x88, 'Server unavailable', %i[connack], true],
+        [0x89, 'Server busy', %i[connack disconnect], true],
+        [0x8A, 'Banned', %i[connack]],
+        [0x8B, 'Server shutting down', %i[disconnect], true],
+        [0x8C, 'Bad authentication method', %i[connack disconnect]],
+        [0x8D, 'Keep alive timeout', %i[disconnect], true],
+        [0x8E, 'Session taken over', %i[disconnect]],
+        [0x8F, 'Topic Filter invalid', %i[suback unsuback disconnect]],
+        [0x90, 'Topic Name invalid', %i[connack puback pubrec disconnect]],
+        [0x91, 'Packet Identifier in use', %i[puback pubrec suback unsuback]],
+        [0x92, 'Packet Identifier not found', %i[pubrel pubcomp]],
+        [0x93, 'Receive Maximum exceeded', %i[disconnect], true],
+        [0x94, 'Topic Alias invalid', %i[disconnect]],
+        [0x95, 'Packet too large', %i[connack disconnect]],
+        [0x96, 'Message rate too high', %i[disconnect], true],
+        [0x97, 'Quota exceeded', %i[connack puback pubrec suback disconnect]],
+        [0x98, 'Administrative action', %i[disconnect]],
+        [0x99, 'Payload format invalid', %i[connack puback pubrec disconnect]],
+        [0x9A, 'Retain not supported', %i[connack disconnect]],
+        [0x9B, 'QoS not supported', %i[connack disconnect]],
+        [0x9C, 'Use another server', %i[connack disconnect]],
+        [0x9E, 'Shared Subscriptions not supported', %i[suback disconnect]],
+        [0x9F, 'Connection rate exceeded', %i[connack disconnect], true],
+        [0xA0, 'Maximum connect time', %i[disconnect]],
+        [0xA1, 'Subscription Identifiers not supported', %i[suback disconnect]],
+        [0xA2, 'Wildcard Subscriptions not supported', %i[suback disconnect]]
+      ].freeze.tap { |codes| codes.each { |code| ReasonCode.register(*code) } }
+
+      # rubocop:disable Style/MutableConstant
+      PACKET_TYPES = {}
+      # rubocop:enable Style/MutableConstant
+
+      # Additional class methods for the packet
+      module Definition
+        def reason_code
+          include ReasonCodeAck
+
+          { type: :int8, default: 0x00 }
+        end
+
+        def reason_codes
+          include ReasonCodeListAck
+
+          list(:int8)
+        end
+      end
+
+      extend MQTT::Core::Packet::ModuleMethods
+
+      def self.included(mod)
+        mod.include(MQTT::Core::Packet)
+        mod.extend(Definition)
+      end
+    end
+  end
+end

data/lib/mqtt/v5/packets.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# MQTT 5.0
+module MQTT
+  # MQTT 5.0 protocol implementation
+  module V5
+    require_relative 'packet/connect'
+    require_relative 'packet/connack'
+    require_relative 'packet/disconnect'
+    require_relative 'packet/ping_req'
+    require_relative 'packet/ping_resp'
+    require_relative 'packet/publish'
+    require_relative 'packet/pub_ack'
+    require_relative 'packet/pub_rec'
+    require_relative 'packet/pub_rel'
+    require_relative 'packet/pub_comp'
+    require_relative 'packet/subscribe'
+    require_relative 'packet/sub_ack'
+    require_relative 'packet/unsubscribe'
+    require_relative 'packet/unsub_ack'
+    require_relative 'packet/auth'
+
+    MQTT::V5::Packet::PACKET_TYPES.freeze
+  end
+end

data/lib/mqtt/v5/topic_alias/cache.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module MQTT
+  module V5
+    module TopicAlias
+      # Bidirectional topic<->alias storage
+      # @!visibility private
+      class Cache
+        # @!visibility private
+        attr_reader :max_assigned
+
+        # @return [Integer] maximum number of topic aliases this cache can hold
+        attr_reader :max
+
+        # @return [Integer] the total size of topic_names held in this cache
+        attr_reader :cached_bytes
+
+        def self.create(max)
+          max&.positive? ? new(max: max) : nil
+        end
+
+        def initialize(max:)
+          @max = max
+          @aliases = {} # String keys: topic => alias, Integer keys: alias => topic
+          @max_assigned = 0
+          @cached_bytes = 0
+          @available = []
+        end
+
+        # Resolve topic to alias or alias to topic
+        # @param topic_or_alias [String, Integer]
+        # @return [Integer, String, nil]
+        def resolve(topic_or_alias)
+          @aliases[topic_or_alias]
+        end
+
+        # @!visibility private
+        def assign
+          return false if full?
+
+          @available.pop || (@max_assigned += 1)
+        end
+
+        # @return [Boolean] true if there are {#max} entries in the map
+        def full?
+          @available.empty? && max_assigned >= max
+        end
+
+        # @return [Integer] number of entries in the map
+        def size
+          @max_assigned - @available.size
+        end
+
+        # @!visibility private
+        # Add bidirectional mapping
+        # @param alias_id [Integer]
+        # @param topic [String]
+        def add(alias_id, topic)
+          raise ProtocolError, "AliasId (#{alias_id}) must be between 1 and #{max}" unless alias_id.between?(1, max)
+
+          @max_assigned = alias_id if alias_id > @max_assigned
+          @cached_bytes += topic.bytesize - (@aliases[alias_id]&.bytesize || 0)
+          @aliases[alias_id] = topic
+          @aliases[topic] = alias_id
+        end
+
+        # @!visibility private
+        # Explicitly Remove a topic (a previously aliased topic later explicitly set to use alias false)
+        # @param topic [String]
+        # rubocop:disable Naming/PredicateMethod
+        def remove(topic)
+          alias_id = @aliases.delete(topic)
+          return false unless alias_id
+
+          @available.push(alias_id)
+          @cached_bytes -= @aliases.delete(alias_id)&.bytesize || 0
+          true
+        end
+        # rubocop:enable Naming/PredicateMethod
+
+        def topics
+          @aliases.keys.select { |k| k.is_a?(String) }
+        end
+      end
+    end
+  end
+end