mqtt-core 0.0.1.ci.release

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module MQTT
+  module Core
+    module Packet
+      # Common processing of CONNECT packets between MQTT versions
+      module Connect
+        # @!visibility private
+        def apply_overrides(data)
+          super
+          data[:connect_flags] ||= {}
+          data[:connect_flags][:will_flag] = !(will_topic || '').empty?
+          data[:connect_flags][:username_flag] = !username.nil?
+          data[:connect_flags][:password_flag] = !password.nil?
+        end
+
+        # @!visibility private
+        def validate
+          will_flag ? validate_will_set : validate_will_not_set
+        end
+
+        # @!visibility private
+        def validate_will_set
+          raise ArgumentError, 'Will (flag:true) topic must be set' if (will_topic || '').empty?
+          raise ArgumentError, 'Will (flag:true) topic must not contain wildcards' if will_topic.match?(/[#+]/)
+          raise ArgumentError, 'Will (flag:true) QoS must be 0, 1, or 2' unless (0..2).include?(will_qos)
+        end
+
+        # @!visibility private
+        def validate_will_not_set
+          raise ArgumentError, 'Will (flag:false) topic must not be set' unless (will_topic || '').empty?
+          raise ArgumentError, 'Will (flag:false) payload must not be set' unless (will_payload || '').empty?
+          raise ArgumentError, 'Will (flag:false) QoS must be 0' unless (will_qos || 0).zero?
+          raise ArgumentError, 'Will (flag:false) retain must be false' if will_retain
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module MQTT
+  module Core
+    module Packet
+      # Common processing of PUBLISH packets between MQTT versions
+      module Publish
+        # Deconstruct message for subscription enumeration
+        # @yield [topic, payload, attributes] optional block to yield deconstructed values
+        # @return [Array<String, String, Hash>] topic, payload, attributes when no block given
+        # @return [Object] block result when block given
+        def deconstruct_message(&)
+          block_given? ? yield(topic, payload, **to_h) : [topic, payload, to_h]
+        end
+
+        def to_s
+          "#{super}(#{topic})"
+        end
+
+        # @!visibility private
+        def success!(ack)
+          return true if qos.zero?
+
+          ack&.success! || raise(ProtocolError, 'No ACK')
+        end
+
+        # @!visibility private
+        def topic_alias
+          nil
+        end
+
+        # @!visibility private
+        def validate
+          raise ArgumentError, 'QoS must be 0, 1, or 2' unless (0..2).include?(qos)
+          raise ArgumentError, 'Topic name cannot be empty' if !topic_alias && topic_name.to_s.empty?
+          raise ArgumentError, 'Topic name cannot contain wildcards' if topic_name.to_s.match?(/[#+]/)
+
+          return unless qos.zero? && (packet_identifier || 0).positive?
+
+          raise MQTT::ProtocolError, 'Must not have packet id for QOS 0'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module MQTT
+  module Core
+    module Packet
+      # Common processing of SUBSCRIBE packets between MQTT versions
+      module Subscribe
+        # @!attribute [r] ignore_qos_limited
+        #   @return [Boolean] treat qos_limited topic_filters as successful - default (true)
+
+        # @!attribute [r] ignore_failed
+        #   @return [Boolean] treat failed topic_filters as successful - default (false)
+
+        def defaults
+          {
+            ignore_failed: false,
+            ignore_qos_limited: false
+          }
+        end
+
+        def apply_data(data)
+          @ignore_failed = data.delete(:ignore_failed) if data.include?(:ignore_failed)
+          @ignore_qos_limited = data.delete(:ignore_qos_limited) if data.include?(:ignore_qos_limited)
+
+          if data.include?(:topic_filters)
+            map_topic_filters(data[:topic_filters], data.delete(:max_qos) || data.delete(:requested_qos) || 0)
+          end
+
+          super
+        end
+
+        # @!visibility private
+        def validate
+          return unless topic_filters
+
+          raise ArgumentError, 'Must contain at least one topic filter' if topic_filters.empty?
+
+          topic_filters.each do |tf|
+            filter = case tf
+                     when String then tf
+                     when Hash then tf[:topic_filter]
+                     else tf.topic_filter
+                     end
+            raise ArgumentError, 'Topic filter cannot be empty' if filter.to_s.empty?
+          end
+        end
+
+        def apply_overrides(data)
+          super
+          topic_filters = data.fetch(:topic_filters, [])
+          @wildcard_topics, @fully_qualified_topics = topic_filters.map(&:topic_filter).partition do |t|
+            contains_wildcard?(t)
+          end
+          @max_qos = topic_filters.map(&:max_qos).max
+        end
+
+        attr_reader :fully_qualified_topics, :wildcard_topics, :max_qos
+
+        def match?(publish_packet)
+          match_topic?(publish_packet.topic_name)
+        end
+
+        def ===(other)
+          case other
+          when Packet
+            match?(other)
+          when String
+            match_topic?(other)
+          else
+            false
+          end
+        end
+
+        def match_topic?(topic_name)
+          match_fully_qualified_topic?(topic_name) || match_wildcard_topic?(topic_name)
+        end
+
+        def match_fully_qualified_topic?(topic_name)
+          fully_qualified_topics.include?(topic_name)
+        end
+
+        def match_wildcard_topic?(topic_name)
+          wildcard_topics.any? { |wt| wc_match?(topic_name, wt) }
+        end
+
+        def contains_wildcard?(topic)
+          topic =~ /[#+]/
+        end
+
+        def wc_match?(topic, wc_topic)
+          wc_parts = wc_topic.split('/')
+          topic_parts = topic.split('/')
+
+          wc_parts.zip(topic_parts).all? do |(wc, t)|
+            return true if wc == '#'
+            return false if t.nil?
+
+            wc == '+' || t == wc
+          end && (wc_parts.last == '#' || topic_parts.size == wc_parts.size)
+        end
+
+        # Map filter expressions to suback status
+        #
+        #   * :`success` - subscription successful with requested QOS
+        #   * :`qos_limited` - subscription accepted but acknowledged QOS is less than the requested QOS
+        #   * :`failed` - subscription failed
+        # @param [Packet] suback the SUBACK packet
+        # @return [Hash<String,Symbol>] map of topic filter to status
+        def filter_status(suback)
+          topic_filters.zip(suback.return_codes).to_h { |tf, rc| [tf.topic_filter, classify(tf, rc)] }
+        end
+
+        # Version dependent partition topic_filters into success and failures
+        #
+        # Attributes {#ignore_qos_limited} 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(suback)
+          filter_status(suback).partition { |(_tf, ack_status)| ack_success?(ack_status) }.map(&:to_h)
+        end
+
+        def success!(suback)
+          success, failed = partition_success(suback)
+
+          raise SubscribeError, failed unless failed.empty?
+
+          success
+        end
+
+        # @return [Array<TopicFilter>]
+        def subscribed_topic_filter_requests(suback = nil)
+          return topic_filters unless suback
+
+          topic_filters.zip(suback.return_codes).filter_map { |tf, rc| tf unless failed?(rc) }
+        end
+
+        alias resubscribe_topic_filters subscribed_topic_filter_requests
+        alias unsubscribe_topic_filters subscribed_topic_filter_requests
+
+        # @return [Array<String>]
+        def subscribed_topic_filters(suback = nil)
+          subscribed_topic_filter_requests(suback).map(&:topic_filter)
+        end
+
+        def unsubscribe_params(suback = nil)
+          { topic_filters: subscribed_topic_filters(suback) }
+        end
+
+        private
+
+        def map_topic_filters(topic_filters, max_qos)
+          topic_filters.map! do |tf|
+            (tf.is_a?(String) ? { topic_filter: tf } : tf).tap do |tf_hash|
+              raise ArgumentError, 'topic filter must be a String or Hash<Symbol>' unless tf_hash.is_a?(Hash)
+
+              tf_hash[self.class::MAX_QOS_FIELD] = max_qos
+            end
+          end
+        end
+
+        def failed?(return_code)
+          return_code >= 0x80
+        end
+
+        def ack_success?(ack_status)
+          case ack_status
+          when :success
+            true
+          when :qos_limited
+            @ignore_qos_limited
+          when :failed
+            @ignore_failed
+          else
+            false
+          end
+        end
+
+        def classify(topic_filter, return_code)
+          if failed?(return_code)
+            :failed
+          elsif return_code < topic_filter.requested_qos
+            :qos_limited
+          else
+            :success
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module MQTT
+  module Core
+    module Packet
+      # Common processing of UNSUBSCRIBE packets between MQTT versions
+      module Unsubscribe
+        # @!visibility private
+        def validate
+          return unless topic_filters
+
+          raise ArgumentError, 'Must contain at least one topic filter' if topic_filters.empty?
+
+          topic_filters.each do |tf|
+            raise ArgumentError, 'Topic filter cannot be empty' if tf.to_s.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mqtt/core/packet.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'mqtt/core/packet'
+require_relative '../errors'
+require_relative 'type/shape'
+require_relative 'type/sub_type'
+require_relative 'type/utf8_string'
+require_relative 'type/utf8_string_pair'
+require_relative 'type/binary'
+require_relative 'type/fixed_int'
+require_relative 'type/var_int'
+require_relative 'type/boolean_byte'
+require_relative 'type/remaining'
+require_relative 'type/properties'
+require_relative 'type/bit_flags'
+require_relative 'type/reason_codes'
+require_relative 'type/list'
+require 'stringio'
+
+module MQTT
+  module Core
+    # Version agnostic packet structure
+    module Packet
+      # Class Methods for defining packet structures (and substructures)
+      module Definition
+        include Type::Shape::Definition
+
+        attr_reader :fixed_fields, :variable_fields, :payload_fields, :packet_type
+
+        # Flags in the fixed header
+        def fixed(packet_type, *flags)
+          self::PACKET_TYPES[packet_type] = self
+          self::PACKET_TYPES[packet_name] = self
+          flags = [[:reserved, 4]] if flags.empty?
+          flags.unshift([:packet_type, 4])
+          @packet_type = packet_type
+          @packet_name = packet_name
+          fields = { fixed_flags: Type::BitFlags.new(*flags) }
+          @fixed_fields = resolve_fields(fields).tap { |resolved| define_field_methods(resolved) }
+          @variable_fields = []
+          @payload_fields = []
+        end
+
+        def packet_name
+          name.split('::').last.downcase.to_sym
+        end
+
+        # Fields in the variable header
+        def variable(**fields)
+          @variable_fields = resolve_fields(fields).tap { |resolved| define_field_methods(resolved) }
+        end
+
+        # Payload structure
+        def payload(**fields)
+          @payload_fields =  resolve_fields(fields).tap { |resolved| define_field_methods(resolved) }
+        end
+
+        def properties(packet_name = self.packet_name)
+          Type::Properties.new(packet_name, self::PROPERTY_TYPES)
+        end
+
+        # for Shape#apply_data
+        def fields
+          @fixed_fields + @variable_fields + @payload_fields
+        end
+      end
+
+      # Methods to be extended into specific version module methods
+      module ModuleMethods
+        def deserialize(io)
+          return nil unless (header_byte = io.getbyte)
+
+          packet(header_byte >> 4).new(header_byte, io)
+        end
+
+        def packet(packet_name)
+          self::PACKET_TYPES.fetch(packet_name) { raise ProtocolError, "Unknown packet id or name #{packet_name}" }
+        end
+
+        def build_packet(packet_name, **packet_data)
+          packet(packet_name).new(**packet_data)
+        end
+      end
+
+      def self.included(mod)
+        mod.extend Definition
+      end
+
+      include Type::Shape
+
+      def apply_overrides(data)
+        data[:fixed_flags] ||= {}
+        data[:fixed_flags][:packet_type] = self.class.packet_type
+        super
+      end
+
+      def packet_type
+        self.class.packet_type
+      end
+
+      def packet_name
+        self.class.packet_name
+      end
+
+      def id
+        return nil if packet_identifier&.zero?
+
+        packet_identifier
+      end
+
+      def to_s
+        @to_s ||=
+          begin
+            parts = [self.class.name]
+            parts << "(#{id})" if respond_to?(:packet_identifier) && id
+            parts.join
+          end
+      end
+
+      def serialize(io)
+        serialize_fields(self.class.fixed_fields, io)
+
+        Packet.write_sio(io) do |sio|
+          serialize_fields(self.class.variable_fields, sio)
+          serialize_fields(self.class.payload_fields, sio)
+        end
+        # io.flush
+        self
+      end
+
+      def deserialize(header_byte, io)
+        @data.merge!(deserialize_fields(self.class.fixed_fields, header_byte))
+        Packet.read_sio(io) do |sio|
+          @data.merge!(deserialize_fields(self.class.variable_fields, sio))
+          @data.merge!(deserialize_fields(self.class.payload_fields, sio))
+        end
+      end
+
+      class << self
+        def read_sio(io, &)
+          length = Type::VarInt.read(io)
+          return unless length
+          raise ProtocolError, "Cannot read negative length #{length}" if length.negative?
+          return if length.zero?
+
+          StringIO.new.binmode
+                  .tap { |sio| length -= IO.copy_stream(io, sio, length) while length.positive? }
+                  .tap(&:rewind)
+                  .tap(&)
+        rescue EOFError
+          raise ProtocolError, "Packet length #{length} exceeds available data"
+        end
+
+        def write_sio(io, &)
+          StringIO.new.binmode.tap(&).tap(&:rewind).tap do |sio|
+            Type::VarInt.write(sio.size, io)
+            IO.copy_stream(sio, io)
+          end
+        end
+
+        # debugging/testing do not log
+        def hex(payload)
+          payload.bytes.map { |byte| format('%02x', byte) }.join(' ')
+        end
+      end
+    end
+  end
+end

data/lib/mqtt/core/type/binary.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module MQTT
+  module Core
+    module Type
+      # Binary data
+      # converts to String with binary encoding
+      module Binary
+        module_function
+
+        # return [String with binary encoding]
+        def read(io)
+          size = io.read(2)&.unpack1('S>')
+          io.read(size)
+        end
+
+        def write(value, io)
+          value ||= default_value
+          io.write([value.size, value].pack('S>A*'))
+        end
+
+        # @return [String(binary)]
+        def from(value, **)
+          return nil if value.nil?
+
+          value.to_s.b
+        end
+
+        def default_value
+          @default_value ||= ''.b.freeze
+        end
+      end
+    end
+  end
+end

data/lib/mqtt/core/type/bit_flags.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative '../../errors'
+require_relative 'fixed_int'
+
+module MQTT
+  module Core
+    module Type
+      # Booleans and small integers encoded in a single byte
+      class BitFlags
+        def initialize(*flags)
+          @flags = flags.map { |f| f.is_a?(Array) ? f : [f, 1] }
+          raise ProtocolError, 'Total bits must be 8' unless @flags.sum { |(_, bitsize)| bitsize } == 8
+        end
+
+        attr_reader :flags
+
+        def sub_properties
+          @sub_properties ||=
+            @flags.filter_map do |(name, bitsize, *)|
+              [name, bitsize == 1 ? BooleanByte : Int8] unless name == :reserved
+            end.to_h
+        end
+
+        # rubocop:disable Metrics/AbcSize
+
+        # @param [Integer,IO] io can be a previously readbyte or an IO to read the byte from
+        # @return [Hash<Symbol, Integer|Boolean>]
+        def read(io)
+          flags_byte = io.is_a?(Integer) ? io : Int8.read(io)
+
+          flags.reverse.filter_map do |(flag, bitsize, reserved)|
+            mask = (1 << bitsize) - 1
+            flag_value = (flags_byte & mask)
+            raise ProtocolError if flag == :reserved && flag_value != (reserved || 0)
+
+            # If bitsize is one, flag is a Boolean,  otherwise leave as Integer
+            flag_value = (flag_value == 1) if bitsize == 1
+            flags_byte >>= bitsize
+            [flag, flag_value] unless flag == :reserved
+          end.to_h
+        end
+
+        def from(input_value)
+          input_value ||= 0
+          input_value = read(input_value) if input_value.is_a?(Integer)
+
+          flags.each do |(flag_name, bitsize)|
+            next if flag_name == :reserved
+
+            # convert to int and validate
+            input_value[flag_name] = to_int(input_value[flag_name], bitsize, exception_class: ArgumentError)
+            # convert to boolean if bitsize is 1
+            input_value[flag_name] = (input_value[flag_name] == 1) if bitsize == 1
+          end
+
+          # Reject unknown flags
+          invalid = input_value.keys.reject { |k| sub_properties.include?(k) }
+
+          return input_value if invalid.empty?
+
+          raise ArgumentError, "Unknown bitflags #{invalid}, expected only #{sub_properties}"
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        def write(values, io)
+          output_byte = 0
+          flags.each do |(property_name, bitsize, reserved)|
+            output_byte <<= bitsize
+            output_byte += to_int(values.fetch(property_name, reserved || 0), bitsize, exception_class: ProtocolError)
+          end
+          Int8.write(output_byte, io)
+        end
+
+        def to_int(value, bitsize, exception_class:)
+          if value.is_a?(Integer)
+            return value if value.between?(0, (1 << bitsize) - 1)
+
+            raise exception_class, "Invalid bitflag value #{value} for bitsize #{bitsize}"
+          elsif bitsize == 1
+            value ? 1 : 0
+          else
+            raise exception_class, "Invalid bitflag value #{value}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mqtt/core/type/boolean_byte.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module MQTT
+  module Core
+    module Type
+      # If we are reading or writing a boolean byte then it will exist
+      # but if it does not exist then it is assumed to be true
+      module BooleanByte
+        module_function
+
+        # rubocop:disable Naming/PredicateMethod
+        def read(io)
+          int_value = Int8.read(io)
+          raise ProtocolError, 'Value must be 0 or 1' unless int_value.between?(0, 1)
+
+          !int_value.zero?
+        end
+        # rubocop:enable Naming/PredicateMethod
+
+        def write(value, io)
+          value = 1 if value.nil?
+          value = value ? 1 : 0 unless value.is_a?(Integer)
+          raise ProtocolError, 'Value must be 0 or 1' unless value.between?(0, 1)
+
+          io.write([value].pack('C'))
+        end
+
+        # param [Integer,Object, nil] value
+        #   for integers anything non-zero is considered true
+        #   everything else uses ruby truthiness
+        #   nil is considered true
+        # @return [Boolean]
+        def from(value, **)
+          return nil if value.nil?
+          return !value.zero? if value.is_a?(Integer)
+
+          !!value
+        end
+
+        # rubocop:disable Naming/PredicateMethod
+        def default_value
+          false
+        end
+        # rubocop:enable Naming/PredicateMethod
+      end
+    end
+  end
+end

data/lib/mqtt/core/type/fixed_int.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module MQTT
+  module Core
+    module Type
+      # unsigned integers of fixed bit size
+      class FixedInt
+        def initialize(bitsize, pack)
+          @bitsize = bitsize
+          @pack = pack
+        end
+
+        def read(io)
+          io.read(@bitsize / 8)&.unpack1(@pack)
+        end
+
+        def from(value, **)
+          return value.to_i if value.respond_to?(:to_i)
+
+          value ? 1 : 0
+        end
+
+        def write(value, io)
+          value = from(value)
+          raise ProtocolError, "Value '#{value}' out of range" unless value.between?(0, (2**@bitsize) - 1)
+
+          io.write([value].pack(@pack))
+        end
+
+        def default_value
+          0
+        end
+      end
+
+      # 8 bit unsigned integer
+      Int8 = FixedInt.new(8, 'C')
+      # 16 bit unsigned integer
+      Int16 = FixedInt.new(16, 'S>')
+      # 32 bit unsigned integer
+      Int32 = FixedInt.new(32, 'L>')
+    end
+  end
+end