karafka 1.2.12 → 1.3.3

data/lib/karafka/serialization/json/serializer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Karafka
+  # Module for all supported by default serialization and deserialization ways
+  module Serialization
+    module Json
+      # Default Karafka Json serializer for serializing data
+      class Serializer
+        # @param content [Object] any object that we want to convert to a json string
+        # @return [String] Valid JSON string containing serialized data
+        # @raise [Karafka::Errors::SerializationError] raised when we don't have a way to
+        #   serialize provided data to json
+        # @note When string is passed to this method, we assume that it is already a json
+        #   string and we don't serialize it again. This allows us to serialize data before
+        #   it is being forwarded to this serializer if we want to have a custom (not that simple)
+        #   json serialization
+        #
+        # @example From an ActiveRecord object
+        #   Serializer.call(Repository.first) #=> "{\"repository\":{\"id\":\"04b504e0\"}}"
+        # @example From a string (no changes)
+        #   Serializer.call("{\"a\":1}") #=> "{\"a\":1}"
+        def call(content)
+          return content if content.is_a?(String)
+          return content.to_json if content.respond_to?(:to_json)
+
+          raise Karafka::Errors::SerializationError, content
+        end
+      end
+    end
+  end
+end

data/lib/karafka/server.rb

@@ -6,9 +6,14 @@ module Karafka
     @consumer_threads = Concurrent::Array.new
 
     # How long should we sleep between checks on shutting down consumers
-    SUPERVISION_SLEEP = 1
+    SUPERVISION_SLEEP = 0.1
     # What system exit code should we use when we terminated forcefully
     FORCEFUL_EXIT_CODE = 2
+    # This factor allows us to calculate how many times we have to sleep before
+    # a forceful shutdown
+    SUPERVISION_CHECK_FACTOR = (1 / SUPERVISION_SLEEP)
+
+    private_constant :SUPERVISION_SLEEP, :FORCEFUL_EXIT_CODE, :SUPERVISION_CHECK_FACTOR
 
     class << self
       # Set of consuming threads. Each consumer thread contains a single consumer
@@ -22,7 +27,7 @@ module Karafka
         process.on_sigint { stop_supervised }
         process.on_sigquit { stop_supervised }
         process.on_sigterm { stop_supervised }
-        start_supervised
+        run_supervised
       end
 
       # @return [Array<String>] array with names of consumer groups that should be consumed in a
@@ -36,49 +41,42 @@ module Karafka
 
       # @return [Karafka::Process] process wrapper instance used to catch system signal calls
       def process
-        Karafka::Process.instance
+        Karafka::App.config.internal.process
       end
 
       # Starts Karafka with a supervision
       # @note We don't need to sleep because Karafka::Fetcher is locking and waiting to
-      # finish loop (and it won't happen until we explicitily want to stop)
-      def start_supervised
+      # finish loop (and it won't happen until we explicitly want to stop)
+      def run_supervised
         process.supervise
         Karafka::App.run!
-        Karafka::Fetcher.call
+        Karafka::App.config.internal.fetcher.call
       end
 
       # Stops Karafka with a supervision (as long as there is a shutdown timeout)
-      # If consumers won't stop in a given timeframe, it will force them to exit
+      # If consumers won't stop in a given time frame, it will force them to exit
       def stop_supervised
-        # Because this is called in the trap context, there is a chance that instrumentation
-        # listeners contain things that aren't allowed from within a trap context.
-        # To bypass that (instead of telling users not to do things they need to)
-        # we spin up a thread to instrument server.stop and server.stop.error and wait until
-        # they're finished
-        Thread.new { Karafka.monitor.instrument('server.stop', {}) }.join
-
         Karafka::App.stop!
-        # If there is no shutdown timeout, we don't exit and wait until all the consumers
-        # had done their work
-        return unless Karafka::App.config.shutdown_timeout
 
-        # If there is a timeout, we check every 1 second (for the timeout period) if all
-        # the threads finished their work and if so, we can just return and normal
-        # shutdown process will take place
-        Karafka::App.config.shutdown_timeout.to_i.times do
-          return if consumer_threads.count(&:alive?).zero?
+        # We check from time to time (for the timeout period) if all the threads finished
+        # their work and if so, we can just return and normal shutdown process will take place
+        (Karafka::App.config.shutdown_timeout * SUPERVISION_CHECK_FACTOR).to_i.times do
+          if consumer_threads.count(&:alive?).zero?
+            Thread.new { Karafka.monitor.instrument('app.stopped') }.join
+            return
+          end
+
           sleep SUPERVISION_SLEEP
         end
 
-        raise Errors::ForcefulShutdown
-      rescue Errors::ForcefulShutdown => error
-        Thread.new { Karafka.monitor.instrument('server.stop.error', error: error) }.join
+        raise Errors::ForcefulShutdownError
+      rescue Errors::ForcefulShutdownError => e
+        Thread.new { Karafka.monitor.instrument('app.stopping.error', error: e) }.join
         # We're done waiting, lets kill them!
         consumer_threads.each(&:terminate)
 
-        # exit is not within the instrumentation as it would not trigger due to exit
-        Kernel.exit FORCEFUL_EXIT_CODE
+        # exit! is not within the instrumentation as it would not trigger due to exit
+        Kernel.exit! FORCEFUL_EXIT_CODE
       end
     end
   end

data/lib/karafka/setup/config.rb

@@ -8,12 +8,16 @@ module Karafka
     # @note If you want to do some configurations after all of this is done, please add to
     #   karafka/config a proper file (needs to inherit from Karafka::Setup::Configurators::Base
     #   and implement setup method) after that everything will happen automatically
-    # @note This config object allows to create a 1 level nestings (nodes) only. This should be
+    # @note This config object allows to create a 1 level nesting (nodes) only. This should be
     #   enough and will still keep the code simple
     # @see Karafka::Setup::Configurators::Base for more details about configurators api
     class Config
       extend Dry::Configurable
-      extend Callbacks::Config
+
+      # Contract for checking the config provided by the user
+      CONTRACT = Karafka::Contracts::Config.new.freeze
+
+      private_constant :CONTRACT
 
       # Available settings
       # option client_id [String] kafka client_id - used to provide
@@ -22,21 +26,23 @@ module Karafka
       # What backend do we want to use to process messages
       setting :backend, :inline
       # option logger [Instance] logger that we want to use
-      setting :logger, -> { ::Karafka::Instrumentation::Logger.instance }
+      setting :logger, ::Karafka::Instrumentation::Logger.new
       # option monitor [Instance] monitor that we will to use (defaults to Karafka::Monitor)
-      setting :monitor, -> { ::Karafka::Instrumentation::Monitor.instance }
+      setting :monitor, ::Karafka::Instrumentation::Monitor.new
       # Mapper used to remap consumer groups ids, so in case users migrate from other tools
       # or they need to maintain their own internal consumer group naming conventions, they
       # can easily do it, replacing the default client_id + consumer name pattern concept
-      setting :consumer_mapper, -> { Routing::ConsumerMapper }
-      # Mapper used to remap names of topics, so we can have a clean internal topic namings
+      setting :consumer_mapper, Routing::ConsumerMapper.new
+      # Mapper used to remap names of topics, so we can have a clean internal topic naming
       # despite using any Kafka provider that uses namespacing, etc
       # It needs to implement two methods:
       #   - #incoming - for remapping from the incoming message to our internal format
       #   - #outgoing - for remapping from internal topic name into outgoing message
-      setting :topic_mapper, -> { Routing::TopicMapper }
-      # Default parser for parsing and unparsing incoming and outgoing data
-      setting :parser, -> { Karafka::Parsers::Json }
+      setting :topic_mapper, Routing::TopicMapper.new
+      # Default serializer for converting whatever we want to send to kafka to json
+      setting :serializer, Karafka::Serialization::Json::Serializer.new
+      # Default deserializer for converting incoming data into ruby objects
+      setting :deserializer, Karafka::Serialization::Json::Deserializer.new
       # If batch_fetching is true, we will fetch kafka messages in batches instead of 1 by 1
       # @note Fetching does not equal consuming, see batch_consuming description for details
       setting :batch_fetching, true
@@ -44,29 +50,15 @@ module Karafka
       # #params_batch will contain params received from Kafka (may be more than 1) so we can
       # process them in batches
       setting :batch_consuming, false
-      # Should we operate in a single consumer instance across multiple batches of messages,
-      # from the same partition or should we build a new one for each incoming batch.
-      # Disabling that can be useful when you want to create a new consumer instance for each
-      # incoming batch. It's disabled by default, not to create more objects that needed
-      # on each batch
-      setting :persistent, true
       # option shutdown_timeout [Integer, nil] the number of seconds after which Karafka no
-      #   longer wait for the consumers to stop gracefully but instead we force
-      #   terminate everything.
-      # @note Keep in mind, that if your business logic
-      # @note If set to nil, it won't forcefully shutdown the process at all.
+      #   longer wait for the consumers to stop gracefully but instead we force terminate
+      #   everything.
       setting :shutdown_timeout, 60
-      # option params_base_class [Class] base class for params class initialization
-      #   This can be either a Hash or a HashWithIndifferentAccess depending on your
-      #   requirements. Note, that by using HashWithIndifferentAccess, you remove some of the
-      #   performance in favor of convenience. This can be useful especially if you already use
-      #   it with Rails, etc
-      setting :params_base_class, Hash
 
       # option kafka [Hash] - optional - kafka configuration options
       setting :kafka do
         # Array with at least one host
-        setting :seed_brokers
+        setting :seed_brokers, %w[kafka://127.0.0.1:9092]
         # option session_timeout [Integer] the number of seconds after which, if a client
         #   hasn't contacted the Kafka cluster, it will be kicked out of the group.
         setting :session_timeout, 30
@@ -75,6 +67,11 @@ module Karafka
         # resolved and also "slows" things down, so it prevents from "eating" up all messages and
         # consuming them with failed code. Use `nil` if you want to pause forever and never retry.
         setting :pause_timeout, 10
+        # option pause_max_timeout [Integer, nil] the maximum number of seconds to pause for,
+        #   or `nil` if no maximum should be enforced.
+        setting :pause_max_timeout, nil
+        # option pause_exponential_backoff [Boolean] whether to enable exponential backoff
+        setting :pause_exponential_backoff, false
         # option offset_commit_interval [Integer] the interval between offset commits,
         #   in seconds.
         setting :offset_commit_interval, 10
@@ -91,7 +88,7 @@ module Karafka
         # option fetcher_max_queue_size [Integer] max number of items in the fetch queue that
         #   are stored for further processing. Note, that each item in the queue represents a
         #   response from a single broker
-        setting :fetcher_max_queue_size, 100
+        setting :fetcher_max_queue_size, 10
         # option max_bytes_per_partition [Integer] the maximum amount of data fetched
         #   from a single partition at a time.
         setting :max_bytes_per_partition, 1_048_576
@@ -136,6 +133,8 @@ module Karafka
         # option ssl_ca_certs_from_system [Boolean] Use the CA certs from your system's default
         #   certificate store
         setting :ssl_ca_certs_from_system, false
+        # option ssl_verify_hostname [Boolean] Verify the hostname for client certs
+        setting :ssl_verify_hostname, true
         # option ssl_client_cert [String, nil] SSL client certificate
         setting :ssl_client_cert, nil
         # option ssl_client_cert_key [String, nil] SSL client certificate password
@@ -156,10 +155,39 @@ module Karafka
         setting :sasl_scram_password, nil
         # option sasl_scram_mechanism [String, nil] Scram mechanism, either 'sha256' or 'sha512'
         setting :sasl_scram_mechanism, nil
+        # option sasl_over_ssl [Boolean] whether to enforce SSL with SASL
+        setting :sasl_over_ssl, true
+        # option ssl_client_cert_chain [String, nil] client cert chain or nil if not used
+        setting :ssl_client_cert_chain, nil
+        # option ssl_client_cert_key_password [String, nil] the password required to read
+        #   the ssl_client_cert_key
+        setting :ssl_client_cert_key_password, nil
+        # @param sasl_oauth_token_provider [Object, nil] OAuthBearer Token Provider instance that
+        #   implements method token.
+        setting :sasl_oauth_token_provider, nil
+      end
+
+      # Namespace for internal settings that should not be modified
+      # It's a temporary step to "declassify" several things internally before we move to a
+      # non global state
+      setting :internal do
+        # option routing_builder [Karafka::Routing::Builder] builder instance
+        setting :routing_builder, Routing::Builder.new
+        # option status [Karafka::Status] app status
+        setting :status, Status.new
+        # option process [Karafka::Process] process status
+        # @note In the future, we need to have a single process representation for all the karafka
+        #   instances
+        setting :process, Process.new
+        # option fetcher [Karafka::Fetcher] fetcher instance
+        setting :fetcher, Fetcher.new
+        # option configurators [Array<Object>] all configurators that we want to run after
+        #   the setup
+        setting :configurators, [Configurators::WaterDrop.new]
       end
 
       class << self
-        # Configurating method
+        # Configuring method
         # @yield Runs a block of code providing a config singleton instance to it
         # @yieldparam [Karafka::Setup::Config] Karafka config instance
         def setup
@@ -170,22 +198,22 @@ module Karafka
         # Components are in karafka/config directory and are all loaded one by one
         # If you want to configure a next component, please add a proper file to config dir
         def setup_components
-          [
-            Configurators::Params,
-            Configurators::WaterDrop
-          ].each { |klass| klass.setup(config) }
+          config
+            .internal
+            .configurators
+            .each { |configurator| configurator.call(config) }
         end
 
-        # Validate config based on ConfigurationSchema
+        # Validate config based on the config contract
         # @return [Boolean] true if configuration is valid
-        # @raise [Karafka::Errors::InvalidConfiguration] raised when configuration
-        #   doesn't match with ConfigurationSchema
+        # @raise [Karafka::Errors::InvalidConfigurationError] raised when configuration
+        #   doesn't match with the config contract
         def validate!
-          validation_result = Karafka::Schemas::Config.call(config.to_h)
+          validation_result = CONTRACT.call(config.to_h)
 
           return true if validation_result.success?
 
-          raise Errors::InvalidConfiguration, validation_result.errors
+          raise Errors::InvalidConfigurationError, validation_result.errors.to_h
         end
       end
     end

data/lib/karafka/setup/configurators/water_drop.rb

@@ -2,26 +2,30 @@
 
 module Karafka
   module Setup
-    class Configurators
+    # Configurators are used to post setup some of the components of Karafka after the core
+    # framework is initialized
+    module Configurators
       # Class responsible for setting up WaterDrop configuration
-      class WaterDrop < Base
+      class WaterDrop
         # Sets up a WaterDrop settings
         # @param config [Karafka::Setup::Config] Config we can user to setup things
         # @note This will also inject Karafka monitor as a default monitor into WaterDrop,
         #   so we have the same monitor within whole Karafka framework (same with logger)
-        def self.setup(config)
+        def call(config)
           ::WaterDrop.setup do |water_config|
             water_config.deliver = true
 
             config.to_h.reject { |k, _v| k == :kafka }.each do |k, v|
               key_assignment = :"#{k}="
               next unless water_config.respond_to?(key_assignment)
+
               water_config.public_send(key_assignment, v)
             end
 
             config.kafka.to_h.each do |k, v|
               key_assignment = :"#{k}="
               next unless water_config.kafka.respond_to?(key_assignment)
+
               water_config.kafka.public_send(key_assignment, v)
             end
           end

data/lib/karafka/setup/dsl.rb

@@ -10,7 +10,6 @@ module Karafka
       # @param [Block] block configuration block
       def setup(&block)
         Setup::Config.setup(&block)
-        initialize!
       end
 
       # @return [Karafka::Config] config instance

data/lib/karafka/status.rb

@@ -3,15 +3,16 @@
 module Karafka
   # App status monitor
   class Status
-    include Singleton
-
     # Available states and their transitions
     STATES = {
       initializing: :initialize!,
+      initialized: :initialized!,
       running: :run!,
-      stopped: :stop!
+      stopping: :stop!
     }.freeze
 
+    private_constant :STATES
+
     STATES.each do |state, transition|
       define_method :"#{state}?" do
         @status == state
@@ -19,6 +20,9 @@ module Karafka
 
       define_method transition do
         @status = state
+        # Trap context disallows to run certain things that we instrument
+        # so the state changes are executed from a separate thread
+        Thread.new { Karafka.monitor.instrument("app.#{state}") }.join
       end
     end
   end

data/lib/karafka/templates/{application_consumer.rb.example → application_consumer.rb.erb}

@@ -3,4 +3,5 @@
 # Application consumer from which all Karafka consumers should inherit
 # You can rename it if it would conflict with your current code base (in case you're integrating
 # Karafka with other frameworks)
-ApplicationConsumer = Class.new(Karafka::BaseConsumer)
+class ApplicationConsumer < Karafka::BaseConsumer
+end

data/lib/karafka/templates/karafka.rb.erb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+<% if rails? -%>
+ENV['RAILS_ENV'] ||= 'development'
+ENV['KARAFKA_ENV'] = ENV['RAILS_ENV']
+require ::File.expand_path('../config/environment', __FILE__)
+Rails.application.eager_load!
+
+# This lines will make Karafka print to stdout like puma or unicorn
+if Rails.env.development?
+  Rails.logger.extend(
+    ActiveSupport::Logger.broadcast(
+      ActiveSupport::Logger.new($stdout)
+    )
+  )
+end
+<% else -%>
+# This file is auto-generated during the install process.
+# If by any chance you've wanted a setup for Rails app, either run the `karafka:install`
+# command again or refer to the install templates available in the source codes
+
+ENV['RACK_ENV'] ||= 'development'
+ENV['KARAFKA_ENV'] ||= ENV['RACK_ENV']
+Bundler.require(:default, ENV['KARAFKA_ENV'])
+
+# Zeitwerk custom loader for loading the app components before the whole
+# Karafka framework configuration
+APP_LOADER = Zeitwerk::Loader.new
+APP_LOADER.enable_reloading
+
+%w[
+  lib
+  app/consumers
+  app/responders
+  app/workers
+].each(&APP_LOADER.method(:push_dir))
+
+APP_LOADER.setup
+APP_LOADER.eager_load
+<% end -%>
+
+class KarafkaApp < Karafka::App
+  setup do |config|
+    config.kafka.seed_brokers = %w[kafka://127.0.0.1:9092]
+    config.client_id = 'example_app'
+<% if rails? -%>
+    config.logger = Rails.logger
+<% end -%>
+  end
+
+  # Comment out this part if you are not using instrumentation and/or you are not
+  # interested in logging events for certain environments. Since instrumentation
+  # notifications add extra boilerplate, if you want to achieve max performance,
+  # listen to only what you really need for given environment.
+  Karafka.monitor.subscribe(WaterDrop::Instrumentation::StdoutListener.new)
+  Karafka.monitor.subscribe(Karafka::Instrumentation::StdoutListener.new)
+  Karafka.monitor.subscribe(Karafka::Instrumentation::ProctitleListener.new)
+
+  # Uncomment that in order to achieve code reload in development mode
+  # Be aware, that this might have some side-effects. Please refer to the wiki
+  # for more details on benefits and downsides of the code reload in the
+  # development mode
+  #
+  # Karafka.monitor.subscribe(
+  #   Karafka::CodeReloader.new(
+  #     <%= rails? ? '*Rails.application.reloaders' : 'APP_LOADER' %>
+  #   )
+  # )
+
+  consumer_groups.draw do
+    # topic :example do
+    #   consumer ExampleConsumer
+    # end
+
+    # consumer_group :bigger_group do
+    #   topic :test do
+    #     consumer TestConsumer
+    #   end
+    #
+    #   topic :test2 do
+    #     consumer Test2Consumer
+    #   end
+    # end
+  end
+end
+
+Karafka.monitor.subscribe('app.initialized') do
+  # Put here all the things you want to do after the Karafka framework
+  # initialization
+end
+
+KarafkaApp.boot!