openframe-adapters-queue-kafka 1.1.0__py3-none-any.whl

openframe/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

openframe/adapters/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

openframe/adapters/queue/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

openframe/adapters/queue/kafka/__init__.py

@@ -0,0 +1,49 @@
+"""
+openframe.adapters.queue.kafka
+================================
+Apache Kafka queue adapter for the OpenFrame Microservice Suite.
+
+Public API::
+
+    KafkaSettings  — Pydantic Settings subclass for connection config.
+    KafkaProducer  — Generic async message producer (BaseProducer[T]).
+    KafkaConsumer  — Generic async message consumer (BaseConsumer[T]).
+    KafkaPlugin    — OpenFramePlugin implementation for PluginRegistry.
+
+Quick start::
+
+    from openframe.adapters.queue.kafka import (
+        KafkaSettings,
+        KafkaProducer,
+        KafkaConsumer,
+    )
+
+    settings = KafkaSettings(kafka_bootstrap_servers="localhost:9092")
+
+    # Produce
+    producer = KafkaProducer(settings)
+    await producer.start()
+    await producer.publish({"event": "item.created", "id": "abc"})
+    await producer.close()
+
+    # Consume
+    consumer = KafkaConsumer(settings)
+
+    async def handle(event: dict) -> None:
+        print(f"Received: {event}")
+
+    await consumer.subscribe(handle)
+"""
+from __future__ import annotations
+
+from .config import KafkaSettings
+from .consumer import KafkaConsumer
+from .plugin import KafkaPlugin
+from .producer import KafkaProducer
+
+__all__ = [
+    "KafkaSettings",
+    "KafkaProducer",
+    "KafkaConsumer",
+    "KafkaPlugin",
+]

openframe/adapters/queue/kafka/config.py

@@ -0,0 +1,51 @@
+"""
+openframe/adapters/queue/kafka/config.py
+==========================================
+Settings for the Kafka queue adapter, sourced from environment variables
+via ``openframe-core``'s ``BaseAdapterSettings`` (pydantic-settings).
+
+Required env vars:
+    KAFKA_BOOTSTRAP_SERVERS: Comma-separated broker list.
+                             Format: host:port,host:port
+
+Optional env vars (all have defaults):
+    KAFKA_TOPIC:              str  = "openframe"       — default topic
+    KAFKA_GROUP_ID:           str  = "openframe-group" — consumer group
+    KAFKA_AUTO_OFFSET_RESET:  str  = "earliest"
+    KAFKA_MAX_POLL_RECORDS:   int  = 10
+    KAFKA_SESSION_TIMEOUT_MS: int  = 30000
+    KAFKA_REQUEST_TIMEOUT_MS: int  = 30000
+    KAFKA_SECURITY_PROTOCOL:  str  = "PLAINTEXT"
+    KAFKA_SASL_MECHANISM:     str  = ""
+    KAFKA_SASL_USERNAME:      str  = ""
+    KAFKA_SASL_PASSWORD:      str  = ""
+    ADAPTER_NAME:             str  = "kafka"
+"""
+from __future__ import annotations
+
+from openframe.core.config import BaseAdapterSettings
+
+__all__ = ["KafkaSettings"]
+
+
+class KafkaSettings(BaseAdapterSettings):
+    """
+    Pydantic-settings subclass for the Kafka queue adapter.
+
+    All fields are read from environment variables with the exact names
+    shown above. ``BaseAdapterSettings`` provides ``operation_timeout``
+    (default 30.0 s) and ``connection_timeout`` (default 30.0 s).
+    """
+
+    kafka_bootstrap_servers: str
+    kafka_topic: str = "openframe"
+    kafka_group_id: str = "openframe-group"
+    kafka_auto_offset_reset: str = "earliest"
+    kafka_max_poll_records: int = 10
+    kafka_session_timeout_ms: int = 30_000
+    kafka_request_timeout_ms: int = 30_000
+    kafka_security_protocol: str = "PLAINTEXT"
+    kafka_sasl_mechanism: str = ""
+    kafka_sasl_username: str = ""
+    kafka_sasl_password: str = ""
+    adapter_name: str = "kafka"

openframe/adapters/queue/kafka/consumer.py

@@ -0,0 +1,214 @@
+"""
+openframe/adapters/queue/kafka/consumer.py
+============================================
+Kafka message consumer implementing ``BaseConsumer[T]`` from
+``openframe-core`` via structural subtyping.
+
+Each ``subscribe()`` call creates, starts, and runs a new
+``AIOKafkaConsumer`` until ``close()`` is called. Manual offset commit
+is used — the offset is committed only after the handler returns
+successfully. If the handler raises, ``nack()`` is called (no commit,
+message will be redelivered on the next poll).
+
+Error handling:
+    ``KafkaConnectionError`` on startup → ``AdapterConnectionError``.
+    ``KafkaError`` on startup → ``AdapterConfigurationError``.
+    Handler exceptions are caught, logged, and the loop continues.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any, Awaitable, Callable, Generic, TypeVar
+
+import aiokafka
+import aiokafka.errors
+from aiokafka import AIOKafkaConsumer
+
+from openframe.core.exceptions import (
+    AdapterConfigurationError,
+    AdapterConnectionError,
+)
+
+from .config import KafkaSettings
+
+__all__ = ["KafkaConsumer"]
+
+T = TypeVar("T")
+_logger = logging.getLogger(__name__)
+
+
+class KafkaConsumer(Generic[T]):
+    """
+    Kafka message consumer.
+
+    Implements ``BaseConsumer[T]`` structurally — no inheritance from Protocol.
+    Deserialises JSON messages. Manual offset commit after handler success.
+
+    Each ``subscribe()`` call creates a new ``AIOKafkaConsumer``, starts it,
+    polls until ``close()`` is called, then stops it. Handler failures trigger
+    ``nack()`` (no commit — message is redelivered).
+
+    Usage::
+
+        consumer = KafkaConsumer(settings)
+
+        async def handle(event: dict) -> None:
+            print(f"Received: {event}")
+
+        await consumer.subscribe(handle)   # runs until close() called
+
+    Structural conformance::
+
+        assert isinstance(consumer, BaseConsumer)
+    """
+
+    def __init__(self, settings: KafkaSettings) -> None:
+        self._settings = settings
+        self._consumer: AIOKafkaConsumer | None = None
+        self._running: bool = False
+
+    # ------------------------------------------------------------------
+    # Deserialisation (override in typed subclasses)
+    # ------------------------------------------------------------------
+
+    def _deserialise(self, raw: bytes) -> T:
+        """
+        Deserialise bytes from Kafka to the message type ``T``.
+
+        Base implementation: ``json.loads(raw.decode("utf-8"))``.
+        Subclasses override for custom deserialisation (protobuf, Avro, etc.).
+        """
+        return json.loads(raw.decode("utf-8"))  # type: ignore[return-value]
+
+    # ------------------------------------------------------------------
+    # BaseConsumer[T] interface
+    # ------------------------------------------------------------------
+
+    async def subscribe(
+        self,
+        handler: Callable[[T], Awaitable[None]],
+    ) -> None:
+        """
+        Start consuming messages and invoke ``handler`` for each one.
+
+        Runs until ``close()`` is called. Uses manual commit — commits
+        the offset only after ``handler`` returns successfully. If
+        ``handler`` raises, calls ``nack()`` and continues to the next
+        message.
+
+        Args:
+            handler: Async callable that processes each deserialised message.
+
+        Raises:
+            AdapterConnectionError:    Cannot reach the Kafka broker.
+            AdapterConfigurationError: Invalid topic, group, or credentials.
+        """
+        kwargs: dict[str, Any] = {
+            "bootstrap_servers": self._settings.kafka_bootstrap_servers,
+            "group_id": self._settings.kafka_group_id,
+            "auto_offset_reset": self._settings.kafka_auto_offset_reset,
+            "enable_auto_commit": False,
+            "max_poll_records": self._settings.kafka_max_poll_records,
+            "session_timeout_ms": self._settings.kafka_session_timeout_ms,
+            "request_timeout_ms": self._settings.kafka_request_timeout_ms,
+            "security_protocol": self._settings.kafka_security_protocol,
+        }
+        if self._settings.kafka_sasl_mechanism:
+            kwargs["sasl_mechanism"] = self._settings.kafka_sasl_mechanism
+            kwargs["sasl_plain_username"] = self._settings.kafka_sasl_username
+            kwargs["sasl_plain_password"] = self._settings.kafka_sasl_password
+
+        try:
+            self._consumer = AIOKafkaConsumer(
+                self._settings.kafka_topic, **kwargs
+            )
+            await self._consumer.start()
+            self._running = True
+        except aiokafka.errors.KafkaConnectionError as exc:
+            self._consumer = None
+            raise AdapterConnectionError(
+                f"Kafka consumer cannot connect to {self._settings.kafka_bootstrap_servers!r}: {exc}",
+                adapter=self._settings.adapter_name,
+                operation="subscribe",
+                cause=exc,
+            ) from exc
+        except aiokafka.errors.KafkaError as exc:
+            self._consumer = None
+            raise AdapterConfigurationError(
+                f"Kafka consumer configuration error: {exc}",
+                adapter=self._settings.adapter_name,
+                operation="subscribe",
+            ) from exc
+
+        try:
+            async for msg in self._consumer:
+                if not self._running:
+                    break
+                try:
+                    message = self._deserialise(msg.value)
+                    await handler(message)
+                    await self.ack(message)
+                except Exception as exc:  # noqa: BLE001
+                    _logger.error(
+                        "KafkaConsumer handler failed for topic %r: %s",
+                        self._settings.kafka_topic,
+                        exc,
+                    )
+                    await self.nack(message)
+        finally:
+            if self._consumer is not None:
+                try:
+                    await self._consumer.stop()
+                except Exception as exc:  # noqa: BLE001
+                    _logger.error("KafkaConsumer stop error (ignored): %s", exc)
+            self._consumer = None
+            self._running = False
+
+    async def ack(self, message: T) -> None:
+        """
+        Acknowledge a message by committing the current offset.
+
+        Called automatically after successful handler invocation.
+        Can also be called manually for custom acknowledgement flows.
+        Never raises.
+
+        Args:
+            message: The message that was successfully processed.
+        """
+        if self._consumer is not None:
+            try:
+                await self._consumer.commit()
+            except Exception as exc:  # noqa: BLE001
+                _logger.error("KafkaConsumer ack (commit) error (ignored): %s", exc)
+
+    async def nack(self, message: T) -> None:
+        """
+        Negatively acknowledge a message.
+
+        Does NOT commit the offset — the message will be redelivered
+        on the next poll. Logs the failure. Never raises.
+
+        Args:
+            message: The message that failed processing.
+        """
+        _logger.warning(
+            "KafkaConsumer nack — message will be redelivered on topic %r",
+            self._settings.kafka_topic,
+        )
+
+    async def close(self) -> None:
+        """
+        Stop the consumer.
+
+        Sets ``_running = False`` to break the polling loop. The consumer
+        is stopped in the ``finally`` block of ``subscribe()``. Never raises.
+        """
+        self._running = False
+        if self._consumer is not None:
+            try:
+                await self._consumer.stop()
+            except Exception as exc:  # noqa: BLE001
+                _logger.error("KafkaConsumer close error (ignored): %s", exc)
+            self._consumer = None

openframe/adapters/queue/kafka/plugin.py

@@ -0,0 +1,160 @@
+"""
+openframe/adapters/queue/kafka/plugin.py
+==========================================
+OpenFrame plugin wrapper for KafkaProducer and KafkaConsumer.
+
+Stability: beta
+Capability: "queue"
+
+Manages the ``KafkaProducer`` lifecycle. Consumers are created on-demand
+via ``make_consumer()`` since each consume session is short-lived.
+
+Usage via PluginRegistry (optional)::
+
+    from openframe.core.plugins import PluginRegistry
+    from openframe.adapters.queue.kafka import KafkaPlugin, KafkaSettings
+
+    registry = PluginRegistry()
+    registry.register(KafkaPlugin(KafkaSettings()))
+    await registry.initialize_all()
+
+    plugin = registry.get("queue")
+    producer = plugin.get_producer()
+    await producer.publish({"event": "item.created"})
+
+    consumer = plugin.make_consumer()
+    await consumer.subscribe(handler)
+
+Usage via deps.py (unchanged, no plugin needed)::
+
+    producer = KafkaProducer(KafkaSettings())
+    await producer.start()
+"""
+from __future__ import annotations
+
+import logging
+
+from openframe.core.plugins import PluginContext, PluginHealth, PluginStatus
+
+from openframe.adapters.queue.kafka.config import KafkaSettings
+from openframe.adapters.queue.kafka.consumer import KafkaConsumer
+from openframe.adapters.queue.kafka.producer import KafkaProducer
+
+__all__ = ["KafkaPlugin"]
+
+_logger = logging.getLogger(__name__)
+
+
+class KafkaPlugin:
+    """
+    Kafka adapter plugin for the OpenFrame plugin registry.
+
+    Capability: "queue"
+
+    Lifecycle:
+        initialize() — starts the ``KafkaProducer`` and verifies connectivity.
+                       Raises on failure.
+        shutdown()   — closes the producer. Never raises.
+        health()     — checks whether the producer is READY. Never raises.
+
+    The plugin exposes ``get_producer()`` and ``make_consumer()`` after
+    initialization for use in the composition root or ApplicationBootstrap.
+    """
+
+    name:       str = "openframe-kafka"
+    version:    str = "1.1.0"
+    capability: str = "queue"
+
+    def __init__(self, settings: KafkaSettings) -> None:
+        self._settings = settings
+        self._producer: KafkaProducer | None = None
+        self._status = PluginStatus.REGISTERED
+
+    async def initialize(self, context: PluginContext) -> None:
+        """
+        Start the KafkaProducer and verify broker connectivity.
+
+        Args:
+            context: Plugin context (config, plugin_name). Unused here —
+                     settings are provided at construction time.
+
+        Raises:
+            AdapterConnectionError:    Broker is unreachable.
+            AdapterConfigurationError: Invalid bootstrap servers or settings.
+            AdapterTimeoutError:       Start exceeded ``connection_timeout``.
+        """
+        self._status = PluginStatus.INITIALIZED
+        try:
+            self._producer = KafkaProducer(self._settings)
+            await self._producer.start()
+            self._status = PluginStatus.READY
+            _logger.info(
+                "KafkaPlugin initialized — %s",
+                self._settings.kafka_bootstrap_servers,
+            )
+        except Exception:
+            self._status = PluginStatus.FAILED
+            raise
+
+    async def shutdown(self) -> None:
+        """
+        Close the KafkaProducer.
+
+        Never raises — logs errors and continues.
+        """
+        self._status = PluginStatus.STOPPING
+        try:
+            if self._producer is not None:
+                await self._producer.close()
+                _logger.info("KafkaPlugin shutdown complete.")
+        except Exception as exc:
+            _logger.error("KafkaPlugin shutdown error (ignored): %s", exc)
+        finally:
+            self._status = PluginStatus.STOPPED
+
+    async def health(self) -> PluginHealth:
+        """
+        Return current health snapshot.
+
+        Never raises — returns FAILED status on any exception.
+        """
+        try:
+            if self._producer is None or self._status != PluginStatus.READY:
+                return PluginHealth(
+                    status=PluginStatus.FAILED,
+                    message=f"Plugin status: {self._status.name}",
+                )
+            return PluginHealth(status=PluginStatus.READY, message="")
+        except Exception as exc:
+            return PluginHealth(
+                status=PluginStatus.FAILED,
+                message=str(exc),
+            )
+
+    def get_producer(self) -> KafkaProducer:
+        """
+        Return the started producer.
+
+        Only valid after ``registry.initialize_all()`` has been called.
+
+        Raises:
+            RuntimeError: Plugin not yet initialized.
+        """
+        if self._producer is None or self._status != PluginStatus.READY:
+            raise RuntimeError(
+                f"KafkaPlugin is not ready (status: {self._status.name}). "
+                "Call await registry.initialize_all() first."
+            )
+        return self._producer
+
+    def make_consumer(self) -> KafkaConsumer:
+        """
+        Create a new ``KafkaConsumer`` with this plugin's settings.
+
+        Consumers are short-lived (one per ``subscribe()`` session) so
+        they are created on demand rather than cached.
+
+        Returns:
+            A fresh ``KafkaConsumer`` ready to call ``subscribe()`` on.
+        """
+        return KafkaConsumer(self._settings)

openframe/adapters/queue/kafka/producer.py

@@ -0,0 +1,238 @@
+"""
+openframe/adapters/queue/kafka/producer.py
+============================================
+Kafka message producer implementing ``BaseProducer[T]`` from
+``openframe-core`` via structural subtyping.
+
+Messages are serialised to JSON bytes before being sent to Kafka.
+The underlying ``AIOKafkaProducer`` must be explicitly started via
+``await producer.start()`` before calling ``publish()`` or
+``publish_batch()``.
+
+Error handling:
+    Every ``aiokafka.errors.*`` is caught and re-raised as the appropriate
+    ``AdapterError`` subclass with cause chaining.
+
+Timeout strategy:
+    ``asyncio.timeout(settings.operation_timeout)`` wraps every send.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any, Generic, TypeVar
+
+import aiokafka
+import aiokafka.errors
+from aiokafka import AIOKafkaProducer
+
+from openframe.core.exceptions import (
+    AdapterConfigurationError,
+    AdapterConnectionError,
+    AdapterQueryError,
+    AdapterTimeoutError,
+)
+from openframe.core.ports import BaseProducer
+
+from .config import KafkaSettings
+
+__all__ = ["KafkaProducer"]
+
+T = TypeVar("T")
+_logger = logging.getLogger(__name__)
+
+
+class KafkaProducer(Generic[T]):
+    """
+    Kafka message producer.
+
+    Implements ``BaseProducer[T]`` structurally — no inheritance from Protocol.
+    Serialises messages to JSON bytes before publishing to Kafka.
+
+    The underlying ``AIOKafkaProducer`` must be started before use.
+    Call ``await producer.start()`` or use ``KafkaPlugin`` for managed
+    lifecycle.
+
+    Usage::
+
+        producer = KafkaProducer(settings)
+        await producer.start()
+        await producer.publish({"event": "item.created", "id": "abc"})
+        await producer.close()
+
+    Structural conformance::
+
+        assert isinstance(producer, BaseProducer)
+    """
+
+    def __init__(self, settings: KafkaSettings) -> None:
+        self._settings = settings
+        self._producer: AIOKafkaProducer | None = None
+
+    # ------------------------------------------------------------------
+    # Serialisation (override in typed subclasses)
+    # ------------------------------------------------------------------
+
+    def _serialise(self, message: T) -> bytes:
+        """
+        Serialise a message to bytes for Kafka.
+
+        Base implementation: ``json.dumps(message).encode("utf-8")``.
+        Subclasses override for custom serialisation (protobuf, Avro, etc.).
+        """
+        return json.dumps(message).encode("utf-8")
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def start(self) -> None:
+        """
+        Start the underlying ``AIOKafkaProducer``.
+
+        Must be called before ``publish()`` or ``publish_batch()``.
+
+        Raises:
+            AdapterConnectionError:    Broker is unreachable.
+            AdapterConfigurationError: Invalid bootstrap servers or settings.
+            AdapterTimeoutError:       Start exceeded ``connection_timeout``.
+        """
+        kwargs: dict[str, Any] = {
+            "bootstrap_servers": self._settings.kafka_bootstrap_servers,
+            "request_timeout_ms": self._settings.kafka_request_timeout_ms,
+            "security_protocol": self._settings.kafka_security_protocol,
+        }
+        if self._settings.kafka_sasl_mechanism:
+            kwargs["sasl_mechanism"] = self._settings.kafka_sasl_mechanism
+            kwargs["sasl_plain_username"] = self._settings.kafka_sasl_username
+            kwargs["sasl_plain_password"] = self._settings.kafka_sasl_password
+
+        try:
+            async with asyncio.timeout(self._settings.connection_timeout):
+                self._producer = AIOKafkaProducer(**kwargs)
+                await self._producer.start()
+        except asyncio.TimeoutError as exc:
+            self._producer = None
+            raise AdapterTimeoutError(
+                f"Kafka producer start timed out after {self._settings.connection_timeout}s",
+                adapter=self._settings.adapter_name,
+                operation="start",
+                cause=exc,
+            ) from exc
+        except aiokafka.errors.KafkaConnectionError as exc:
+            self._producer = None
+            raise AdapterConnectionError(
+                f"Kafka producer cannot connect to {self._settings.kafka_bootstrap_servers!r}: {exc}",
+                adapter=self._settings.adapter_name,
+                operation="start",
+                cause=exc,
+            ) from exc
+        except aiokafka.errors.KafkaError as exc:
+            self._producer = None
+            raise AdapterConfigurationError(
+                f"Kafka producer configuration error: {exc}",
+                adapter=self._settings.adapter_name,
+                operation="start",
+            ) from exc
+
+    async def close(self) -> None:
+        """
+        Stop the producer and release resources.
+
+        Idempotent — safe to call multiple times. Never raises.
+        """
+        if self._producer is not None:
+            try:
+                await self._producer.stop()
+            except Exception as exc:  # noqa: BLE001
+                _logger.error("KafkaProducer close error (ignored): %s", exc)
+            finally:
+                self._producer = None
+
+    # ------------------------------------------------------------------
+    # BaseProducer[T] interface
+    # ------------------------------------------------------------------
+
+    async def publish(self, message: T) -> None:
+        """
+        Publish a single message to the configured topic.
+
+        Serialises the message to JSON bytes and waits for broker
+        acknowledgement via ``send_and_wait``.
+
+        Args:
+            message: The message to publish.
+
+        Raises:
+            RuntimeError:        Producer not started — call ``start()`` first.
+            AdapterQueryError:   Publish failed (broker error).
+            AdapterTimeoutError: Publish exceeded ``operation_timeout``.
+        """
+        if self._producer is None:
+            raise RuntimeError(
+                "KafkaProducer not started. Call await producer.start() first."
+            )
+        value = self._serialise(message)
+        try:
+            async with asyncio.timeout(self._settings.operation_timeout):
+                await self._producer.send_and_wait(
+                    self._settings.kafka_topic, value
+                )
+        except asyncio.TimeoutError as exc:
+            raise AdapterTimeoutError(
+                f"publish exceeded {self._settings.operation_timeout}s operation_timeout",
+                adapter=self._settings.adapter_name,
+                operation="publish",
+                cause=exc,
+            ) from exc
+        except aiokafka.errors.KafkaError as exc:
+            raise AdapterQueryError(
+                f"publish to topic {self._settings.kafka_topic!r} failed: {exc}",
+                adapter=self._settings.adapter_name,
+                operation="publish",
+                cause=exc,
+            ) from exc
+
+    async def publish_batch(self, messages: list[T]) -> None:
+        """
+        Publish multiple messages to the configured topic.
+
+        Sends each message individually, then flushes to ensure all
+        are delivered. Raises on the first failure — messages already
+        sent are not rolled back.
+
+        Args:
+            messages: List of messages to publish.
+
+        Raises:
+            RuntimeError:        Producer not started.
+            AdapterQueryError:   Batch publish failed.
+            AdapterTimeoutError: Exceeded ``operation_timeout``.
+        """
+        if self._producer is None:
+            raise RuntimeError(
+                "KafkaProducer not started. Call await producer.start() first."
+            )
+        try:
+            async with asyncio.timeout(self._settings.operation_timeout):
+                for message in messages:
+                    value = self._serialise(message)
+                    await self._producer.send_and_wait(
+                        self._settings.kafka_topic, value
+                    )
+                await self._producer.flush()
+        except asyncio.TimeoutError as exc:
+            raise AdapterTimeoutError(
+                f"publish_batch exceeded {self._settings.operation_timeout}s operation_timeout",
+                adapter=self._settings.adapter_name,
+                operation="publish_batch",
+                cause=exc,
+            ) from exc
+        except aiokafka.errors.KafkaError as exc:
+            raise AdapterQueryError(
+                f"publish_batch to topic {self._settings.kafka_topic!r} failed: {exc}",
+                adapter=self._settings.adapter_name,
+                operation="publish_batch",
+                cause=exc,
+            ) from exc

openframe_adapters_queue_kafka-1.1.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: openframe-adapters-queue-kafka
+Version: 1.1.0
+Summary: OpenFrame Microservice Suite - Apache Kafka queue adapter.
+Project-URL: Homepage, https://github.com/Furious-Meteors/openframe-adapters
+Project-URL: Documentation, https://furious-meteors.github.io/openframe-adapters/
+Project-URL: Repository, https://github.com/Furious-Meteors/openframe-adapters
+Project-URL: Changelog, https://github.com/Furious-Meteors/openframe-adapters/blob/production/.github/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/Furious-Meteors/openframe-adapters/issues
+Author-email: Furious Meteors Engineering <engineering@furiousmeteors.dev>
+Maintainer-email: Furious Meteors Engineering <engineering@furiousmeteors.dev>
+License: MIT
+Keywords: hexagonal,kafka,messaging,microservice,openframe,queue
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiokafka>=0.11
+Requires-Dist: openframe-core<3,>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# openframe-adapters-queue-kafka
+
+Apache Kafka queue adapter for the **OpenFrame Microservice Development Suite**.
+
+Part of the [`openframe-adapters`](https://github.com/Furious-Meteors/openframe-adapters) monorepo.
+
+---
+
+## What it provides
+
+| Symbol | Purpose |
+|---|---|
+| `KafkaSettings` | Pydantic-settings subclass — reads all config from env vars |
+| `KafkaProducer[T]` | Generic async message producer — `BaseProducer[T]` |
+| `KafkaConsumer[T]` | Generic async message consumer — `BaseConsumer[T]` |
+| `KafkaPlugin` | `OpenFramePlugin` — structured lifecycle via `PluginRegistry` |
+
+## Installation
+
+```bash
+# Via meta-package (recommended)
+pip install "openframe-adapters[kafka]"
+
+# Or directly
+pip install openframe-adapters-queue-kafka
+```
+
+## Quick start
+
+```python
+from openframe.adapters.queue.kafka import KafkaSettings, KafkaProducer, KafkaConsumer
+
+settings = KafkaSettings(kafka_bootstrap_servers="localhost:9092")
+
+# Produce
+producer = KafkaProducer(settings)
+await producer.start()
+await producer.publish({"event": "item.created", "id": "abc"})
+await producer.publish_batch([{"event": "x"}, {"event": "y"}])
+await producer.close()
+
+# Consume
+consumer = KafkaConsumer(settings)
+
+async def handle(event: dict) -> None:
+    print(f"Received: {event}")
+
+await consumer.subscribe(handle)   # runs until consumer.close() called
+```
+
+## Configuration
+
+| Env var | Default | Description |
+|---|---|---|
+| `KAFKA_BOOTSTRAP_SERVERS` | **required** | `host:port,host:port` |
+| `KAFKA_TOPIC` | `"openframe"` | Default topic for producer and consumer |
+| `KAFKA_GROUP_ID` | `"openframe-group"` | Consumer group ID |
+| `KAFKA_AUTO_OFFSET_RESET` | `"earliest"` | `"earliest"` or `"latest"` |
+| `KAFKA_MAX_POLL_RECORDS` | `10` | Max messages per poll |
+| `KAFKA_SESSION_TIMEOUT_MS` | `30000` | Consumer session timeout |
+| `KAFKA_REQUEST_TIMEOUT_MS` | `30000` | Broker request timeout |
+| `KAFKA_SECURITY_PROTOCOL` | `"PLAINTEXT"` | `"PLAINTEXT"`, `"SSL"`, `"SASL_PLAINTEXT"` |
+| `KAFKA_SASL_MECHANISM` | `""` | `"PLAIN"`, `"SCRAM-SHA-256"`, etc. |
+| `KAFKA_SASL_USERNAME` | `""` | SASL username |
+| `KAFKA_SASL_PASSWORD` | `""` | SASL password |
+
+## Typed domain objects
+
+```python
+from openframe.adapters.queue.kafka import KafkaProducer, KafkaConsumer, KafkaSettings
+from dataclasses import dataclass, asdict
+
+@dataclass
+class OrderEvent:
+    order_id: str
+    event_type: str
+
+class OrderProducer(KafkaProducer[OrderEvent]):
+    def _serialise(self, message: OrderEvent) -> bytes:
+        import json
+        return json.dumps(asdict(message)).encode("utf-8")
+
+class OrderConsumer(KafkaConsumer[OrderEvent]):
+    def _deserialise(self, raw: bytes) -> OrderEvent:
+        import json
+        return OrderEvent(**json.loads(raw.decode("utf-8")))
+```
+
+## Plugin lifecycle (optional)
+
+```python
+from openframe.core.plugins import PluginRegistry
+from openframe.adapters.queue.kafka import KafkaPlugin, KafkaSettings
+
+registry = PluginRegistry()
+registry.register(KafkaPlugin(KafkaSettings()))
+await registry.initialize_all()
+
+plugin = registry.get("queue")
+producer = plugin.get_producer()
+await producer.publish({"event": "item.created"})
+
+consumer = plugin.make_consumer()
+await consumer.subscribe(handler)
+```
+
+## Consumer acknowledgement semantics
+
+| Outcome | Behaviour |
+|---|---|
+| Handler returns | `ack()` called → offset committed → message consumed |
+| Handler raises | `nack()` called → no commit → message redelivered |
+| `consumer.close()` | polling loop exits → consumer stopped cleanly |
+
+## License
+
+MIT — © Furious Meteors Engineering

openframe_adapters_queue_kafka-1.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+openframe/__init__.py,sha256=ED6jHcYiuYpr_0vjGz0zx2lrrmJT9sDJCzIljoDfmlM,65
+openframe/adapters/__init__.py,sha256=ED6jHcYiuYpr_0vjGz0zx2lrrmJT9sDJCzIljoDfmlM,65
+openframe/adapters/queue/__init__.py,sha256=ED6jHcYiuYpr_0vjGz0zx2lrrmJT9sDJCzIljoDfmlM,65
+openframe/adapters/queue/kafka/__init__.py,sha256=SvuSQQ767qsrEi9vuK1B2oERt5UYjfa-Mn1x6nvOFSI,1275
+openframe/adapters/queue/kafka/config.py,sha256=AbjKdT5us_vcjPop8f7hrvMRg8FLivt3Tdo78PkiZPI,1859
+openframe/adapters/queue/kafka/consumer.py,sha256=CzD0j39mnIECaI4FzYLEoDRy43APRnrWEkW4U7u5Xg8,7834
+openframe/adapters/queue/kafka/plugin.py,sha256=6InEjWSpqWecVPd3Ef1bszfKXVMg8-iKEirSFz0xPMI,5302
+openframe/adapters/queue/kafka/producer.py,sha256=rpoHs1Gw2lqgzS_CUW6hhvTVTS_wpqP27dPKFupL2ew,8798
+openframe_adapters_queue_kafka-1.1.0.dist-info/METADATA,sha256=WYtSUYjsj9quT2-bbh7HYWPTkcjfD6sOG7E6SiLeSP8,5241
+openframe_adapters_queue_kafka-1.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+openframe_adapters_queue_kafka-1.1.0.dist-info/RECORD,,

openframe_adapters_queue_kafka-1.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any