mqtt-core 0.0.1.ci.release

data/lib/mqtt/logger.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Sugar for logging
+require 'logger'
+require 'delegate'
+
+module MQTT
+  # The MQTT Logger
+  module Logger
+    # @!visibility private
+    # Adds classname info as progname to each log message
+    class InstanceLogger < SimpleDelegator
+      def initialize(obj)
+        @obj = obj
+        super(Logger.log)
+      end
+
+      %i[debug info warn error fatal].each do |lvl|
+        lvl_check = :"#{lvl}?"
+        lvl_const = ::Logger.const_get(lvl.upcase)
+        define_method(lvl) do |message = nil, &block|
+          next unless __get_obj__.public_send(lvl_check)
+
+          add(lvl_const, message, &block)
+        end
+      end
+
+      def add(severity, message = nil, &block)
+        if block
+          __get_obj__.add(severity, nil, @obj.log_name) { convert_message(block.call) }
+        else
+          __get_obj__.add(severity, convert_message(message), @obj.log_name)
+        end
+      end
+
+      private
+
+      def __get_obj__
+        Logger.log
+      end
+
+      def convert_message(msg)
+        case msg
+        when Exception
+          ["#{msg.class.name}: #{msg.message}", *(__get_obj__.debug? ? msg.backtrace : [])].join("\n")
+        else
+          msg
+        end
+      end
+    end
+
+    class << self
+      # @!visibility private
+      def configure(file: nil, shift_age: nil, shift_size: nil, level: nil)
+        shift_age = Integer(shift_age) if shift_age
+        shift_size = Integer(shift_size) if shift_size
+
+        device = [file, shift_age, shift_size].compact
+        if device.any?
+          send(:log=, *device, level: (level || defined?(@log) ? @log.level : ::Logger::INFO))
+        elsif level
+          log.level = level
+        end
+      end
+
+      # @!visibility private
+      # Set the log device
+      def log=(*device, level: defined?(@log) ? @log.level : ::Logger::INFO)
+        @log = ::Logger.new(*device, level:)
+      end
+
+      # @!visibility private
+      # The actual logger
+      # @return [::Logger]
+      # @example
+      #   MQTT::Logger.log.warn! # set level to WARN
+      def log
+        @log ||= send(:log=, $stdout).tap { $stdout.sync = true }
+      end
+    end
+
+    # @!visibility private
+    def log
+      @log ||= InstanceLogger.new(self)
+    end
+
+    # @!visibility private
+    def log_name
+      self.class.name
+    end
+  end
+end

data/lib/mqtt/open.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require_relative 'core/client'
+require_relative 'options'
+
+# MQTT top level namespace
+module MQTT
+  class << self
+    include Options
+
+    # Construct and Configure an MQTT client
+    #
+    # If a block is provided, yields the client and ensures disconnection.
+    # Otherwise, the client is returned directly.
+    #
+    # In either case the client is provided in `:configure` state and not yet connected to the broker.
+    #
+    # @note All scalar-valued options (String, Integer, Float, Boolean) can be provided as URI query parameters
+    #   unless `ignore_uri_params: true` is set. URI parameters override explicit keyword arguments.
+    #
+    # @overload open(*io_args, **client_opts)
+    #   @param io_args see {Core::Client::SocketFactory}. Typically an `mqtt[s]://` or `unix://` URI
+    #   @param [Hash<Symbol>] client_opts
+    #   @option client_opts [Boolean] ignore_uri_params (false)
+    #     When true, URI query parameters are ignored. Use where URI input is untrusted.
+    #   @option client_opts [Hash<Symbol>] **socket_factory options passed to {Core::Client::SocketFactory}
+    #
+    #      - `host`, `port`, `local_addr`, `local_port`, `scheme`, `connect_timeout`, `ssl_(.*)`
+    #   @option client_opts [Hash<Symbol>] **logger options passed to {MQTT::Logger.configure}
+    #
+    #      - `log_(.*)`
+    #   @option client_opts [Integer] protocol_version ([5, 3]) MQTT protocol major version
+    #
+    #     - 5 requires `mqtt/v5` gem
+    #     - 3 requires `mqtt/v3` gem.
+    #     - If not set, v5 is preferred over v3 based on the ability to load the requisite gem.
+    #   @option client_opts [String, nil] client_id ('') Session identifier
+    #
+    #     - Default empty string implies anonymous or server-assigned ids
+    #     - Set to nil to force generation of a random id if the broker does not support anonymous ids
+    #     - {Core::Client::FilesystemSessionStore} requires a fixed, non-empty client_id
+    #   @option client_opts [Integer, nil] session_expiry_interval Duration in seconds before the session
+    #     expires after disconnect
+    #
+    #     - Set to nil to use maximum (130+ years) expiry
+    #   @option client_opts [String, Pathname] session_base_dir Base directory for
+    #     {Core::Client::FilesystemSessionStore}
+    #   @option client_opts [Core::Client::SessionStore, Class, Proc] session_store SessionStore instance, Class,
+    #     or factory
+    #
+    #     - Class/Proc is called with `client_id` and `session_(.*)` options
+    #     - If not set
+    #        - with `:session_base_dir` a {Core::Client::FilesystemSessionStore} is constructed
+    #        - with `:session_expiry_interval` a {Core::Client::MemorySessionStore} is constructed
+    #        - defaults to constructing a {Core::Client::Qos0SessionStore}
+    #
+    #   @option client_opts [Core::Client::RetryStrategy, Class, Proc, Boolean] retry_strategy RetryStrategy instance,
+    #     Class, or factory. Determines how to retry after connection dropouts.
+    #
+    #     - Class/Proc is called with other `retry_(.*)` options
+    #     - Explicitly false or nil disables retries
+    #     - If not set
+    #        - If other `retry_(.*)` options are present, they are used to construct a {Core::Client::RetryStrategy}
+    #        - If the `:session_store` option resolves to only support QoS0, then retries are disabled
+    #        - Otherwise, a {Core::Client::RetryStrategy} is constructed with default settings
+    #   @option client_opts [Integer] keep_alive (60)
+    #     Duration in seconds between PING packets sent to the broker to keep the connection alive.
+    #   @option client_opts [Hash<Symbol>] **topic_alias options to build a {V5::TopicAlias::Manager} (V5 only)
+    #
+    #     - `topic_aliases` TopicAlias::Manager instance, Class, or factory. (default {V5::TopicAlias::Manager})
+    #     - `policy` TopicAlias::Policy instance, Class, or factory. (default {V5::TopicAlias::LRUPolicy})
+    #     - `send_maximum` Integer maximum number of topic aliases to send to the broker.
+    #           Default is the broker limit if a policy is set, otherwise 0, effectively disabling outgoing topic
+    #           aliases.
+    #
+    #   @option client_opts [Hash<Symbol>] **connect other CONNECT packet options
+    #   @yield [client] Yields the configured client for use within the block
+    #   @yieldparam client [Core::Client] the MQTT client instance {V5::Client} or {V3::Client}
+    #   @return [Core::Client] the client if no block is given
+    #   @return [void] if a block is given
+    #   @raise [LoadError] if no suitable MQTT gem can be found
+    # @example Default usage - entirely configured via URI from environment variable
+    #   # ENV['MQTT_SERVER'] => 'mqtt://localhost'
+    #   MQTT.open do |client|
+    #     client.connect(will_topic: 'status', will_payload: 'offline')
+    #     client.publish(topic, payload)
+    #   end
+    # @example Untrusted URI input, only directly set options are used
+    #   MQTT.open(untrusted_uri, ignore_uri_params: true, ssl_min_version: :TLSv1_2) do |client|
+    #     client.connect
+    #     #...
+    #   end
+    # @example Force v5 protocol
+    #   MQTT.open(mqtt_uri, protocol_version: 5) do |client|
+    #     client.connect
+    #     # ...
+    #   end
+    # @example Need Qos1/2 guarantees only as long as the process is running
+    #   MQTT.open(mqtt_uri, session_expiry_interval: nil) do |client|
+    #     client.session_store # => Core::Client::MemorySessionStore
+    #     client.publish(topic, payload, qos: 2)
+    #     # ...
+    #   end
+    # @example Full Qos1/2 guarantees including over process restarts within one day
+    #   mqtt_uri = "mqtt://host.example.com/?client_id=#{ENV['HOSTNAME']}"
+    #   MQTT.open(mqtt_uri, session_base_dir: '/data/mqtt', session_expiry_interval: 86400) do |client|
+    #     client.session_store # => Core::Client::FilesystemSessionStore
+    #     client.on_birth do
+    #       client.subscribe(*topics, max_qos: 2).async { |topic, payload| process(topic, payload) }
+    #     end
+    #     sleep # until process terminates
+    #   end
+    #
+    def open(*io_args, async: false, **client_opts, &)
+      # SocketFactory will claim its keyword options, client_opts is left with the remaining options
+      sf = Core::Client::SocketFactory.create(*io_args, options: client_opts)
+      client_opts.merge!(sf.query_params) if sf.respond_to?(:query_params)
+      MQTT::Logger.configure(**slice_opts!(client_opts, /^log_(.*)$/))
+
+      class_opts = { async: async, protocol_version: client_opts.delete(:protocol_version) || %w[5 3] }
+      client_class = client_class(**class_opts)
+
+      session_store = session_store(**slice_opts!(client_opts, :client_id, :session_store, /^session_(.*)$/))
+
+      open_opts = {
+        **retry_strategy(max_qos: session_store.max_qos, **slice_opts!(client_opts, :retry_strategy, /^retry_(.*)$/)),
+        **slice_opts!(client_opts, :keep_alive)
+      }
+
+      v5_specific_options(client_class.protocol_version, client_opts, open_opts)
+
+      client_class.open(sf, session_store:, **client_opts, **open_opts, &)
+    end
+
+    # Utility to test broker connectivity
+    #
+    # Connect to the broker, outputting status information
+    # @see open
+    def test(*io_args, **client_opts)
+      self.open(*io_args, **client_opts) do |client|
+        client.configure_retry(false)
+        puts "Client: #{client}"
+        puts "   Session: #{client.session_store}"
+        client.connect
+        puts "   Status: #{client.status}"
+      end
+    end
+
+    # As per {open} but returns an Async client that uses Fibers for concurrency
+    #
+    # If not using the block form, {Core::Client#connect} and later methods must be called within the reactor.
+    # @example Async client usage
+    #   require 'async'
+    #   require 'mqtt/core'
+    #
+    #   client = MQTT.async_open('localhost')
+    #   Sync do
+    #     client.connect
+    #     client.publish(topic, payload)
+    #   end
+    # @yield [client] Yields the configured client for use within the block
+    # @yieldparam client [Core::Client] the MQTT client instance {V5::Async::Client} or {V3::Async::Client}
+    # @return [Core::Client] the client if no block is given
+    # @return [void] if a block is given
+    def async_open(*io_args, **client_opts, &)
+      self.open(*io_args, async: true, **client_opts, &)
+    end
+
+    private
+
+    def client_class(protocol_version:, async:)
+      protocol_version = [protocol_version] unless protocol_version.is_a?(Array)
+      protocol_version.map(&:to_s).each do |v|
+        raise ArgumentError, "Invalid mqtt-version #{v}" unless %w[3 5 31 3.1 50 5.0 3.1.1 311].include?(v)
+
+        v = v[0]
+        require async ? "mqtt/v#{v}/async/client" : "mqtt/v#{v}"
+        return Class.const_get("MQTT::V#{v}::#{'Async::' if async}Client")
+      rescue LoadError => _e
+        # warn e
+      end
+      raise LoadError, "Could not find MQTT gem for protocol versions: #{protocol_version}"
+    end
+
+    def session_store(session_store: nil, **opts)
+      return session_store.call(**opts) if session_store.respond_to?(:call)
+      return session_store.new(**opts) if session_store.is_a?(Class)
+      return session_store if session_store # expecting something that quacks like Core::Client::SessionStore
+
+      return Core::Client.file_store(**opts) if opts.key?(:base_dir)
+      return Core::Client.memory_store(**opts) if opts.key?(:expiry_interval)
+
+      Core::Client.qos0_store(**opts)
+    end
+
+    # @return [RetryStrategy] URI parameters (prefixed 'retry_') override provided defaults
+    # @see open
+    def retry_strategy(max_qos:, retry_strategy: max_qos.positive? || :__not_set__, **options)
+      return {} if retry_strategy == :__not_set__ && options.empty?
+      return { retry_strategy: retry_strategy.call(**options) } if retry_strategy.respond_to?(:call)
+      return { retry_strategy: retry_strategy.new(**options) } if retry_strategy.is_a?(Class)
+      return { retry_strategy: false } if %w[false 0 no n nil].include?(retry_strategy.to_s.downcase)
+
+      { retry_strategy: Core::Client.retry_strategy(**options) }
+    end
+
+    # extract from client_opts into open_opts
+    def v5_specific_options(protocol_version, client_opts, open_opts)
+      ta_keys = [:topic_aliases, :topic_alias_maximum, /^topic_alias_(.*)$/]
+      v5_opts(protocol_version, client_opts, open_opts, *ta_keys) { |**ta_opts| topic_alias_opts(**ta_opts) }
+    end
+
+    def v5_opts(protocol_version, client_opts, open_opts, *slice_keys, &block)
+      v5_opts = slice_opts!(client_opts, *slice_keys)
+      if protocol_version == 5
+        open_opts.merge!(block.call(**v5_opts))
+      else
+        MQTT::Logger.log.warn "Ignoring #{slice_keys.last} options for protocol version #{protocol_version}"
+      end
+    end
+
+    def topic_alias_opts(
+      topic_aliases: V5::TopicAlias::Manager, topic_alias_maximum: nil,
+      policy: nil, send_maximum: :__not_set__, **
+    )
+      # Use broker limit if we have a policy but no send limit
+      send_maximum = nil if send_maximum == :__not_set__
+      send_maximum = coerce_integer(send_maximum:) if send_maximum
+
+      policy = policy.call(**) if policy.respond_to?(:call)
+      policy = policy.new(**) if policy.is_a?(Class)
+
+      topic_aliases = topic_aliases.call(policy:, send_maximum:, **) if topic_aliases.respond_to?(:call)
+      topic_aliases = topic_aliases.new(policy:, send_maximum:, **) if topic_aliases.is_a?(Class)
+
+      { topic_aliases: topic_aliases, topic_alias_maximum: }.compact
+    end
+  end
+end

data/lib/mqtt/options.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module MQTT
+  # @!visibility private
+  module Options
+    private
+
+    # Slice out a set of options, removing them from  the original hash
+    # @param [Hash] opts
+    # @param [Array<Symbol,Regexp>] keys
+    #   - Symbol: exact match
+    #   - Regexp: match against key, using first matching group to name the option (eg remove prefix/suffix)
+    # @return [Hash]
+    def slice_opts!(opts, *keys) # rubocop:disable Metrics/AbcSize
+      {}.tap do |slice|
+        opts.delete_if do |o, v|
+          keys.any? do |k|
+            if k.is_a?(Regexp)
+              k.match(o).tap { slice[(it[1] || o).to_sym] = v if it }
+            else
+              (k.to_sym == o).tap { slice[o] = v if it }
+            end
+          end
+        end
+        slice.each { |k, v| slice[k] = yield(k, v) } if block_given?
+      end
+    end
+
+    def coerce_boolean(_key, value)
+      return value if [true, false, nil].include?(value)
+      return false if value.to_s.match?(/^(false|f|no|n|0)$/i)
+
+      !!value
+    end
+
+    def coerce_integer(key = nil, value = nil, **opts)
+      key, value = opts.first if opts.size == 1
+      coerce(key, value, type: :Integer)
+    end
+
+    def coerce_float(key, value)
+      coerce(key, value, type: :Float)
+    end
+
+    # @!visibility private
+    def coerce(key, value, type: :Integer)
+      return value unless value
+
+      case type
+      when :Integer
+        Integer(value)
+      when :Float
+        Float(value)
+      end
+    rescue ArgumentError => e
+      raise ArgumentError, "#{key}: #{e.message}"
+    end
+  end
+end

data/lib/mqtt/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module MQTT
+  # The version number shared across MQTT gems (mqtt-core, mqtt-v3, mqtt-v5)
+  VERSION = '0.0.1'
+end

data/lib/mqtt.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+raise LoadError, 'this is not njh/ruby-mqtt.  Please require "mqtt/core" , "mqtt/v5" or "mqtt/v3"'

data/lib/patches/openssl.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+if Gem::Version.new(OpenSSL::VERSION) < Gem::Version.new('3.3.0')
+  module OpenSSL
+    module SSL
+      # Socket patches
+      class SSLSocket
+        # https://github.com/ruby/openssl/pull/771
+        unless method_defined?(:readbyte)
+          def readbyte
+            getbyte or raise EOFError
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: mqtt-core
+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: concurrent_monitor
+  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: ''
+email:
+- grant@lastweekend.com.au
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/mqtt.rb
+- lib/mqtt/core.rb
+- lib/mqtt/core/client.rb
+- lib/mqtt/core/client/acknowledgement.rb
+- lib/mqtt/core/client/client_id_generator.rb
+- lib/mqtt/core/client/connection.rb
+- lib/mqtt/core/client/enumerable_subscription.rb
+- lib/mqtt/core/client/filesystem_session_store.rb
+- lib/mqtt/core/client/memory_session_store.rb
+- lib/mqtt/core/client/qos0_session_store.rb
+- lib/mqtt/core/client/qos2_session_store.rb
+- lib/mqtt/core/client/qos_tracker.rb
+- lib/mqtt/core/client/retry_strategy.rb
+- lib/mqtt/core/client/session.rb
+- lib/mqtt/core/client/session_store.rb
+- lib/mqtt/core/client/socket_factory.rb
+- lib/mqtt/core/client/subscription.rb
+- lib/mqtt/core/client/uri.rb
+- lib/mqtt/core/packet.rb
+- lib/mqtt/core/packet/connect.rb
+- lib/mqtt/core/packet/publish.rb
+- lib/mqtt/core/packet/subscribe.rb
+- lib/mqtt/core/packet/unsubscribe.rb
+- lib/mqtt/core/type/binary.rb
+- lib/mqtt/core/type/bit_flags.rb
+- lib/mqtt/core/type/boolean_byte.rb
+- lib/mqtt/core/type/fixed_int.rb
+- lib/mqtt/core/type/list.rb
+- lib/mqtt/core/type/password.rb
+- lib/mqtt/core/type/properties.rb
+- lib/mqtt/core/type/reason_codes.rb
+- lib/mqtt/core/type/remaining.rb
+- lib/mqtt/core/type/shape.rb
+- lib/mqtt/core/type/sub_type.rb
+- lib/mqtt/core/type/utf8_string.rb
+- lib/mqtt/core/type/utf8_string_pair.rb
+- lib/mqtt/core/type/var_int.rb
+- lib/mqtt/core/version.rb
+- lib/mqtt/errors.rb
+- lib/mqtt/logger.rb
+- lib/mqtt/open.rb
+- lib/mqtt/options.rb
+- lib/mqtt/version.rb
+- lib/patches/openssl.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 Core
+test_files: []