# Upgrading to WaterDrop 2.7

**PLEASE MAKE SURE TO READ AND APPLY THEM!**

## Upgrading to WaterDrop 2.7 / `wait_timeout` Configuration No Longer Needed

The `wait_timeout` WaterDrop configuration option is no longer needed. You can safely remove it.

```ruby
producer = WaterDrop::Producer.new

producer.setup do |config|
  # Other config...

  # Remove this, no longer needed
  config.wait_timeout = 30
end
```

## Upgrading to WaterDrop 2.7 / Time Settings Format Alignment

**All** time-related values are now configured in milliseconds instead of some being in seconds and some in milliseconds.

The values that were changed from seconds to milliseconds are:

- `max_wait_timeout`
- `wait_backoff_on_queue_full`
- `wait_timeout_on_queue_full`
- `wait_backoff_on_transaction_command, default`

If you have configured any of those yourself, please replace the seconds representation with milliseconds:

```ruby
producer = WaterDrop::Producer.new

producer.setup do |config|
  config.deliver = true

  # Replace this:
  config.max_wait_timeout = 30

  # With
  config.max_wait_timeout = 30_000
  # ...
end
```

## Upgrading to WaterDrop 2.7 / Defaults Alignment

In this release, we've updated our default settings to address a crucial issue: previous defaults could lead to inconclusive outcomes in synchronous operations due to wait timeout errors. Users often mistakenly believed that a message dispatch was halted because of these errors when, in fact, the timeout was related to awaiting the final dispatch verdict, not the dispatch action itself.

The new defaults in WaterDrop 2.7.0 eliminate this confusion by ensuring synchronous operation results are always transparent and conclusive. This change aims to provide a straightforward understanding of wait timeout errors, reinforcing that they reflect the wait state, not the dispatch success.

Below, you can find a table with what has changed, the new defaults, and the current ones in case you want to retain the previous behavior:

<table>
  <thead>
    <tr>
      <th>Config</th>
      <th>Previous Default</th>
      <th>New Default</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>root <code>max_wait_timeout</code></td>
      <td>5000 ms (5 seconds)</td>
      <td>60000 ms (60 seconds)</td>
    </tr>
    <tr>
      <td>kafka <code>message.timeout.ms</code></td>
      <td>300000 ms (5 minutes)</td>
      <td>50000 ms (50 seconds)</td>
    </tr>
    <tr>
      <td>kafka <code>transaction.timeout.ms</code></td>
      <td>60000 ms (1 minute)</td>
      <td>55000 ms (55 seconds)</td>
    </tr>
  </tbody>
</table>

This alignment ensures that when using sync operations or invoking `#wait`, any exception you get should give you a conclusive and final delivery verdict.

## Upgrading to WaterDrop 2.7 / Buffering No Longer Early Validates Messages

As of version `2.7.0`, WaterDrop has changed how message buffering works. Previously, messages underwent validation and middleware processing when they were buffered. Now, these steps are deferred until just before dispatching the messages. The buffer functions strictly as a thread-safe storage area without performing any validations or middleware operations until the messages are ready to be sent.

This adjustment was made primarily to ensure that middleware runs and validations are applied when most relevant—shortly before message dispatch. This approach addresses potential issues with buffers that might hold messages for extended periods:

- **Temporal Relevance**: Validating and processing messages near their dispatch time helps ensure that actions such as partition assignments reflect the current system state. This is crucial in dynamic environments where system states are subject to rapid changes.

- **Stale State Management**: By delaying validations and middleware to the dispatch phase, the system minimizes the risk of acting on outdated information, which could lead to incorrect processing or partitioning decisions.

```ruby
# Prior to 2.7.0 this would raise an error
producer.buffer(topic: nil, payload: '')
# => WaterDrop::Errors::MessageInvalidError

# After 2.7.0 buffer will not, but flush_async will
producer.buffer(topic: nil, payload: '')
# => all good here
producer.flush_async(topic: nil, payload: '')
# => WaterDrop::Errors::MessageInvalidError
```

## Upgrading to WaterDrop 2.7 / Middleware Execution Prior to Flush When Buffering

The timing of middleware execution has been adjusted. Middleware, which was previously run when messages were added to the buffer, will now only execute immediately before the messages are flushed from the buffer and dispatched. This change is similar to the validation-related changes.


---

*Last modified: 2025-04-29 12:37:29*