Merge pull request #121 from zmstone/260723-fix-offset-reply-spec

fix: add missing drop-reason atoms to offset_reply() spec

Author: zmstone

changelog.md

@@ -1,3 +1,10 @@
+* 4.2.1
+  - Fix the stale `wolff:offset_reply()` type spec: add the missing drop-reason
+    atoms an ack callback (or `send_sync`) may receive: `partition_lost`,
+    and the ones introduced in 4.2.0: `message_expired` (`max_batch_age`)
+    and `max_retry_exceeded` (`max_retry`).
+    No behavior change, spec (dialyzer) only.
+
 * 4.2.0
   - Add `max_retry` producer option (default `infinity`, i.e. retry forever).
     When set to a non-negative integer, a batch that keeps getting Kafka error

src/wolff.erl

@@ -66,7 +66,20 @@
 -type partition() :: kpro:partition().
 -type name() :: atom() | binary().
 -type offset() :: kpro:offset().
--type offset_reply() :: offset() | buffer_overflow_discarded | message_too_large.
+%% Kafka offset for successfully produced messages (`-1' when `required_acks'
+%% is `none'), or the reason atom when the message is dropped instead:
+%% - `buffer_overflow_discarded': pushed out of the buffer by newer messages
+%%   (replayq overflow, or high memory pressure with `drop_if_highmem').
+%% - `partition_lost': the partition is gone (e.g. topic deleted or shrunk).
+%% - `message_expired': all messages in the batch are older than `max_batch_age'.
+%% - `max_retry_exceeded': dropped after `max_retry' failed retries.
+%% - `message_too_large': a single-call batch is too large for the topic.
+-type offset_reply() :: offset()
+                      | buffer_overflow_discarded
+                      | partition_lost
+                      | message_expired
+                      | max_retry_exceeded
+                      | message_too_large.
 -type producers_cfg() :: wolff_producers:config().
 -type producers() :: wolff_producers:producers().
 -type partitioner() :: wolff_producers:partitioner().