karafka 1.4.13 → 2.0.0

data/lib/karafka/licenser.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Karafka
+  # Checks the license presence for pro and loads pro components when needed (if any)
+  class Licenser
+    # Location in the gem where we store the public key
+    PUBLIC_KEY_LOCATION = File.join(Karafka.gem_root, 'certs', 'karafka-pro.pem')
+
+    private_constant :PUBLIC_KEY_LOCATION
+
+    # Tries to prepare license and verifies it
+    #
+    # @param license_config [Karafka::Core::Configurable::Node] config related to the licensing
+    def prepare_and_verify(license_config)
+      prepare(license_config)
+      verify(license_config)
+    end
+
+    private
+
+    # @param license_config [Karafka::Core::Configurable::Node] config related to the licensing
+    def prepare(license_config)
+      # If there is token, no action needed
+      # We support a case where someone would put the token in instead of using one from the
+      # license. That's in case there are limitations to using external package sources, etc
+      return if license_config.token
+
+      begin
+        license_config.token || require('karafka-license')
+      rescue LoadError
+        return
+      end
+
+      license_config.token = Karafka::License.token
+    end
+
+    # Check license and setup license details (if needed)
+    # @param license_config [Karafka::Core::Configurable::Node] config related to the licensing
+    def verify(license_config)
+      # If no license, it will just run LGPL components without anything extra
+      return unless license_config.token
+
+      public_key = OpenSSL::PKey::RSA.new(File.read(PUBLIC_KEY_LOCATION))
+
+      # We gsub and strip in case someone copy-pasted it as a multi line string
+      formatted_token = license_config.token.strip.delete("\n").delete(' ')
+      decoded_token = Base64.decode64(formatted_token)
+
+      begin
+        data = public_key.public_decrypt(decoded_token)
+      rescue OpenSSL::OpenSSLError
+        data = nil
+      end
+
+      details = data ? JSON.parse(data) : raise_invalid_license_token(license_config)
+
+      license_config.entity = details.fetch('entity')
+    end
+
+    # Raises an error with info, that used token is invalid
+    # @param license_config [Karafka::Core::Configurable::Node]
+    def raise_invalid_license_token(license_config)
+      # We set it to false so `Karafka.pro?` method behaves as expected
+      license_config.token = false
+
+      raise(
+        Errors::InvalidLicenseTokenError,
+        <<~MSG.tr("\n", ' ')
+          License key you provided is invalid.
+          Please reach us at contact@karafka.io or visit https://karafka.io to obtain a valid one.
+        MSG
+      )
+    end
+  end
+end

data/lib/karafka/messages/batch_metadata.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Messages
+    # Simple batch metadata object that stores all non-message information received from Kafka
+    # cluster while fetching the data.
+    #
+    # @note This metadata object refers to per batch metadata, not `#message.metadata`
+    BatchMetadata = Struct.new(
+      :size,
+      :first_offset,
+      :last_offset,
+      :deserializer,
+      :partition,
+      :topic,
+      :created_at,
+      :scheduled_at,
+      :processed_at,
+      keyword_init: true
+    ) do
+      # This lag describes how long did it take for a message to be consumed from the moment it was
+      # created
+      def consumption_lag
+        time_distance_in_ms(processed_at, created_at)
+      end
+
+      # This lag describes how long did a batch have to wait before it was picked up by one of the
+      # workers
+      def processing_lag
+        time_distance_in_ms(processed_at, scheduled_at)
+      end
+
+      private
+
+      # Computes time distance in between two times in ms
+      #
+      # @param time1 [Time]
+      # @param time2 [Time]
+      # @return [Integer] distance in between two times in ms
+      def time_distance_in_ms(time1, time2)
+        ((time1 - time2) * 1_000).round
+      end
+    end
+  end
+end

data/lib/karafka/messages/builders/batch_metadata.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Messages
+    module Builders
+      # Builder for creating batch metadata object based on the batch informations.
+      module BatchMetadata
+        class << self
+          # Creates metadata based on the kafka batch data.
+          #
+          # @param messages [Array<Karafka::Messages::Message>] messages array
+          # @param topic [Karafka::Routing::Topic] topic for which we've fetched the batch
+          # @param scheduled_at [Time] moment when the batch was scheduled for processing
+          # @return [Karafka::Messages::BatchMetadata] batch metadata object
+          #
+          # @note We do not set `processed_at` as this needs to be assigned when the batch is
+          #   picked up for processing.
+          def call(messages, topic, scheduled_at)
+            Karafka::Messages::BatchMetadata.new(
+              size: messages.count,
+              first_offset: messages.first.offset,
+              last_offset: messages.last.offset,
+              deserializer: topic.deserializer,
+              partition: messages.first.partition,
+              topic: topic.name,
+              # We go with the assumption that the creation of the whole batch is the last message
+              # creation time
+              created_at: messages.last.timestamp,
+              # When this batch was built and scheduled for execution
+              scheduled_at: scheduled_at,
+              # We build the batch metadata when we pick up the job in the worker, thus we can use
+              # current time here
+              processed_at: Time.now
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/messages/builders/message.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Messages
+    # Builders encapsulate logic related to creating messages related objects.
+    module Builders
+      # Builder of a single message based on raw rdkafka message.
+      module Message
+        class << self
+          # @param kafka_message [Rdkafka::Consumer::Message] raw fetched message
+          # @param topic [Karafka::Routing::Topic] topic for which this message was fetched
+          # @param received_at [Time] moment when we've received the message
+          # @return [Karafka::Messages::Message] message object with payload and metadata
+          def call(kafka_message, topic, received_at)
+            # @see https://github.com/appsignal/rdkafka-ruby/issues/168
+            kafka_message.headers.transform_keys!(&:to_s)
+
+            metadata = Karafka::Messages::Metadata.new(
+              timestamp: kafka_message.timestamp,
+              headers: kafka_message.headers,
+              key: kafka_message.key,
+              offset: kafka_message.offset,
+              deserializer: topic.deserializer,
+              partition: kafka_message.partition,
+              topic: topic.name,
+              received_at: received_at
+            ).freeze
+
+            # Karafka messages cannot be frozen because of the lazy deserialization feature
+            Karafka::Messages::Message.new(
+              kafka_message.payload,
+              metadata
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/messages/builders/messages.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Messages
+    module Builders
+      # Builder for creating message batch instances.
+      module Messages
+        class << self
+          # Creates messages batch with messages inside based on the incoming messages and the
+          # topic from which it comes.
+          #
+          # @param messages [Array<Karafka::Messages::Message>] karafka messages array
+          # @param topic [Karafka::Routing::Topic] topic for which we're received messages
+          # @param received_at [Time] moment in time when the messages were received
+          # @return [Karafka::Messages::Messages] messages batch object
+          def call(messages, topic, received_at)
+            metadata = BatchMetadata.call(
+              messages,
+              topic,
+              received_at
+            ).freeze
+
+            Karafka::Messages::Messages.new(
+              messages,
+              metadata
+            ).freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/{params/params.rb → messages/message.rb}

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module Karafka
-  # Params namespace encapsulating all the logic that is directly related to params handling
-  module Params
+  # Messages namespace encapsulating all the logic that is directly related to messages handling
+  module Messages
     # It provides lazy loading not only until the first usage, but also allows us to skip
     # using deserializer until we execute our logic. That way we can operate with
     # heavy-deserialization data without slowing down the whole application.
-    class Params
+    class Message
       extend Forwardable
 
       attr_reader :raw_payload, :metadata
@@ -14,7 +14,7 @@ module Karafka
       def_delegators :metadata, *Metadata.members
 
       # @param raw_payload [Object] incoming payload before deserialization
-      # @param metadata [Karafka::Params::Metadata] message metadata object
+      # @param metadata [Karafka::Messages::Metadata] message metadata object
       def initialize(raw_payload, metadata)
         @raw_payload = raw_payload
         @metadata = metadata
@@ -33,21 +33,16 @@ module Karafka
         @payload
       end
 
-      # @return [Boolean] did given params payload were deserialized already
+      # @return [Boolean] did we deserialize payload already
       def deserialized?
         @deserialized
       end
 
       private
 
-      # @return [Object] tries de-serializes data
+      # @return [Object] deserialized data
       def deserialize
-        Karafka.monitor.instrument('params.params.deserialize', caller: self) do
-          metadata.deserializer.call(self)
-        end
-      rescue ::StandardError => e
-        Karafka.monitor.instrument('params.params.deserialize.error', caller: self, error: e)
-        raise e
+        metadata.deserializer.call(self)
       end
     end
   end

data/lib/karafka/messages/messages.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Messages
+    # Messages batch represents a set of messages received from Kafka of a single topic partition.
+    class Messages
+      include Enumerable
+
+      attr_reader :metadata
+
+      # @param messages_array [Array<Karafka::Messages::Message>] array with karafka messages
+      # @param metadata [Karafka::Messages::BatchMetadata]
+      # @return [Karafka::Messages::Messages] lazy evaluated messages batch object
+      def initialize(messages_array, metadata)
+        @messages_array = messages_array
+        @metadata = metadata
+      end
+
+      # @param block [Proc] block we want to execute per each message
+      # @note Invocation of this method will not cause loading and deserializing of messages.
+      def each(&block)
+        @messages_array.each(&block)
+      end
+
+      # Runs deserialization of all the messages and returns them
+      # @return [Array<Karafka::Messages::Message>]
+      def deserialize!
+        each(&:payload)
+      end
+
+      # @return [Array<Object>] array with deserialized payloads. This method can be useful when
+      #   we don't care about metadata and just want to extract all the data payloads from the
+      #   batch
+      def payloads
+        map(&:payload)
+      end
+
+      # @return [Array<String>] array with raw, not deserialized payloads
+      def raw_payloads
+        map(&:raw_payload)
+      end
+
+      # @return [Karafka::Messages::Message] first message
+      def first
+        @messages_array.first
+      end
+
+      # @return [Karafka::Messages::Message] last message
+      def last
+        @messages_array.last
+      end
+
+      # @return [Integer] number of messages in the batch
+      def size
+        @messages_array.size
+      end
+
+      # @return [Array<Karafka::Messages::Message>] pure array with messages
+      def to_a
+        @messages_array
+      end
+    end
+  end
+end

data/lib/karafka/{params → messages}/metadata.rb

@@ -1,18 +1,16 @@
 # frozen_string_literal: true
 
 module Karafka
-  module Params
-    # Single message / params metadata details that can be accessed without the need for the
-    # payload deserialization
+  module Messages
+    # Single message metadata details that can be accessed without the need of deserialization.
     Metadata = Struct.new(
-      :create_time,
+      :timestamp,
       :headers,
-      :is_control_record,
       :key,
       :offset,
       :deserializer,
       :partition,
-      :receive_time,
+      :received_at,
       :topic,
       keyword_init: true
     )

data/lib/karafka/messages/seek.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Karafka
+  module Messages
+    # "Fake" message that we use as an abstraction layer when seeking back.
+    # This allows us to encapsulate a seek with a simple abstraction
+    Seek = Struct.new(:topic, :partition, :offset)
+  end
+end

data/lib/karafka/patches/rdkafka/consumer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Karafka
+  # Patches to external components
+  module Patches
+    # Rdkafka related patches
+    module Rdkafka
+      # Rdkafka::Consumer patches
+      module Consumer
+        # A method that allows us to get the native kafka producer name
+        # @return [String] producer instance name
+        # @note We need this to make sure that we allocate proper dispatched events only to
+        #   callback listeners that should publish them
+        def name
+          @name ||= ::Rdkafka::Bindings.rd_kafka_name(@native_kafka)
+        end
+      end
+    end
+  end
+end
+
+::Rdkafka::Consumer.include ::Karafka::Patches::Rdkafka::Consumer

data/lib/karafka/pro/active_job/consumer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# This Karafka component is a Pro component.
+# All of the commercial components are present in the lib/karafka/pro directory of this
+# repository and their usage requires commercial license agreement.
+#
+# Karafka has also commercial-friendly license, commercial support and commercial components.
+#
+# By sending a pull request to the pro components, you are agreeing to transfer the copyright of
+# your code to Maciej Mensfeld.
+
+module Karafka
+  module Pro
+    module ActiveJob
+      # Pro ActiveJob consumer that is suppose to handle long-running jobs as well as short
+      # running jobs
+      #
+      # When in LRJ, it will pause a given partition forever and will resume its processing only
+      # when all the jobs are done processing.
+      #
+      # It contains slightly better revocation warranties than the regular blocking consumer as
+      # it can stop processing batch of jobs in the middle after the revocation.
+      class Consumer < Karafka::Pro::BaseConsumer
+        # Runs ActiveJob jobs processing and handles lrj if needed
+        def consume
+          messages.each do |message|
+            # If for any reason we've lost this partition, not worth iterating over new messages
+            # as they are no longer ours
+            break if revoked?
+            break if Karafka::App.stopping?
+
+            ::ActiveJob::Base.execute(
+              ::ActiveSupport::JSON.decode(message.raw_payload)
+            )
+
+            # We cannot mark jobs as done after each if there are virtual partitions. Otherwise
+            # this could create random markings
+            next if topic.virtual_partitioner?
+
+            mark_as_consumed(message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karafka/pro/active_job/dispatcher.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# This Karafka component is a Pro component.
+# All of the commercial components are present in the lib/karafka/pro directory of this
+# repository and their usage requires commercial license agreement.
+#
+# Karafka has also commercial-friendly license, commercial support and commercial components.
+#
+# By sending a pull request to the pro components, you are agreeing to transfer the copyright of
+# your code to Maciej Mensfeld.
+
+module Karafka
+  module Pro
+    # Karafka Pro ActiveJob components
+    module ActiveJob
+      # Pro dispatcher that sends the ActiveJob job to a proper topic based on the queue name
+      # and that allows to inject additional options into the producer, effectively allowing for a
+      # much better and more granular control over the dispatch and consumption process.
+      class Dispatcher < ::Karafka::ActiveJob::Dispatcher
+        # Defaults for dispatching
+        # They can be updated by using `#karafka_options` on the job
+        DEFAULTS = {
+          dispatch_method: :produce_async,
+          # We don't create a dummy proc based partitioner as we would have to evaluate it with
+          # each job.
+          partitioner: nil,
+          # Allows for usage of `:key` or `:partition_key`
+          partition_key_type: :key
+        }.freeze
+
+        private_constant :DEFAULTS
+
+        # @param job [ActiveJob::Base] job
+        def call(job)
+          ::Karafka.producer.public_send(
+            fetch_option(job, :dispatch_method, DEFAULTS),
+            dispatch_details(job).merge!(
+              topic: job.queue_name,
+              payload: ::ActiveSupport::JSON.encode(job.serialize)
+            )
+          )
+        end
+
+        private
+
+        # @param job [ActiveJob::Base] job instance
+        # @return [Hash] hash with dispatch details to which we merge topic and payload
+        def dispatch_details(job)
+          partitioner = fetch_option(job, :partitioner, DEFAULTS)
+          key_type = fetch_option(job, :partition_key_type, DEFAULTS)
+
+          return {} unless partitioner
+
+          {
+            key_type => partitioner.call(job)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/karafka/pro/active_job/job_options_contract.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# This Karafka component is a Pro component.
+# All of the commercial components are present in the lib/karafka/pro directory of this
+# repository and their usage requires commercial license agreement.
+#
+# Karafka has also commercial-friendly license, commercial support and commercial components.
+#
+# By sending a pull request to the pro components, you are agreeing to transfer the copyright of
+# your code to Maciej Mensfeld.
+
+module Karafka
+  module Pro
+    module ActiveJob
+      # Contract for validating the options that can be altered with `#karafka_options` per job
+      # class that works with Pro features.
+      class JobOptionsContract < Contracts::Base
+        configure do |config|
+          config.error_messages = YAML.safe_load(
+            File.read(
+              File.join(Karafka.gem_root, 'config', 'errors.yml')
+            )
+          ).fetch('en').fetch('validations').fetch('job_options')
+        end
+
+        optional(:dispatch_method) { |val| %i[produce_async produce_sync].include?(val) }
+        optional(:partitioner) { |val| val.respond_to?(:call) }
+        optional(:partition_key_type) { |val| %i[key partition_key].include?(val) }
+      end
+    end
+  end
+end

data/lib/karafka/pro/base_consumer.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# This Karafka component is a Pro component.
+# All of the commercial components are present in the lib/karafka/pro directory of this
+# repository and their usage requires commercial license agreement.
+#
+# Karafka has also commercial-friendly license, commercial support and commercial components.
+#
+# By sending a pull request to the pro components, you are agreeing to transfer the copyright of
+# your code to Maciej Mensfeld.
+
+module Karafka
+  module Pro
+    # Karafka PRO consumer.
+    #
+    # If you use PRO, all your consumers should inherit (indirectly) from it.
+    #
+    # @note In case of using lrj, manual pausing may not be the best idea as resume needs to happen
+    #   after each batch is processed.
+    class BaseConsumer < Karafka::BaseConsumer
+      # Pause for tops 31 years
+      MAX_PAUSE_TIME = 1_000_000_000_000
+
+      private_constant :MAX_PAUSE_TIME
+
+      # Pauses processing of a given partition until we're done with the processing
+      # This ensures, that we can easily poll not reaching the `max.poll.interval`
+      def on_before_consume
+        return unless topic.long_running_job?
+
+        # This ensures, that when running LRJ with VP, things operate as expected
+        coordinator.on_started do |first_group_message|
+          # Pause at the first message in a batch. That way in case of a crash, we will not loose
+          # any messages
+          pause(first_group_message.offset, MAX_PAUSE_TIME)
+        end
+      end
+
+      # Runs extra logic after consumption that is related to handling long-running jobs
+      # @note This overwrites the '#on_after_consume' from the base consumer
+      def on_after_consume
+        coordinator.on_finished do |first_group_message, last_group_message|
+          on_after_consume_regular(first_group_message, last_group_message)
+        end
+      end
+
+      private
+
+      # Handles the post-consumption flow depending on topic settings
+      #
+      # @param first_message [Karafka::Messages::Message]
+      # @param last_message [Karafka::Messages::Message]
+      def on_after_consume_regular(first_message, last_message)
+        if coordinator.success?
+          coordinator.pause_tracker.reset
+
+          # We use the non-blocking one here. If someone needs the blocking one, can implement it
+          # with manual offset management
+          # Mark as consumed only if manual offset management is not on
+          mark_as_consumed(last_message) unless topic.manual_offset_management? || revoked?
+
+          # If this is not a long-running job there is nothing for us to do here
+          return unless topic.long_running_job?
+
+          # Once processing is done, we move to the new offset based on commits
+          # Here, in case manual offset management is off, we have the new proper offset of a
+          # first message from another batch from `@seek_offset`. If manual offset management
+          # is on, we move to place where the user indicated it was finished. This can create an
+          # interesting (yet valid) corner case, where with manual offset management on and no
+          # marking as consumed, we end up with an infinite loop processing same messages over and
+          # over again
+          seek(@seek_offset || first_message.offset)
+
+          resume
+        else
+          # If processing failed, we need to pause
+          pause(@seek_offset || first_message.offset)
+        end
+      end
+    end
+  end
+end

data/lib/karafka/pro/contracts/base.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# This Karafka component is a Pro component.
+# All of the commercial components are present in the lib/karafka/pro directory of this
+# repository and their usage requires commercial license agreement.
+#
+# Karafka has also commercial-friendly license, commercial support and commercial components.
+#
+# By sending a pull request to the pro components, you are agreeing to transfer the copyright of
+# your code to Maciej Mensfeld.
+
+module Karafka
+  module Pro
+    # Namespace for Karafka Pro related contracts
+    module Contracts
+      # Base contract for Pro components contracts
+      class Base < ::Karafka::Contracts::Base
+      end
+    end
+  end
+end