fastapi-modular 0.1.0__py3-none-any.whl

pymodular/infrastructure/kafka/broker.py

@@ -0,0 +1,231 @@
+"""Kết nối Kafka: gửi tin có xác nhận, tự nối lại, không chặn lúc khởi động.
+
+Kafka là TUỲ CHỌN. `APP_KAFKA__ENABLED` mặc định false thì lớp này nằm im.
+
+    pip install 'fastapi-modular[kafka]'   # cài aiokafka + ghi sẵn APP_KAFKA__* vào .env
+
+Kafka khác RabbitMQ ở chỗ căn bản: tin KHÔNG mất đi sau khi được xử lý. Nó nằm
+lại trong nhật ký theo thời gian giữ (retention) của topic, và mỗi nhóm
+consumer có con trỏ đọc riêng. Nhờ vậy thêm một nhóm mới là đọc lại được cả
+lịch sử — thứ hàng đợi không làm được. Cái giá: không có "hàng đợi thử lại",
+không xoá được một tin lẻ, và thứ tự chỉ bảo đảm TRONG MỘT phân vùng.
+
+Về tự nối lại: aiokafka tự tìm lại broker khi cụm chuyển leader hoặc rớt giữa
+chừng. Thứ nó không lo là lúc khởi động mà cụm chưa lên — `producer.start()`
+ném lỗi ngay. Chỗ đó lớp này chạy vòng thử lại có backoff, y như RabbitMQ, để
+app vẫn phục vụ HTTP bình thường.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from pymodular.core.compat import TimeoutErrors
+from pymodular.core.config import Settings
+from pymodular.core.container import injectable
+from pymodular.core.exceptions import ComponentNotEnabledError, ServiceUnavailableError
+from pymodular.core.logging import get_logger
+from pymodular.infrastructure.kafka.metrics import kafka_publish_failed, kafka_published
+
+log = get_logger(__name__)
+
+DEFAULT_SERVERS = "localhost:9092"
+
+
+def _require_aiokafka() -> Any:
+    try:
+        import aiokafka
+    except ModuleNotFoundError as exc:
+        raise ComponentNotEnabledError(
+            "APP_KAFKA__ENABLED=true nhưng chưa cài thư viện aiokafka. "
+            "Chạy `pip install 'fastapi-modular[kafka]'`, hoặc đặt APP_KAFKA__ENABLED=false nếu "
+            "dự án này không dùng Kafka."
+        ) from exc
+    return aiokafka
+
+
+@injectable
+class KafkaBroker:
+    def __init__(self, settings: Settings) -> None:
+        self._config = settings.kafka
+        self._producer: Any = None
+        self._supervisor: asyncio.Task[None] | None = None
+        self._closing = False
+        self._ready_hooks: list[Callable[[], Awaitable[None]]] = []
+
+    # ------------------------------------------------------------- vòng đời
+    @property
+    def enabled(self) -> bool:
+        return self._config.enabled
+
+    @property
+    def connected(self) -> bool:
+        return self._producer is not None
+
+    @property
+    def servers(self) -> str:
+        return self._config.bootstrap_servers
+
+    async def startup(self) -> None:
+        if not self._config.enabled:
+            log.debug("kafka.disabled")
+            return
+
+        _require_aiokafka()
+        self._closing = False
+        if await self._thu_noi():
+            return
+
+        log.warning(
+            "kafka.starting_degraded",
+            servers=self.servers,
+            hint="app vẫn chạy; sẽ nối lại ngầm cho tới khi được",
+        )
+        self._supervisor = asyncio.create_task(self._reconnect_forever(), name="kafka-reconnect")
+
+    async def _thu_noi(self) -> bool:
+        aiokafka = _require_aiokafka()
+        producer = aiokafka.AIOKafkaProducer(
+            bootstrap_servers=self._config.bootstrap_servers,
+            client_id=self._config.client_id,
+            acks=self._config.acks if self._config.acks != "all" else "all",
+            request_timeout_ms=int(self._config.request_timeout_seconds * 1000),
+            # Không bật idempotence mặc định: nó đòi acks=all và bản Kafka đủ
+            # mới; bật ngầm sẽ làm cụm cũ từ chối kết nối mà không rõ vì sao.
+        )
+        try:
+            await asyncio.wait_for(producer.start(), self._config.connect_timeout_seconds)
+        except Exception as exc:  # noqa: BLE001 - mọi lỗi đều dẫn tới cùng một việc: thử lại
+            with contextlib.suppress(Exception):
+                await producer.stop()
+            log.warning(
+                "kafka.connect_failed",
+                servers=self.servers,
+                error=f"{type(exc).__name__}: {exc}",
+            )
+            return False
+
+        self._producer = producer
+        log.info("kafka.connected", servers=self.servers, client_id=self._config.client_id)
+        await self._run_hooks()
+        return True
+
+    async def _reconnect_forever(self) -> None:
+        delay = self._config.reconnect_delay_seconds
+        while not self._closing and self._producer is None:
+            await asyncio.sleep(delay)
+            if self._closing:
+                return
+            if await self._thu_noi():
+                log.info("kafka.recovered", servers=self.servers)
+                return
+            delay = min(delay * 2, self._config.max_reconnect_delay_seconds)
+
+    def on_ready(self, hook: Callable[[], Awaitable[None]]) -> None:
+        """Việc cần làm sau mỗi lần nối được — consumer dùng để bật vòng đọc."""
+        self._ready_hooks.append(hook)
+
+    async def _run_hooks(self) -> None:
+        for hook in list(self._ready_hooks):
+            try:
+                await hook()
+            except Exception as exc:
+                log.exception("kafka.ready_hook_failed", error=str(exc))
+
+    async def shutdown(self) -> None:
+        self._closing = True
+        if self._supervisor is not None:
+            self._supervisor.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._supervisor
+            self._supervisor = None
+        if self._producer is not None:
+            with contextlib.suppress(Exception):
+                await self._producer.stop()
+            log.info("kafka.disconnected")
+        self._producer = None
+
+    def _ready(self) -> Any:
+        if not self._config.enabled:
+            raise ComponentNotEnabledError(
+                "Kafka đang tắt (APP_KAFKA__ENABLED=false) nên không gửi tin được."
+            )
+        if self._producer is None:
+            raise ServiceUnavailableError("Chưa kết nối được Kafka")
+        return self._producer
+
+    # ---------------------------------------------------------------- gửi
+    async def publish(
+        self,
+        topic: str,
+        payload: Any = None,
+        *,
+        key: str | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+        fire_and_forget: bool = False,
+    ) -> bool:
+        """Gửi một tin và CHỜ cụm xác nhận. Trả về True nếu đã ghi xong.
+
+        `key` quyết định phân vùng: mọi tin cùng key rơi vào cùng một phân vùng,
+        nên chúng được xử lý ĐÚNG THỨ TỰ. Không có key thì tin rải đều và thứ tự
+        giữa chúng không còn bảo đảm gì. Quy tắc thực dụng: lấy id của thực thể
+        làm key (`key=order_id`) khi thứ tự có ý nghĩa.
+
+        Mức bảo đảm ghi lấy theo `APP_KAFKA__ACKS` — đây là thuộc tính của cụm,
+        không phải quyết định của từng lời gọi.
+        """
+        if not self._config.enabled:
+            raise ComponentNotEnabledError(
+                "Kafka đang tắt (APP_KAFKA__ENABLED=false) nên không gửi tin được."
+            )
+        if self._producer is None:
+            kafka_publish_failed.inc(topic=topic)
+            if fire_and_forget:
+                log.warning("kafka.publish_skipped", topic=topic, reason="chưa kết nối")
+                return False
+            raise ServiceUnavailableError("Chưa kết nối được Kafka")
+
+        body = payload if isinstance(payload, bytes) else json.dumps(
+            payload, ensure_ascii=False, default=str
+        ).encode()
+        try:
+            await asyncio.wait_for(
+                self._producer.send_and_wait(
+                    topic,
+                    value=body,
+                    key=key.encode() if key else None,
+                    headers=[(k, str(v).encode()) for k, v in (headers or {}).items()] or None,
+                ),
+                timeout or self._config.request_timeout_seconds,
+            )
+        except Exception as exc:
+            kafka_publish_failed.inc(topic=topic)
+            if fire_and_forget:
+                log.warning(
+                    "kafka.publish_failed",
+                    topic=topic,
+                    error=f"{type(exc).__name__}: {exc}",
+                )
+                return False
+            if isinstance(exc, TimeoutErrors):
+                raise ServiceUnavailableError(
+                    f"Kafka không xác nhận trong {timeout or self._config.request_timeout_seconds}s"
+                ) from exc
+            raise
+
+        kafka_published.inc(topic=topic)
+        log.debug("kafka.published", topic=topic, key=key)
+        return True
+
+    def stats(self) -> dict[str, Any]:
+        return {
+            "enabled": self._config.enabled,
+            "connected": self.connected,
+            "servers": self.servers if self._config.enabled else None,
+            "acks": self._config.acks,
+        }

pymodular/infrastructure/kafka/consumers.py

@@ -0,0 +1,371 @@
+"""Consumer Kafka — `@kafka_subscriber`, tương đương `@rabbitmq_subscriber` của RabbitMQ.
+
+    @injectable
+    class DonHangConsumer:
+        @kafka_subscriber("don-hang", group="kho-van")
+        async def xu_ly(self, payload: DonHang, meta: dict) -> None:
+            ...
+
+`group` là BẮT BUỘC và cố ý không tự sinh, giống `queue` bên RabbitMQ: nhóm
+chính là danh tính của con trỏ đọc. Tên tự sinh sẽ đổi sau mỗi lần deploy, và
+mỗi lần deploy sẽ đọc lại từ đầu (hoặc bỏ qua sạch phần cũ, tuỳ
+`auto_offset_reset`).
+
+Ba điều khác RabbitMQ, phải nắm trước khi dùng:
+
+1. **Thử lại làm ĐỨNG phân vùng.** Kafka không cho ack lẻ từng tin: con trỏ đọc
+   chỉ tiến lên. Nên thử lại tin thứ 5 nghĩa là tin thứ 6, 7, 8... phải chờ.
+   Đó là cái giá của việc giữ đúng thứ tự, và cũng là lý do `retry_delay` ở đây
+   nên nhỏ hơn nhiều so với bên RabbitMQ.
+
+2. **Không xoá được một tin.** Tin lỗi được sao sang topic `<topic>.dlt` rồi con
+   trỏ đi tiếp; bản gốc vẫn nằm trong nhật ký cho tới khi hết hạn giữ.
+
+3. **Số worker chạy song song bị chặn bởi số phân vùng.** Topic một phân vùng
+   thì chạy mười worker cũng chỉ một worker có việc.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import inspect
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, get_type_hints
+
+from pydantic import BaseModel, ValidationError
+
+from pymodular.core.config import Settings
+from pymodular.core.container import _REGISTRY, container, injectable, request_scope
+from pymodular.core.context import new_request_id, reset_request_id, set_request_id
+from pymodular.core.logging import get_logger
+from pymodular.infrastructure.kafka.broker import KafkaBroker, _require_aiokafka
+from pymodular.infrastructure.kafka.metrics import (
+    kafka_consume_failed,
+    kafka_consumed,
+    kafka_dead_lettered,
+)
+
+log = get_logger(__name__)
+
+_SPEC_ATTR = "__kafka_subscriber__"
+
+
+class PermanentMessageError(Exception):
+    """Tin này sai vĩnh viễn — bỏ qua mọi lượt thử, đẩy thẳng sang `<topic>.dlt`."""
+
+
+@dataclass(slots=True)
+class KafkaSpec:
+    topic: str
+    group: str
+    auto_offset_reset: str = "latest"
+    max_retries: int = 3
+    retry_delay: float = 1.0
+    dead_letter: bool = True
+    cls: type | None = None
+    fn: Callable | None = None
+    model: type[BaseModel] | None = None
+    wants_meta: bool = False
+
+    @property
+    def label(self) -> str:
+        return f"{self.cls.__name__}.{self.fn.__name__}" if self.cls and self.fn else self.topic
+
+    @property
+    def dlt(self) -> str:
+        return f"{self.topic}.dlt"
+
+
+def kafka_subscriber(
+    topic: str,
+    *,
+    group: str,
+    auto_offset_reset: str = "latest",
+    max_retries: int = 3,
+    retry_delay: float = 1.0,
+    dead_letter: bool = True,
+) -> Callable[[Callable], Callable]:
+    """Gắn method vào một topic Kafka, đọc dưới danh nghĩa nhóm `group`.
+
+        group               BẮT BUỘC — danh tính con trỏ đọc. Nhiều worker cùng
+                            group thì CHIA NHAU phân vùng; khác group thì mỗi
+                            bên nhận đủ một bản sao của mọi tin.
+        auto_offset_reset   nhóm MỚI (chưa có con trỏ) bắt đầu từ đâu:
+                            "latest" = chỉ tin phát sinh từ giờ trở đi (mặc
+                            định, an toàn) | "earliest" = đọc lại từ đầu nhật
+                            ký, có thể là hàng triệu tin. Nhóm đã có con trỏ thì
+                            tham số này KHÔNG có tác dụng.
+        max_retries         thử lại mấy lần trước khi bỏ sang <topic>.dlt.
+                            Nhớ: thử lại làm đứng cả phân vùng.
+        retry_delay         chờ giữa các lần thử (giây). Để nhỏ.
+        dead_letter         False = tin lỗi bị BỎ QUA hẳn, con trỏ vẫn đi tiếp.
+    """
+    if not group:
+        raise ValueError("kafka_subscriber cần `group` — xem docstring")
+    if auto_offset_reset not in ("latest", "earliest"):
+        raise ValueError("auto_offset_reset phải là 'latest' hoặc 'earliest'")
+
+    def decorate(fn: Callable) -> Callable:
+        if not inspect.iscoroutinefunction(fn):
+            raise RuntimeError(f"{fn.__name__} phải là `async def`")
+        setattr(
+            fn,
+            _SPEC_ATTR,
+            KafkaSpec(
+                topic=topic,
+                group=group,
+                auto_offset_reset=auto_offset_reset,
+                max_retries=max_retries,
+                retry_delay=retry_delay,
+                dead_letter=dead_letter,
+            ),
+        )
+        return fn
+
+    return decorate
+
+
+def discover_kafka_subscribers() -> list[KafkaSpec]:
+    """Quét mọi provider đã đăng ký để tìm method mang @kafka_subscriber."""
+    found: list[KafkaSpec] = []
+    for cls in _REGISTRY.values():
+        for fn in vars(cls).values():
+            spec: KafkaSpec | None = getattr(fn, _SPEC_ATTR, None)
+            if spec is None:
+                continue
+
+            params = list(inspect.signature(fn).parameters.values())[1:]
+            if not params or len(params) > 2:
+                raise RuntimeError(
+                    f"{cls.__name__}.{fn.__name__}: chữ ký phải là "
+                    "(self, payload) hoặc (self, payload, meta)"
+                )
+
+            hints = get_type_hints(fn)
+            annotation = hints.get(params[0].name)
+            model = (
+                annotation
+                if isinstance(annotation, type) and issubclass(annotation, BaseModel)
+                else None
+            )
+            found.append(
+                KafkaSpec(
+                    topic=spec.topic,
+                    group=spec.group,
+                    auto_offset_reset=spec.auto_offset_reset,
+                    max_retries=spec.max_retries,
+                    retry_delay=spec.retry_delay,
+                    dead_letter=spec.dead_letter,
+                    cls=cls,
+                    fn=fn,
+                    model=model,
+                    wants_meta=len(params) == 2,
+                )
+            )
+    return sorted(found, key=lambda s: (s.group, s.topic))
+
+
+@injectable
+class KafkaRunner:
+    """Một AIOKafkaConsumer cho mỗi @kafka_subscriber, mỗi cái một task."""
+
+    def __init__(self, broker: KafkaBroker, settings: Settings) -> None:
+        self._broker = broker
+        self._config = settings.kafka
+        self._specs: list[KafkaSpec] = []
+        self._tasks: dict[str, asyncio.Task[None]] = {}
+        self._closing = False
+
+    async def startup(self) -> None:
+        if not self._config.enabled:
+            return
+        self._specs = discover_kafka_subscribers()
+        if not self._specs:
+            return
+
+        self._closing = False
+        self._broker.on_ready(self._setup)
+        if self._broker.connected:
+            await self._setup()
+
+    async def _setup(self) -> None:
+        """Idempotent: gọi lại bao nhiêu lần cũng không sinh consumer trùng."""
+        for spec in self._specs:
+            khoa = f"{spec.group}:{spec.topic}"
+            cu = self._tasks.get(khoa)
+            if cu is not None and not cu.done():
+                continue
+            self._tasks[khoa] = asyncio.create_task(self._vong_doc(spec), name=f"kafka-{khoa}")
+
+    async def _vong_doc(self, spec: KafkaSpec) -> None:
+        """Đọc mãi. Consumer chết vì bất cứ lý do gì thì dựng lại, có backoff.
+
+        Mỗi spec một consumer RIÊNG: dùng chung một consumer cho nhiều nhóm là
+        không thể (nhóm gắn với con trỏ đọc), và một topic khai sai không được
+        phép kéo các topic khác chết theo.
+        """
+        aiokafka = _require_aiokafka()
+        delay = self._config.reconnect_delay_seconds
+        while not self._closing:
+            consumer = aiokafka.AIOKafkaConsumer(
+                spec.topic,
+                bootstrap_servers=self._config.bootstrap_servers,
+                group_id=spec.group,
+                client_id=self._config.client_id,
+                auto_offset_reset=spec.auto_offset_reset,
+                # Tự commit theo đồng hồ sẽ commit cả những tin CHƯA xử lý xong
+                # — tiến trình chết đúng lúc đó là mất tin. Commit tay sau khi
+                # handler xong cho ngữ nghĩa "ít nhất một lần".
+                enable_auto_commit=False,
+            )
+            try:
+                await consumer.start()
+                log.info(
+                    "kafka.consumer_started",
+                    handler=spec.label,
+                    topic=spec.topic,
+                    group=spec.group,
+                    tu=spec.auto_offset_reset,
+                )
+                delay = self._config.reconnect_delay_seconds
+                async for message in consumer:
+                    if self._closing:
+                        break
+                    await self._xu_ly(spec, message)
+                    await consumer.commit()
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:  # noqa: BLE001 - hỏng kiểu gì cũng dựng lại
+                if self._closing:
+                    return
+                log.warning(
+                    "kafka.consumer_lost",
+                    handler=spec.label,
+                    error=f"{type(exc).__name__}: {exc}",
+                    retry=delay,
+                )
+            finally:
+                with contextlib.suppress(Exception):
+                    await consumer.stop()
+
+            if self._closing:
+                return
+            await asyncio.sleep(delay)
+            delay = min(delay * 2, self._config.max_reconnect_delay_seconds)
+
+    async def _xu_ly(self, spec: KafkaSpec, message: Any) -> None:
+        """Chạy handler, thử lại tại chỗ, hết lượt thì sang <topic>.dlt.
+
+        Hàm này KHÔNG được ném lỗi ra ngoài: ném là vòng đọc đứt và cả phân
+        vùng dừng lại vì một tin hỏng.
+        """
+        for lan in range(1, spec.max_retries + 2):
+            try:
+                await self._goi(spec, message, lan)
+            except PermanentMessageError as exc:
+                log.error("kafka.permanent_error", handler=spec.label, error=str(exc))
+                await self._bo_sang_dlt(spec, message, exc)
+                return
+            except Exception as exc:
+                kafka_consume_failed.inc(topic=spec.topic)
+                log.exception(
+                    "kafka.handler_failed",
+                    handler=spec.label,
+                    topic=spec.topic,
+                    partition=message.partition,
+                    offset=message.offset,
+                    attempt=lan,
+                    error=str(exc),
+                )
+                if lan > spec.max_retries:
+                    await self._bo_sang_dlt(spec, message, exc)
+                    return
+                await asyncio.sleep(spec.retry_delay)
+            else:
+                kafka_consumed.inc(topic=spec.topic)
+                return
+
+    async def _goi(self, spec: KafkaSpec, message: Any, lan: int) -> None:
+        token = set_request_id(new_request_id())
+        try:
+            async with request_scope():
+                payload: Any = json.loads(message.value)
+                if spec.model is not None:
+                    try:
+                        payload = spec.model.model_validate(payload)
+                    except ValidationError as exc:
+                        raise PermanentMessageError(f"Payload không hợp lệ: {exc}") from exc
+
+                instance = container.resolve(spec.cls)      # type: ignore[arg-type]
+                if spec.wants_meta:
+                    meta = {
+                        "topic": message.topic,
+                        "partition": message.partition,
+                        "offset": message.offset,
+                        "key": message.key.decode() if message.key else None,
+                        "timestamp": message.timestamp,
+                        "attempt": lan,
+                    }
+                    await spec.fn(instance, payload, meta)  # type: ignore[misc]
+                else:
+                    await spec.fn(instance, payload)        # type: ignore[misc]
+        finally:
+            reset_request_id(token)
+
+    async def _bo_sang_dlt(self, spec: KafkaSpec, message: Any, error: BaseException) -> None:
+        kafka_dead_lettered.inc(topic=spec.topic)
+        if not spec.dead_letter:
+            log.error(
+                "kafka.message_dropped",
+                handler=spec.label,
+                offset=message.offset,
+                hint="consumer khai dead_letter=False nên tin bị bỏ qua, không lưu lại",
+            )
+            return
+
+        try:
+            await self._broker.publish(
+                spec.dlt,
+                json.loads(message.value),
+                key=message.key.decode() if message.key else None,
+                headers={
+                    "x-original-topic": message.topic,
+                    "x-original-partition": str(message.partition),
+                    "x-original-offset": str(message.offset),
+                    "x-error": f"{type(error).__name__}: {error}"[:500],
+                },
+                fire_and_forget=True,
+            )
+            log.error("kafka.dead_lettered", handler=spec.label, topic=spec.dlt)
+        except Exception as exc:  # không cứu được thì cũng đừng chặn phân vùng
+            log.exception("kafka.dlt_publish_failed", handler=spec.label, error=str(exc))
+
+    async def shutdown(self) -> None:
+        self._closing = True
+        for task in self._tasks.values():
+            task.cancel()
+        for task in self._tasks.values():
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await task
+        self._tasks.clear()
+
+    def stats(self) -> dict[str, Any]:
+        return {
+            "consumers": [
+                {
+                    "handler": spec.label,
+                    "topic": spec.topic,
+                    "group": spec.group,
+                    "retries": spec.max_retries,
+                    "dead_letter": spec.dlt if spec.dead_letter else None,
+                    "running": (
+                        (task := self._tasks.get(f"{spec.group}:{spec.topic}")) is not None
+                        and not task.done()
+                    ),
+                }
+                for spec in self._specs
+            ]
+        }

pymodular/infrastructure/kafka/metrics.py

@@ -0,0 +1,17 @@
+"""Số đo của lớp Kafka."""
+
+from __future__ import annotations
+
+from pymodular.core.metrics import Counter, registry
+
+kafka_published = registry.register(Counter("kafka_published_total", "Số tin đã gửi lên Kafka"))
+kafka_publish_failed = registry.register(
+    Counter("kafka_publish_failed_total", "Số lần gửi tin thất bại")
+)
+kafka_consumed = registry.register(Counter("kafka_consumed_total", "Số tin đã xử lý xong"))
+kafka_consume_failed = registry.register(
+    Counter("kafka_consume_failed_total", "Số lần handler xử lý lỗi (tính cả lần thử lại)")
+)
+kafka_dead_lettered = registry.register(
+    Counter("kafka_dead_lettered_total", "Số tin bị đẩy sang topic chết")
+)

pymodular/infrastructure/mqtt/__init__.py

@@ -0,0 +1,35 @@
+"""Lớp MQTT — TUỲ CHỌN, và độc lập với mọi thứ khác.
+
+    pip install 'fastapi-modular[mqtt]'   # cài aiomqtt + ghi sẵn APP_MQTT__* vào .env
+
+Dùng cho thiết bị IoT: giao thức nhẹ, giữ kết nối lâu, chịu được mạng chập
+chờn. Không dùng thì để `APP_MQTT__ENABLED=false` (mặc định).
+"""
+
+from __future__ import annotations
+
+from pymodular.infrastructure.mqtt.client import MqttClient
+from pymodular.infrastructure.mqtt.consumers import (
+    MqttRunner,
+    discover_mqtt_subscribers,
+    mqtt_subscriber,
+)
+from pymodular.infrastructure.mqtt.patterns import (
+    covers,
+    matches,
+    narrow_filters,
+    validate_topic,
+    validate_topic_filter,
+)
+
+__all__ = [
+    "MqttClient",
+    "MqttRunner",
+    "covers",
+    "discover_mqtt_subscribers",
+    "matches",
+    "mqtt_subscriber",
+    "narrow_filters",
+    "validate_topic",
+    "validate_topic_filter",
+]