4.4.0 — 2026-03-13

← 4.3.6 | ↑ 4.x series

Added

Adapters - Kafka

• Async Kafka Producer Adapter - Introduced AsyncKafkaProducerAdapter for non-blocking message production using confluent-kafka's thread-based async delivery model.
  • Implements the new AsyncKafkaProducerPort interface with async produce, async flush, and async close methods
  • Lazy-initialises the underlying confluent-kafka Producer on first use to avoid blocking the event loop at construction time
  • Supports configurable worker threads (kafka_async_worker_threads) and buffer flush timeout (kafka_async_buffer_timeout_seconds) via KafkaConfig
• Async Kafka Consumer Adapter - Introduced AsyncKafkaConsumerAdapter for non-blocking message consumption.
  • Implements the new AsyncKafkaConsumerPort interface with async consume, async subscribe, async commit, and async close methods
  • Offloads blocking confluent-kafka Consumer calls to a thread pool executor to keep the event loop free
• Async Kafka Ports - Added AsyncKafkaProducerPort and AsyncKafkaConsumerPort abstract base classes to archipy/adapters/kafka/ports.py.
  • Defines the async contract that all async Kafka adapter implementations must satisfy
• Close Methods on Sync Adapters - Added explicit close() methods to KafkaConsumerAdapter and KafkaProducerAdapter for deterministic resource cleanup.

Configs - Kafka

• Async Kafka Config Fields - Extended KafkaConfig with two new settings for the async adapters.
  • kafka_async_worker_threads: int — number of threads in the async executor pool (default 4)
  • kafka_async_buffer_timeout_seconds: float — maximum seconds to wait when flushing the producer buffer on close (default 5.0)

Tests - Kafka

• Async BDD Scenarios - Expanded features/kafka_adapters.feature with end-to-end scenarios for AsyncKafkaProducerAdapter and AsyncKafkaConsumerAdapter.
  • Covers produce, consume, subscribe, commit, flush, and close lifecycle
  • Step implementations in features/steps/kafka_adapter_steps.py use await throughout instead of asyncio.run()

Changed

Tests - BDD

• Async Step Implementations - Refactored all async Behave step functions across multiple feature files to use await instead of asyncio.run().
  • Affected files: atomic_transaction_steps.py, error_utils_steps.py, grpc_error_handling_steps.py, metric_interceptor_steps.py
  • Eliminates nested event-loop errors when steps run inside an already-running loop
• test_helpers.py Cleanup - Removed deprecated utility functions from features/test_helpers.py that were superseded by the async step refactor.

Chore

Docs - Kafka

• Kafka Tutorial Expansion - Substantially expanded docs/tutorials/adapters/kafka.md to document all five adapter classes (KafkaAdminAdapter, KafkaConsumerAdapter, KafkaProducerAdapter, AsyncKafkaConsumerAdapter, AsyncKafkaProducerAdapter).
  • Added dedicated sections for async adapters, lazy initialisation behaviour, and usage in non-async contexts
  • Improved logging examples for consistency with documentation standards
• Kafka API Reference Update - Updated docs/api_reference/adapters/kafka.md to list all five adapter classes and their async configuration options.
• Documentation Admonition Style - Migrated all admonitions across 19 documentation files from MkDocs !!! directives to block-quote callouts (> **Type:** ...) to prevent formatting issues in PyCharm.
• Quickstart Redis Update - Updated docs/getting-started/quickstart.md to reflect the current Redis caching implementation.
• BDD Testing Rule Update - Clarified Behave version (1.3.3) and async step conventions in .cursor/rules/testing-bdd.mdc.