fastapi-modular 0.1.0__py3-none-any.whl

pymodular/core/websocket/socket.py

@@ -0,0 +1,241 @@
+"""Một kết nối của một client.
+
+`Socket` bọc quanh `WebSocket` của Starlette và thêm ba thứ mà bản trần không
+có, nhưng thiếu chúng thì không chạy nổi ngoài đời:
+
+1. **Hàng đợi gửi + một task ghi duy nhất.** Starlette KHÔNG cho hai task cùng
+   `send_text()` trên một kết nối — làm vậy sẽ hỏng khung tin hoặc ném
+   RuntimeError. Mà broadcast thì bản chất là nhiều nơi cùng gửi. Nên mọi lời
+   gọi `emit()` chỉ bỏ tin vào hàng đợi; đúng một task lấy ra và ghi.
+
+2. **Chống nghẽn (backpressure).** Hàng đợi có TRẦN. Client đọc chậm (mạng 3G,
+   tab bị treo) mà server cứ đẩy thì bộ nhớ server phình tới lúc sập — một
+   client hỏng kéo sập cả server. Đầy hàng đợi thì xử theo chính sách đã chọn:
+   ngắt kết nối (mặc định) hoặc bỏ tin cũ nhất.
+
+3. **Danh tính và phòng.** `user_id` (một người có thể mở nhiều tab = nhiều
+   socket) và tập phòng đang tham gia.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any
+
+from starlette.websockets import WebSocket, WebSocketState
+
+from pymodular.core.compat import TimeoutErrors
+from pymodular.core.logging import get_logger
+from pymodular.core.metrics import ws_messages_out, ws_send_dropped
+from pymodular.core.websocket.protocol import CloseCode, Frame
+
+if TYPE_CHECKING:
+    from pymodular.core.websocket.namespace import Namespace
+
+log = get_logger(__name__)
+
+# Bỏ vào hàng đợi để báo task ghi dừng lại.
+_STOP = object()
+
+
+class Socket:
+    """Một client đang kết nối. Do framework tạo, code nghiệp vụ chỉ dùng."""
+
+    __slots__ = (
+        "_close_hooks",
+        "_closer",
+        "_closing",
+        "_overflow",
+        "_queue",
+        "_writer",
+        "connected_at",
+        "data",
+        "id",
+        "namespace",
+        "roles",
+        "rooms",
+        "user_id",
+        "ws",
+    )
+
+    def __init__(
+        self,
+        ws: WebSocket,
+        namespace: Namespace,
+        *,
+        user_id: str | None = None,
+        roles: frozenset[str] = frozenset(),
+        queue_size: int = 100,
+        overflow: str = "close",
+    ) -> None:
+        self.id = uuid.uuid4().hex[:16]
+        self.ws = ws
+        self.namespace = namespace
+        self.user_id = user_id
+        self.roles = roles
+        self.rooms: set[str] = set()
+        # Chỗ để handler ghi trạng thái riêng của kết nối này (tên hiển thị,
+        # bộ lọc đang chọn...). Không đụng tới framework.
+        self.data: dict[str, Any] = {}
+        self.connected_at = time.time()
+
+        self._queue: asyncio.Queue[Frame | object] = asyncio.Queue(maxsize=queue_size)
+        self._overflow = overflow
+        self._writer: asyncio.Task[None] | None = None
+        self._closer: asyncio.Task[None] | None = None
+        self._closing = False
+        self._close_hooks: list[Callable[[Socket], Awaitable[None]]] = []
+
+    # ------------------------------------------------------------------ gửi
+    def emit(
+        self,
+        event: str,
+        data: Any = None,
+        *,
+        ack: str | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> bool:
+        """Xếp một tin vào hàng đợi gửi. Trả về False nếu tin bị bỏ.
+
+        KHÔNG phải coroutine: gọi được từ bất cứ đâu (kể cả handler HTTP) mà
+        không phải await, và không bao giờ chặn người gọi vì client chậm.
+        """
+        return self.send(Frame(event=event, data=data, ack=ack, meta=meta))
+
+    def send(self, frame: Frame) -> bool:
+        if self._closing:
+            return False
+
+        try:
+            self._queue.put_nowait(frame)
+        except asyncio.QueueFull:
+            return self._on_full(frame)
+
+        ws_messages_out.inc(namespace=self.namespace.path, event=frame.event)
+        return True
+
+    def _on_full(self, frame: Frame) -> bool:
+        """Hàng đợi đầy: client không theo kịp tốc độ server đẩy."""
+        ws_send_dropped.inc(namespace=self.namespace.path)
+
+        if self._overflow == "drop_oldest":
+            # Hợp với dữ liệu "chỉ cần bản mới nhất" (vị trí, nhiệt độ, tiến độ).
+            try:
+                self._queue.get_nowait()
+                self._queue.task_done()
+                self._queue.put_nowait(frame)
+                return True
+            except (asyncio.QueueEmpty, asyncio.QueueFull):
+                return False
+
+        # Mặc định: ngắt kết nối. Client tự nối lại và tải lại trạng thái, như
+        # vậy trung thực hơn là âm thầm nuốt tin khiến client tưởng mình vẫn
+        # đang đồng bộ.
+        log.warning(
+            "ws.slow_consumer",
+            socket_id=self.id,
+            user_id=self.user_id,
+            namespace=self.namespace.path,
+            queue_size=self._queue.maxsize,
+        )
+        self.close_soon(CloseCode.TRY_AGAIN_LATER, "client đọc quá chậm")
+        return False
+
+    # ----------------------------------------------------------------- vòng ghi
+    def start_writer(self) -> None:
+        self._writer = asyncio.create_task(self._writer_loop(), name=f"ws-writer-{self.id}")
+
+    async def _writer_loop(self) -> None:
+        while True:
+            item = await self._queue.get()
+            if item is _STOP:
+                return
+            try:
+                await self.ws.send_text(item.to_json())  # type: ignore[union-attr]
+            except (RuntimeError, ConnectionError, asyncio.CancelledError):
+                # Kết nối đã đứt giữa chừng; vòng nhận sẽ dọn dẹp.
+                return
+            except Exception as exc:  # noqa: BLE001 - lỗi khi ghi socket không được giết vòng nhận
+                log.warning("ws.send_failed", socket_id=self.id, error=str(exc))
+                return
+
+    async def stop_writer(self) -> None:
+        if self._writer is None:
+            return
+        # Đợi task ghi xả nốt hàng đợi, đừng cắt ngang giữa lúc đang ghi.
+        try:
+            self._queue.put_nowait(_STOP)
+        except asyncio.QueueFull:
+            self._writer.cancel()
+        try:
+            await asyncio.wait_for(asyncio.shield(self._writer), timeout=2.0)
+        except (*TimeoutErrors, asyncio.CancelledError):
+            self._writer.cancel()
+        self._writer = None
+
+    # ------------------------------------------------------- dọn khi đóng
+    def on_close(self, hook: Callable[[Socket], Awaitable[None]]) -> None:
+        """Đăng ký việc cần làm khi kết nối này đóng.
+
+        Đây là chỗ để những lớp NGOÀI framework gắn phần dọn dẹp của mình mà
+        không phải sửa vào lõi WebSocket — ví dụ lớp nhắn tin gỡ các đăng ký
+        sự kiện của kết nối. Lõi chỉ biết "có việc phải gọi", không biết đó là
+        việc gì.
+        """
+        self._close_hooks.append(hook)
+
+    async def run_close_hooks(self) -> None:
+        for hook in self._close_hooks:
+            try:
+                await hook(self)
+            except Exception as exc:  # noqa: BLE001 - một hook hỏng không được cản phần dọn còn lại
+                log.warning("ws.close_hook_failed", socket_id=self.id, error=str(exc))
+        self._close_hooks.clear()
+
+    # ------------------------------------------------------------------ phòng
+    def join(self, room: str) -> None:
+        """Vào phòng. Gọi lại nhiều lần không sao."""
+        self.namespace.join(self, room)
+
+    def leave(self, room: str) -> None:
+        self.namespace.leave(self, room)
+
+    def in_room(self, room: str) -> bool:
+        return room in self.rooms
+
+    # ------------------------------------------------------------------- đóng
+    def close_soon(self, code: int = CloseCode.NORMAL, reason: str = "") -> None:
+        """Yêu cầu đóng mà không cần await — dùng được trong hàm đồng bộ."""
+        if self._closing:
+            return
+        self._closing = True
+        # Giữ tham chiếu: task không có ai nắm có thể bị GC dọn giữa chừng.
+        self._closer = asyncio.create_task(self._close(code, reason), name=f"ws-close-{self.id}")
+
+    async def close(self, code: int = CloseCode.NORMAL, reason: str = "") -> None:
+        if self._closing:
+            return
+        self._closing = True
+        await self._close(code, reason)
+
+    async def _close(self, code: int, reason: str) -> None:
+        try:
+            if self.ws.client_state is WebSocketState.CONNECTED:
+                await self.ws.close(code=code, reason=reason)
+        except (RuntimeError, ConnectionError):
+            pass  # đối phương đã đóng trước
+
+    @property
+    def closing(self) -> bool:
+        return self._closing
+
+    @property
+    def pending(self) -> int:
+        """Số tin còn nằm trong hàng đợi — soi được client nào đang chậm."""
+        return self._queue.qsize()
+
+    def __repr__(self) -> str:
+        return f"<Socket {self.id} user={self.user_id} rooms={sorted(self.rooms)}>"

pymodular/discovery.py

@@ -0,0 +1,180 @@
+"""Module registry — tự động gom controller của mọi module trong package ứng dụng.
+
+Tương đương module scanning của NestJS. Mỗi thư mục con của package ứng dụng là
+một module; hàm ở đây nạp hết submodule bên trong để các decorator @controller
+chạy, rồi dựng router từ những controller vừa đăng ký.
+
+Thêm module mới = tạo thư mục, viết @controller. Không sửa file này, và cũng
+không phải export biến `router` nào trong module.
+
+Trường hợp cần một APIRouter dựng tay (websocket, router của thư viện ngoài),
+module vẫn có thể export biến `router` — nếu có, khung dùng luôn cái đó.
+
+Package ứng dụng mặc định là `src.api`. Dự án xếp khác thì truyền vào:
+
+    create_app(settings, package="cong_ty.dich_vu")
+"""
+
+from __future__ import annotations
+
+import pkgutil
+from importlib import import_module
+from pathlib import Path
+
+from fastapi import APIRouter, FastAPI
+
+from pymodular.core.controller import build_router, controllers_in
+from pymodular.core.logging import get_logger
+from pymodular.core.websocket import build_ws_router, gateways_in
+
+log = get_logger(__name__)
+
+DEFAULT_PACKAGE = "src.api"
+"""Package chứa các module ứng dụng, khi không truyền gì khác.
+
+Khớp với bộ khung `pym init` sinh ra: `src/api/<module>/`. Dự án xếp khác thì
+nói ra một lần trong `src/main.py`:
+
+    register_routes(app, package="cong_ty.dich_vu")
+"""
+
+
+def _package_dir(package: str) -> Path:
+    """Thư mục thật của package — quét file phải dựa vào đây, không phải __file__.
+
+    Trước đây hàm này lấy `Path(__file__).parent`, đúng khi khung và ứng dụng
+    nằm chung một cây thư mục. Cài bằng pip thì khung nằm trong site-packages
+    còn ứng dụng nằm ở dự án của người dùng, nên phải hỏi chính package đó.
+    """
+    module = import_module(package)
+    paths = list(getattr(module, "__path__", []))
+    if not paths:
+        raise RuntimeError(
+            f"{package!r} không phải một package (thiếu __init__.py?). "
+            "Đây là nơi chứa các module ứng dụng — xem pymodular.discovery."
+        )
+    return Path(paths[0])
+
+
+def _import_submodules(package: str, package_dir: Path) -> None:
+    """Nạp mọi submodule để decorator @controller/@injectable/@entity chạy."""
+    for info in pkgutil.walk_packages([str(package_dir)], prefix=f"{package}."):
+        import_module(info.name)
+
+
+def load_all_modules(package: str = DEFAULT_PACKAGE) -> None:
+    """Nạp mọi module trong package ứng dụng để decorator @entity/@injectable chạy.
+
+    Migration cần hàm này: Alembic phải thấy đủ entity mới sinh được diff, mà
+    nó không đi qua đường khởi động app.
+    """
+    _iter_packages(package)
+
+
+def _iter_packages(package: str) -> list[str]:
+    """Tên các module con, đã nạp xong, theo thứ tự alphabet."""
+    goc = _package_dir(package)
+    names: list[str] = []
+    for info in sorted(pkgutil.iter_modules([str(goc)]), key=lambda i: i.name):
+        if not info.ispkg or info.name.startswith("_"):
+            continue
+        import_module(f"{package}.{info.name}")
+        _import_submodules(f"{package}.{info.name}", goc / info.name)
+        names.append(info.name)
+    return names
+
+
+def discover_routers(package: str = DEFAULT_PACKAGE) -> list[tuple[str, APIRouter]]:
+    """Quét package ứng dụng, trả về [(tên module, router HTTP)] theo alphabet."""
+    found: list[tuple[str, APIRouter]] = []
+
+    for name in _iter_packages(package):
+        module_package = f"{package}.{name}"
+        module = import_module(module_package)
+
+        explicit = getattr(module, "router", None)
+        if isinstance(explicit, APIRouter):
+            found.append((name, explicit))
+            continue
+
+        controllers = controllers_in(module_package)
+        if not controllers:
+            if gateways_in(module_package):
+                # Module chỉ có gateway WebSocket là hợp lệ, không phải thiếu sót.
+                continue
+            # Im lặng ở đây là nguyên nhân số một của "sao route của tôi 404?".
+            log.warning("api.module_without_controller", module=name)
+            continue
+
+        log.debug(
+            "api.module_scanned",
+            module=name,
+            controllers=[c.__name__ for c in controllers],
+        )
+        found.append((name, build_router(*controllers)))
+
+    return found
+
+
+def discover_gateways(package: str = DEFAULT_PACKAGE) -> list[tuple[str, list[type]]]:
+    """Quét package ứng dụng, trả về [(tên module, các class gateway)]."""
+    return [
+        (name, found)
+        for name in _iter_packages(package)
+        if (found := gateways_in(f"{package}.{name}"))
+    ]
+
+
+def register_routes(
+    app: FastAPI, *, prefix: str = "/api", package: str = DEFAULT_PACKAGE
+) -> None:
+    """Gắn toàn bộ module đã phát hiện vào app."""
+    api = APIRouter(prefix=prefix)
+    names: list[str] = []
+
+    for name, router in discover_routers(package):
+        api.include_router(router)
+        names.append(name)
+
+    app.include_router(api)
+    log.info(
+        "api.modules_registered",
+        package=package,
+        prefix=prefix,
+        count=len(names),
+        modules=names,
+    )
+
+    register_gateways(app, package=package)
+
+
+def register_gateways(app: FastAPI, *, package: str = DEFAULT_PACKAGE) -> None:
+    """Gắn route WebSocket.
+
+    KHÔNG nằm dưới tiền tố /api: đường dẫn WebSocket do @gateway(path=...) khai
+    trọn vẹn, vì WebSocket không phải REST và thường được reverse proxy định
+    tuyến riêng (nginx phải bật Upgrade cho đúng những đường dẫn này).
+    """
+    classes: list[type] = []
+    paths: dict[str, str] = {}
+
+    for module_name, gateways in discover_gateways(package):
+        for cls in gateways:
+            path = cls.__gateway_meta__.path
+            if path in paths:
+                raise RuntimeError(
+                    f"Hai gateway cùng path {path!r}: {paths[path]} và {cls.__name__}"
+                )
+            paths[path] = cls.__name__
+            classes.append(cls)
+        log.debug("api.gateways_scanned", module=module_name)
+
+    if not classes:
+        return
+
+    app.include_router(build_ws_router(*classes))
+    log.info(
+        "api.gateways_registered",
+        count=len(classes),
+        gateways=[f"{cls.__name__} {cls.__gateway_meta__.path}" for cls in classes],
+    )

pymodular/factory.py

@@ -0,0 +1,126 @@
+"""Các mảnh ghép để dựng app — và `create_app()` gom sẵn chúng lại.
+
+`src/main.py` là file CỦA BẠN, không phải của khung. Nên mỗi bước lắp ráp ở đây
+là một hàm công khai, gọi riêng được, chèn thêm được:
+
+    settings = bind_settings(AppSettings())
+    configure_logging(settings.log)
+
+    app = new_fastapi(settings, lifespan=lifespan)
+    add_middleware(app, settings)
+    register_error_handlers(app, debug=settings.debug)
+    register_routes(app, prefix=settings.api_prefix)
+
+Cần thêm middleware của mình, đổi thứ tự, bỏ CORS, gắn router bên thứ ba? Sửa
+thẳng trong main.py của bạn, không phải ngồi tìm cách "ghi đè" cái gì trong
+khung.
+
+`create_app()` chạy đúng dãy trên, không hơn. Dùng nó khi chưa cần sửa gì:
+
+    app = create_app(AppSettings())
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from pymodular.core.config import Settings, get_settings, use_settings
+from pymodular.core.container import container
+from pymodular.core.error_handlers import register_error_handlers
+from pymodular.core.lifespan import lifespan
+from pymodular.core.logging import configure_logging
+from pymodular.discovery import DEFAULT_PACKAGE, register_routes
+from pymodular.middleware.request_context import AccessLogMiddleware, RequestContextMiddleware
+
+
+def bind_settings(settings: Settings | None = None) -> Settings:
+    """Chốt cấu hình cho cả tiến trình và cắm nó vào DI container.
+
+    Truyền `None` thì đọc từ `.env` bằng lớp `Settings` gốc. Truyền một instance
+    lớp con thì lớp đó được ghi nhớ, để những chỗ khung tự dựng cấu hình
+    (Alembic, gateway lúc không có request) không ra một bản cấu hình khác.
+
+    Đăng ký dưới CẢ chuỗi kế thừa: container tra provider theo TÊN lớp, nên khai
+    `def __init__(self, settings: AppSettings)` mà chỉ đăng ký "Settings" thì sẽ
+    báo không có provider 'AppSettings'.
+    """
+    if settings is None:
+        settings = get_settings()
+    else:
+        use_settings(type(settings))
+
+    for lop in type(settings).__mro__:
+        if not (isinstance(lop, type) and issubclass(lop, Settings)):
+            break
+        container.override(lop, settings)
+    return settings
+
+
+def new_fastapi(settings: Settings, **kwargs: Any) -> FastAPI:
+    """`FastAPI(...)` với tiêu đề, phiên bản và đường dẫn docs lấy từ cấu hình.
+
+    Ở prod, `docs_url`/`redoc_url`/`openapi_url` là None nên trang docs biến
+    mất — đừng để lộ sơ đồ API ra ngoài mà không có chủ ý.
+
+    `kwargs` truyền thẳng cho FastAPI, và ĐÈ được mọi giá trị ở trên.
+    """
+    mac_dinh: dict[str, Any] = {
+        "title": settings.name,
+        "version": settings.version,
+        "debug": settings.debug,
+        "lifespan": lifespan,
+        "docs_url": settings.docs_url,
+        "redoc_url": settings.redoc_url,
+        "openapi_url": settings.openapi_url,
+    }
+    return FastAPI(**{**mac_dinh, **kwargs})
+
+
+def add_middleware(app: FastAPI, settings: Settings) -> None:
+    """Ba middleware của khung: CORS, access log, request-id.
+
+    Thứ tự add là NGƯỢC với thứ tự chạy, nên RequestContext (thứ sinh ra
+    request-id) được add sau cùng để chạy đầu tiên — mọi log của các lớp sau nó
+    mới có id để bám theo.
+
+    Thêm middleware của bạn thì gọi `app.add_middleware(...)` sau hàm này nếu
+    muốn nó chạy TRƯỚC, hoặc trước hàm này nếu muốn nó chạy SAU.
+    """
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors.allow_origins,
+        allow_credentials=settings.cors.allow_credentials,
+        allow_methods=settings.cors.allow_methods,
+        allow_headers=settings.cors.allow_headers,
+    )
+    app.add_middleware(AccessLogMiddleware)
+    app.add_middleware(RequestContextMiddleware)
+
+
+def create_app(
+    settings: Settings | None = None, *, package: str = DEFAULT_PACKAGE
+) -> FastAPI:
+    """Dựng app theo cách mặc định. `package` là nơi chứa module ứng dụng.
+
+    Không có gì ở đây mà `src/main.py` của bạn không gọi được từng phần.
+    """
+    settings = bind_settings(settings)
+    configure_logging(settings.log)
+
+    app = new_fastapi(settings)
+    add_middleware(app, settings)
+    register_error_handlers(app, debug=settings.debug)
+    register_routes(app, prefix=settings.api_prefix, package=package)
+
+    @app.get("/", include_in_schema=False)
+    async def root() -> dict[str, str]:
+        return {
+            "service": settings.name,
+            "version": settings.version,
+            "docs": settings.docs_url or "disabled",
+        }
+
+    return app

pymodular/infrastructure/__init__.py

@@ -0,0 +1 @@
+"""Hạ tầng: những thứ nói chuyện với thế giới bên ngoài (database, cache, message bus)."""

pymodular/infrastructure/database/__init__.py

@@ -0,0 +1,8 @@
+"""Tầng database: hợp đồng chung, các backend cụ thể, và Repository dùng chung.
+
+Import từ đây:  from pymodular.infrastructure.database import Repository
+"""
+
+from pymodular.infrastructure.database.repository import Database, Repository
+
+__all__ = ["Database", "Repository"]