mqtt-v5 0.0.1.ci.release

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+require_relative '../version'
+require 'mqtt/core/packet/connect'
+
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 CONNECT packet
+      #
+      # Sent by client to establish connection with the broker.
+      #
+      # @see Core::Client#connect
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901033 MQTT 5.0 Spec §3.1
+      class Connect
+        include Packet
+        include Core::Packet::Connect
+
+        # Avoid name clashes between sub-properties
+        def self.sub_property_method(name, property_name)
+          case name
+          when :will_properties
+            return :will_user_properties if property_name == :user_properties
+          end
+          property_name
+        end
+
+        fixed(1)
+
+        # @!attribute [r] protocol_name
+        #   @return [String<UTF8>] protocol name (managed automatically)
+        # @!attribute [r] protocol_version
+        #   @return [Integer] protocol version (managed automatically)
+        # @!attribute [r] clean_start
+        #   @return [Boolean] if true server will abandon any stored session (managed automatically from session store)
+        # @!attribute [r] will_qos
+        #   @return [Integer] QoS level for the Will message: 0, 1, or 2 (default 0)
+        # @!attribute [r] will_retain
+        #   @return [Boolean] should the Will message be retained (default false)
+        # @!attribute [r] keep_alive
+        #   @return [Integer] maximum duration in seconds between packets sent by the client (default 60)
+
+        # @!group Properties
+
+        # @!attribute [r] session_expiry_interval
+        #   @return [Integer] session expiry interval in seconds (managed automatically from session store)
+        # @!attribute [r] receive_maximum
+        #   @return [Integer] maximum number of QoS 1 and 2 messages the client will process concurrently
+        # @!attribute [r] maximum_packet_size
+        #   @return [Integer] maximum packet size the client is willing to accept
+        # @!attribute [r] topic_alias_maximum
+        #   @return [Integer] maximum topic alias value the client accepts
+        # @!attribute [r] request_response_information
+        #   @return [Boolean] whether the client requests response information
+        # @!attribute [r] request_problem_information
+        #   @return [Boolean] whether the client requests problem information
+        # @!attribute [r] user_properties
+        #   @return [Array<String, String>] user-defined properties as key-value pairs
+        # @!attribute [r] authentication_method
+        #   @return [String<UTF8>] authentication method name
+        # @!attribute [r] authentication_data
+        #   @return [String<Binary>] authentication data
+
+        # @!endgroup
+
+        # @!attribute [r] client_id
+        #   @return [String<UTF8>] client identifier string (managed from session store, default '')
+        # @!attribute [r] will_topic
+        #   @return [String<UTF8>] topic name to send the Will message to
+        # @!attribute [r] will_payload
+        #   @return [String<Binary>] payload of the Will message
+        # @!attribute [r] will_properties
+        #   @return [Hash<Symbol>] properties for the Will message
+        # @!attribute [r] username
+        #   @return [String<UTF8>] username for authenticating with the server
+        # @!attribute [r] password
+        #   @return [String<Binary>] password for authenticating with the server
+
+        variable(
+          protocol_name: :utf8string,
+          protocol_version: :int8,
+          connect_flags: flags(
+            :username_flag, :password_flag,
+            :will_retain,
+            [:will_qos, 2],
+            :will_flag,
+            :clean_start,
+            :reserved
+          ),
+          keep_alive: :int16,
+          properties: properties(:connect)
+        )
+
+        payload(
+          client_id: :utf8string,
+          will_properties: { type: properties(:will), if: :will_flag },
+          will_topic: { type: :utf8string, if: :will_flag },
+          will_payload: { type: :binary, if:  :will_flag },
+          username: { type: :utf8string, if:  :username },
+          password: { type: :binary, if: :password }
+        )
+
+        alias clean_requested? clean_start
+        alias username? :username_flag
+        alias password? :password_flag
+        alias will_flag? :will_flag
+
+        # @!visibility private
+        def defaults
+          super.merge!(client_id: '', keep_alive: 60, will_retain: false, will_qos: 0, clean_start: false)
+        end
+
+        # @!visibility private
+        def apply_overrides(data)
+          super
+          data.merge!(
+            protocol_name: 'MQTT',
+            protocol_version: PROTOCOL_VERSION
+          )
+        end
+
+        # @!visibility private
+        def success!(connack)
+          connack.success!
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 DISCONNECT packet
+      #
+      # Sent by client to gracefully disconnect, or received from broker to indicate disconnection.
+      #
+      # @see Core::Client#disconnect
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901205 MQTT 5.0 Spec §3.14
+      class Disconnect
+        include Packet
+
+        fixed(14)
+
+        # @!parse include ReasonCodeAck
+        # @!attribute [r] reason_code
+        #   disconnection reason
+        #
+        #   ✅ Success:
+        #
+        #   - `0x00` Normal disconnection
+        #   - `0x04` Disconnect with Will Message
+        #
+        #   ❌ Error:
+        #
+        #   - `0x80` Unspecified error
+        #   - `0x81` Malformed Packet
+        #   - `0x82` Protocol Error
+        #   - `0x83` Implementation specific error
+        #   - `0x87` Not authorized
+        #   - `0x89` Server busy
+        #   - `0x8B` Server shutting down
+        #   - `0x8C` Bad authentication method
+        #   - `0x8D` Keep alive timeout
+        #   - `0x8E` Session taken over
+        #   - `0x8F` Topic Filter invalid
+        #   - `0x90` Topic Name invalid
+        #   - `0x93` Receive Maximum exceeded
+        #   - `0x94` Topic Alias invalid
+        #   - `0x95` Packet too large
+        #   - `0x96` Message rate too high
+        #   - `0x97` Quota exceeded
+        #   - `0x98` Administrative action
+        #   - `0x99` Payload format invalid
+        #   - `0x9A` Retain not supported
+        #   - `0x9B` QoS not supported
+        #   - `0x9C` Use another server
+        #   - `0x9E` Shared Subscriptions not supported
+        #   - `0x9F` Connection rate exceeded
+        #   - `0xA0` Maximum connect time
+        #   - `0xA1` Subscription Identifiers not supported
+        #   - `0xA2` Wildcard Subscriptions not supported
+        #
+        #   @return [ReasonCode]
+
+        # @!group Properties
+
+        # @!attribute [r] session_expiry_interval
+        #   @return [Integer] session expiry interval in seconds
+        # @!attribute [r] reason_string
+        #   @return [String<UTF8>] human-readable reason for disconnection
+        # @!attribute [r] user_properties
+        #   @return [Array<String, String>] user-defined properties as key-value pairs
+        # @!attribute [r] server_reference
+        #   @return [String<UTF8>] server reference for redirection
+
+        # @!endgroup
+
+        variable(
+          reason_code:, # automatically includes ReasonCodeAck
+          properties:
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 PINGREQ packet
+      #
+      # Sent by client to keep the connection alive.
+      #
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901195 MQTT 5.0 Spec §3.12
+      class PingReq
+        include Packet
+
+        fixed(12)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 PINGRESP packet
+      #
+      # Sent by broker in response to a PINGREQ packet.
+      #
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901200 MQTT 5.0 Spec §3.13
+      class PingResp
+        include Packet
+
+        fixed(13)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 PUBACK packet
+      #
+      # QoS 1 acknowledgement sent by broker in response to a PUBLISH packet.
+      #
+      # @see Core::Client#publish
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901121 MQTT 5.0 Spec §3.4
+      class PubAck
+        include Packet
+
+        fixed(4)
+
+        # @!attribute [r] packet_identifier
+        #   @return [Integer] packet identifier matching the PUBLISH packet (receive only)
+
+        # @!parse include ReasonCodeAck
+        # @!attribute [r] reason_code
+        #   acknowledgement status
+        #
+        #   ✅ Success:
+        #
+        #   - `0x00` Success
+        #   - `0x10` No matching subscribers
+        #
+        #   ❌ Error:
+        #
+        #   - `0x80` Unspecified error
+        #   - `0x83` Implementation specific error
+        #   - `0x87` Not authorized
+        #   - `0x90` Topic Name invalid
+        #   - `0x91` Packet Identifier in use
+        #   - `0x97` Quota exceeded
+        #   - `0x99` Payload format invalid
+        #
+        #   @return [ReasonCode]
+
+        # @!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
+
+        variable(
+          packet_identifier: :int16,
+          reason_code:, # automatically includes ReasonCodeAck
+          properties:
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 PUBCOMP packet
+      #
+      # QoS 2 publish complete (part 3) sent by broker in response to a PUBREL packet.
+      #
+      # @see Core::Client#publish
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901151 MQTT 5.0 Spec §3.7
+      class PubComp
+        include Packet
+
+        fixed(7)
+
+        # @!attribute [r] packet_identifier
+        #   @return [Integer] packet identifier matching the PUBREL packet (receive only)
+
+        # @!parse include ReasonCodeAck
+        # @!attribute [r] reason_code
+        #   acknowledgement status
+        #
+        #   ✅ Success:
+        #
+        #   - `0x00` Success
+        #
+        #   ❌ Error:
+        #
+        #   - `0x92` Packet Identifier not found
+        #
+        #   @return [ReasonCode]
+
+        # @!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
+
+        variable(
+          packet_identifier: :int16,
+          reason_code:, # automatically includes ReasonCodeAck
+          properties:
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 PUBREC packet
+      #
+      # QoS 2 acknowledgement (part 1) sent by broker in response to a PUBLISH packet.
+      #
+      # @see Core::Client#publish
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901131 MQTT 5.0 Spec §3.5
+      class PubRec
+        include Packet
+
+        fixed(5)
+
+        # @!attribute [r] packet_identifier
+        #   @return [Integer] packet identifier matching the PUBLISH packet (receive only)
+
+        # @!parse include ReasonCodeAck
+        # @!attribute [r] reason_code
+        #   acknowledgement status
+        #
+        #   ✅ Success:
+        #
+        #   - `0x00` Success
+        #   - `0x10` No matching subscribers
+        #
+        #   ❌ Error:
+        #
+        #   - `0x80` Unspecified error
+        #   - `0x83` Implementation specific error
+        #   - `0x87` Not authorized
+        #   - `0x90` Topic Name invalid
+        #   - `0x91` Packet Identifier in use
+        #   - `0x97` Quota exceeded
+        #   - `0x99` Payload format invalid
+        #
+        #   @return [ReasonCode]
+
+        # @!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
+
+        variable(
+          packet_identifier: :int16,
+          reason_code:, # automatically includes ReasonCodeAck
+          properties:
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 PUBREL packet
+      #
+      # QoS 2 publish release (part 2) sent by client in response to a PUBREC packet.
+      #
+      # @see Core::Client#publish
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901141 MQTT 5.0 Spec §3.6
+      class PubRel
+        include Packet
+
+        fixed(6, [:reserved, 4, 0b0010])
+
+        # @!attribute [r] packet_identifier
+        #   @return [Integer] packet identifier matching the PUBREC packet (receive only)
+
+        # @!parse include ReasonCodeAck
+        # @!attribute [r] reason_code
+        #   acknowledgement status
+        #
+        #   ✅ Success:
+        #
+        #   - `0x00` Success
+        #
+        #   ❌ Error:
+        #
+        #   - `0x92` Packet Identifier not found
+        #
+        #   @return [ReasonCode]
+
+        # @!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
+
+        variable(
+          packet_identifier: :int16,
+          reason_code:, # automatically includes ReasonCodeAck
+          properties:
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative '../packet'
+require 'mqtt/core/packet/publish'
+
+module MQTT
+  module V5
+    module Packet
+      # MQTT 5.0 PUBLISH packet
+      #
+      # Sent by client to publish a message to the broker, or received from broker when subscribed to a topic.
+      #
+      # @see Client#publish
+      # @see https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901100 MQTT 5.0 Spec §3.3
+      class Publish
+        include Packet
+        include Core::Packet::Publish
+
+        # @!attribute [r] dup
+        #   @return [Boolean] duplicate delivery flag (managed automatically by session)
+        # @!attribute [r] qos
+        #   @return [Integer] QoS level: 0, 1, or 2 (default 0)
+        # @!attribute [r] retain
+        #   @return [Boolean] should this message be retained by the broker (default false)
+        fixed(3, :dup, [:qos, 2], :retain)
+
+        # @!attribute [r] packet_identifier
+        #   @return [Integer] packet identifier for QoS 1/2 exchanges (managed automatically by session)
+
+        # @!group Properties
+
+        # @!attribute [r] payload_format_indicator
+        #   @return [Integer] 0 = unspecified, 1 = UTF-8 encoded payload (auto-detected from payload encoding)
+        # @!attribute [r] message_expiry_interval
+        #   @return [Integer] message expiry interval in seconds
+        # @!attribute [r] response_topic
+        #   @return [String<UTF8>] topic name for response messages
+        # @!attribute [r] correlation_data
+        #   @return [String<Binary>] correlation data for request/response
+        # @!attribute [r] user_properties
+        #   @return [Array<String, String>] user-defined properties as key-value pairs
+        # @!attribute [r] subscription_identifiers
+        #   @return [Array<Integer>] subscription identifiers (receive only, set by broker)
+        # @!attribute [r] content_type
+        #   @return [String<UTF8>] content type description
+
+        variable(
+          topic_name: :utf8string,
+          packet_identifier: { type: :int16, if: -> { qos.positive? } },
+          properties:
+        )
+
+        # @!visibility private
+        alias orig_topic_alias topic_alias
+
+        # @!attribute [r] topic_alias
+        # Managed automatically by {TopicAlias::Manager}. See {Client#publish}.
+        # @return [Integer|nil] the assigned topic alias id
+        def topic_alias
+          (@alias_info && @alias_info[:alias]) || orig_topic_alias
+        end
+
+        # @!endgroup
+
+        # @return [Boolean] whether {TopicAlias::Manager} will try to assign an outgoing {#topic_alias}
+        # @see Client#publish
+        def assign_alias?
+          @assign_alias
+        end
+
+        # @!visibility private
+        attr_reader :alias_info
+
+        # @!visibility private
+        alias orig_topic_name topic_name
+
+        # @!attribute [r] topic_name
+        # @return [String<UTF8>] topic name to publish to
+        def topic_name
+          (@alias_info && @alias_info[:name]) || orig_topic_name
+        end
+
+        alias topic topic_name
+
+        # @!attribute [r] payload
+        #   @return [String<Binary>] message payload
+        payload(payload: :remaining)
+
+        # @!visibility private
+        def apply_alias(alias: nil, name: nil)
+          @alias_info = { alias:, name: }
+        end
+
+        # @!visibility private
+        # Check if this packet matches a subscription identifier
+        # @param [Integer] sub_id subscription identifier to check
+        # @return [Boolean]
+        def match_subscription_identifier?(sub_id)
+          (subscription_identifiers || []).include?(sub_id)
+        end
+
+        # @!visibility private
+        def apply_data(data)
+          @assign_alias = data.delete(:assign_alias) if data.key?(:assign_alias)
+          super
+        end
+
+        # @!visibility private
+        def apply_overrides(data)
+          super
+          data[:payload_format_indicator] = 1 if payload&.encoding == Encoding::UTF_8
+        end
+
+        # @!visibility private
+        def validate
+          super
+          raise ArgumentError, 'Response topic cannot contain wildcards' if response_topic&.match?(/[#+]/)
+        end
+      end
+    end
+  end
+end