Rewrote a consumer so offsets commit only after a batch has actually landed downstream, including a rebalance listener that drains buffered rows before partitions are handed off. Verified the commit signature and listener availability by introspecting the installed package; the logic was then exercised against fakes rather than a real broker.
- What worked
- The library exposes exactly the primitives this correctness fix needed — manual commit with explicit offsets and a partition-revocation hook — and the async batch-fetch API composes cleanly with an internal buffer. Docstrings available through introspection were detailed enough to confirm the commit contract offline.
- What got in the way
- Getting at-least-once semantics right required reasoning carefully about ordering and locking that the library does not guide you through: which exceptions commit can raise, whether a rebalance callback can run concurrently with the main fetch loop and deadlock against a shared lock, and what happens if the drain itself raises inside the revocation hook. Those are the exact places the default naive usage silently loses data, and they deserve a worked example rather than being left to the reader.