fastapi-modular 0.1.0__py3-none-any.whl

pymodular/infrastructure/mqtt/client.py

@@ -0,0 +1,292 @@
+"""Kết nối MQTT: giữ một phiên lâu dài, gửi tin, và nuôi vòng đọc tin về.
+
+MQTT là TUỲ CHỌN. `APP_MQTT__ENABLED` mặc định false thì lớp này nằm im.
+
+    pip install 'fastapi-modular[mqtt]'   # cài aiomqtt + ghi sẵn APP_MQTT__* vào .env
+
+Về tự nối lại: aiomqtt KHÔNG tự nối lại (khác aio-pika). Nó cố ý để việc đó cho
+người dùng, nên lớp này chạy một vòng
+`connect -> subscribe -> đọc -> đứt -> chờ -> lặp lại` với backoff. Mọi đăng ký
+topic được khai lại sau mỗi lần nối, vì broker chỉ nhớ chúng khi phiên là
+persistent (`clean_session=false` + `client_id` cố định).
+
+Gửi tin trong lúc đang đứt thì ném `ServiceUnavailableError`, trừ khi gọi với
+`fire_and_forget=True`. Không có hàng đợi chờ gửi ở phía client: giữ tin trong
+RAM rồi hứa gửi sau là một lời hứa mà tiến trình chết là mất — muốn bảo đảm thì
+đó là việc của QoS 1/2 với phiên persistent, hoặc của RabbitMQ/Kafka.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import uuid
+from collections.abc import Awaitable, Callable
+from typing import Any
+from urllib.parse import urlparse
+
+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.mqtt.metrics import mqtt_publish_failed, mqtt_published
+from pymodular.infrastructure.mqtt.patterns import narrow_filters, validate_topic
+
+log = get_logger(__name__)
+
+DEFAULT_URL = "mqtt://localhost:1883"
+
+
+def _require_aiomqtt() -> Any:
+    try:
+        import aiomqtt
+    except ModuleNotFoundError as exc:
+        raise ComponentNotEnabledError(
+            "APP_MQTT__ENABLED=true nhưng chưa cài thư viện aiomqtt. "
+            "Chạy `pip install 'fastapi-modular[mqtt]'`, hoặc đặt APP_MQTT__ENABLED=false nếu "
+            "dự án này không dùng MQTT."
+        ) from exc
+    return aiomqtt
+
+
+def parse_url(url: str) -> dict[str, Any]:
+    """Tách mqtt://user:pass@host:port thành tham số cho aiomqtt."""
+    parsed = urlparse(url)
+    if parsed.scheme not in ("mqtt", "mqtts"):
+        raise ValueError(f"APP_MQTT__URL phải bắt đầu bằng mqtt:// hoặc mqtts://, nhận {url!r}")
+    return {
+        "hostname": parsed.hostname or "localhost",
+        "port": parsed.port or (8883 if parsed.scheme == "mqtts" else 1883),
+        "username": parsed.username or None,
+        "password": parsed.password or None,
+        "tls": parsed.scheme == "mqtts",
+    }
+
+
+def safe_url(url: str) -> str:
+    parsed = urlparse(url)
+    if not parsed.password:
+        return url
+    cong = f":{parsed.port}" if parsed.port else ""
+    return f"{parsed.scheme}://{parsed.username or ''}:***@{parsed.hostname}{cong}"
+
+
+@injectable
+class MqttClient:
+    def __init__(self, settings: Settings) -> None:
+        self._config = settings.mqtt
+        self._client: Any = None
+        self._task: asyncio.Task[None] | None = None
+        self._closing = False
+        self._connected = asyncio.Event()
+        self._dang_ky: dict[str, int] = {}          # topic -> qos
+        self._router: Callable[[Any], Awaitable[None]] | None = None
+        self._lan_dut = 0
+
+    # ------------------------------------------------------------- vòng đời
+    @property
+    def enabled(self) -> bool:
+        return self._config.enabled
+
+    @property
+    def connected(self) -> bool:
+        return self._connected.is_set()
+
+    @property
+    def url(self) -> str:
+        return safe_url(self._config.url)
+
+    @property
+    def client_id(self) -> str:
+        return self._config.client_id or f"pymodular-{uuid.uuid4().hex[:8]}"
+
+    def subscribe_topic(self, topic: str, qos: int = 1) -> None:
+        """Ghi nhận một topic cần đăng ký. Gọi TRƯỚC startup().
+
+        Giữ mức QoS cao nhất khi hai handler cùng nghe một topic: đăng ký ở
+        QoS 0 rồi lại đòi QoS 1 thì broker giao theo mức đã đăng ký, tin sẽ
+        lặng lẽ mất khi mạng chớp.
+        """
+        self._dang_ky[topic] = max(self._dang_ky.get(topic, 0), qos)
+
+    def _de_dang_ky(self) -> dict[str, int]:
+        """Danh sách thật sự gửi lên broker: đã bỏ bộ lọc bị bộ lọc khác bao trọn.
+
+        Đăng ký chồng nhau ("thiet-bi/#" và "thiet-bi/+/nhiet-do") thì broker
+        giao MỘT tin thành HAI lần — mỗi đăng ký một bản — và mọi handler khớp
+        sẽ chạy hai lượt. Đo trên mosquitto: gửi 1 tin, handler chạy 4 lượt.
+        Đăng ký cái rộng nhất rồi tự chia tin trong tiến trình thì đúng một lượt.
+        """
+        gon = narrow_filters(self._dang_ky)
+        if bo := sorted(set(self._dang_ky) - set(gon)):
+            log.debug("mqtt.subscription_gop", bo_qua=bo, giu=sorted(gon))
+        return gon
+
+    def set_router(self, router: Callable[[Any], Awaitable[None]]) -> None:
+        """Ai nhận tin về: `MqttRunner` cắm vào đây."""
+        self._router = router
+
+    async def startup(self) -> None:
+        if not self._config.enabled:
+            log.debug("mqtt.disabled")
+            return
+
+        _require_aiomqtt()
+        parse_url(self._config.url)           # sai dạng thì báo ngay, đừng đợi vòng nối lại
+        if self._config.url == DEFAULT_URL:
+            log.info("mqtt.default_url", url=DEFAULT_URL, hint="chưa đặt APP_MQTT__URL?")
+        if not self._config.clean_session and not self._config.client_id:
+            log.warning(
+                "mqtt.session_khong_ben",
+                hint="clean_session=false cần APP_MQTT__CLIENT_ID cố định, "
+                "không thì mỗi lần khởi động là một phiên mới và tin giữ lại bị bỏ",
+            )
+
+        self._closing = False
+        self._task = asyncio.create_task(self._vong_ket_noi(), name="mqtt-connection")
+
+        # Chờ một nhịp cho lần nối đầu, để log khởi động nói đúng trạng thái.
+        with contextlib.suppress(*TimeoutErrors):
+            await asyncio.wait_for(
+                self._connected.wait(), self._config.connect_timeout_seconds
+            )
+        if not self.connected:
+            log.warning(
+                "mqtt.starting_degraded",
+                url=self.url,
+                hint="app vẫn chạy; sẽ nối lại ngầm cho tới khi được",
+            )
+
+    async def _vong_ket_noi(self) -> None:
+        """Nối, đăng ký, đọc tới khi đứt, chờ rồi làm lại. Không bao giờ bỏ cuộc."""
+        aiomqtt = _require_aiomqtt()
+        tham_so = parse_url(self._config.url)
+        tls = tham_so.pop("tls")
+        delay = self._config.reconnect_delay_seconds
+        ma_so = self.client_id
+
+        while not self._closing:
+            try:
+                async with aiomqtt.Client(
+                    **tham_so,
+                    identifier=ma_so,
+                    keepalive=self._config.keepalive_seconds,
+                    clean_session=self._config.clean_session,
+                    tls_context=_tls_context() if tls else None,
+                ) as client:
+                    self._client = client
+                    dang_ky = self._de_dang_ky()
+                    for topic, qos in sorted(dang_ky.items()):
+                        await client.subscribe(topic, qos=qos)
+                    self._connected.set()
+                    delay = self._config.reconnect_delay_seconds
+                    log.info(
+                        "mqtt.connected",
+                        url=self.url,
+                        client_id=ma_so,
+                        topics=sorted(dang_ky),
+                    )
+                    async for message in client.messages:
+                        if self._router is not None:
+                            await self._router(message)
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:  # noqa: BLE001 - đứt kiểu gì cũng nối lại
+                if self._closing:
+                    return
+                self._lan_dut += 1
+                log.warning(
+                    "mqtt.connection_lost",
+                    url=self.url,
+                    error=f"{type(exc).__name__}: {exc}",
+                    retry=delay,
+                )
+            finally:
+                self._connected.clear()
+                self._client = None
+
+            if self._closing:
+                return
+            await asyncio.sleep(delay)
+            delay = min(delay * 2, self._config.max_reconnect_delay_seconds)
+
+    async def shutdown(self) -> None:
+        self._closing = True
+        if self._task is not None:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+            self._task = None
+        self._connected.clear()
+        log.info("mqtt.disconnected")
+
+    # ---------------------------------------------------------------- gửi
+    async def publish(
+        self,
+        topic: str,
+        payload: Any = None,
+        *,
+        qos: int = 1,
+        retain: bool = False,
+        fire_and_forget: bool = False,
+    ) -> bool:
+        """Gửi một tin. Trả về True nếu broker đã nhận.
+
+        qos=0  gửi rồi thôi, không xác nhận — nhanh nhất, mất cũng không biết
+        qos=1  ít nhất một lần: có xác nhận, nhưng CÓ THỂ TRÙNG khi mạng chớp
+        qos=2  đúng một lần: chắc nhất, tốn hai vòng bắt tay, chậm nhất
+
+        `retain=True` bảo broker GIỮ tin này làm giá trị hiện tại của topic:
+        client nào đăng ký sau cũng nhận được ngay bản mới nhất mà không phải
+        chờ lần cập nhật kế tiếp. Đúng cho trạng thái (nhiệt độ, bật/tắt), sai
+        cho sự kiện (nút vừa được bấm) — người nối vào sau sẽ tưởng nút vừa mới
+        bấm lần nữa.
+        """
+        validate_topic(topic)
+        if not self._config.enabled:
+            raise ComponentNotEnabledError(
+                "MQTT đang tắt (APP_MQTT__ENABLED=false) nên không gửi được."
+            )
+
+        client = self._client
+        if client is None or not self.connected:
+            mqtt_publish_failed.inc(topic=topic)
+            if fire_and_forget:
+                log.warning("mqtt.publish_skipped", topic=topic, reason="chưa kết nối")
+                return False
+            raise ServiceUnavailableError("Chưa kết nối được MQTT broker")
+
+        body = payload if isinstance(payload, (bytes, str)) else json.dumps(
+            payload, ensure_ascii=False, default=str
+        )
+        try:
+            await client.publish(topic, payload=body, qos=qos, retain=retain)
+        except Exception as exc:
+            mqtt_publish_failed.inc(topic=topic)
+            if fire_and_forget:
+                log.warning("mqtt.publish_failed", topic=topic, error=str(exc))
+                return False
+            raise ServiceUnavailableError(f"Gửi MQTT thất bại: {exc}") from exc
+
+        mqtt_published.inc(topic=topic)
+        log.debug("mqtt.published", topic=topic, qos=qos, retain=retain)
+        return True
+
+    def stats(self) -> dict[str, Any]:
+        return {
+            "enabled": self._config.enabled,
+            "connected": self.connected,
+            "url": self.url if self._config.enabled else None,
+            "client_id": self._config.client_id or "(tự sinh)",
+            "topics": sorted(self._de_dang_ky()),
+            "listeners": sorted(self._dang_ky),
+            "disconnects": self._lan_dut,
+        }
+
+
+def _tls_context() -> Any:
+    import ssl
+
+    return ssl.create_default_context()

pymodular/infrastructure/mqtt/consumers.py

@@ -0,0 +1,219 @@
+"""Nhận tin MQTT — tương đương `@rabbitmq_subscriber` của RabbitMQ, cho thiết bị IoT.
+
+    @injectable
+    class DenListener:
+        @mqtt_subscriber("nha/+/den", qos=1)
+        async def trang_thai(self, payload: dict, meta: dict) -> None:
+            print(meta["topic"], payload)
+
+Khác RabbitMQ ở chỗ **không có hàng đợi thử lại và không có DLQ**. MQTT không
+cho client từ chối một tin: nhận là xong, broker coi như đã giao. Nên khi
+handler ném lỗi, khung ghi log và ĐI TIẾP — bịa ra vòng thử lại trong tiến
+trình sẽ chặn mọi tin phía sau của cùng một kết nối.
+
+Cần chắc chắn không mất việc thì đẩy sang chỗ có hàng đợi ngay trong handler:
+nhận tin MQTT rồi `broker.publish(...)` vào RabbitMQ, xử lý nặng ở đó.
+"""
+
+from __future__ import annotations
+
+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.mqtt.client import MqttClient
+from pymodular.infrastructure.mqtt.metrics import (
+    mqtt_handler_failed,
+    mqtt_received,
+    mqtt_unrouted,
+)
+from pymodular.infrastructure.mqtt.patterns import matches, validate_topic_filter
+
+log = get_logger(__name__)
+
+_SPEC_ATTR = "__mqtt_subscriber__"
+
+
+@dataclass(slots=True)
+class MqttSpec:
+    topic: str
+    qos: int = 1
+    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
+
+
+def mqtt_subscriber(topic: str, *, qos: int = 1) -> Callable[[Callable], Callable]:
+    """Gắn method vào một topic MQTT (có thể chứa `+` và `#`).
+
+        topic   bộ lọc: "nha/bep/den" khớp đúng, "nha/+/den" một tầng bất kỳ,
+                "nha/#" mọi tầng phía dưới
+        qos     mức bảo đảm khi broker GIAO tin cho mình:
+                0 = có thì nhận, mất không biết (số đo dày đặc, mất vài cái
+                    không sao)
+                1 = ít nhất một lần — mặc định. Handler PHẢI chịu được tin
+                    trùng, vì mạng chớp là broker giao lại.
+                2 = đúng một lần, chậm hơn hẳn; chỉ dùng khi xử lý trùng thật
+                    sự gây hại (trừ tiền, mở khoá)
+
+    Hai handler cùng một topic ở hai mức QoS khác nhau thì lấy mức CAO HƠN cho
+    lần đăng ký với broker.
+    """
+    validate_topic_filter(topic)
+    if qos not in (0, 1, 2):
+        raise ValueError(f"qos phải là 0, 1 hoặc 2 — nhận {qos!r}")
+
+    def decorate(fn: Callable) -> Callable:
+        if not inspect.iscoroutinefunction(fn):
+            raise RuntimeError(f"{fn.__name__} phải là `async def`")
+        setattr(fn, _SPEC_ATTR, MqttSpec(topic=topic, qos=qos))
+        return fn
+
+    return decorate
+
+
+def discover_mqtt_subscribers() -> list[MqttSpec]:
+    """Quét mọi provider đã đăng ký để tìm method mang @mqtt_subscriber."""
+    found: list[MqttSpec] = []
+    for cls in _REGISTRY.values():
+        for fn in vars(cls).values():
+            spec: MqttSpec | 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(
+                MqttSpec(
+                    topic=spec.topic,
+                    qos=spec.qos,
+                    cls=cls,
+                    fn=fn,
+                    model=model,
+                    wants_meta=len(params) == 2,
+                )
+            )
+    return sorted(found, key=lambda s: s.topic)
+
+
+@injectable
+class MqttRunner:
+    """Đăng ký topic với client và chia tin về đúng handler."""
+
+    def __init__(self, client: MqttClient, settings: Settings) -> None:
+        self._client = client
+        self._config = settings.mqtt
+        self._specs: list[MqttSpec] = []
+
+    async def startup(self) -> None:
+        if not self._config.enabled:
+            return
+        self._specs = discover_mqtt_subscribers()
+        if not self._specs:
+            return
+
+        # Đăng ký TRƯỚC khi client mở kết nối, để lần nối đầu tiên đã có đủ
+        # topic — và mọi lần nối lại sau đó cũng dùng đúng danh sách này.
+        for spec in self._specs:
+            self._client.subscribe_topic(spec.topic, spec.qos)
+        self._client.set_router(self._giao)
+        log.info(
+            "mqtt.listeners_registered",
+            count=len(self._specs),
+            topics=sorted({s.topic for s in self._specs}),
+        )
+
+    async def _giao(self, message: Any) -> None:
+        topic = str(message.topic)
+        mqtt_received.inc(topic=topic)
+
+        khop = [spec for spec in self._specs if matches(spec.topic, topic)]
+        if not khop:
+            # Broker giao một topic không ai nghe: gần như luôn là đăng ký thừa
+            # hoặc gõ nhầm bộ lọc. Im lặng ở đây thì không cách nào biết.
+            mqtt_unrouted.inc(topic=topic)
+            log.debug("mqtt.unrouted", topic=topic)
+            return
+
+        for spec in khop:
+            await self._chay(spec, topic, message)
+
+    async def _chay(self, spec: MqttSpec, topic: str, message: Any) -> None:
+        token = set_request_id(new_request_id())
+        try:
+            async with request_scope():
+                payload = _doc(message.payload)
+                if spec.model is not None:
+                    try:
+                        payload = spec.model.model_validate(payload)
+                    except ValidationError as exc:
+                        # Không có DLQ để đẩy vào — thiết bị gửi sai khuôn thì
+                        # ghi log kèm topic để còn lần ra đúng con nào.
+                        log.error(
+                            "mqtt.payload_invalid",
+                            handler=spec.label,
+                            topic=topic,
+                            error=str(exc),
+                        )
+                        return
+
+                instance = container.resolve(spec.cls)      # type: ignore[arg-type]
+                if spec.wants_meta:
+                    meta = {
+                        "topic": topic,
+                        "filter": spec.topic,
+                        "qos": int(getattr(message, "qos", spec.qos)),
+                        "retain": bool(getattr(message, "retain", False)),
+                    }
+                    await spec.fn(instance, payload, meta)  # type: ignore[misc]
+                else:
+                    await spec.fn(instance, payload)        # type: ignore[misc]
+        except Exception as exc:
+            # Ném ra khỏi đây sẽ làm đứt vòng đọc, tức là mọi handler khác im
+            # theo cho tới lần nối lại. Một tin hỏng không đáng giá vậy.
+            mqtt_handler_failed.inc(topic=spec.topic)
+            log.exception("mqtt.handler_failed", handler=spec.label, topic=topic, error=str(exc))
+        finally:
+            reset_request_id(token)
+
+    def stats(self) -> dict[str, Any]:
+        return {
+            "listeners": [
+                {"handler": spec.label, "topic": spec.topic, "qos": spec.qos}
+                for spec in self._specs
+            ]
+        }
+
+
+def _doc(payload: Any) -> Any:
+    """Thiết bị hay gửi chuỗi thuần ("ON", "23.5") chứ không phải JSON."""
+    raw = payload.decode("utf-8", errors="replace") if isinstance(payload, bytes) else str(payload)
+    try:
+        return json.loads(raw)
+    except (TypeError, ValueError):
+        return raw

pymodular/infrastructure/mqtt/metrics.py

@@ -0,0 +1,17 @@
+"""Số đo của lớp MQTT."""
+
+from __future__ import annotations
+
+from pymodular.core.metrics import Counter, registry
+
+mqtt_published = registry.register(Counter("mqtt_published_total", "Số tin đã gửi lên broker"))
+mqtt_publish_failed = registry.register(
+    Counter("mqtt_publish_failed_total", "Số lần gửi tin thất bại")
+)
+mqtt_received = registry.register(Counter("mqtt_received_total", "Số tin nhận được"))
+mqtt_handler_failed = registry.register(
+    Counter("mqtt_handler_failed_total", "Số tin handler xử lý lỗi")
+)
+mqtt_unrouted = registry.register(
+    Counter("mqtt_unrouted_total", "Số tin nhận được mà không handler nào khớp")
+)

pymodular/infrastructure/mqtt/patterns.py

@@ -0,0 +1,116 @@
+"""Khớp topic MQTT: `+` một tầng, `#` mọi tầng còn lại.
+
+Khác hẳn routing key của AMQP dù nhìn na ná:
+
+    AMQP    "alert.*"     * = đúng một từ,   # = nhiều từ,  ngăn bằng dấu chấm
+    MQTT    "alert/+"     + = đúng một tầng, # = nhiều tầng, ngăn bằng dấu /
+
+`#` phải là ký tự CUỐI và chiếm trọn một tầng: "nha/#" hợp lệ, "nha/#/den" và
+"nha#" thì không. Broker sẽ từ chối, nhưng nó từ chối lúc chạy còn hàm dưới đây
+từ chối ngay lúc khai báo decorator.
+"""
+
+from __future__ import annotations
+
+from pymodular.core.exceptions import BadRequestError
+
+
+def validate_topic_filter(topic_filter: str) -> None:
+    if not topic_filter:
+        raise BadRequestError("Topic MQTT không được rỗng")
+    tang = topic_filter.split("/")
+    for i, phan in enumerate(tang):
+        if "#" in phan:
+            if phan != "#":
+                raise BadRequestError(
+                    f"Topic {topic_filter!r} sai: '#' phải chiếm trọn một tầng (vd 'nha/#')"
+                )
+            if i != len(tang) - 1:
+                raise BadRequestError(
+                    f"Topic {topic_filter!r} sai: '#' phải nằm ở cuối cùng"
+                )
+        elif "+" in phan and phan != "+":
+            raise BadRequestError(
+                f"Topic {topic_filter!r} sai: '+' phải chiếm trọn một tầng (vd 'nha/+/den')"
+            )
+
+
+def validate_topic(topic: str) -> None:
+    """Topic để GỬI thì không được chứa ký tự đại diện."""
+    if not topic:
+        raise BadRequestError("Topic MQTT không được rỗng")
+    if "+" in topic or "#" in topic:
+        raise BadRequestError(
+            f"Topic {topic!r} chứa ký tự đại diện — chỉ dùng được khi ĐĂNG KÝ NGHE, "
+            "không dùng để gửi"
+        )
+
+
+def matches(topic_filter: str, topic: str) -> bool:
+    """Topic cụ thể có khớp bộ lọc không."""
+    loc = topic_filter.split("/")
+    that = topic.split("/")
+
+    # Theo chuẩn MQTT, ký tự đại diện ở tầng đầu KHÔNG chạm tới topic hệ thống
+    # ($SYS/...). Không có luật này thì một handler nghe "#" sẽ hút cả số liệu
+    # nội bộ của broker.
+    if that and that[0].startswith("$") and loc[0] in ("+", "#"):
+        return False
+
+    for i, phan in enumerate(loc):
+        if phan == "#":
+            return True                      # nuốt mọi tầng còn lại, kể cả không còn tầng nào
+        if i >= len(that):
+            return False
+        if phan != "+" and phan != that[i]:
+            return False
+    return len(loc) == len(that)
+
+
+def covers(rong: str, hep: str) -> bool:
+    """Bộ lọc `rong` có bao trọn `hep` không — tức mọi topic khớp `hep` đều khớp `rong`.
+
+    Cần để KHÔNG đăng ký hai bộ lọc chồng nhau lên broker. Đăng ký cả
+    "thiet-bi/#" lẫn "thiet-bi/+/nhiet-do" thì mosquitto giao MỘT tin thành HAI
+    lần (mỗi đăng ký một bản), và handler chạy gấp đôi. Đo được: gửi 1 tin,
+    handler chạy 4 lượt.
+
+    Cách sửa là chỉ đăng ký bộ lọc rộng nhất rồi tự chia tin ở trong tiến trình.
+
+    Chú ý không dùng `matches()` để thay hàm này: `matches("a/+", "a/#")` trả về
+    True vì nó coi "#" là một tầng chữ thường, trong khi "a/+" hoàn toàn KHÔNG
+    bao được "a/#" (thiếu "a/b/c").
+    """
+    a = rong.split("/")
+    b = hep.split("/")
+    for i, phan in enumerate(a):
+        if phan == "#":
+            return True                     # nuốt trọn phần còn lại của b
+        if i >= len(b):
+            return False                    # a còn đòi thêm tầng, b hết
+        if b[i] == "#":
+            return False                    # b rộng hơn ở đây (a không phải "#")
+        if phan == "+":
+            continue                        # + bao được mọi tầng đơn, kể cả "+"
+        if phan != b[i]:
+            return False
+    return len(a) == len(b)
+
+
+def narrow_filters(loc: dict[str, int]) -> dict[str, int]:
+    """Bỏ bộ lọc bị bộ lọc khác bao trọn; QoS dồn về cái còn lại (lấy mức cao nhất).
+
+    Vào:  {"thiet-bi/#": 0, "thiet-bi/+/nhiet-do": 1}
+    Ra:   {"thiet-bi/#": 1}
+    """
+    con: dict[str, int] = {}
+    for hep, qos in sorted(loc.items()):
+        bao = next(
+            (r for r in loc if r != hep and covers(r, hep)),
+            None,
+        )
+        if bao is None:
+            con[hep] = max(con.get(hep, 0), qos)
+        else:
+            con[bao] = max(con.get(bao, 0), qos, loc[bao])
+    return con

pymodular/infrastructure/rabbitmq/__init__.py

@@ -0,0 +1,33 @@
+"""Lớp RabbitMQ — TUỲ CHỌN, và độc lập với mọi thứ khác.
+
+Dự án không dùng RabbitMQ thì không cần cài gì và không phải đụng tới đây:
+`APP_RABBITMQ__ENABLED` mặc định là false, thư viện `aio-pika` chỉ được import khi
+thật sự bật lên.
+
+    pip install 'fastapi-modular[rabbitmq]'   # cài thư viện + ghi sẵn APP_RABBITMQ__* vào .env
+
+Lớp này KHÔNG biết gì về HTTP hay WebSocket, và chúng cũng không biết nó. Muốn
+một sự kiện từ hàng đợi hiện lên màn hình người dùng thì đó là việc của code
+ứng dụng — ba dòng trong consumer của bạn, xem docs/rabbitmq.md.
+"""
+
+from __future__ import annotations
+
+from pymodular.infrastructure.rabbitmq.broker import RabbitBroker
+from pymodular.infrastructure.rabbitmq.consumers import (
+    PermanentMessageError,
+    RabbitmqRunner,
+    discover_rabbitmq_subscribers,
+    rabbitmq_subscriber,
+)
+from pymodular.infrastructure.rabbitmq.patterns import validate_pattern, validate_routing_key
+
+__all__ = [
+    "PermanentMessageError",
+    "RabbitBroker",
+    "RabbitmqRunner",
+    "discover_rabbitmq_subscribers",
+    "rabbitmq_subscriber",
+    "validate_pattern",
+    "validate_routing_key",
+]