Changelog

All notable changes to kafka-effectful are documented here.

This package follows the Haskell Package Versioning Policy.

0.2.0.0 — 2026-05-06

Additive release. No breaking changes to existing modules.

• Add produceMessage' and produceMessageSync to the KafkaProducer effect. produceMessage' mirrors Kafka.Producer.produceMessage', taking a per-message DeliveryReport -> IO () callback. produceMessageSync blocks until the broker acknowledges the record and returns the assigned Offset. Both throw KafkaError via the Error effect on failure.
• Add produceMessageBatch to the KafkaProducer effect. Returns only the records that failed to enqueue, paired with their KafkaError. The interpreter inlines the upstream definition (mapM over the list) because Hackage hw-kafka-client-5.3.0 does not re-export Kafka.Producer.produceMessageBatch.
• Add the transaction API to the KafkaProducer effect — initTransactions, beginTransaction, commitTransaction, abortTransaction — plus the cross-effect helper commitOffsetMessageTransaction (in new module Kafka.Effectful.Producer.Transaction) that commits consumer offsets as part of the producer's open transaction. Re-exports TxError with its three accessors (kafkaErrorTxnRequiresAbort, kafkaErrorIsRetriable, kafkaErrorIsFatal).
• Add narrow handle-ask escape hatches askProducerHandle and askConsumerHandle on the scoped facades. Reachable only from Kafka.Effectful.Producer and Kafka.Effectful.Consumer; not re-exported from the combined Kafka.Effectful facade.
• Add OpenTelemetry tracing support via opt-in interpreter variants runKafkaProducerTraced and runKafkaConsumerTraced. New modules under Kafka.Effectful.OpenTelemetry.* provide the attribute-builder helpers (producerRecordAttributes, consumerRecordAttributes) and the W3C trace-context header bridges (extractTraceContextFromRecord, injectTraceContextIntoRecord). The default interpreters runKafkaProducer and runKafkaConsumer are unchanged and remain zero-cost for users who do not want tracing. The attribute keys and value types match what shibuya-kafka-adapter already emits, so layering the two remains compatible.
• Add kafka-effectful-test test suite covering the OpenTelemetry attribute helpers and trace-context propagation bridges.
• Add example projects: example-sync-publish, example-transactional-etl, and example-otel-tracing demonstrating an end-to-end traced producer/consumer pipeline.
• Expand the README with a "Producer scenarios" walkthrough covering all eight best-practice cases from upstream's producer-best-practices.md, and document the new tracing support.

0.1.0.0 — 2026-04-16

Initial release.

This is an experimental release. Breaking changes are expected in subsequent 0.x versions. Pin to an exact version in production until the API stabilizes at 1.0.

• KafkaProducer effect with produceMessage and flushProducer operations.
• KafkaConsumer effect with polling, offset management, partition management, and querying operations.
• Resource-safe interpreters that acquire and release Kafka handles via bracket.
• Errors surfaced through Effectful.Error.Static as Error KafkaError.