waterdrop 1.4.2 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3264233762968462432ad2d4c37809289966e943908df7c8c08d9939d585e621
-  data.tar.gz: '079c4e36222105d110f7268dff2abb3cfbdab20a019963a80552555d084f20ae'
+  metadata.gz: 24189103d7583fac3c911f4b32244655ffa2cd1b5a95abe0e73dbd4344530c5b
+  data.tar.gz: b4f5c0e95af559e0a0a929d14a3b56b39c4da5edc9b1d9ffe995e8b1852d9c14
 SHA512:
-  metadata.gz: 7b8759d6f7c7d3b7bb685ce725497e5b171bcc85efbdd3a5c5620c51b9a78d0c97715efe7f6ff2c3544fd39628a40122f5dbdc58164ba98355c789e487a4b4de
-  data.tar.gz: 38e8d05a29d782446865a203289757f68d4af23f0f63e161c429b96f87dd17cfeec0786f716c1ef71615e3b2136ef6a4b88e78d96c3a4396e39945b9e3a089a8
+  metadata.gz: bd49152ec9f6325cf58d9d470ed1ccfdb0c5b5d9a899bcdca289500ab56008b1153db35bf90f8e5e167692be8c79cd5bf96bbf66f9f515f97922bb217a0544d5
+  data.tar.gz: 32b36daf1f26227c58690fea5a6846c7599d1e8859e074ca3f2075cf0effa187cfbb4cb86a50ea22dfe169d3af54fd2e3232e14c569efcaa625f52166f227dbb

data/.github/workflows/ci.yml

@@ -17,8 +17,7 @@ jobs:
           - '3.0'
           - '2.7'
           - '2.6'
-          - '2.5'
-          - 'jruby'
+          - 'jruby-head'
         include:
           - ruby: '3.0'
             coverage: 'true'

data/.gitignore

@@ -4,6 +4,7 @@
 /vendor/ruby/
 /ruby/
 app.god
+example.rb
 
 # minimal Rails specific artifacts
 db/*.sqlite3
@@ -12,6 +13,7 @@ db/*.sqlite3
 *.gem
 *.~
 /.coditsu/local.yml
+.byebug_history
 
 # various artifacts
 **.war

data/.ruby-version

@@ -1 +1 @@
-3.0.0
+3.0.2

data/CHANGELOG.md

@@ -1,10 +1,22 @@
 # WaterDrop changelog
 
-## 1.4.2 (2021-03-30)
-- Additional 3.0 fixes (ojab)
-
-## 1.4.1 (2021-03-23)
-- Support for Ruby 3.0
+## 2.0.2 (2021-08-13)
+- Add support for `partition_key`
+- Switch license from `LGPL-3.0` to  `MIT`
+- Switch flushing on close to sync
+
+## 2.0.1 (2021-06-05)
+- Remove Ruby 2.5 support and update minimum Ruby requirement to 2.6
+- Fix the `finalizer references object to be finalized` warning issued with 3.0
+
+## 2.0.0 (2020-12-13)
+- Redesign of the whole API (see `README.md` for the use-cases and the current API)
+- Replace `ruby-kafka` with `rdkafka`
+- Switch license from `MIT` to `LGPL-3.0`
+- #113 - Add some basic validations of the kafka scope of the config (Azdaroth)
+- Global state removed
+- Redesigned metrics that use `rdkafka` internal data + custom diffing
+- Restore JRuby support
 
 ## 1.4.0 (2020-08-25)
 - Release to match Karafka 1.4 versioning.

data/Gemfile

@@ -2,9 +2,18 @@
 
 source 'https://rubygems.org'
 
+plugin 'diffend'
+
 gemspec
 
+gem 'rdkafka'
+
+group :development do
+  gem 'byebug'
+end
+
 group :test do
+  gem 'factory_bot'
   gem 'rspec'
   gem 'simplecov'
 end

data/Gemfile.lock

@@ -1,49 +1,49 @@
 PATH
   remote: .
   specs:
-    waterdrop (1.4.2)
-      delivery_boy (>= 0.2, < 2.x)
+    waterdrop (2.0.2)
+      concurrent-ruby (>= 1.1)
       dry-configurable (~> 0.8)
       dry-monitor (~> 0.3)
-      dry-validation (~> 1.2)
-      ruby-kafka (>= 0.7.8)
+      dry-validation (~> 1.3)
+      rdkafka (>= 0.6.0)
       zeitwerk (~> 2.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    concurrent-ruby (1.1.8)
-    delivery_boy (1.1.0)
-      king_konf (~> 1.0)
-      ruby-kafka (~> 1.0)
+    activesupport (6.1.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    byebug (11.1.3)
+    concurrent-ruby (1.1.9)
     diff-lcs (1.4.4)
-    digest-crc (0.6.3)
-      rake (>= 12.0.0, < 14.0.0)
-    docile (1.3.5)
+    docile (1.4.0)
     dry-configurable (0.12.1)
       concurrent-ruby (~> 1.0)
       dry-core (~> 0.5, >= 0.5.0)
-    dry-container (0.7.2)
+    dry-container (0.8.0)
       concurrent-ruby (~> 1.0)
       dry-configurable (~> 0.1, >= 0.1.3)
-    dry-core (0.5.0)
+    dry-core (0.7.1)
       concurrent-ruby (~> 1.0)
     dry-equalizer (0.3.0)
-    dry-events (0.2.0)
+    dry-events (0.3.0)
       concurrent-ruby (~> 1.0)
-      dry-core (~> 0.4)
-      dry-equalizer (~> 0.2)
-    dry-inflector (0.2.0)
+      dry-core (~> 0.5, >= 0.5)
+    dry-inflector (0.2.1)
     dry-initializer (3.0.4)
-    dry-logic (1.1.0)
+    dry-logic (1.2.0)
       concurrent-ruby (~> 1.0)
       dry-core (~> 0.5, >= 0.5)
-    dry-monitor (0.3.2)
+    dry-monitor (0.4.0)
       dry-configurable (~> 0.5)
-      dry-core (~> 0.4)
-      dry-equalizer (~> 0.2)
+      dry-core (~> 0.5, >= 0.5)
       dry-events (~> 0.2)
-    dry-schema (1.6.1)
+    dry-schema (1.7.0)
       concurrent-ruby (~> 1.0)
       dry-configurable (~> 0.8, >= 0.8.3)
       dry-core (~> 0.5, >= 0.5)
@@ -63,8 +63,18 @@ GEM
       dry-equalizer (~> 0.2)
       dry-initializer (~> 3.0)
       dry-schema (~> 1.5, >= 1.5.2)
-    king_konf (1.0.0)
-    rake (13.0.3)
+    factory_bot (6.2.0)
+      activesupport (>= 5.0.0)
+    ffi (1.15.3)
+    i18n (1.8.10)
+      concurrent-ruby (~> 1.0)
+    mini_portile2 (2.6.1)
+    minitest (5.14.4)
+    rake (13.0.6)
+    rdkafka (0.9.0)
+      ffi (~> 1.9)
+      mini_portile2 (~> 2.1)
+      rake (>= 12.3)
     rspec (3.10.0)
       rspec-core (~> 3.10.0)
       rspec-expectations (~> 3.10.0)
@@ -78,24 +88,27 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
     rspec-support (3.10.2)
-    ruby-kafka (1.3.0)
-      digest-crc
     simplecov (0.21.2)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
-    simplecov_json_formatter (0.1.2)
+    simplecov_json_formatter (0.1.3)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
     zeitwerk (2.4.2)
 
 PLATFORMS
-  x86_64-darwin-19
+  x86_64-darwin
   x86_64-linux
 
 DEPENDENCIES
+  byebug
+  factory_bot
+  rdkafka
   rspec
   simplecov
   waterdrop!
 
 BUNDLED WITH
-   2.2.15
+   2.2.25

data/README.md

@@ -1,17 +1,45 @@
 # WaterDrop
 
-[![Build Status](https://travis-ci.org/karafka/waterdrop.svg)](https://travis-ci.org/karafka/waterdrop)
-[![Join the chat at https://gitter.im/karafka/karafka](https://badges.gitter.im/karafka/karafka.svg)](https://gitter.im/karafka/karafka?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+**Note**: Documentation presented here refers to WaterDrop `2.0.0`.
 
-Gem used to send messages to Kafka in an easy way with an extra validation layer. It is a part of the [Karafka](https://github.com/karafka/karafka) ecosystem.
+WaterDrop `2.0` does **not** work with Karafka `1.*` and aims to either work as a standalone producer outside of Karafka `1.*` ecosystem or as a part of not yet released Karafka `2.0.*`.
+
+Please refer to [this](https://github.com/karafka/waterdrop/tree/1.4) branch and its documentation for details about WaterDrop `1.*` usage.
 
-WaterDrop is based on Zendesks [delivery_boy](https://github.com/zendesk/delivery_boy) gem.
+[![Build Status](https://github.com/karafka/waterdrop/workflows/ci/badge.svg)](https://github.com/karafka/waterdrop/actions?query=workflow%3Aci)
+[![Gem Version](https://badge.fury.io/rb/waterdrop.svg)](http://badge.fury.io/rb/waterdrop)
+[![Join the chat at https://gitter.im/karafka/karafka](https://badges.gitter.im/karafka/karafka.svg)](https://gitter.im/karafka/karafka)
 
-It is:
+Gem used to send messages to Kafka in an easy way with an extra validation layer. It is a part of the [Karafka](https://github.com/karafka/karafka) ecosystem.
 
- - Thread safe
- - Supports sync and async producers
- - Working with 0.11+ Kafka
+It:
+
+ - Is thread safe
+ - Supports sync producing
+ - Supports async producing
+ - Supports buffering
+ - Supports producing messages to multiple clusters
+ - Supports multiple delivery policies
+ - Works with Kafka 1.0+ and Ruby 2.6+
+
+## Table of contents
+
+- [WaterDrop](#waterdrop)
+  * [Table of contents](#table-of-contents)
+  * [Installation](#installation)
+  * [Setup](#setup)
+    + [WaterDrop configuration options](#waterdrop-configuration-options)
+    + [Kafka configuration options](#kafka-configuration-options)
+  * [Usage](#usage)
+    + [Basic usage](#basic-usage)
+    + [Buffering](#buffering)
+      - [Using WaterDrop to buffer messages based on the application logic](#using-waterdrop-to-buffer-messages-based-on-the-application-logic)
+      - [Using WaterDrop with rdkafka buffers to achieve periodic auto-flushing](#using-waterdrop-with-rdkafka-buffers-to-achieve-periodic-auto-flushing)
+  * [Instrumentation](#instrumentation)
+    + [Usage statistics](#usage-statistics)
+    + [Forking and potential memory problems](#forking-and-potential-memory-problems)
+  * [References](#references)
+  * [Note on contributions](#note-on-contributions)
 
 ## Installation
 
@@ -35,83 +63,244 @@ bundle install
 
 WaterDrop is a complex tool, that contains multiple configuration options. To keep everything organized, all the configuration options were divided into two groups:
 
-- WaterDrop options - options directly related to Karafka framework and it's components
-- Ruby-Kafka driver options - options related to Ruby-Kafka/Delivery boy
+- WaterDrop options - options directly related to WaterDrop and its components
+- Kafka driver options - options related to `rdkafka`
+
+To apply all those configuration options, you need to create a producer instance and use the ```#setup``` method:
+
+```ruby
+producer = WaterDrop::Producer.new
+
+producer.setup do |config|
+  config.deliver = true
+  config.kafka = {
+    'bootstrap.servers': 'localhost:9092',
+    'request.required.acks': 1
+  }
+end
+```
 
-To apply all those configuration options, you need to use the ```#setup``` method:
+or you can do the same while initializing the producer:
 
 ```ruby
-WaterDrop.setup do |config|
+producer = WaterDrop::Producer.new do |config|
   config.deliver = true
-  config.kafka.seed_brokers = %w[kafka://localhost:9092]
+  config.kafka = {
+    'bootstrap.servers': 'localhost:9092',
+    'request.required.acks': 1
+  }
 end
 ```
 
 ### WaterDrop configuration options
 
-| Option                      | Description                                                      |
-|-----------------------------|------------------------------------------------------------------|
-| client_id                   | This is how the client will identify itself to the Kafka brokers |
-| logger                      | Logger that we want to use                                       |
-| deliver                     | Should we send messages to Kafka                                 |
+| Option             | Description                                                     |
+|--------------------|-----------------------------------------------------------------|
+| `id`               | id of the producer for instrumentation and logging              |
+| `logger`           | Logger that we want to use                                      |
+| `deliver`          | Should we send messages to Kafka or just fake the delivery      |
+| `max_wait_timeout` | Waits that long for the delivery report or raises an error      |
+| `wait_timeout`     | Waits that long before re-check of delivery report availability |
 
-### Ruby-Kafka driver and Delivery boy configuration options
+### Kafka configuration options
 
-**Note:** We've listed here only **the most important** configuration options. If you're interested in all the options, please go to the [config.rb](https://github.com/karafka/waterdrop/blob/master/lib/water_drop/config.rb) file for more details.
+You can create producers with different `kafka` settings. Documentation of the available configuration options is available on https://github.com/edenhill/librdkafka/blob/master/CONFIGURATION.md.
 
-**Note:** All the options are subject to validations. In order to check what is and what is not acceptable, please go to the [config.rb validation schema](https://github.com/karafka/waterdrop/blob/master/lib/water_drop/schemas/config.rb) file.
+## Usage
+
+Please refer to the [documentation](https://www.rubydoc.info/gems/waterdrop) in case you're interested in the more advanced API.
 
-| Option                   | Description                                                                                                                                           |
-|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
-| raise_on_buffer_overflow | Should we raise an exception, when messages can't be sent in an async way due to the message buffer overflow or should we just drop them              |
-| delivery_interval        | The number of seconds between background message deliveries. Disable timer-based background deliveries by setting this to 0.                          |
-| delivery_threshold       | The number of buffered messages that will trigger a background message delivery. Disable buffer size based background deliveries by setting this to 0.|
-| required_acks            | The number of Kafka replicas that must acknowledge messages before they're considered as successfully written.                                        |
-| ack_timeout              | A timeout executed by a broker when the client is sending messages to it.                                                                             |
-| max_retries              | The number of retries when attempting to deliver messages.                                                                                            |
-| retry_backoff            | The number of seconds to wait after a failed attempt to send messages to a Kafka broker before retrying.                                              |
-| max_buffer_bytesize      | The maximum number of bytes allowed in the buffer before new messages are rejected.                                                                   |
-| max_buffer_size          | The maximum number of messages allowed in the buffer before new messages are rejected.                                                                |
-| max_queue_size           | The maximum number of messages allowed in the queue before new messages are rejected.                                                                 |
-| sasl_plain_username      | The username used to authenticate.                                                                                                                    |
-| sasl_plain_password      | The password used to authenticate.                                                                                                                    |
+### Basic usage
 
-This configuration can be also placed in *config/initializers* and can vary based on the environment:
+To send Kafka messages, just create a producer and use it:
 
 ```ruby
-WaterDrop.setup do |config|
-  config.deliver = Rails.env.production?
-  config.kafka.seed_brokers = [Rails.env.production? ? 'kafka://prod-host:9091' : 'kafka://localhost:9092']
+producer = WaterDrop::Producer.new
+
+producer.setup do |config|
+  config.kafka = { 'bootstrap.servers': 'localhost:9092' }
 end
+
+producer.produce_sync(topic: 'my-topic', payload: 'my message')
+
+# or for async
+producer.produce_async(topic: 'my-topic', payload: 'my message')
+
+# or in batches
+producer.produce_many_sync(
+  [
+    { topic: 'my-topic', payload: 'my message'},
+    { topic: 'my-topic', payload: 'my message'}
+  ]
+)
+
+# both sync and async
+producer.produce_many_async(
+  [
+    { topic: 'my-topic', payload: 'my message'},
+    { topic: 'my-topic', payload: 'my message'}
+  ]
+)
+
+# Don't forget to close the producer once you're done to flush the internal buffers, etc
+producer.close
 ```
 
-## Usage
+Each message that you want to publish, will have its value checked.
+
+Here are all the things you can provide in the message hash:
+
+| Option          | Required | Value type    | Description                                              |
+|-----------------|----------|---------------|----------------------------------------------------------|
+| `topic`         | true     | String        | The Kafka topic that should be written to                |
+| `payload`       | true     | String        | Data you want to send to Kafka                           |
+| `key`           | false    | String        | The key that should be set in the Kafka message          |
+| `partition`     | false    | Integer       | A specific partition number that should be written to    |
+| `partition_key` | false    | String        | Key to indicate the destination partition of the message |
+| `timestamp`     | false    | Time, Integer | The timestamp that should be set on the message          |
+| `headers`       | false    | Hash          | Headers for the message                                  |
 
-To send Kafka messages, just use one of the producers:
+Keep in mind, that message you want to send should be either binary or stringified (to_s, to_json, etc).
+
+### Buffering
+
+WaterDrop producers support buffering messages in their internal buffers and on the `rdkafka` level via `queue.buffering.*` set of settings.
+
+This means that depending on your use case, you can achieve both granular buffering and flushing control when needed with context awareness and periodic and size-based flushing functionalities.
+
+#### Using WaterDrop to buffer messages based on the application logic
 
 ```ruby
-WaterDrop::SyncProducer.call('message', topic: 'my-topic')
-# or for async
-WaterDrop::AsyncProducer.call('message', topic: 'my-topic')
+producer = WaterDrop::Producer.new
+
+producer.setup do |config|
+  config.kafka = { 'bootstrap.servers': 'localhost:9092' }
+end
+
+# Simulating some events states of a transaction - notice, that the messages will be flushed to
+# kafka only upon arrival of the `finished` state.
+%w[
+  started
+  processed
+  finished
+].each do |state|
+  producer.buffer(topic: 'events', payload: state)
+
+  puts "The messages buffer size #{producer.messages.size}"
+  producer.flush_sync if state == 'finished'
+  puts "The messages buffer size #{producer.messages.size}"
+end
+
+producer.close
 ```
 
-Both ```SyncProducer``` and ```AsyncProducer``` accept following options:
+#### Using WaterDrop with rdkafka buffers to achieve periodic auto-flushing
 
-| Option              | Required | Value type | Description                                                         |
-|-------------------- |----------|------------|---------------------------------------------------------------------|
-| ```topic```         | true     | String     | The Kafka topic that should be written to                           |
-| ```key```           | false    | String     | The key that should be set in the Kafka message                     |
-| ```partition```     | false    | Integer    | A specific partition number that should be written to               |
-| ```partition_key``` | false    | String     | A string that can be used to deterministically select the partition |
-| ```create_time```   | false    | Time       | The timestamp that should be set on the message                     |
-| ```headers```       | false    | Hash       | Headers for the message                                             |
+```ruby
+producer = WaterDrop::Producer.new
+
+producer.setup do |config|
+  config.kafka = {
+    'bootstrap.servers': 'localhost:9092',
+    # Accumulate messages for at most 10 seconds
+    'queue.buffering.max.ms' => 10_000
+  }
+end
 
-Keep in mind, that message you want to send should be either binary or stringified (to_s, to_json, etc).
+# WaterDrop will flush messages minimum once every 10 seconds
+30.times do |i|
+  producer.produce_async(topic: 'events', payload: i.to_s)
+  sleep(1)
+end
+
+producer.close
+```
+
+## Instrumentation
+
+Each of the producers after the `#setup` is done, has a custom monitor to which you can subscribe.
+
+```ruby
+producer = WaterDrop::Producer.new
+
+producer.setup do |config|
+  config.kafka = { 'bootstrap.servers': 'localhost:9092' }
+end
+
+producer.monitor.subscribe('message.produced_async') do |event|
+  puts "A message was produced to '#{event[:message][:topic]}' topic!"
+end
+
+producer.produce_async(topic: 'events', payload: 'data')
+
+producer.close
+```
+
+See the `WaterDrop::Instrumentation::Monitor::EVENTS` for the list of all the supported events.
+
+### Usage statistics
+
+WaterDrop may be configured to emit internal metrics at a fixed interval by setting the `kafka` `statistics.interval.ms` configuration property to a value > `0`. Once that is done, emitted statistics are available after subscribing to the `statistics.emitted` publisher event.
+
+The statistics include all of the metrics from `librdkafka` (full list [here](https://github.com/edenhill/librdkafka/blob/master/STATISTICS.md)) as well as the diff of those against the previously emitted values.
+
+For several attributes like `txmsgs`, `librdkafka` publishes only the totals. In order to make it easier to track the progress (for example number of messages sent between statistics emitted events), WaterDrop diffs all the numeric values against previously available numbers. All of those metrics are available under the same key as the metric but with additional `_d` postfix:
+
+
+```ruby
+producer = WaterDrop::Producer.new do |config|
+  config.kafka = {
+    'bootstrap.servers': 'localhost:9092',
+    'statistics.interval.ms': 2_000 # emit statistics every 2 seconds
+  }
+end
+
+producer.monitor.subscribe('statistics.emitted') do |event|
+  sum = event[:statistics]['txmsgs']
+  diff = event[:statistics]['txmsgs_d']
+
+  p "Sent messages: #{sum}"
+  p "Messages sent from last statistics report: #{diff}"
+end
+
+sleep(2)
+
+# Sent messages: 0
+# Messages sent from last statistics report: 0
+
+20.times { producer.produce_async(topic: 'events', payload: 'data') }
+
+# Sent messages: 20
+# Messages sent from last statistics report: 20
+
+sleep(2)
+
+20.times { producer.produce_async(topic: 'events', payload: 'data') }
+
+# Sent messages: 40
+# Messages sent from last statistics report: 20
+
+sleep(2)
+
+# Sent messages: 40
+# Messages sent from last statistics report: 0
+
+producer.close
+```
+
+Note: The metrics returned may not be completely consistent between brokers, toppars and totals, due to the internal asynchronous nature of librdkafka. E.g., the top level tx total may be less than the sum of the broker tx values which it represents.
+
+### Forking and potential memory problems
+
+If you work with forked processes, make sure you **don't** use the producer before the fork. You can easily configure the producer and then fork and use it.
+
+To tackle this [obstacle](https://github.com/appsignal/rdkafka-ruby/issues/15) related to rdkafka, WaterDrop adds finalizer to each of the producers to close the rdkafka client before the Ruby process is shutdown. Due to the [nature of the finalizers](https://www.mikeperham.com/2010/02/24/the-trouble-with-ruby-finalizers/), this implementation prevents producers from being GCed (except upon VM shutdown) and can cause memory leaks if you don't use persistent/long-lived producers in a long-running process or if you don't use the `#close` method of a producer when it is no longer needed. Creating a producer instance for each message is anyhow a rather bad idea, so we recommend not to.
 
 ## References
 
+* [WaterDrop code documentation](https://www.rubydoc.info/github/karafka/waterdrop)
 * [Karafka framework](https://github.com/karafka/karafka)
-* [WaterDrop Travis CI](https://travis-ci.org/karafka/waterdrop)
+* [WaterDrop Actions CI](https://github.com/karafka/waterdrop/actions?query=workflow%3Ac)
 * [WaterDrop Coditsu](https://app.coditsu.io/karafka/repositories/waterdrop)
 
 ## Note on contributions
@@ -123,5 +312,3 @@ Each pull request must pass all the RSpec specs and meet our quality requirement
 To check if everything is as it should be, we use [Coditsu](https://coditsu.io) that combines multiple linters and code analyzers for both code and documentation. Once you're done with your changes, submit a pull request.
 
 Coditsu will automatically check your work against our quality standards. You can find your commit check results on the [builds page](https://app.coditsu.io/karafka/repositories/waterdrop/builds/commit_builds) of WaterDrop repository.
-
-[![coditsu](https://coditsu.io/assets/quality_bar.svg)](https://app.coditsu.io/karafka/repositories/waterdrop/builds/commit_builds)