fastapi-modular 0.1.0__py3-none-any.whl

pymodular/infrastructure/database/mongo.py

@@ -0,0 +1,186 @@
+"""Backend MongoDB dùng motor (driver async chính thức).
+
+File này CHỈ được import khi settings chọn driver mongodb — xem `factory.py`.
+
+Ánh xạ: mỗi entity một collection, trường `id` của entity lưu vào `_id` của
+document nên không tốn thêm index.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, TypeVar
+
+from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorCollection
+
+from pymodular.core.logging import get_logger
+from pymodular.infrastructure.database.base import (
+    DatabaseBackend,
+    Filters,
+    Match,
+    active_filters,
+    from_document,
+    mapping_for,
+    to_document,
+)
+
+log = get_logger(__name__)
+
+E = TypeVar("E")
+
+
+def _to_mongo(doc: dict[str, Any]) -> dict[str, Any]:
+    out = dict(doc)
+    out["_id"] = out.pop("id")
+    return out
+
+
+def _from_mongo(doc: dict[str, Any]) -> dict[str, Any]:
+    out = dict(doc)
+    out["id"] = out.pop("_id")
+    return out
+
+
+class MongoBackend(DatabaseBackend):
+    name = "mongodb"
+
+    def __init__(
+        self,
+        dsn: str,
+        *,
+        database: str,
+        connect_timeout_seconds: float = 10.0,
+        query_timeout_seconds: float = 15.0,
+    ) -> None:
+        self._dsn = dsn
+        self._database_name = database
+        self._timeout_ms = int(connect_timeout_seconds * 1000)
+        self._query_timeout_ms = int(query_timeout_seconds * 1000)
+        self._client: AsyncIOMotorClient | None = None
+
+    async def startup(self) -> None:
+        # motor/pymongo tự dò lại server và kết nối lại; chỉ cần siết thời gian
+        # chờ, vì mặc định 30 giây sẽ khiến request treo rất lâu khi Mongo chết.
+        self._client = AsyncIOMotorClient(
+            self._dsn,
+            uuidRepresentation="standard",
+            serverSelectionTimeoutMS=self._timeout_ms,
+            connectTimeoutMS=self._timeout_ms,
+            # Chặn câu lệnh đã gửi: server treo thì socket đọc mãi không xong.
+            socketTimeoutMS=self._query_timeout_ms,
+        )
+        log.info("db.connected", backend=self.name, database=self._database_name)
+
+    async def shutdown(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    async def ping(self) -> bool:
+        await self._client[self._database_name].command("ping")  # type: ignore[index]
+        return True
+
+    async def create_schema(self, *entities: type) -> None:
+        """Mongo không cần tạo collection, nhưng index thì có.
+
+        Không có index, mọi truy vấn lọc đều quét toàn bộ collection; và không
+        có unique index thì hai request đồng thời cùng tạo được bản trùng.
+        """
+        for entity in entities:
+            mapping = mapping_for(entity)
+            collection = self._collection(entity)
+            for name, columns, is_unique in mapping.index_specs():
+                try:
+                    await collection.create_index(
+                        [(column, 1) for column in columns], unique=is_unique, name=name
+                    )
+                except Exception as exc:  # noqa: BLE001 - index hỏng không được làm chết app
+                    log.error(
+                        "db.index_failed",
+                        collection=mapping.storage,
+                        index=name,
+                        columns=list(columns),
+                        unique=is_unique,
+                        error=str(exc).splitlines()[0],
+                        hint="dọn document trùng rồi khởi động lại",
+                    )
+        log.info("db.indexes_ready", collections=[mapping_for(e).storage for e in entities])
+
+    def _collection(self, entity: type) -> AsyncIOMotorCollection:
+        assert self._client is not None, "backend chưa startup()"
+        return self._client[self._database_name][mapping_for(entity).storage]
+
+    def _query(self, filters: Filters) -> dict[str, Any]:
+        query = active_filters(filters)
+        if "id" in query:
+            query["_id"] = query.pop("id")
+        return query
+
+    async def get(self, entity: type[E], id_: str) -> E | None:
+        doc = await self._collection(entity).find_one({"_id": id_})
+        return from_document(entity, _from_mongo(doc)) if doc else None
+
+    async def find(
+        self,
+        entity: type[E],
+        *,
+        filters: Filters,
+        match: Match = None,
+        order_by: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+    ) -> list[E]:
+        cursor = self._collection(entity).find(self._query(filters))
+        if order_by:
+            cursor = cursor.sort(order_by, 1)
+
+        # `match=` là predicate Python, không dịch sang query Mongo được:
+        # phải lấy về rồi lọc. Chỉ phân trang ở DB khi không có match.
+        if match is None:
+            if offset:
+                cursor = cursor.skip(offset)
+            if limit is not None:
+                cursor = cursor.limit(limit)
+
+        items = [from_document(entity, _from_mongo(d)) async for d in cursor]
+        if match is not None:
+            items = [o for o in items if match(o)][offset:]
+            if limit is not None:
+                items = items[:limit]
+        return items
+
+    async def find_one(
+        self, entity: type[E], *, filters: Filters, match: Match = None
+    ) -> E | None:
+        items = await self.find(entity, filters=filters, match=match, limit=1)
+        return items[0] if items else None
+
+    async def count(
+        self, entity: type[E], *, filters: Filters, match: Match = None
+    ) -> int:
+        if match is not None:
+            return len(await self.find(entity, filters=filters, match=match))
+        return await self._collection(entity).count_documents(self._query(filters))
+
+    async def save(self, entity: type[E], obj: E) -> E:
+        if not getattr(obj, "id", None):
+            obj.id = uuid.uuid4().hex  # type: ignore[attr-defined]
+        doc = _to_mongo(to_document(obj))
+        await self._collection(entity).replace_one({"_id": doc["_id"]}, doc, upsert=True)
+        return obj
+
+    async def delete(self, entity: type[E], id_: str) -> bool:
+        result = await self._collection(entity).delete_one({"_id": id_})
+        return result.deleted_count > 0
+
+    async def delete_where(
+        self, entity: type[E], *, filters: Filters, match: Match = None
+    ) -> int:
+        if match is not None:
+            victims = await self.find(entity, filters=filters, match=match)
+            removed = 0
+            for obj in victims:
+                removed += int(await self.delete(entity, obj.id))  # type: ignore[attr-defined]
+            return removed
+        result = await self._collection(entity).delete_many(self._query(filters))
+        return int(result.deleted_count)

pymodular/infrastructure/database/repository.py

@@ -0,0 +1,188 @@
+"""`Database` (kết nối) và `Repository[E]` (kho dữ liệu của một entity).
+
+Service chỉ khai báo `repo: Repository[User]` là có sẵn CRUD, giống
+`Repository<Camera>` của TypeORM trong NestJS. Repository không biết đang chạy
+trên memory, SQL hay Mongo — nó chuyển tiếp xuống backend do `Database` chọn
+theo cấu hình.
+
+Quy ước lọc: tham số `**equals` có giá trị None đều bị BỎ QUA (coi như "không
+lọc theo trường này"). Cần điều kiện phức tạp hơn bằng nhau thì dùng `match=`
+với một predicate — lưu ý predicate chạy trong Python nên KHÔNG đẩy được
+xuống SQL/Mongo (backend sẽ lấy dữ liệu về rồi mới lọc).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Generic, TypeVar
+
+from pymodular.core.clock import utcnow
+from pymodular.core.config import Settings
+from pymodular.core.container import injectable
+from pymodular.core.logging import get_logger
+from pymodular.infrastructure.database.base import DatabaseBackend, is_transient_error
+from pymodular.infrastructure.database.factory import create_backend
+
+log = get_logger(__name__)
+
+E = TypeVar("E")
+
+
+@injectable
+class Database:
+    """Sở hữu kết nối tới database đang được cấu hình."""
+
+    def __init__(self, settings: Settings) -> None:
+        self._settings = settings
+        self._backend: DatabaseBackend = create_backend(settings.db)
+
+    @property
+    def backend(self) -> DatabaseBackend:
+        return self._backend
+
+    @property
+    def driver(self) -> str:
+        return self._backend.name
+
+    async def startup(self, *entities: type) -> None:
+        await self._backend.startup()
+        await self._wait_until_reachable()
+
+        create_schema = getattr(self._backend, "create_schema", None)
+        if create_schema is not None and entities:
+            await create_schema(*entities)
+
+    async def _wait_until_reachable(self) -> None:
+        """Thử ping vài lần trước khi bỏ cuộc.
+
+        Hay gặp với docker compose: app khởi động xong trước khi database sẵn
+        sàng nhận kết nối. Thử lại vài giây rẻ hơn nhiều so với để container
+        chết rồi chờ orchestrator dựng lại.
+        """
+        import asyncio
+
+        attempts = max(1, self._settings.db.startup_retries)
+        delay = self._settings.db.startup_retry_delay_seconds
+
+        for attempt in range(1, attempts + 1):
+            try:
+                await self._backend.ping()
+                if attempt > 1:
+                    log.info("db.connected_after_retry", backend=self._backend.name,
+                             attempts=attempt)
+                return
+            except Exception as exc:
+                reason = f"{type(exc).__name__}: {exc}"
+
+                # Sai mật khẩu / sai tên database thì thử lại vô ích, chỉ làm
+                # chậm lúc phát hiện cấu hình sai. Dừng ngay.
+                if not is_transient_error(exc):
+                    log.error(
+                        "db.config_error_at_startup",
+                        backend=self._backend.name,
+                        error=reason,
+                        hint="lỗi này không tự hết khi thử lại — kiểm tra APP_DB__DSN",
+                    )
+                    raise
+
+                if attempt == attempts:
+                    log.error(
+                        "db.unreachable_at_startup",
+                        backend=self._backend.name,
+                        attempts=attempts,
+                        error=reason,
+                    )
+                    raise
+
+                log.warning(
+                    "db.retry_connect",
+                    backend=self._backend.name,
+                    attempt=attempt,
+                    of=attempts,
+                    retry_in=delay,
+                    error=reason,          # nói luôn lý do, đừng bắt chờ tới lần cuối
+                )
+                await asyncio.sleep(delay)
+
+    async def shutdown(self) -> None:
+        await self._backend.shutdown()
+
+    async def ping(self) -> bool:
+        return await self._backend.ping()
+
+
+@injectable
+class Repository(Generic[E]):
+    """CRUD sẵn có cho một entity, bất kể backend nào bên dưới."""
+
+    def __init__(self, entity: type[E], database: Database) -> None:
+        self._entity = entity
+        self._db = database
+
+    @property
+    def _backend(self) -> DatabaseBackend:
+        return self._db.backend
+
+    # ------------------------------------------------------------------ đọc
+    async def get(self, id_: str) -> E | None:
+        return await self._backend.get(self._entity, id_)
+
+    async def find(
+        self,
+        *,
+        match: Callable[[E], bool] | None = None,
+        order_by: str | None = "created_at",
+        limit: int | None = None,
+        offset: int = 0,
+        **equals: Any,
+    ) -> list[E]:
+        return await self._backend.find(
+            self._entity,
+            filters=equals,
+            match=match,
+            order_by=order_by,
+            limit=limit,
+            offset=offset,
+        )
+
+    async def find_one(
+        self, *, match: Callable[[E], bool] | None = None, **equals: Any
+    ) -> E | None:
+        return await self._backend.find_one(self._entity, filters=equals, match=match)
+
+    async def count(
+        self, *, match: Callable[[E], bool] | None = None, **equals: Any
+    ) -> int:
+        return await self._backend.count(self._entity, filters=equals, match=match)
+
+    async def exists(
+        self, *, match: Callable[[E], bool] | None = None, **equals: Any
+    ) -> bool:
+        return await self.find_one(match=match, **equals) is not None
+
+    # ------------------------------------------------------------------ ghi
+    async def save(self, obj: E) -> E:
+        """Upsert. Tự sinh id nếu entity chưa có, và tự đóng dấu `updated_at`.
+
+        Đóng dấu ở đây chứ không ở service: mọi đường ghi đều đi qua save(),
+        nên không có chỗ nào quên. Tương đương @UpdateDateColumn của TypeORM.
+        Entity không có trường `updated_at` thì bỏ qua.
+        """
+        if hasattr(obj, "updated_at"):
+            # Bản ghi mới: cho updated_at trùng created_at thay vì lệch vài
+            # micro giây, để "chưa từng sửa" nhận ra được bằng created == updated.
+            is_new = not getattr(obj, "id", None)
+            created = getattr(obj, "created_at", None)
+            obj.updated_at = created if (is_new and created is not None) else utcnow()  # type: ignore[attr-defined]
+        return await self._backend.save(self._entity, obj)
+
+    async def delete(self, id_: str) -> bool:
+        return await self._backend.delete(self._entity, id_)
+
+    async def delete_where(
+        self, *, match: Callable[[E], bool] | None = None, **equals: Any
+    ) -> int:
+        return await self._backend.delete_where(self._entity, filters=equals, match=match)
+
+    def __repr__(self) -> str:
+        return f"<Repository[{self._entity.__name__}] on {self._db.driver}>"