phobos 2.1.4 → 2.1.6

data/lib/phobos/batch_handler.rb

@@ -2,21 +2,32 @@
 
 module Phobos
   module BatchHandler
+    # @!visibility private
     def self.included(base)
       base.extend(ClassMethods)
     end
 
+    # @param _payloads [Array]
+    # @param _metadata [Hash<String, Object>]
+    # @return [void]
     def consume_batch(_payloads, _metadata)
       raise NotImplementedError
     end
 
+    # @param payloads [Array]
+    # @param metadata [Hash<String, Object>]
+    # @yield [Array, Hash<String, Object>]
+    # @return [void]
     def around_consume_batch(payloads, metadata)
       yield payloads, metadata
     end
 
     module ClassMethods
+      # @param kafka_client
+      # @return [void]
       def start(kafka_client); end
 
+      # @return [void]
       def stop; end
     end
   end

data/lib/phobos/batch_message.rb

@@ -2,8 +2,23 @@
 
 module Phobos
   class BatchMessage
-    attr_accessor :key, :partition, :offset, :payload, :headers
+    # @return
+    attr_accessor :key
+    # @return [Integer]
+    attr_accessor :partition
+    # @return [Integer]
+    attr_accessor :offset
+    # @return
+    attr_accessor :payload
+    # @return
+    attr_accessor :headers
 
+    # @param key
+    # @param partition [Integer]
+    # @param offset [Integer]
+    # @param payload
+    # @param headers
+    # @return [void]
     def initialize(key:, partition:, offset:, payload:, headers:)
       @key = key
       @partition = partition
@@ -12,6 +27,8 @@ module Phobos
       @headers = headers
     end
 
+    # @param other [Phobos::BatchMessage]
+    # @return [Boolean]
     def ==(other)
       [:key, :partition, :offset, :payload, :headers].all? do |s|
         public_send(s) == other.public_send(s)

data/lib/phobos/cli.rb

@@ -4,6 +4,7 @@ require 'thor'
 require 'phobos/cli/start'
 
 module Phobos
+  # @!visibility private
   module CLI
     def self.logger
       @logger ||= Logging.logger[self].tap do |l|
@@ -11,7 +12,8 @@ module Phobos
       end
     end
 
-    class Commands < Thor
+    # @!visibility private
+    class Commands < ::Thor
       include Thor::Actions
 
       map '-v' => :version

data/lib/phobos/configuration.rb

@@ -4,6 +4,8 @@ require 'phobos/deep_struct'
 
 module Phobos
   module Configuration
+    # @param configuration
+    # @return [void]
     def configure(configuration)
       @config = fetch_configuration(configuration)
       @config.class.send(:define_method, :producer_hash) do
@@ -16,7 +18,7 @@ module Phobos
       configure_logger
     end
 
-    # :nodoc:
+    # @return [void]
     def configure_logger
       Logging.backtrace(true)
       Logging.logger.root.level = silence_log ? :fatal : config.logger.level

data/lib/phobos/handler.rb

@@ -2,6 +2,7 @@
 
 module Phobos
   module Handler
+    # @!visibility private
     def self.included(base)
       base.extend(ClassMethods)
     end

data/lib/phobos/listener.rb

@@ -9,9 +9,28 @@ module Phobos
     DEFAULT_MAX_BYTES_PER_PARTITION = 1_048_576 # 1 MB
     DELIVERY_OPTS = %w[batch message inline_batch].freeze
 
-    attr_reader :group_id, :topic, :id
-    attr_reader :handler_class, :encoding, :consumer
-
+    # @return [String]
+    attr_reader :group_id
+    # @return [String]
+    attr_reader :topic
+    attr_reader :id
+    # @return [Class<BasicObject>]
+    attr_reader :handler_class
+    attr_reader :encoding, :consumer
+
+    # @param handler [Class<BasicObject>]
+    # @param group_id [String]
+    # @param topic [String]
+    # @param min_bytes [Integer]
+    # @param max_wait_time [Integer]
+    # @param start_from_beginning [Boolean]
+    # @param delivery [String]
+    # @param max_bytes_per_partition [Integer]
+    # @param session_timeout [Integer]
+    # @param offset_commit_interval [Integer]
+    # @param heartbeat_interval [Integer]
+    # @param offset_commit_threshold [Integer]
+    # @param offset_retention_time [Integer]
     # rubocop:disable Metrics/MethodLength
     def initialize(handler:, group_id:, topic:, min_bytes: nil, max_wait_time: nil,
                    force_encoding: nil, start_from_beginning: true, backoff: nil,
@@ -40,6 +59,7 @@ module Phobos
     end
     # rubocop:enable Metrics/MethodLength
 
+    # @return [void]
     def start
       @signal_to_stop = false
       start_listener
@@ -60,6 +80,7 @@ module Phobos
       stop_listener
     end
 
+    # @return [void]
     def stop
       return if should_stop?
 

data/lib/phobos/producer.rb

@@ -2,10 +2,12 @@
 
 module Phobos
   module Producer
+    # @!visibility private
     def self.included(base)
       base.extend(Phobos::Producer::ClassMethods)
     end
 
+    # @return [Phobos::Producer::PublicAPI]
     def producer
       Phobos::Producer::PublicAPI.new(self)
     end
@@ -15,6 +17,12 @@ module Phobos
         @host_obj = host_obj
       end
 
+      # @param topic [String]
+      # @param payload [String]
+      # @param key [String]
+      # @param partition_key [Integer]
+      # @param headers [Hash]
+      # @return [void]
       def publish(topic:, payload:, key: nil, partition_key: nil, headers: nil)
         class_producer.publish(topic: topic,
                                payload: payload,
@@ -23,6 +31,12 @@ module Phobos
                                headers: headers)
       end
 
+      # @param topic [String]
+      # @param payload [String]
+      # @param key [String]
+      # @param partition_key [Integer]
+      # @param headers [Hash]
+      # @return [void]
       def async_publish(topic:, payload:, key: nil, partition_key: nil, headers: nil)
         class_producer.async_publish(topic: topic,
                                      payload: payload,
@@ -31,7 +45,7 @@ module Phobos
                                      headers: headers)
       end
 
-      # @param messages [Array(Hash(:topic, :payload, :key, :headers))]
+      # @param messages [Array<Hash>]
       #        e.g.: [
       #          { topic: 'A', payload: 'message-1', key: '1', headers: { foo: 'bar' } },
       #          { topic: 'B', payload: 'message-2', key: '2', headers: { foo: 'bar' } }
@@ -41,6 +55,7 @@ module Phobos
         class_producer.publish_list(messages)
       end
 
+      # @param messages [Array<Hash>]
       def async_publish_list(messages)
         class_producer.async_publish_list(messages)
       end
@@ -53,29 +68,35 @@ module Phobos
     end
 
     module ClassMethods
+      # @return [Phobos::Producer::ClassMethods::PublicAPI]
       def producer
         Phobos::Producer::ClassMethods::PublicAPI.new
       end
 
       class PublicAPI
+        # @return [Symbol]
         NAMESPACE = :phobos_producer_store
+        # @return [Array<Symbol>]
         ASYNC_PRODUCER_PARAMS = [:max_queue_size, :delivery_threshold, :delivery_interval].freeze
+        # @return [Array<Symbol>]
         INTERNAL_PRODUCER_PARAMS = [:persistent_connections].freeze
 
         # This method configures the kafka client used with publish operations
         # performed by the host class
         #
         # @param kafka_client [Kafka::Client]
-        #
+        # @return [void]
         def configure_kafka_client(kafka_client)
           async_producer_shutdown
           producer_store[:kafka_client] = kafka_client
         end
 
+        # @return [Kafka::Client]
         def kafka_client
           producer_store[:kafka_client]
         end
 
+        # @return [Kafka::Producer]
         def create_sync_producer
           client = kafka_client || configure_kafka_client(Phobos.create_kafka_client(:producer))
           sync_producer = client.producer(**regular_configs)
@@ -85,20 +106,29 @@ module Phobos
           sync_producer
         end
 
+        # @return [Kafka::Producer]
         def sync_producer
           producer_store[:sync_producer]
         end
 
+        # @return [void]
         def sync_producer_shutdown
           sync_producer&.shutdown
           producer_store[:sync_producer] = nil
         end
 
+        # @param topic [String]
+        # @param payload [String]
+        # @param partition_key [Integer]
+        # @param headers [Hash]
+        # @return [void]
         def publish(topic:, payload:, key: nil, partition_key: nil, headers: nil)
           publish_list([{ topic: topic, payload: payload, key: key,
                           partition_key: partition_key, headers: headers }])
         end
 
+        # @param messages [Array<Hash>]
+        # @return [void]
         def publish_list(messages)
           producer = sync_producer || create_sync_producer
           produce_messages(producer, messages)
@@ -107,39 +137,51 @@ module Phobos
           producer&.shutdown unless Phobos.config.producer_hash[:persistent_connections]
         end
 
+        # @return [Kafka::AsyncProducer]
         def create_async_producer
           client = kafka_client || configure_kafka_client(Phobos.create_kafka_client(:producer))
           async_producer = client.async_producer(**async_configs)
           producer_store[:async_producer] = async_producer
         end
 
+        # @return [Kafka::AsyncProducer]
         def async_producer
           producer_store[:async_producer]
         end
 
+        # @param topic [String]
+        # @param payload [String]
+        # @param partition_key [Integer]
+        # @param headers [Hash]
+        # @return [void]
         def async_publish(topic:, payload:, key: nil, partition_key: nil, headers: nil)
           async_publish_list([{ topic: topic, payload: payload, key: key,
                                 partition_key: partition_key, headers: headers }])
         end
 
+        # @param messages [Array<Hash>]
+        # @return [void]
         def async_publish_list(messages)
           producer = async_producer || create_async_producer
           produce_messages(producer, messages)
           producer.deliver_messages unless async_automatic_delivery?
         end
 
+        # @return [void]
         def async_producer_shutdown
           async_producer&.deliver_messages
           async_producer&.shutdown
           producer_store[:async_producer] = nil
         end
 
+        # @return [Hash]
         def regular_configs
           Phobos.config.producer_hash
                 .reject { |k, _| ASYNC_PRODUCER_PARAMS.include?(k) }
                 .reject { |k, _| INTERNAL_PRODUCER_PARAMS.include?(k) }
         end
 
+        # @return [Hash]
         def async_configs
           Phobos.config.producer_hash
                 .reject { |k, _| INTERNAL_PRODUCER_PARAMS.include?(k) }

data/lib/phobos/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Phobos
-  VERSION = '2.1.4'
+  # @return [String]
+  VERSION = '2.1.6'
 end

data/lib/phobos.rb

@@ -34,6 +34,7 @@ Thread.abort_on_exception = true
 Logging.init :debug, :info, :warn, :error, :fatal
 
 # Monkey patch to fix this issue: https://github.com/zendesk/ruby-kafka/pull/732
+# @!visibility private
 module Logging
   # :nodoc:
   class Logger
@@ -51,14 +52,21 @@ end
 module Phobos
   extend Configuration
   class << self
-    attr_reader :config, :logger
+    # @return [Phobos::DeepStruct]
+    attr_reader :config
+    # @return [Logger]
+    attr_reader :logger
+    # @return [Boolean]
     attr_accessor :silence_log
 
+    # @param configuration [Hash<String, Object>]
+    # @return [void]
     def add_listeners(configuration)
       listeners_config = fetch_configuration(configuration)
       @config.listeners += listeners_config.listeners
     end
 
+    # @param config_key [String]
     def create_kafka_client(config_key = nil)
       kafka_config = config.kafka.to_hash.merge(logger: @ruby_kafka_logger)
 
@@ -69,6 +77,7 @@ module Phobos
       Kafka.new(**kafka_config)
     end
 
+    # @param backoff_config [Hash<Symbol, Integer>]
     def create_exponential_backoff(backoff_config = nil)
       backoff_config ||= Phobos.config.backoff.to_hash
       min = backoff_config[:min_ms] / 1000.0
@@ -76,6 +85,8 @@ module Phobos
       ExponentialBackoff.new(min, max).tap { |backoff| backoff.randomize_factor = rand }
     end
 
+    # @param message [String]
+    # @return [void]
     def deprecate(message)
       location = caller.find { |line| line !~ %r{/phobos/} }
       warn "DEPRECATION WARNING: #{message}: #{location}"

data/phobos.gemspec

@@ -44,7 +44,7 @@ Gem::Specification.new do |spec|
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
+    f.match(%r{^(test|spec|features|sorbet)/})
   end
   spec.bindir        = 'bin'
   spec.executables   = spec.files.grep(%r{^bin/phobos}) { |f| File.basename(f) }
@@ -58,7 +58,11 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop', '0.62.0'
   spec.add_development_dependency 'rubocop_rules'
   spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'sorbet'
+  spec.add_development_dependency 'sord'
+  spec.add_development_dependency 'tapioca'
   spec.add_development_dependency 'timecop'
+  spec.add_development_dependency 'yard'
 
   spec.add_dependency 'activesupport', '>= 3.0.0'
   spec.add_dependency 'concurrent-ruby', '>= 1.0.2'