mqtt-v5 0.0.1.ci.release

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'weighted_policy'
+
+module MQTT
+  module V5
+    module TopicAlias
+      # Scores topics by `hits * bytesize. Tracks hit counts for all topics
+      class FrequencyWeightedPolicy
+        include WeightedPolicy
+
+        # The minimum topic size for a new topic to avoid O(n) scan of the topic list for each eviction
+        attr_reader :min_topic_score
+
+        def initialize
+          super
+          @hits = Hash.new(0)
+        end
+
+        # @!attribute [r] hits
+        # @return [Hash<String,Integer>] (frozen) topics by the number of times they have been published to.
+        def hits
+          @hits.dup.freeze
+        end
+
+        # Delete topics from the map (ie because they won't be used again) and recalculate the minimum topic score.
+        def clean!(*topics)
+          topics.each { |t| @hits.delete(t) }
+        end
+
+        # Evict the topic with the lowest score, unless the new_topic is even lower.
+        def evict(new_topic, &)
+          super.tap { |victim| @hits[new_topic] += 1 unless victim }
+        end
+
+        # Record a hit for topic, check if lower than minimum score.
+        def alias_hit(topic)
+          @hits[topic] += 1
+          super
+        end
+
+        private
+
+        def topic_score(topic, new: false)
+          (@hits[topic] + (new ? 1 : 0)) * topic.bytesize
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'weighted_policy'
+
+module MQTT
+  module V5
+    module TopicAlias
+      # Minimum length policy - only aliases topics above a minimum size, evicts shortest
+      class LengthWeightedPolicy
+        include WeightedPolicy
+
+        private
+
+        def topic_score(topic, **)
+          topic.bytesize
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module MQTT
+  module V5
+    module TopicAlias
+      # Least Recently Used replacement policy
+      class LRUPolicy
+        def initialize
+          @topics = Set.new
+        end
+
+        # Alias any topic
+        def aliasable?(_packet)
+          true
+        end
+
+        # Evict the first entry in the Set (ie the least recently used)
+        def evict(_topic, &)
+          @topics.first
+        end
+
+        # Move the topic to the end of the Set (ie make it the most recently used)
+        def alias_hit(topic)
+          # Move the topic to the end of the set (relies on Set being ordered)
+          @topics.delete(topic)
+          @topics << topic
+        end
+
+        # Delete the evicted topic from the Set
+        def alias_evicted(topic)
+          @topics.delete(topic)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative 'cache'
+require_relative 'lru_policy'
+
+module MQTT
+  module V5
+    module TopicAlias
+      # Manages topic aliases for a connection
+      class Manager
+        # maximum size of alias caches
+        MAXIMUM_ALIAS_ID = 65_535
+
+        # @return [Cache|nil] the incoming Cache
+        attr_reader :incoming
+
+        # @return [Cache|nil] the outgoing Cache
+        attr_reader :outgoing
+
+        # @return [Policy] the policy used to manage the outgoing Cache
+        attr_reader :policy
+
+        # Topic Alias Management
+        #
+        # Outgoing aliasing upper limit and replacement policy is configured by properties to {#initialize}
+        #
+        # For a Client...
+        #   - Outgoing limit is further restricted by the CONNACK response from the Server.
+        #   - Incoming limit is configured in the CONNECT packet. Records alias information as received from Server.
+        #
+        # For a Server...
+        #   - Outgoing limit is further restricted by the CONNECT packet received from the Client.
+        #   - Incoming limit is configured in the CONNACK packet. Records alias information as received from Client.
+        #
+        # @param [Integer|nil] send_maximum
+        #   maximum number of topic aliases to hold for outgoing PUBLISH packets
+        #
+        #  - `nil` will mean the value is determined only by the response from the other side
+        #  - `0` (default) disables outgoing aliasing regardless of what the other side will accept
+        #
+        # @param  [Policy|nil] policy replacement policy for evicting topics from the outgoing cache when
+        #     it is full.
+        #
+        #  - `nil` will use {LRUPolicy} as the default policy
+        #
+        # @return [Manager]
+        def initialize(send_maximum: 0, policy: nil)
+          @configured_outgoing_maximum = send_maximum || MAXIMUM_ALIAS_ID
+          @policy = policy
+          @policy ||= LRUPolicy.new if @configured_outgoing_maximum.positive?
+        end
+
+        # @visibility private
+        # Clear incoming alias cache
+        #   - called from Client with CONNECT packet it will send to Server
+        #   - called from Server with CONNACK packet it will send to Client
+        def clear_incoming!(packet)
+          @incoming = Cache.create(packet.topic_alias_maximum)
+        end
+
+        # @visibility private
+        # Clear outgoing alias cache
+        #    - called from Client with CONNACK packet received from Server
+        #    - called from Server with CONNECT packet received from Client
+        def clear_outgoing!(packet)
+          max = [@configured_outgoing_maximum, packet.topic_alias_maximum || 0].min
+          @outgoing = Cache.create(max)
+        end
+
+        # @visibility private
+        # Process incoming PUBLISH packet - resolve alias and update packet
+        # @param packet [Packet::Publish] incoming PUBLISH packet
+        # @raise [ProtocolError] if alias exceeds the maximum or cannot be resolved
+        def handle_incoming(packet)
+          return unless packet.topic_alias&.positive?
+
+          if (max = incoming&.max || 0) < packet.topic_alias
+            raise TopicAliasInvalid, "#{packet.topic_alias} exceeds maximum #{max}"
+          end
+
+          if packet.topic_name.empty?
+            resolved_topic = @incoming.resolve(packet.topic_alias)
+            raise TopicAliasInvalid, "Unknown topic alias #{packet.topic_alias}" unless resolved_topic
+
+            # override the empty topic name with the resolved topic
+            packet.apply_alias(name: resolved_topic)
+          else
+            @incoming.add(packet.topic_alias, packet.topic_name)
+          end
+        end
+
+        # Force removal of an outgoing topic from the alias cache. eg. because it is not going to be used any more.
+        # @param [Array<String>] topics the topics to remove
+        # @return [void]
+        # @note Prefer sending `topic_alias: false` to {Client#publish} to indicate topics that should not be aliased
+        def evict!(*topics)
+          topics.each do |topic|
+            @outgoing&.remove(topic) && @policy.alias_evicted(topic)
+          end
+        end
+
+        # @visibility private
+        # Get outgoing alias for topic (policy decides whether to alias and what to evict)
+        def handle_outgoing(packet)
+          return unless @outgoing && @policy&.aliasable?(packet)
+
+          if (alias_id = @outgoing.resolve(packet.topic_name))
+            return outgoing_alias_hit(alias_id, packet)
+          end
+
+          outgoing_alias_miss(packet)
+        end
+
+        private
+
+        def outgoing_alias_hit(alias_id, packet)
+          # We had one already, but we don't want to keep it any more (might as well use it now though)
+          evict!(packet.topic_name) unless packet.assign_alias?
+
+          @policy.alias_hit(packet.topic_name)
+          # We've seen and sent this one before, just send the alias_id and an empty topic name
+          packet.apply_alias(alias: alias_id, name: '')
+        end
+
+        def outgoing_alias_miss(packet)
+          return unless packet.assign_alias? # We don't want to alias this topic
+
+          alias_id = @outgoing.assign
+          unless alias_id
+            (evict = @policy.evict(packet.topic_name) { @outgoing.topics }) && evict!(evict)
+            alias_id = @outgoing.assign
+          end
+
+          return unless alias_id # evicting did not result in an available alias
+
+          @policy.alias_hit(packet.topic_name)
+          @outgoing.add(alias_id, packet.topic_name)
+          packet.apply_alias(alias: alias_id)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module MQTT
+  module V5
+    module TopicAlias
+      # Defaults the policy interface for evicting topics from a full Cache
+      # @abstract
+      module Policy
+        # @!method aliasable?(packet)
+        # @abstract
+        # @param [Packet::Publish] packet
+        # @return [Boolean] whether the packet is eligible for aliasing
+
+        # @method alias_evicted(topic)
+        # Called when an alias is evicted
+        # @param [String] topic The topic that was evicted.
+        # @return [void]
+
+        # @!method alias_hit(topic)
+        # Called when an alias is used (including the first time a topic is aliased)
+        # @param [String] topic
+        # @return [void]
+
+        # @!method evict(topic)
+        # Choose a topic to evict
+        # @param [String] topic The new topic that is looking for an alias
+        # @yield()
+        # @yieldreturn [Array<String>] the list of topics currently in the cache
+        # @return [String, nil] topic to evict
+        # @return [nil] evict nothing (ie do not alias the topic)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module MQTT
+  module V5
+    module TopicAlias
+      # Base module for evicting {Policy} based on a minimum topic score
+      module WeightedPolicy
+        def initialize
+          @min_topic_score = 0
+        end
+
+        # Aliases everything
+        def aliasable?(_packet)
+          true
+        end
+
+        # Evict the topic with the lowest score, unless the new_topic is even lower.
+        def evict(new_topic, &topics)
+          new_topic_score = topic_score(new_topic, new: true)
+
+          return nil unless new_topic_score >= @min_topic_score
+
+          victim = topics.call.min_by { |t| topic_score(t) }
+          @min_topic_score = topic_score(victim)
+          return victim if new_topic_score >= @min_topic_score
+
+          nil
+        end
+
+        # Record a hit for topic, check if lower than minimum score.
+        def alias_hit(topic)
+          @min_topic_score = [topic_score(topic), @min_topic_score].min
+        end
+
+        # Does nothing on eviction.
+        def alias_evicted(_topic)
+          # does not change scores
+        end
+
+        # @!method topic_score(topic, new: false)
+        # @abstract
+        # @param topic [String]
+        # @param new [Boolean] whether the topic is new (ie has not been aliased before)
+        # @return [Integer] the score of the topic
+      end
+    end
+  end
+end

data/lib/mqtt/v5/topic_alias.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'topic_alias/cache'
+require_relative 'topic_alias/policy'
+require_relative 'topic_alias/lru_policy'
+require_relative 'topic_alias/frequency_weighted_policy'
+require_relative 'topic_alias/length_weighted_policy'
+require_relative 'topic_alias/manager'
+
+module MQTT
+  module V5
+    # Topic Alias support for MQTT 5.0
+    #
+    # Provides bidirectional topic aliasing for Clients/Servers to reduce bandwidth usage by replacing
+    # repetitive topic names with small integer identifiers.
+    #
+    # @example Basic usage with default LRUPolicy policy
+    #   alias_manager = MQTT::V5::TopicAlias::Manager.new(send_maximum: 100)
+    #
+    # @example Custom policy
+    #   policy = MQTT::V5::TopicAlias::FrequencyWeightedPolicy.new
+    #   alias_manager = MQTT::V5::TopicAlias::Manager.new(send_maximum: 50, policy: policy )
+    # @see Client#topic_aliases
+    module TopicAlias
+    end
+  end
+end

data/lib/mqtt/v5/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'mqtt/version'
+
+module MQTT
+  module V5
+    VERSION = MQTT::VERSION
+    MQTT_VERSION = Gem::Version.new('5.0')
+    PROTOCOL_VERSION = 0x05
+  end
+end

data/lib/mqtt/v5.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'v5/version'
+require_relative 'v5/client'

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: mqtt-v5
+version: !ruby/object:Gem::Version
+  version: 0.0.1.ci.release
+platform: ruby
+authors:
+- Grant Gardner
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mqtt-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: MQTT version 5.0 protocol implementation
+email:
+- grant@lastweekend.com.au
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/mqtt/v5.rb
+- lib/mqtt/v5/async/client.rb
+- lib/mqtt/v5/client.rb
+- lib/mqtt/v5/client/authenticator.rb
+- lib/mqtt/v5/client/connection.rb
+- lib/mqtt/v5/client/session.rb
+- lib/mqtt/v5/errors.rb
+- lib/mqtt/v5/packet.rb
+- lib/mqtt/v5/packet/auth.rb
+- lib/mqtt/v5/packet/connack.rb
+- lib/mqtt/v5/packet/connect.rb
+- lib/mqtt/v5/packet/disconnect.rb
+- lib/mqtt/v5/packet/ping_req.rb
+- lib/mqtt/v5/packet/ping_resp.rb
+- lib/mqtt/v5/packet/pub_ack.rb
+- lib/mqtt/v5/packet/pub_comp.rb
+- lib/mqtt/v5/packet/pub_rec.rb
+- lib/mqtt/v5/packet/pub_rel.rb
+- lib/mqtt/v5/packet/publish.rb
+- lib/mqtt/v5/packet/reason_code.rb
+- lib/mqtt/v5/packet/sub_ack.rb
+- lib/mqtt/v5/packet/subscribe.rb
+- lib/mqtt/v5/packet/unsub_ack.rb
+- lib/mqtt/v5/packet/unsubscribe.rb
+- lib/mqtt/v5/packets.rb
+- lib/mqtt/v5/topic_alias.rb
+- lib/mqtt/v5/topic_alias/cache.rb
+- lib/mqtt/v5/topic_alias/frequency_weighted_policy.rb
+- lib/mqtt/v5/topic_alias/length_weighted_policy.rb
+- lib/mqtt/v5/topic_alias/lru_policy.rb
+- lib/mqtt/v5/topic_alias/manager.rb
+- lib/mqtt/v5/topic_alias/policy.rb
+- lib/mqtt/v5/topic_alias/weighted_policy.rb
+- lib/mqtt/v5/version.rb
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby MQTT 5.0
+test_files: []