fastapi-modular 0.1.0__py3-none-any.whl

pymodular/core/logging.py

@@ -0,0 +1,88 @@
+"""Cấu hình structlog + stdlib logging thành một đường ống duy nhất."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Any
+
+import structlog
+
+from pymodular.core.config import LogSettings
+from pymodular.core.context import get_request_id, get_trace_id, get_user_id
+
+
+def _inject_context(
+    _logger: Any, _method: str, event_dict: structlog.types.EventDict
+) -> structlog.types.EventDict:
+    """Gắn request_id / trace_id / user_id từ contextvars vào mọi dòng log."""
+    request_id = get_request_id()
+    if request_id:
+        event_dict.setdefault("request_id", request_id)
+    trace_id = get_trace_id()
+    if trace_id:
+        # trace_id nối log của dịch vụ này với log của các dịch vụ khác trong
+        # cùng một hành trình; request_id chỉ có ý nghĩa trong dịch vụ này.
+        event_dict.setdefault("trace_id", trace_id)
+    user_id = get_user_id()
+    if user_id:
+        event_dict.setdefault("user_id", user_id)
+    return event_dict
+
+
+def configure_logging(settings: LogSettings) -> None:
+    level = getattr(logging, settings.level.upper(), logging.INFO)
+
+    shared_processors: list[structlog.types.Processor] = [
+        structlog.contextvars.merge_contextvars,
+        _inject_context,
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso", utc=True),
+        structlog.processors.StackInfoRenderer(),
+    ]
+
+    renderer: structlog.types.Processor = (
+        structlog.processors.JSONRenderer()
+        if settings.json_format
+        else structlog.dev.ConsoleRenderer(colors=sys.stderr.isatty())
+    )
+
+    structlog.configure(
+        processors=[
+            *shared_processors,
+            structlog.processors.format_exc_info,
+            renderer,
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(level),
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stdout),
+        cache_logger_on_first_use=True,
+    )
+
+    # Đưa log của thư viện bên thứ ba (uvicorn, sqlalchemy, ...) qua structlog.
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(
+        structlog.stdlib.ProcessorFormatter(
+            foreign_pre_chain=shared_processors,
+            processors=[
+                structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+                renderer,
+            ],
+        )
+    )
+
+    root = logging.getLogger()
+    root.handlers = [handler]
+    root.setLevel(level)
+
+    for noisy in ("uvicorn", "uvicorn.error", "uvicorn.access"):
+        lg = logging.getLogger(noisy)
+        lg.handlers = []
+        lg.propagate = True
+
+    # uvicorn.access bị tắt vì middleware AccessLog đã ghi log request đầy đủ hơn.
+    logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+    logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING)
+
+
+def get_logger(name: str | None = None) -> structlog.stdlib.BoundLogger:
+    return structlog.get_logger(name)

pymodular/core/metrics.py

@@ -0,0 +1,190 @@
+"""Số đo dạng Prometheus, viết tay để không phải thêm thư viện.
+
+Chỉ có ba loại cần dùng: Counter (chỉ tăng), Gauge (lên xuống), Histogram
+(phân bố độ trễ). Đủ để trả lời bốn câu hỏi vận hành quan trọng nhất: bao nhiêu
+request, bao nhiêu lỗi, chậm cỡ nào, và tài nguyên còn bao nhiêu.
+
+Một cạm bẫy phải tránh: KHÔNG lấy đường dẫn thật làm nhãn. `/api/users/abc123`
+và `/api/users/def456` là hai nhãn khác nhau, mỗi user tạo một chuỗi số đo mới
+và làm nổ bộ nhớ Prometheus. Phải dùng khuôn đường dẫn `/api/users/{user_id}`.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import defaultdict
+from typing import Any
+
+Labels = tuple[tuple[str, str], ...]
+
+# Mốc chia histogram, tính bằng giây. Chọn quanh ngưỡng người dùng cảm nhận
+# được: dưới 100ms là nhanh, trên 1s là chậm, trên 5s coi như hỏng.
+DEFAULT_BUCKETS = (0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0)
+
+
+def _labels(**kwargs: Any) -> Labels:
+    return tuple(sorted((k, str(v)) for k, v in kwargs.items()))
+
+
+def _render_labels(labels: Labels) -> str:
+    if not labels:
+        return ""
+    inner = ",".join(f'{k}="{_escape(v)}"' for k, v in labels)
+    return "{" + inner + "}"
+
+
+def _escape(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+
+
+class Counter:
+    def __init__(self, name: str, help_text: str) -> None:
+        self.name = name
+        self.help = help_text
+        self._values: dict[Labels, float] = defaultdict(float)
+        self._lock = threading.Lock()
+
+    def inc(self, amount: float = 1.0, **labels: Any) -> None:
+        with self._lock:
+            self._values[_labels(**labels)] += amount
+
+    def render(self) -> list[str]:
+        lines = [f"# HELP {self.name} {self.help}", f"# TYPE {self.name} counter"]
+        with self._lock:
+            for labels, value in sorted(self._values.items()):
+                lines.append(f"{self.name}{_render_labels(labels)} {value:g}")
+        return lines
+
+
+class Gauge:
+    def __init__(self, name: str, help_text: str) -> None:
+        self.name = name
+        self.help = help_text
+        self._values: dict[Labels, float] = defaultdict(float)
+        self._lock = threading.Lock()
+
+    def set(self, value: float, **labels: Any) -> None:
+        with self._lock:
+            self._values[_labels(**labels)] = value
+
+    def inc_gauge(self, amount: float = 1.0, **labels: Any) -> None:
+        with self._lock:
+            self._values[_labels(**labels)] += amount
+
+    def render(self) -> list[str]:
+        lines = [f"# HELP {self.name} {self.help}", f"# TYPE {self.name} gauge"]
+        with self._lock:
+            for labels, value in sorted(self._values.items()):
+                lines.append(f"{self.name}{_render_labels(labels)} {value:g}")
+        return lines
+
+
+class Histogram:
+    def __init__(
+        self, name: str, help_text: str, buckets: tuple[float, ...] = DEFAULT_BUCKETS
+    ) -> None:
+        self.name = name
+        self.help = help_text
+        self.buckets = buckets
+        self._counts: dict[Labels, list[int]] = defaultdict(lambda: [0] * len(buckets))
+        self._sums: dict[Labels, float] = defaultdict(float)
+        self._totals: dict[Labels, int] = defaultdict(int)
+        self._lock = threading.Lock()
+
+    def observe(self, value: float, **labels: Any) -> None:
+        key = _labels(**labels)
+        with self._lock:
+            counts = self._counts[key]
+            for index, edge in enumerate(self.buckets):
+                if value <= edge:
+                    counts[index] += 1
+            self._sums[key] += value
+            self._totals[key] += 1
+
+    def render(self) -> list[str]:
+        lines = [f"# HELP {self.name} {self.help}", f"# TYPE {self.name} histogram"]
+        with self._lock:
+            for key in sorted(self._totals):
+                counts = self._counts[key]
+                for edge, count in zip(self.buckets, counts, strict=True):
+                    labels = _render_labels((*key, ("le", str(edge))))
+                    lines.append(f"{self.name}_bucket{labels} {count}")
+                total = self._totals[key]
+                lines.append(f"{self.name}_bucket{_render_labels((*key, ('le', '+Inf')))} {total}")
+                lines.append(f"{self.name}_sum{_render_labels(key)} {self._sums[key]:g}")
+                lines.append(f"{self.name}_count{_render_labels(key)} {total}")
+        return lines
+
+
+class Registry:
+    def __init__(self) -> None:
+        self._metrics: list[Counter | Gauge | Histogram] = []
+        self._callbacks: list[Any] = []
+
+    def register(self, metric: Counter | Gauge | Histogram):
+        self._metrics.append(metric)
+        return metric
+
+    def on_scrape(self, callback: Any) -> None:
+        """Hàm được gọi ngay trước khi xuất số đo, để cập nhật gauge tức thời."""
+        self._callbacks.append(callback)
+
+    def render(self) -> str:
+        for callback in self._callbacks:
+            callback()
+        lines: list[str] = []
+        for metric in self._metrics:
+            lines.extend(metric.render())
+        return "\n".join(lines) + "\n"
+
+
+registry = Registry()
+
+http_requests = registry.register(
+    Counter("http_requests_total", "Số HTTP request đã xử lý")
+)
+http_duration = registry.register(
+    Histogram("http_request_duration_seconds", "Thời gian xử lý HTTP request")
+)
+http_in_flight = registry.register(
+    Gauge("http_requests_in_flight", "Số request đang xử lý")
+)
+app_info = registry.register(Gauge("app_info", "Thông tin phiên bản ứng dụng"))
+db_circuit_state = registry.register(
+    Gauge("db_circuit_state", "Trạng thái ngắt mạch database (0=đóng 1=nửa mở 2=ngắt)")
+)
+
+# ---- WebSocket ----------------------------------------------------------
+# Nhãn chỉ có `namespace` và `event`, cả hai đều là tập hữu hạn do code khai
+# báo. Tuyệt đối không lấy socket_id hay user_id làm nhãn: mỗi người dùng sẽ
+# đẻ ra một chuỗi số đo mới và làm nổ Prometheus.
+ws_connections = registry.register(
+    Gauge("ws_connections", "Số kết nối WebSocket đang mở")
+)
+ws_connections_total = registry.register(
+    Counter("ws_connections_total", "Tổng số kết nối WebSocket đã mở")
+)
+ws_messages_in = registry.register(
+    Counter("ws_messages_in_total", "Số khung tin nhận từ client")
+)
+ws_messages_out = registry.register(
+    Counter("ws_messages_out_total", "Số khung tin đã xếp hàng gửi cho client")
+)
+ws_send_dropped = registry.register(
+    Counter("ws_send_dropped_total", "Số khung tin bị bỏ vì hàng đợi gửi đầy")
+)
+
+
+class Timer:
+    """Đo thời gian một khối lệnh bằng đồng hồ đơn điệu."""
+
+    __slots__ = ("_started", "elapsed")
+
+    def __enter__(self) -> Timer:
+        self._started = time.perf_counter()
+        self.elapsed = 0.0
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.elapsed = time.perf_counter() - self._started

pymodular/core/schemas.py

@@ -0,0 +1,105 @@
+"""Lớp nền cho DTO và vài tiện ích dùng chung cho mọi module.
+
+Ba thứ ở đây thay cho việc lặp `model_config` trong từng file DTO:
+
+- `InputSchema`  — nền cho DTO đi vào (body request)
+- `OutputSchema` — nền cho DTO đi ra (response)
+- `partial_of()` — sinh biến thể "mọi field optional" cho PATCH, giữ nguyên
+  ràng buộc validate, thay cho việc chép tay lần thứ hai
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, create_model
+
+T = TypeVar("T")
+ModelT = TypeVar("ModelT", bound=BaseModel)
+
+
+class InputSchema(BaseModel):
+    """Nền cho mọi DTO nhận từ client.
+
+    - `extra="forbid"`: gửi thừa field sẽ bị 422 thay vì âm thầm bỏ qua, nhờ
+      vậy client gõ sai tên field biết ngay.
+    - `str_strip_whitespace`: cắt khoảng trắng thừa hai đầu chuỗi, tránh cảnh
+      `"An "` và `"An"` thành hai giá trị khác nhau trong database.
+    """
+
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+
+class OutputSchema(BaseModel):
+    """Nền cho mọi DTO trả về client.
+
+    `from_attributes` cho phép `model_validate()` đọc thẳng từ dataclass entity
+    hay object ORM, không phải chuyển sang dict trước.
+    """
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+def partial_of(model: type[ModelT], *, name: str | None = None) -> type[BaseModel]:
+    """Sinh bản sao của `model` với mọi field thành optional (mặc định None).
+
+    Dùng cho PATCH: chỉ field nào client gửi lên mới bị ghi đè. Ràng buộc
+    validate (pattern, min_length, ge/le...) được giữ nguyên, nên không phải
+    chép lại lần thứ hai và không sợ hai bản lệch nhau khi sửa.
+
+    Cách dùng thường gặp — kế thừa để thêm field chỉ có ở PATCH:
+
+        class UserUpdate(partial_of(UserBase)):
+            is_active: bool | None = None
+
+    `name` là TUỲ CHỌN và hầu như không cần. Nó chỉ đặt tên cho class được sinh
+    ra, mà class đó là LỚP CHA ẩn khi bạn kế thừa — tên hiện trong OpenAPI là
+    tên lớp con của bạn. Chỉ truyền `name` khi dùng thẳng kết quả, vì lúc đó
+    tên sinh ra chính là tên schema client nhìn thấy:
+
+        DeviceFilter = partial_of(DeviceBase, name="DeviceFilter")
+        # không có name thì schema sẽ mang tên "DeviceBasePartial"
+
+    Đừng đặt `name` trùng tên lớp con — sẽ có hai class cùng tên, và nếu cả hai
+    cùng xuất hiện trong OpenAPI thì FastAPI phải tự thêm tiền tố để phân biệt.
+    """
+    fields: dict[str, Any] = {}
+
+    for field_name, field in model.model_fields.items():
+        optional = copy.deepcopy(field)
+        optional.default = None
+        optional.default_factory = None
+        fields[field_name] = (field.annotation | None, optional)
+
+    # Kế thừa chính `model` chứ không phải lớp cha của nó: nhờ vậy field
+    # validator, model validator và model_config tuỳ chỉnh đều được giữ. Field
+    # bắt buộc bị ghi đè thành optional ngay bên dưới nên không mâu thuẫn.
+    return create_model(  # type: ignore[call-overload]
+        name or f"{model.__name__}Partial",
+        __base__=model,
+        __doc__=f"Bản PATCH của {model.__name__}: mọi field optional.",
+        **fields,
+    )
+
+
+def apply_changes(entity: Any, payload: BaseModel) -> list[str]:
+    """Chép các field client THỰC SỰ gửi lên vào entity. Trả về tên field đã đổi.
+
+    `exclude_unset=True` là mấu chốt: nó phân biệt "không gửi field này" với
+    "gửi field này = null". Thiếu nó thì PATCH một field sẽ xoá trắng các field
+    còn lại.
+    """
+    changes = payload.model_dump(exclude_unset=True)
+    for field_name, value in changes.items():
+        setattr(entity, field_name, value)
+    return sorted(changes)
+
+
+class Page(BaseModel, Generic[T]):
+    """Bao ngoài cho danh sách có phân trang."""
+
+    items: list[T]
+    total: int
+    limit: int
+    offset: int

pymodular/core/websocket/__init__.py

@@ -0,0 +1,31 @@
+"""Thư viện WebSocket của khung: gateway, phòng, gửi thẳng cho một client.
+
+Đọc `docs/websocket.md` để có hướng dẫn đầy đủ (kèm ví dụ Postman và Next.js).
+
+    from pymodular.core.websocket import Socket, WebSocketServer, gateway, subscribe
+"""
+
+from __future__ import annotations
+
+from pymodular.core.websocket.adapter import BroadcastAdapter, LocalAdapter, RedisAdapter
+from pymodular.core.websocket.gateway import build_ws_router, gateway, gateways_in, subscribe
+from pymodular.core.websocket.namespace import Namespace
+from pymodular.core.websocket.protocol import CloseCode, Frame, ProtocolError
+from pymodular.core.websocket.server import WebSocketServer
+from pymodular.core.websocket.socket import Socket
+
+__all__ = [
+    "BroadcastAdapter",
+    "CloseCode",
+    "Frame",
+    "LocalAdapter",
+    "Namespace",
+    "ProtocolError",
+    "RedisAdapter",
+    "Socket",
+    "WebSocketServer",
+    "build_ws_router",
+    "gateway",
+    "gateways_in",
+    "subscribe",
+]

pymodular/core/websocket/adapter.py

@@ -0,0 +1,192 @@
+"""Cầu nối giữa các tiến trình worker.
+
+Vấn đề: sổ kết nối nằm trong BỘ NHỚ của một tiến trình. `pym run --workers 4` chạy 4
+worker, mỗi worker là một tiến trình riêng. Client A nối vào worker 1, client B
+nối vào worker 3; A gửi tin cho phòng "alerts" thì worker 1 chỉ thấy các kết
+nối của chính nó — B không nhận được gì. Bệnh này chỉ lộ ra khi lên nhiều
+worker/nhiều máy, nên rất hay bị phát hiện muộn.
+
+Cách chữa: mỗi lần phát tin, ngoài việc gửi cho kết nối tại chỗ thì còn đăng
+tin lên một kênh chung; các worker khác nghe kênh đó và gửi tiếp cho kết nối
+của mình. Đây đúng là vai trò của Redis adapter trong NestJS.
+
+Hai lựa chọn:
+
+- `local` (mặc định): không có kênh chung. Đúng khi chạy MỘT worker. Nhanh
+  nhất, không phụ thuộc gì thêm.
+- `redis`: dùng Redis pub/sub. Bật bằng `APP_WS__ADAPTER=redis`, cài bằng
+  `pip install 'fastapi-modular[redis]'`. Thư viện redis chỉ được import khi thật sự chọn nó.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import uuid
+from collections.abc import Callable, Iterable
+from typing import Any, Protocol
+
+from pymodular.core.exceptions import ComponentNotEnabledError
+from pymodular.core.logging import get_logger
+
+log = get_logger(__name__)
+
+OnMessage = Callable[[dict[str, Any]], None]
+
+
+def new_origin_id() -> str:
+    """Mã nhận dạng worker này — để không nhận lại chính tin mình vừa đăng."""
+    return f"{os.getpid()}-{uuid.uuid4().hex[:8]}"
+
+
+def envelope(
+    origin: str,
+    namespace: str,
+    event: str,
+    data: Any,
+    *,
+    room: str | None = None,
+    user: str | None = None,
+    socket: str | None = None,
+    exclude: Iterable[str] = (),
+) -> dict[str, Any]:
+    return {
+        "origin": origin,
+        "ns": namespace,
+        "event": event,
+        "data": data,
+        "room": room,
+        "user": user,
+        "socket": socket,
+        "exclude": list(exclude),
+    }
+
+
+class BroadcastAdapter(Protocol):
+    name: str
+
+    async def start(self, on_message: OnMessage) -> None: ...
+    async def publish(self, payload: dict[str, Any]) -> None: ...
+    async def stop(self) -> None: ...
+
+
+class LocalAdapter:
+    """Không làm gì cả — mọi kết nối đều nằm trong tiến trình này."""
+
+    name = "local"
+
+    async def start(self, on_message: OnMessage) -> None:
+        return None
+
+    async def publish(self, payload: dict[str, Any]) -> None:
+        return None
+
+    async def stop(self) -> None:
+        return None
+
+
+class RedisAdapter:
+    """Phát tin xuyên worker qua Redis pub/sub.
+
+    Cố ý dùng pub/sub chứ không phải stream: tin nhắn realtime hết giá trị sau
+    vài giây, không đáng để lưu lại. Worker vừa khởi động sẽ không nhận được
+    tin phát lúc nó chưa lên — đúng như mong đợi.
+    """
+
+    name = "redis"
+
+    def __init__(self, url: str, channel: str, *, origin: str | None = None) -> None:
+        self.url = url
+        self.channel = channel
+        self.origin = origin or new_origin_id()
+        self._client: Any = None
+        self._pubsub: Any = None
+        self._task: asyncio.Task[None] | None = None
+        self._on_message: OnMessage | None = None
+        self._stopping = False
+
+    async def start(self, on_message: OnMessage) -> None:
+        try:
+            import redis.asyncio as redis
+        except ModuleNotFoundError as exc:
+            raise ComponentNotEnabledError(
+                "APP_WS__ADAPTER=redis nhưng chưa cài thư viện redis. "
+                "Chạy `pip install 'fastapi-modular[redis]'`, hoặc đổi về APP_WS__ADAPTER=local nếu "
+                "chỉ chạy một worker."
+            ) from exc
+
+        self._on_message = on_message
+        self._client = redis.from_url(self.url, decode_responses=True)
+        await self._client.ping()   # hỏng cấu hình thì báo ngay lúc boot
+        self._task = asyncio.create_task(self._listen(), name="ws-redis-rabbitmq_subscriber")
+        log.info("ws.adapter_started", adapter=self.name, channel=self.channel, origin=self.origin)
+
+    async def publish(self, payload: dict[str, Any]) -> None:
+        if self._client is None:
+            return
+        try:
+            await self._client.publish(self.channel, json.dumps(payload, default=str))
+        except Exception as exc:  # noqa: BLE001 - Redis hỏng không được làm hỏng request
+            # Tin đã tới được các kết nối tại chỗ; mất phần xuyên worker thôi.
+            log.warning("ws.publish_failed", error=f"{type(exc).__name__}: {exc}")
+
+    async def _listen(self) -> None:
+        delay = 0.5
+        while not self._stopping:
+            try:
+                self._pubsub = self._client.pubsub()
+                await self._pubsub.subscribe(self.channel)
+                delay = 0.5
+                async for message in self._pubsub.listen():
+                    if message.get("type") != "message":
+                        continue
+                    self._dispatch(message.get("data"))
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:  # noqa: BLE001 - mất Redis phải tự nối lại, không được chết task
+                if self._stopping:
+                    return
+                log.warning(
+                    "ws.adapter_reconnecting",
+                    error=f"{type(exc).__name__}: {exc}",
+                    retry_in=delay,
+                )
+                await asyncio.sleep(delay)
+                delay = min(delay * 2, 10.0)
+
+    def _dispatch(self, raw: Any) -> None:
+        try:
+            payload = json.loads(raw)
+        except (TypeError, ValueError):
+            log.warning("ws.adapter_bad_payload")
+            return
+        if payload.get("origin") == self.origin:
+            return   # tin của chính mình, đã gửi tại chỗ rồi
+        if self._on_message is not None:
+            self._on_message(payload)
+
+    async def stop(self) -> None:
+        # Đang tắt tiến trình: mọi lỗi dọn dẹp đều nuốt, vì báo lỗi lúc này
+        # chẳng ai xử lý được mà lại che mất phần shutdown còn lại.
+        self._stopping = True
+        if self._task is not None:
+            self._task.cancel()
+            with contextlib.suppress(BaseException):
+                await self._task
+            self._task = None
+        if self._pubsub is not None:
+            with contextlib.suppress(Exception):
+                await self._pubsub.aclose()
+            self._pubsub = None
+        if self._client is not None:
+            with contextlib.suppress(Exception):
+                await self._client.aclose()
+            self._client = None
+
+
+def build_adapter(kind: str, *, url: str, channel: str, origin: str) -> BroadcastAdapter:
+    if kind == "redis":
+        return RedisAdapter(url, channel, origin=origin)
+    return LocalAdapter()