fastapi-modular 0.3.0__tar.gz → 0.3.1__tar.gz

{fastapi_modular-0.3.0 → fastapi_modular-0.3.1}/CHANGELOG.md

@@ -5,6 +5,34 @@ Theo [Keep a Changelog](https://keepachangelog.com/vi/1.1.0/); phiên bản theo
 
 ## [Chưa phát hành]
 
+## [0.3.1] — 2026-08-27
+
+### Sửa
+
+- **Worker ghi database không được commit.** `contextvars` được sao chép khi tạo
+  Task/Thread, nên `@worker` sinh ra từ trong một HTTP request — hoặc từ
+  `@interval`/`@job`, vốn cũng mở request scope — thừa hưởng đúng store của
+  request đó. Mà `SqlUnitOfWork` là provider request-scoped: nó mở transaction
+  rồi chỉ commit ở `on_request_end`. Worker sống lâu hơn request nên transaction
+  ấy không bao giờ được commit.
+
+  Kiểu hỏng này im lặng đến khó chịu:
+
+  ```python
+  print("Deleted:", await repo.delete(row.id))   # -> True
+  ```
+
+  `True` là đúng — DELETE khớp một dòng, và câu SELECT ngay sau cũng thấy dữ
+  liệu mới vì cùng một connection. Chỉ có điều trên đĩa không đổi gì, và tắt app
+  là mất sạch.
+
+  Nay worker được cắt khỏi request scope thừa hưởng (`detach_request_scope`),
+  nên mỗi thao tác tự commit như docs vẫn mô tả. Gộp nhiều lệnh ghi thì bọc
+  `async with db.transaction():` — vẫn dùng được trong `ctx.run`.
+
+  Hệ quả có thể thấy: `container.resolve(<provider Scope.REQUEST>)` trong worker
+  giờ báo lỗi thay vì trả về một instance mồ côi. Đó là cố ý.
+
 ## [0.3.0] — 2026-08-27
 
 Bản này thêm **query builder** (JOIN, khoá ngoại, transaction, dữ liệu lồng

{fastapi_modular-0.3.0 → fastapi_modular-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-modular
-Version: 0.3.0
+Version: 0.3.1
 Summary: NestJS-style modular architecture for FastAPI: DI container, class-based controllers, auto-discovered modules, WebSocket gateway, RabbitMQ/Redis/MQTT/Kafka
 Project-URL: Homepage, https://github.com/quanglinh2909/fastapi-modular
 Project-URL: Documentation, https://github.com/quanglinh2909/fastapi-modular/tree/main/docs
@@ -165,7 +165,7 @@ same job `package.json` does for `npm i`.
 
 ```
 # requirements.txt, after `fam install sqlite` and `fam install redis`
-fastapi-modular[redis,sqlite]>=0.3.0
+fastapi-modular[redis,sqlite]>=0.3.1
 ```
 
 It records the extras, not the individual packages: the version ranges of
@@ -511,7 +511,7 @@ src/                SAMPLE APPLICATION — not shipped in the package; delete fr
   core/config.py    AppSettings: subclass Settings to add your own .env variables
   core/lifespan.py  application-specific startup / shutdown work
   api/              business modules; every subdirectory is one module
-tests/              1097 tests that need no infrastructure, 292 more with real drivers/servers
+tests/              1101 tests that need no infrastructure, 292 more with real drivers/servers
 docs/               reference documentation (Vietnamese)
 ```
 

{fastapi_modular-0.3.0 → fastapi_modular-0.3.1}/README.md

@@ -95,7 +95,7 @@ same job `package.json` does for `npm i`.
 
 ```
 # requirements.txt, after `fam install sqlite` and `fam install redis`
-fastapi-modular[redis,sqlite]>=0.3.0
+fastapi-modular[redis,sqlite]>=0.3.1
 ```
 
 It records the extras, not the individual packages: the version ranges of
@@ -441,7 +441,7 @@ src/                SAMPLE APPLICATION — not shipped in the package; delete fr
   core/config.py    AppSettings: subclass Settings to add your own .env variables
   core/lifespan.py  application-specific startup / shutdown work
   api/              business modules; every subdirectory is one module
-tests/              1097 tests that need no infrastructure, 292 more with real drivers/servers
+tests/              1101 tests that need no infrastructure, 292 more with real drivers/servers
 docs/               reference documentation (Vietnamese)
 ```
 

{fastapi_modular-0.3.0 → fastapi_modular-0.3.1}/README.vi.md

@@ -87,7 +87,7 @@ phần vào `requirements.txt`** để đồng nghiệp clone repo về chỉ c
 
 ```
 # requirements.txt, sau khi `fam install sqlite` rồi `fam install redis`
-fastapi-modular[redis,sqlite]>=0.3.0
+fastapi-modular[redis,sqlite]>=0.3.1
 ```
 
 Nó ghi extras chứ không liệt kê từng gói con: khoảng phiên bản của
@@ -439,7 +439,7 @@ src/                ỨNG DỤNG MẪU — không nằm trong gói cài; xoá th
   core/config.py    AppSettings: kế thừa Settings để thêm biến .env của bạn
   core/lifespan.py  việc lúc khởi động / lúc tắt của riêng ứng dụng
   api/              các module nghiệp vụ; mỗi thư mục con là một module
-tests/              1097 test chạy không cần hạ tầng, 292 test nữa cần driver/server thật
+tests/              1101 test chạy không cần hạ tầng, 292 test nữa cần driver/server thật
 docs/               tài liệu tra cứu
 ```
 

{fastapi_modular-0.3.0 → fastapi_modular-0.3.1}/docs/architecture.md

@@ -288,7 +288,7 @@ truy vấn database thật (1–10 ms) thì dưới 2%.
 fam lint                      # ruff trên `src` (mặc định): F, E, W, I, B, UP, SIM, RUF, BLE
 fam lint fastapi_modular src tests  # soi cả thư viện và test — dùng cái này khi phát triển repo
 fam lint --fix                # tự sửa phần sửa được
-fam test       # 1097 test trên backend memory (292 test nữa cần hạ tầng hoặc driver thật)
+fam test       # 1101 test trên backend memory (292 test nữa cần hạ tầng hoặc driver thật)
 ```
 
 Cấu hình ở [`ruff.toml`](../ruff.toml). Rule `BLE` được bật có chủ ý: mỗi

{fastapi_modular-0.3.0 → fastapi_modular-0.3.1}/docs/background.md

@@ -642,6 +642,26 @@ ctx.run(self._repo.save(event))
 Đừng gọi `asyncio.run()` — nó tạo một event loop MỚI, mà connection pool của
 database thuộc về loop cũ, và nó sẽ hỏng theo những cách rất khó hiểu.
 
+**Mỗi lời gọi tự commit.** Worker không nằm trong request nào, nên mỗi
+`save`/`delete` là một transaction riêng, xong là xong. Muốn nhiều lệnh ghi
+"cùng thành công hoặc cùng không" thì bọc lại — `db.transaction()` dùng được
+trong `ctx.run` như thường:
+
+```python
+async def chuyen_kho(self, tu: str, den: str) -> None:
+    async with self._db.transaction():
+        await self._repo.save(...)
+        await self._repo.delete(...)
+
+# trong worker:
+ctx.run(self._service.chuyen_kho("A", "B"))
+```
+
+**Đừng resolve provider request-scoped trong worker.** Worker sống lâu hơn thứ
+sinh ra nó, nên khung cắt nó khỏi request scope — `container.resolve(Principal)`
+hay bất cứ provider `Scope.REQUEST` nào cũng sẽ báo lỗi ngay. Đó là cố ý: không
+có request thì không có "danh tính của request này".
+
 ---
 
 ## Hỏng thì tra ở đây
@@ -663,6 +683,7 @@ database thuộc về loop cũ, và nó sẽ hỏng theo những cách rất kh
 | **`ctx.blocking` chậm dần khi thêm worker** | vượt trần pool — nới `APP_WORKERS__THREAD_POOL_SIZE` |
 | **`workers_restarted_total` tăng đều** | camera rớt mạng, hoặc vòng lặp ném lỗi mỗi lượt — xem log `worker.crashed` |
 | **`worker.stop_timeout` lúc tắt app** | vòng lặp không kiểm `ctx.running`, hoặc lời gọi chặn không có timeout |
+| **Ghi/xoá trong worker: `delete()` trả `True` mà dữ liệu vẫn còn** | Bản **trước 0.3.1**: worker thừa hưởng transaction của request sinh ra nó và không ai commit. Nâng cấp: `pip install -U fastapi-modular`. Nhận ra nó bằng cách đọc database bằng **công cụ khác** (`sqlite3 app.db "SELECT …"`), chứ hỏi lại repository thì vẫn thấy "xong rồi" |
 | **Ctrl+C bấm mà không có gì xảy ra** | xem ngay dưới |
 
 ### Ctrl+C như không ăn

{fastapi_modular-0.3.0 → fastapi_modular-0.3.1}/fastapi_modular/__init__.py

@@ -42,7 +42,7 @@ from fastapi_modular.discovery import DEFAULT_PACKAGE, register_routes
 from fastapi_modular.factory import add_middleware, bind_settings, create_app, new_fastapi
 from fastapi_modular.infrastructure.database.base import Entity, reference
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 __all__ = [
     "DEFAULT_PACKAGE",

{fastapi_modular-0.3.0 → fastapi_modular-0.3.1}/fastapi_modular/core/container.py

@@ -363,6 +363,28 @@ async def request_scope() -> AsyncIterator[dict[str, Any]]:
         _request_store.reset(token)
 
 
+def detach_request_scope() -> None:
+    """Cắt khỏi request scope THỪA HƯỞNG từ nơi sinh ra, cho việc chạy nền.
+
+    Vì sao cần: `contextvars` được sao chép khi tạo Task hay Thread, nên một
+    `@worker` sinh ra từ trong một HTTP request — hoặc từ một `@interval` /
+    `@job`, vốn cũng mở request scope — sẽ thấy đúng cái store đó, dù request ấy
+    đã đóng từ lâu.
+
+    Hậu quả đo được, và nó im lặng đến khó chịu: `SqlUnitOfWork` là provider
+    request-scoped, mở một transaction rồi chỉ commit ở `on_request_end`. Worker
+    thừa hưởng nó thì mọi lệnh ghi rơi vào một transaction KHÔNG BAO GIỜ được
+    commit — `repo.delete()` vẫn trả `True` (đúng, nó khớp một dòng), câu SELECT
+    ngay sau đó vẫn thấy dữ liệu mới (cùng connection), nhưng trên đĩa không có
+    gì đổi và tắt app là mất sạch.
+
+    Cắt rồi thì `_conn()` rơi về nhánh "ngoài request": mỗi thao tác một
+    `engine.begin()`, tự commit — đúng như docs mô tả cho worker/job/script.
+    Cần gộp nhiều lệnh ghi thì bọc `async with db.transaction():`.
+    """
+    _request_store.set(None)
+
+
 def Inject(token: type[T] | str) -> Any:
     """Cầu nối container -> FastAPI Depends.
 

{fastapi_modular-0.3.0 → fastapi_modular-0.3.1}/fastapi_modular/core/workers.py

@@ -79,7 +79,7 @@ from dataclasses import dataclass
 from typing import Any
 
 from fastapi_modular.core.config import Settings
-from fastapi_modular.core.container import container, injectable
+from fastapi_modular.core.container import container, detach_request_scope, injectable
 from fastapi_modular.core.context import new_request_id, reset_request_id, set_request_id
 from fastapi_modular.core.exceptions import BadRequestError, ServiceUnavailableError
 from fastapi_modular.core.locks import NoLock, SingleFlight, build_lock
@@ -621,6 +621,10 @@ class WorkerPool:
         self, spec: WorkerSpec, instance: Any, data: Any, context: WorkerContext
     ) -> None:
         """Chạy vòng lặp, và dựng lại khi nó hỏng."""
+        # Worker sống lâu hơn thứ sinh ra nó, nên không được dùng chung request
+        # scope với nó — xem `detach_request_scope`. Đặt ở đây là đủ cho cả
+        # thread (`copy_context` lấy từ context của Task này) lẫn `ctx.run`.
+        detach_request_scope()
         if spec.single and not await self._become_owner(spec, context):
             return
 

fastapi_modular-0.3.1/tests/test_ghi_du_lieu_tu_worker.py

@@ -0,0 +1,254 @@
+"""Worker ghi database thì dữ liệu phải THẬT SỰ tới đĩa.
+
+Vì sao có file này. `contextvars` được sao chép khi tạo Task/Thread, nên một
+`@worker` sinh ra từ trong một HTTP request — hoặc từ `@interval`/`@job`, vốn
+cũng mở request scope — thừa hưởng đúng cái store của request đó. Mà
+`SqlUnitOfWork` là provider request-scoped: nó mở một transaction rồi chỉ commit
+ở `on_request_end`. Worker sống lâu hơn request, nên transaction ấy KHÔNG BAO
+GIỜ được commit.
+
+Kiểu hỏng này im lặng đến khó chịu, và người dùng thật đã mất buổi vì nó:
+
+    print("Deleted device offline:", await repo.delete(row.id))
+    # -> True
+
+`True` là đúng: DELETE khớp một dòng. Câu SELECT ngay sau cũng thấy dữ liệu mới,
+vì cùng một connection. Chỉ có điều trên đĩa không có gì đổi, và tắt app là mất
+sạch.
+
+Nên mọi phép kiểm ở đây đọc bằng **một kết nối sqlite KHÁC** (`tren_dia`), chứ
+không hỏi lại chính repository — hỏi lại repository là hỏi đúng cái connection
+đang giữ transaction chưa commit, và nó sẽ trả lời "xong rồi" trong mọi trường
+hợp.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sqlite3
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+
+import pytest
+from fastapi.testclient import TestClient
+
+from fastapi_modular import Entity, entity, injectable
+from fastapi_modular.core.clock import utcnow
+from fastapi_modular.core.config import (
+    DatabaseSettings,
+    KafkaSettings,
+    MqttSettings,
+    RabbitSettings,
+    RedisSettings,
+    Settings,
+    WebSocketSettings,
+)
+from fastapi_modular.core.controller import build_router, controller, post
+from fastapi_modular.core.workers import WorkerContext, worker
+from fastapi_modular.factory import create_app
+from fastapi_modular.infrastructure.database import Repository
+from fastapi_modular.infrastructure.database.repository import Database
+
+CO_SQLITE = importlib.util.find_spec("aiosqlite") is not None
+pytestmark = pytest.mark.skipif(not CO_SQLITE, reason="cần aiosqlite")
+
+DA_CHAY: set[str] = set()
+DB_PATH = ""
+
+
+@entity(name="wk_rows")
+@dataclass(slots=True)
+class WkRow(Entity):
+    id: str
+    nguon: str = ""
+    created_at: datetime = field(default_factory=utcnow)
+
+
+def tren_dia() -> list[str]:
+    """Đọc bằng kết nối KHÁC — chỉ thấy thứ đã COMMIT."""
+    conn = sqlite3.connect(DB_PATH)
+    try:
+        return sorted(r[0] for r in conn.execute("SELECT id FROM wk_rows"))
+    finally:
+        conn.close()
+
+
+@injectable
+class WkService:
+    def __init__(self, repo: Repository[WkRow], db: Database) -> None:
+        self._repo = repo
+        self._db = db
+
+    async def them(self, id_: str) -> None:
+        await self._repo.save(WkRow(id=id_, nguon="worker"))
+
+    async def xoa(self, id_: str) -> bool:
+        return await self._repo.delete(id_)
+
+    async def them_roi_huy(self, id_: str) -> None:
+        """Ghi trong transaction rồi ném lỗi — không được để lại gì."""
+        try:
+            async with self._db.transaction():
+                await self._repo.save(WkRow(id=id_, nguon="worker"))
+                raise RuntimeError("hỏng giữa chừng")
+        except RuntimeError:
+            pass
+
+
+@injectable
+class WkWorkers:
+    def __init__(self, service: WkService) -> None:
+        self._service = service
+
+    @worker("wk-ghi", thread=True)
+    def ghi_trong_thread(self, data: dict, ctx: WorkerContext) -> None:
+        """Đúng hình dạng của worker thật: `def` thường + `ctx.run(...)`."""
+        ctx.run(self._service.them(data["id"]))
+        DA_CHAY.add("da-ghi")
+        while ctx.running:
+            ctx.wait(0.02)
+
+    @worker("wk-xoa", thread=True)
+    def ghi_roi_xoa(self, data: dict, ctx: WorkerContext) -> None:
+        ctx.run(self._service.them(data["id"]))
+        DA_CHAY.add("da-ghi-lan-hai")
+        ctx.run(self._service.xoa(data["id"]))
+        DA_CHAY.add("da-xoa")
+        while ctx.running:
+            ctx.wait(0.02)
+
+    @worker("wk-tx", thread=True)
+    def ghi_roi_huy(self, data: dict, ctx: WorkerContext) -> None:
+        ctx.run(self._service.them_roi_huy(data["id"]))
+        DA_CHAY.add("da-huy")
+        while ctx.running:
+            ctx.wait(0.02)
+
+
+@controller(prefix="/wk")
+class WkController:
+    def __init__(self, workers: WkWorkers) -> None:
+        self._workers = workers
+
+    @post("/ghi")
+    async def ghi(self, id_: str) -> dict:
+        """Sinh worker TỪ TRONG một HTTP request — ca nguy hiểm nhất.
+
+        Ở đây request scope chắc chắn đang mở, nên worker sao chép được nó.
+        """
+        await self._workers.ghi_trong_thread(id_, {"id": id_})
+        return {"ok": True}
+
+    @post("/ghi-xoa")
+    async def ghi_xoa(self, id_: str) -> dict:
+        await self._workers.ghi_roi_xoa(id_, {"id": id_})
+        return {"ok": True}
+
+    @post("/ghi-huy")
+    async def ghi_huy(self, id_: str) -> dict:
+        await self._workers.ghi_roi_huy(id_, {"id": id_})
+        return {"ok": True}
+
+
+@pytest.fixture
+def client(tmp_path):
+    global DB_PATH
+    DB_PATH = str(tmp_path / f"{uuid.uuid4().hex}.db")
+    DA_CHAY.clear()
+
+    settings = Settings(
+        APP_ENV="local",
+        APP_DEBUG=True,
+        APP_DB=DatabaseSettings(driver="sqlite", dsn=f"sqlite+aiosqlite:///{DB_PATH}"),
+        APP_RABBITMQ=RabbitSettings(enabled=False),
+        APP_REDIS=RedisSettings(enabled=False),
+        APP_MQTT=MqttSettings(enabled=False),
+        APP_KAFKA=KafkaSettings(enabled=False),
+        APP_WS=WebSocketSettings(adapter="local"),
+    )
+    app = create_app(settings, package="tests")
+    app.include_router(build_router(WkController), prefix="/api")
+    with TestClient(app) as client:
+        yield client
+    assert os.path.exists(DB_PATH)
+
+
+def cho(dau_moc: str, han: float = 5.0) -> None:
+    """Chờ worker chạy tới mốc, tối đa `han` giây (đừng ngủ theo đồng hồ)."""
+    moc = time.monotonic()
+    while dau_moc not in DA_CHAY and time.monotonic() - moc < han:
+        time.sleep(0.01)
+    assert dau_moc in DA_CHAY, f"worker không tới được mốc {dau_moc!r}"
+
+
+def cho_tren_dia(mong_doi: list[str], han: float = 5.0) -> None:
+    moc = time.monotonic()
+    while tren_dia() != mong_doi and time.monotonic() - moc < han:
+        time.sleep(0.01)
+    assert tren_dia() == mong_doi
+
+
+def test_worker_ghi_thi_du_lieu_toi_dia(client):
+    """Ca chính: trước đây câu INSERT nằm trong transaction không ai commit."""
+    client.post("/api/wk/ghi", params={"id_": "r1"})
+    cho("da-ghi")
+    cho_tren_dia(["r1"])
+
+
+def test_worker_xoa_thi_du_lieu_bien_khoi_dia(client):
+    """`delete()` trả True mà dòng vẫn còn trên đĩa — đúng lỗi người dùng gặp."""
+    client.post("/api/wk/ghi-xoa", params={"id_": "r2"})
+    cho("da-xoa")
+    cho_tren_dia([])
+
+
+def test_worker_khong_dung_chung_UnitOfWork_voi_request_sinh_ra_no(client):
+    """Chốt đúng cơ chế, không chỉ chốt hệ quả.
+
+    Worker phải KHÔNG resolve được provider request-scoped: nó sống lâu hơn
+    request sinh ra nó, nên dùng chung là dùng một transaction đã mồ côi.
+    """
+    from fastapi_modular.core.container import container
+    from fastapi_modular.infrastructure.database.sql import SqlUnitOfWork
+
+    ket_qua: list[str] = []
+
+    @injectable
+    class Soi:
+        @worker("wk-soi", thread=True)
+        def soi(self, data: dict, ctx: WorkerContext) -> None:
+            try:
+                container.resolve(SqlUnitOfWork)
+                ket_qua.append("resolve được")
+            except RuntimeError:
+                ket_qua.append("đã cắt")
+            DA_CHAY.add("da-soi")
+            while ctx.running:
+                ctx.wait(0.02)
+
+    @controller(prefix="/soi")
+    class SoiController:
+        def __init__(self, soi: Soi) -> None:
+            self._soi = soi
+
+        @post("")
+        async def chay(self) -> dict:
+            await self._soi.soi("k", {})
+            return {"ok": True}
+
+    client.app.include_router(build_router(SoiController), prefix="/api")
+    client.post("/api/soi")
+    cho("da-soi")
+
+    assert ket_qua == ["đã cắt"]
+
+
+def test_transaction_trong_worker_van_huy_duoc(client):
+    """Cắt request scope không được làm mất `db.transaction()` của worker."""
+    client.post("/api/wk/ghi-huy", params={"id_": "r3"})
+    cho("da-huy")
+    time.sleep(0.2)                      # cho nó cơ hội ghi sai, nếu có
+    assert tren_dia() == [], "khối transaction ném lỗi thì không được để lại gì"