waterdrop 2.8.13 → 2.8.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da869aec5fa217a2adda674c787dd142a4f4e50e99a9b86d349d42f700821c88
-  data.tar.gz: 1934d9b60db038b6ea2f99faf7961a5f3ea2b3dfe845f84632db7f145f094cd2
+  metadata.gz: 57d1e899a312c47c5101a9029914468881e0ebb9437926767078c37f1ce1b4d1
+  data.tar.gz: 1767c8a557324bb5bccf93d79847705ecdbe1587d5ff97210597c41ee9cfa0d4
 SHA512:
-  metadata.gz: c25b0221d070e1ba2b9badcff468caad02d4f4da158083a3514aa8a4d2b5b867579d6bebdaa35f45416c97de6bdddcb9c080a9d5399bca7f509e26e9f1775140
-  data.tar.gz: d2c32960c72034b00a48d3cd5b7ab30e12908638945f08aa69ddd27947b98cf38b9b3b0d3ccf78b02ce25b569a5ad551d1bedcbaf40b06df0b1caa7565567b56
+  metadata.gz: 5286d33cd2bf81f947ddb8c08c77b580aba8ff818f1e01431df36ae31dfbaf7984d3720e4463e1e9551379630fcfc6bcff161e5502d4b9bfa583c913ca050f7c
+  data.tar.gz: 7365a54e15b397d1c108db6949c6048c3c7e125b2063f2483e13c4ed6d38f961faaeed101a280cb5b9ef4c8d21335fb429e764c5939dbcf558eebc35aa21f3db

data/.github/workflows/ci.yml

@@ -110,6 +110,21 @@ jobs:
       - name: Run Coditsu
         run: ./coditsu_script.sh
 
+  yard-lint:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@2a7b30092b0caf9c046252510f9273b4875f3db9 # v1.254.0
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+      - name: Run yard-lint
+        run: bundle exec yard-lint lib/
+
   ci-success:
     name: CI Success
     runs-on: ubuntu-latest
@@ -117,6 +132,7 @@ jobs:
     needs:
       - coditsu
       - specs
+      - yard-lint
     steps:
       - name: Check all jobs passed
         if: |

data/.yard-lint.yml

@@ -0,0 +1,174 @@
+# YARD-Lint Configuration
+# See https://github.com/mensfeld/yard-lint for documentation
+
+# Global settings for all validators
+AllValidators:
+  # YARD command-line options (applied to all validators by default)
+  YardOptions:
+    - --private
+    - --protected
+
+  # Global file exclusion patterns
+  Exclude:
+    - '\.git'
+    - 'vendor/**/*'
+    - 'node_modules/**/*'
+    - 'spec/**/*'
+    - 'test/**/*'
+
+  # Exit code behavior (error, warning, convention, never)
+  FailOnSeverity: error
+
+  # Minimum documentation coverage percentage (0-100)
+  # Fails if coverage is below this threshold
+  MinCoverage: 100
+
+  # Diff mode settings
+  DiffMode:
+    # Default base ref for --diff (auto-detects main/master if not specified)
+    DefaultBaseRef: ~
+
+# Documentation validators
+Documentation/UndocumentedObjects:
+  Description: 'Checks for classes, modules, and methods without documentation.'
+  Enabled: true
+  Severity: error
+  ExcludedMethods:
+    - 'initialize/0'  # Exclude parameter-less initialize
+    - '/^_/'          # Exclude private methods (by convention)
+
+Documentation/UndocumentedMethodArguments:
+  Description: 'Checks for method parameters without @param tags.'
+  Enabled: true
+  Severity: error
+
+Documentation/UndocumentedBooleanMethods:
+  Description: 'Checks that question mark methods document their boolean return.'
+  Enabled: true
+  Severity: error
+
+Documentation/UndocumentedOptions:
+  Description: 'Detects methods with options hash parameters but no @option tags.'
+  Enabled: true
+  Severity: error
+
+Documentation/MarkdownSyntax:
+  Description: 'Detects common markdown syntax errors in documentation.'
+  Enabled: true
+  Severity: error
+
+# Tags validators
+Tags/Order:
+  Description: 'Enforces consistent ordering of YARD tags.'
+  Enabled: true
+  Severity: error
+  EnforcedOrder:
+    - param
+    - option
+    - return
+    - raise
+    - example
+
+Tags/InvalidTypes:
+  Description: 'Validates type definitions in @param, @return, @option tags.'
+  Enabled: true
+  Severity: error
+  ValidatedTags:
+    - param
+    - option
+    - return
+
+Tags/TypeSyntax:
+  Description: 'Validates YARD type syntax using YARD parser.'
+  Enabled: true
+  Severity: error
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/MeaninglessTag:
+  Description: 'Detects @param/@option tags on classes, modules, or constants.'
+  Enabled: true
+  Severity: error
+  CheckedTags:
+    - param
+    - option
+  InvalidObjectTypes:
+    - class
+    - module
+    - constant
+
+Tags/CollectionType:
+  Description: 'Validates Hash collection syntax consistency.'
+  Enabled: true
+  Severity: error
+  EnforcedStyle: long  # 'long' for Hash{K => V} (YARD standard), 'short' for {K => V}
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/TagTypePosition:
+  Description: 'Validates type annotation position in tags.'
+  Enabled: true
+  Severity: error
+  CheckedTags:
+    - param
+    - option
+  # EnforcedStyle: 'type_after_name' (YARD standard: @param name [Type])
+  #                or 'type_first' (@param [Type] name)
+  EnforcedStyle: type_after_name
+
+Tags/ApiTags:
+  Description: 'Enforces @api tags on public objects.'
+  Enabled: false  # Opt-in validator
+  Severity: error
+  AllowedApis:
+    - public
+    - private
+    - internal
+
+Tags/OptionTags:
+  Description: 'Requires @option tags for methods with options parameters.'
+  Enabled: true
+  Severity: error
+
+# Warnings validators - catches YARD parser errors
+Warnings/UnknownTag:
+  Description: 'Detects unknown YARD tags.'
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownDirective:
+  Description: 'Detects unknown YARD directives.'
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidTagFormat:
+  Description: 'Detects malformed tag syntax.'
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidDirectiveFormat:
+  Description: 'Detects malformed directive syntax.'
+  Enabled: true
+  Severity: error
+
+Warnings/DuplicatedParameterName:
+  Description: 'Detects duplicate @param tags.'
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownParameterName:
+  Description: 'Detects @param tags for non-existent parameters.'
+  Enabled: true
+  Severity: error
+
+# Semantic validators
+Semantic/AbstractMethods:
+  Description: 'Ensures @abstract methods do not have real implementations.'
+  Enabled: true
+  Severity: error

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # WaterDrop changelog
 
+## 2.8.14 (2025-11-14)
+- [Fix] Fatal error replacement not working without exact error unwind from the fatal envelope
+- [Testing] Add `WaterDrop::Producer::Testing` module for injecting and querying librdkafka fatal errors in tests.
+- [Testing] Add `#trigger_test_fatal_error(error_code, reason)` method to simulate fatal errors without requiring actual broker-side conditions.
+- [Testing] Add `#fatal_error` method to query current fatal error state for validation in tests.
+- [Testing] Add comprehensive test coverage for fatal error injection, reload behavior, and event instrumentation with real librdkafka errors.
+- [Change] Require `karafka-rdkafka` `>=` `0.23.1` due to error handling fixes.
+
 ## 2.8.13 (2025-10-31)
 - [Enhancement] Make `fenced` error skip-reload behavior configurable via new `non_reloadable_errors` setting (defaults to `[:fenced]` for backward compatibility).
 - [Enhancement] Add `producer.reload` event allowing config modification before reload to escape fencing loops (#706).

data/Gemfile

@@ -17,4 +17,5 @@ group :test do
   gem 'rspec'
   gem 'simplecov'
   gem 'warning'
+  gem 'yard-lint'
 end

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    waterdrop (2.8.13)
+    waterdrop (2.8.14)
       karafka-core (>= 2.4.9, < 3.0.0)
-      karafka-rdkafka (>= 0.20.0)
+      karafka-rdkafka (>= 0.23.1)
       zeitwerk (~> 2.3)
 
 GEM
@@ -28,32 +28,32 @@ GEM
     karafka-core (2.5.7)
       karafka-rdkafka (>= 0.20.0)
       logger (>= 1.6.0)
-    karafka-rdkafka (0.22.2)
-      ffi (~> 1.15)
+    karafka-rdkafka (0.23.1)
+      ffi (~> 1.17.1)
       json (> 2.0)
       logger
       mini_portile2 (~> 2.6)
       rake (> 12)
-    karafka-rdkafka (0.22.2-aarch64-linux-gnu)
-      ffi (~> 1.15)
+    karafka-rdkafka (0.23.1-aarch64-linux-gnu)
+      ffi (~> 1.17.1)
       json (> 2.0)
       logger
       mini_portile2 (~> 2.6)
       rake (> 12)
-    karafka-rdkafka (0.22.2-arm64-darwin)
-      ffi (~> 1.15)
+    karafka-rdkafka (0.23.1-arm64-darwin)
+      ffi (~> 1.17.1)
       json (> 2.0)
       logger
       mini_portile2 (~> 2.6)
       rake (> 12)
-    karafka-rdkafka (0.22.2-x86_64-linux-gnu)
-      ffi (~> 1.15)
+    karafka-rdkafka (0.23.1-x86_64-linux-gnu)
+      ffi (~> 1.17.1)
       json (> 2.0)
       logger
       mini_portile2 (~> 2.6)
       rake (> 12)
-    karafka-rdkafka (0.22.2-x86_64-linux-musl)
-      ffi (~> 1.15)
+    karafka-rdkafka (0.23.1-x86_64-linux-musl)
+      ffi (~> 1.17.1)
       json (> 2.0)
       logger
       mini_portile2 (~> 2.6)
@@ -82,6 +82,10 @@ GEM
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
     warning (1.5.0)
+    yard (0.9.37)
+    yard-lint (1.2.3)
+      yard (~> 0.9)
+      zeitwerk (~> 2.6)
     zeitwerk (2.7.3)
 
 PLATFORMS
@@ -105,6 +109,7 @@ DEPENDENCIES
   simplecov
   warning
   waterdrop!
+  yard-lint
   zeitwerk (~> 2.7.0)
 
 BUNDLED WITH

data/lib/waterdrop/clients/dummy.rb

@@ -49,6 +49,9 @@ module WaterDrop
       # @param topic [String, Symbol] topic where we want to dispatch message
       # @param partition [Integer] target partition
       # @param _args [Hash] remaining details that are ignored in the dummy mode
+      # @option _args [String] :payload message payload
+      # @option _args [String, nil] :key message key
+      # @option _args [Hash, nil] :headers message headers
       # @return [Handle] delivery handle
       def produce(topic:, partition: 0, **_args)
         Handle.new(topic.to_s, partition, @counters["#{topic}#{partition}"] += 1)

data/lib/waterdrop/helpers/counter.rb

@@ -8,6 +8,7 @@ module WaterDrop
       # @return [Integer] current value
       attr_reader :value
 
+      # Creates a new counter initialized to 0
       def initialize
         @value = 0
         @mutex = Mutex.new

data/lib/waterdrop/instrumentation/callbacks/delivery.rb

@@ -22,7 +22,7 @@ module WaterDrop
 
         private_constant :RD_KAFKA_RESP_PURGE_QUEUE, :RD_KAFKA_RESP_PURGE_INFLIGHT, :PURGE_ERRORS
 
-        # @param producer_id [String] id of the current producer
+        # @param producer_id [String]
         # @param transactional [Boolean] is this handle for a transactional or regular producer
         # @param monitor [WaterDrop::Instrumentation::Monitor] monitor we are using
         def initialize(producer_id, transactional, monitor)

data/lib/waterdrop/instrumentation/callbacks/error.rb

@@ -5,7 +5,7 @@ module WaterDrop
     module Callbacks
       # Callback that kicks in when error occurs and is published in a background thread
       class Error
-        # @param producer_id [String] id of the current producer
+        # @param producer_id [String]
         # @param client_name [String] rdkafka client name
         # @param monitor [WaterDrop::Instrumentation::Monitor] monitor we are using
         def initialize(producer_id, client_name, monitor)

data/lib/waterdrop/instrumentation/callbacks/statistics.rb

@@ -10,7 +10,7 @@ module WaterDrop
       #   previous statistics emit but from the beginning of the process. We decorate it with diff
       #   of all the numeric values against the data from the previous callback emit
       class Statistics
-        # @param producer_id [String] id of the current producer
+        # @param producer_id [String]
         # @param client_name [String] rdkafka client name
         # @param monitor [WaterDrop::Instrumentation::Monitor] monitor we are using
         def initialize(producer_id, client_name, monitor)

data/lib/waterdrop/middleware.rb

@@ -3,6 +3,7 @@
 module WaterDrop
   # Simple middleware layer for manipulating messages prior to their validation
   class Middleware
+    # Creates a new middleware chain with no registered steps
     def initialize
       @mutex = Mutex.new
       @steps = []

data/lib/waterdrop/producer/testing.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module WaterDrop
+  class Producer
+    # Testing utilities for WaterDrop Producer instances.
+    #
+    # This module provides methods for triggering and querying fatal errors on producers,
+    # which is useful for testing error handling and recovery logic (such as automatic
+    # producer reloading on fatal errors).
+    #
+    # @note This module should only be used in test environments.
+    # @note Requires karafka-rdkafka >= 0.23.1 which includes Rdkafka::Testing support.
+    # @note This module is not auto-loaded by Zeitwerk and must be manually required.
+    #
+    # @example Including for a single producer instance
+    #   require 'waterdrop/producer/testing'
+    #
+    #   producer = WaterDrop::Producer.new
+    #   producer.singleton_class.include(WaterDrop::Producer::Testing)
+    #   producer.trigger_test_fatal_error(47, "Test producer fencing")
+    #
+    # @example Including for all producers in a test suite
+    #   # In spec_helper.rb or test setup:
+    #   require 'waterdrop/producer/testing'
+    #
+    #   WaterDrop::Producer.include(WaterDrop::Producer::Testing)
+    #
+    # @example Testing idempotent producer reload on fatal error
+    #   producer = WaterDrop::Producer.new do |config|
+    #     config.kafka = { 'bootstrap.servers': 'localhost:9092' }
+    #     config.reload_on_idempotent_fatal_error = true
+    #   end
+    #   producer.singleton_class.include(WaterDrop::Producer::Testing)
+    #
+    #   # Trigger a fatal error that should cause reload
+    #   producer.trigger_test_fatal_error(47, "Invalid producer epoch")
+    #
+    #   # Produce should succeed after automatic reload
+    #   producer.produce_sync(topic: 'test', payload: 'message')
+    #
+    #   # Fatal error should be cleared after reload
+    #   expect(producer.fatal_error).to be_nil
+    module Testing
+      # Triggers a test fatal error on the underlying rdkafka producer.
+      #
+      # This method uses librdkafka's test error injection functionality to simulate
+      # fatal errors without requiring actual error conditions. This is particularly
+      # useful for testing WaterDrop's fatal error handling and automatic reload logic.
+      #
+      # @param error_code [Integer] The librdkafka error code to trigger.
+      #   Common error codes for testing:
+      #   - 47 (RD_KAFKA_RESP_ERR_INVALID_PRODUCER_EPOCH) - Producer fencing
+      #   - 64 (RD_KAFKA_RESP_ERR_INVALID_PRODUCER_ID_MAPPING) - Invalid producer ID
+      # @param reason [String] A descriptive reason for the error, used for debugging
+      #   and logging purposes
+      #
+      # @return [Integer] Result code from rd_kafka_test_fatal_error (0 on success)
+      #
+      # @raise [RuntimeError] If the underlying rdkafka client doesn't support testing
+      #
+      # @example Trigger producer fencing error
+      #   producer.trigger_test_fatal_error(47, "Test producer fencing scenario")
+      #
+      # @example Trigger invalid producer ID error
+      #   producer.trigger_test_fatal_error(64, "Test invalid producer ID mapping")
+      def trigger_test_fatal_error(error_code, reason)
+        ensure_testing_support!
+        client.trigger_test_fatal_error(error_code, reason)
+      end
+
+      # Checks if a fatal error has occurred on the underlying rdkafka producer.
+      #
+      # This method queries librdkafka's fatal error state to retrieve information
+      # about any fatal error that has occurred. Fatal errors are serious errors that
+      # prevent the producer from continuing normal operation.
+      #
+      # @return [Hash, nil] A hash containing error details if a fatal error occurred,
+      #   or nil if no fatal error is present. The hash contains:
+      #   - :error_code [Integer] The librdkafka error code
+      #   - :error_string [String] Human-readable error description
+      #
+      # @example Check for fatal error
+      #   if error = producer.fatal_error
+      #     puts "Fatal error #{error[:error_code]}: #{error[:error_string]}"
+      #   else
+      #     puts "No fatal error present"
+      #   end
+      #
+      # @example Verify fatal error after triggering
+      #   producer.trigger_test_fatal_error(47, "Test error")
+      #   error = producer.fatal_error
+      #   expect(error[:error_code]).to eq(47)
+      def fatal_error
+        ensure_testing_support!
+        client.fatal_error
+      end
+
+      private
+
+      # Ensures the underlying rdkafka client has testing support available.
+      # Automatically requires and includes Rdkafka::Testing if not already present.
+      #
+      # @return [void]
+      # @api private
+      def ensure_testing_support!
+        return if client.respond_to?(:trigger_test_fatal_error)
+
+        # Require the rdkafka testing module if not already loaded
+        require 'rdkafka/producer/testing' unless defined?(::Rdkafka::Testing)
+
+        client.singleton_class.include(::Rdkafka::Testing)
+      end
+    end
+  end
+end

data/lib/waterdrop/producer.rb

@@ -205,8 +205,13 @@ module WaterDrop
 
     # Builds the variant alteration and returns it.
     #
-    # @param args [Object] anything `Producer::Variant` initializer accepts
+    # @param args [Hash] variant configuration options
+    # @option args [Integer, nil] :max_wait_timeout alteration to max wait timeout or nil to use
+    #   default
+    # @option args [Hash] :topic_config extra topic configuration that can be altered
+    # @option args [Boolean] :default is this a default variant or an altered one
     # @return [WaterDrop::Producer::Variant] variant proxy to use with alterations
+    # @see https://karafka.io/docs/Librdkafka-Configuration/#topic-configuration-properties
     def with(**args)
       ensure_active!
 

data/lib/waterdrop/version.rb

@@ -3,5 +3,5 @@
 # WaterDrop library
 module WaterDrop
   # Current WaterDrop version
-  VERSION = '2.8.13'
+  VERSION = '2.8.14'
 end

data/lib/waterdrop.rb

@@ -42,5 +42,7 @@ loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect('waterdrop' => 'WaterDrop')
 # Do not load vendors instrumentation components. Those need to be required manually if needed
 loader.ignore("#{__dir__}/waterdrop/instrumentation/vendors/**/*.rb")
+# Do not load testing components. Those need to be required manually in test environments
+loader.ignore("#{__dir__}/waterdrop/producer/testing.rb")
 loader.setup
 loader.eager_load

data/waterdrop.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
   spec.licenses      = %w[LGPL-3.0-only Commercial]
 
   spec.add_dependency 'karafka-core', '>= 2.4.9', '< 3.0.0'
-  spec.add_dependency 'karafka-rdkafka', '>= 0.20.0'
+  spec.add_dependency 'karafka-rdkafka', '>= 0.23.1'
   spec.add_dependency 'zeitwerk', '~> 2.3'
 
   spec.required_ruby_version = '>= 3.2.0'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: waterdrop
 version: !ruby/object:Gem::Version
-  version: 2.8.13
+  version: 2.8.14
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -35,14 +35,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.20.0
+        version: 0.23.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.20.0
+        version: 0.23.1
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -77,6 +77,7 @@ files:
 - ".rspec"
 - ".ruby-gemset"
 - ".ruby-version"
+- ".yard-lint.yml"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -122,6 +123,7 @@ files:
 - lib/waterdrop/producer/idempotence.rb
 - lib/waterdrop/producer/status.rb
 - lib/waterdrop/producer/sync.rb
+- lib/waterdrop/producer/testing.rb
 - lib/waterdrop/producer/transactions.rb
 - lib/waterdrop/producer/variant.rb
 - lib/waterdrop/version.rb