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

fastapi_modular-0.3.1/CHANGELOG.md

@@ -0,0 +1,240 @@
+# Thay đổi
+
+Theo [Keep a Changelog](https://keepachangelog.com/vi/1.1.0/); phiên bản theo
+[SemVer](https://semver.org/lang/vi/).
+
+## [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
+nhau), **việc chạy nền** (`@worker`, `@interval`, `@cron`, `@job`, `@on_event`),
+**RPC gửi-rồi-chờ-trả-lời** cho cả bốn hạ tầng, và **provider cắm được**.
+
+Nâng cấp từ 0.2.x cần sửa ba chỗ, xem mục "Thay đổi phá vỡ" ở cuối.
+
+### Thêm
+
+- **Provider cắm được** — chọn bản hiện thực bằng TÊN lúc chạy, thứ mà container
+  (tra theo kiểu) không làm được: cổng thanh toán lấy từ cột trong đơn hàng, nhà
+  mạng SMS lấy từ cấu hình, hãng camera lấy từ bản ghi thiết bị.
+
+  Dùng đúng khuôn `Repository[User]` — service khai **năng lực** nó cần:
+
+  ```python
+  def __init__(self, payments: Providers[PaymentGateway]) -> None: ...
+
+  cong = self._payments.get(don.cong_thanh_toan)   # -> PaymentGateway
+  ```
+
+  Thêm bản hiện thực mới = thả một file mang `@provider("tên")` vào
+  `src/providers/<họ>/`. Không sửa service, không sửa `main.py`.
+
+  `get()` trả 404 nếu không có tên, **501** nếu có tên nhưng thiếu năng lực —
+  Hik không mở được cửa thì đó không phải bug của server. `names()` chỉ liệt kê
+  provider làm được việc của sổ đó. Xem `docs/providers.md`, trong đó có mục
+  "Viết năng lực cho dễ bảo trì": khi nào tách `capabilities.py` thành package,
+  và ba nguyên tắc đặt tên / chia nhỏ interface.
+
+- **`fam provider <họ> <tên>`** — sinh khung. Lần đầu dựng cả họ; lần sau đọc
+  `capabilities.py` rồi sinh sẵn stub đúng chữ ký các method cần viết.
+
+- **`container.build(cls, key=..., scope=...)`** — dựng một lớp có nối phụ thuộc
+  mà KHÔNG đăng ký vào sổ toàn cục. Cần cho provider: sổ toàn cục tra theo tên
+  class, trong khi hai họ có quyền cùng có một `OryzaProvider`.
+
+### Thay đổi
+
+- `fam p` giờ **nhập nhằng** giữa `publish` và `provider` nên `fam` hỏi lại. Viết
+  tắt mới: `fam pu` cho publish, `fam pr` cho provider.
+- `create_app()` và `src/main.py` sinh sẵn gọi `register_providers()` trước khi
+  dựng route. Không có `src/providers/` thì bỏ qua, không lỗi.
+
+### Thêm — query builder
+
+- **`repo.query()`** sinh SQL thật: `join` / `left_join` / `right_join` /
+  `outer_join`, `where` nối tiếp là AND còn `or_where` mở nhánh OR, `group_by` +
+  `having`, `limit` / `offset` / `distinct`. Xem câu sinh ra bằng `.sql()`.
+- **Toán tử thường trên cột**: `Camera.score >= 0.9` thay cho `score__gte=0.9`,
+  nhờ `class Camera(Entity)`. Bảy toán tử không có ký hiệu (`like`, `ilike`,
+  `in_`, `not_in`, `is_null`, `is_not_null`, `between`) có cả ở dạng method của
+  builder — `query().like(...)` — để IDE gợi ý được.
+- **Khoá ngoại**: `field(metadata=reference(Camera, on_delete="CASCADE"))`, đủ
+  bốn hành vi `CASCADE` / `SET NULL` / `SET DEFAULT` / `RESTRICT`. Áp bởi chính
+  database với SQL; khung tự áp cho `memory` và `mongodb` để ba backend cùng
+  kết quả.
+- **Transaction**: `async with db.transaction() as tx:` — khối lồng nhau thành
+  SAVEPOINT, `await tx.rollback()` huỷ mà không phải ném lỗi. HTTP handler đã
+  nằm sẵn trong một transaction của cả request.
+- **Dữ liệu lồng nhau**: `include(X)` khai X trả về những cột nào,
+  `nest_under(A, B, C)` khai thứ tự lồng từ NGOÀI vào TRONG. Mỗi mức đúng một
+  câu lệnh, không phải một câu cho mỗi dòng.
+- **`select(...)`** gộp cả `fields=` / `exclude=` / `rename=` / `add=`.
+- **MongoDB** chạy được phần lớn builder (`docs/mongodb.md` liệt kê cái không có:
+  JOIN, `group_by`, `distinct`, transaction).
+- **Chặn injection ở tầng dùng chung**: giá trị mang toán tử (`{"$ne": ""}` —
+  qua được cửa đăng nhập trên Mongo), khoá `$where` chạy JavaScript, và tên cột
+  không có thật (SQL trước đây âm thầm bỏ điều kiện, trả về cả bảng).
+- **Soi khoá ngoại lúc khởi động** (`db.foreign_keys_stale`): thêm
+  `reference(...)` vào entity đã chạy rồi thì database không biết — cascade
+  dừng giữa chừng, cháu ở lại thành mồ côi, không lỗi không cảnh báo.
+
+### Thêm — việc chạy nền
+
+- `@worker` (vòng lặp sống mãi, N bản, mỗi bản một tham số), `@interval` /
+  `@cron` / `@timeout` (theo lịch), `@job` (hàng đợi trong tiến trình),
+  `@on_event` + `EventBus` (fanout trong tiến trình). Cả bốn nhận `thread=True`
+  cho hàm chặn, và `ctx: WorkerContext` để dừng đúng cách.
+- Khoá `flock` / Redis để nhiều worker không cùng chạy một việc định kỳ.
+
+### Thêm — RPC và hạ tầng
+
+- **`emit` / `send` + `@*_responder`** cho RabbitMQ, Redis, MQTT, Kafka — khuôn
+  tin tương thích `@nestjs/microservices`, đã chạy đối chứng hai chiều với
+  NestJS 11.2.1.
+- RabbitMQ: đủ 5 kiểu exchange, 3 dạng hạn dùng (TTL), `emit_many`.
+- SQLite: mặc định WAL + `synchronous=NORMAL` — đo được nhanh gấp 20 lần
+  (68 → 1.269 ghi/s) mà vẫn không hỏng file khi mất điện.
+
+### Thêm — CLI
+
+- **`fam install` ghi nhớ thành phần vào `requirements.txt`**
+  (`fastapi-modular[redis,sqlite]>=0.3.0`), để người clone repo về chỉ cần
+  `pip install -r requirements.txt`. `fam init` sinh sẵn file này. Dự án dùng
+  `pyproject.toml` đã khai fastapi-modular thì sửa ngay dòng đó. `fam install
+  dev` đi vào `requirements-dev.txt`.
+- `fam module` sinh entity kế thừa `Entity`.
+
+### Sửa
+
+- **Controller viết `def` thường** nổ `TypeError: object dict can't be used in
+  'await' expression`. Khung bọc mọi method thành endpoint async rồi await
+  thẳng, nên mất luôn luật của FastAPI: `def` phải chạy ở thread pool. Guard
+  đồng bộ cũng nổ y hệt. Đo lại sau khi sửa: 4 request chặn 0,3s xong trong
+  0,31s.
+- **`fam install` chạy trước `fam init`** chỉ ghi khối database vào `.env`,
+  thiếu sạch `APP_NAME` / `APP_ENV` / `APP_DEBUG` / `APP_HOST` / `APP_PORT` —
+  app chạy bằng toàn giá trị mặc định, im lặng.
+- **Lọc bằng `Enum` thường** (không phải `StrEnum`) chạy trên `memory` nhưng nổ
+  trên sqlite lẫn mongo. Chiều ngược lại cũng lệch: lọc bằng chuỗi `.value` thì
+  SQL khớp còn memory trượt.
+- **`nest_under` + sắp theo cột của một lớp**: sqlite ném lỗi, memory và mongo
+  lặng lẽ bỏ qua.
+- **Lồng ba tầng từ repo trong cùng**: `include(Camera)` ném lỗi dù chuỗi
+  `nest_under` nối được qua bảng giữa.
+- **`include(X, name=...)`** bị bỏ qua khi X nằm trong chuỗi `nest_under`.
+- **Hai transaction `memory` đồng thời**: task rollback cuốn luôn bản ghi task
+  khác vừa commit.
+- **MongoDB cho ghi con trỏ tới cha không tồn tại**, trong khi SQL và memory từ
+  chối 409.
+- `Ctrl+C` không thoát được khi có worker đang chạy; `@worker(thread=True)` mượn
+  pool dùng chung của event loop nên làm treo cả tiến trình.
+
+### Thay đổi phá vỡ
+
+| 0.2.x | 0.3.0 |
+|---|---|
+| `.order_by("score")` | `.order_by_desc("score")` / `.order_by_asc("score")` — chiều nằm trong TÊN HÀM |
+| `.fields([...])` · `.exclude([...])` | `.select(fields=[...], exclude=[...])` |
+| `fam p` | nhập nhằng — `fam pu` (publish) hoặc `fam pr` (provider) |
+
+Định danh trong thư viện đổi hết sang tiếng Anh; nếu bạn import hàm `_private`
+nào của khung thì kiểm lại tên. API công khai không đổi.
+
+## [0.2.1] — 2026-08-22
+
+### Thay đổi
+
+- Tác giả và chủ bản quyền: Oryza <developer@oryza.vn> -> quanglinh
+  <hackcoquanglinh2000@gmail.com>, ở cả `pyproject.toml` lẫn `LICENSE`.
+- README tách làm hai bản song ngữ: `README.md` (tiếng Anh, là bản hiện trên
+  PyPI) và `README.vi.md` (tiếng Việt). Hai bản giữ cùng thứ tự mục.
+- Metadata PyPI viết lại cho tìm kiếm: summary sang tiếng Anh, keywords từ 9 lên
+  39 từ, thêm 7 classifier.
+
+### Tài liệu
+
+- Viết lại `docs/websocket.md` theo hướng làm-theo thay vì tra-cứu: đưa "bốn
+  việc client bắt buộc phải làm" lên đầu trang, thêm client tối thiểu 30 dòng
+  chạy được ngay, giải thích cơ chế nhịp tim bằng sơ đồ thời gian, và thêm mục
+  tra sự cố theo triệu chứng.
+
+## [0.2.0] — 2026-08-22
+
+**Đổi tên toàn bộ.** Tên `pymodular` bị PyPI từ chối vì trùng với project
+`py-modular` đã có, nên cả dự án đổi sang `fastapi-modular` cho thống nhất từ
+PyPI, GitHub, thư mục nguồn cho tới tên lệnh.
+
+### Phá vỡ
+
+- Gói trên PyPI: `pymodular` -> **`fastapi-modular`**.
+- Tên import: `import pymodular` -> **`import fastapi_modular`** (gạch dưới,
+  vì gạch ngang không hợp lệ trong tên module Python).
+- Lệnh CLI: `pymodular` / `pym` -> **`fastapi-modular` / `fam`**.
+- Thư mục nguồn `pymodular/` -> `fastapi_modular/`.
+- `APP_NAME` mặc định: `pymodular` -> `fastapi-modular`.
+- `APP_KAFKA__CLIENT_ID` mặc định: `pymodular` -> `fastapi-modular`.
+
+Nâng cấp từ 0.1.0: gỡ gói cũ (`pip uninstall pymodular`), cài
+`pip install fastapi-modular`, rồi đổi mọi `pymodular` trong import thành
+`fastapi_modular` và mọi lệnh `pym` thành `fam`.
+
+### Sửa
+
+- `fam lint` không tham số trỏ vào thư mục `app` không tồn tại nên lỗi ngay;
+  mặc định đổi thành `src`, đúng thứ `fam init` sinh ra.
+- `fam migrate-create` trong docs/migrations.md không phải lệnh có thật; lệnh
+  đúng là `fam migrate create`.
+- Link trong README đổi sang URL tuyệt đối: README là trang hiển thị trên PyPI,
+  ở đó link tương đối `docs/...` phân giải sai và trả 404.
+- Job đóng gói trong CI không bao giờ xanh được: import sai đường dẫn
+  (`src.api.main`) và liệt kê route bằng `r.path`, hỏng từ FastAPI 0.141.
+
+## [0.1.0] — 2026-08-21
+
+Bản đầu tiên. Cần **Python 3.10 trở lên**.
+
+### Có gì
+
+- **Kiến trúc module kiểu NestJS**: DI container (`@injectable`, `Lazy[...]`,
+  `Scope.REQUEST`), controller dạng class (`@controller`, `@get`/`@post`/...),
+  tự quét module — thêm thư mục là có route, không phải đăng ký ở đâu cả.
+- **Repository dùng chung cho 4 backend**: memory, SQLite, PostgreSQL, MongoDB.
+  Đổi backend không phải sửa service. Kèm circuit breaker và hạn thời gian.
+- **WebSocket**: `@gateway` / `@subscribe`, phòng, gửi thẳng tới một người,
+  nhịp tim, giới hạn tần suất, adapter Redis để phát tin xuyên worker.
+- **Bốn lớp hạ tầng tuỳ chọn, cùng một khuôn**: RabbitMQ, Redis, MQTT, Kafka.
+  Mặc định TẮT; thư viện chỉ được import khi bật. Tất cả tự nối lại.
+- **CLI** `fastapi-modular`, gõ tắt là `fam`: `init` (dựng dự án ngay trong thư mục
+  hiện tại) · `new` · `dev` / `run` · `module` · `env` · `info` · `migrate` ·
+  `test` / `lint`. `init` không bao giờ ghi đè file đã có.
+- **Tài liệu tiếng Việt** trong `docs/`, viết theo lối tra cứu: mỗi hàm nói rõ
+  truyền gì, không truyền thì mặc định là gì.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-modular
-Version: 0.2.1
+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
@@ -97,14 +97,33 @@ public API, and this README, are in English. Start with
 | `@Module()` + module scanning | a directory under `src/api/`, auto-scanned |
 | `@Controller('users')` | `@controller(prefix="/users", tags=["users"])` |
 | `@Get()` `@Post()` `@Patch()` `@Delete()` | `@get()` `@post()` `@patch()` `@delete()` |
+| sync handler runs on the main thread (Nest) | `def` handler runs in a thread pool, `async def` on the event loop — FastAPI's own rule |
 | `@Injectable()` | `@injectable` |
 | `@Injectable({scope: Scope.REQUEST})` | `@injectable(scope=Scope.REQUEST)` |
 | `forwardRef(() => X)` | `Lazy[X]` |
 | `@InjectRepository(X) repo: Repository<X>` | `repo: Repository[X]` |
+| `@Transaction()` / `queryRunner.startTransaction()` | `async with db.transaction():` — nested blocks become SAVEPOINTs |
+| `queryRunner.rollbackTransaction()` | automatic on exception; `await tx.rollback()` to bail out without raising |
+| `repo.createQueryBuilder()` (TypeORM) | `repo.query().join(X).where(Event.score >= …)` — real SQL, `.sql()` to see it |
+| `Repository.find({where: {score: MoreThan(…)}})` (TypeORM) | `class Event(Entity)` then `.where(Event.score >= …)`, or `.where(score__gte=…)` |
+| `.groupBy().having()` (TypeORM) | `.group_by(Event.camera_id).select(n=count()).having(count() > 5)` |
+| `.leftJoin()` / `.orWhere()` (TypeORM) | `.left_join(X)` / `.or_where(…)` — one method per join kind |
+| `.orderBy('x', 'DESC')` (TypeORM) | `.order_by_desc("x")` — the direction is in the method name |
+| `Like()` / `In()` / `IsNull()` (TypeORM) | `.like(X.name, "a%")` · `.in_(X.zone, [...])` · `.is_null(X.ip)` — right on the builder |
+| `select([...])` / `AS` (TypeORM) | `.select(fields=…, exclude=…, rename={"new": "col"})` — same names on `include` |
+| `addSelect()` (TypeORM) | `.select(add={"cam_name": Camera.name})` — keep every column, add one |
+| `find({relations: {events: true}})` (TypeORM) | `.include(Event)` — nested rows, one extra query, not N+1 |
+| `relations: {camera: {logs: {items: true}}}` (TypeORM) | `.nest_under(Camera, CameraLog, ItemLog)` — one query per level |
+| *(no TypeORM equivalent)* | `.nest_under(Camera)` — filter on events, get cameras back with them nested |
+| `@ManyToOne(…, {onDelete: 'CASCADE'})` (TypeORM) | `field(metadata=reference(Camera, on_delete="CASCADE"))` — a real FK in the database |
 | `@UseGuards()` | `guards=[...]` on the controller or a single route |
 | `@WebSocketGateway()` | `@gateway(path="/ws/…")` |
 | `@SubscribeMessage('x')` | `@subscribe("x")` |
 | `@EventPattern('x')` (RabbitMQ) | `@rabbitmq_subscriber("events", "x", queue="…")` |
+| `@MessagePattern('x')` | `@rabbitmq_responder("x", queue="…")` — the return value is sent back |
+| `@Interval()` / `@Cron()` / `@Timeout()` | `@interval(seconds=5)` / `@cron("0 3 * * *")` / `@timeout(seconds=10)` |
+| `@OnEvent('x')` + `EventEmitter2` | `@on_event("x")` + `EventBus.emit()` — in-process fanout |
+| `client.emit(p, d)` / `client.send(p, d)` | `broker.emit(p, d, queue=…)` / `await broker.send(p, d, queue=…)` |
 | `CacheModule` / `CACHE_MANAGER` | `RedisClient.cached(key, factory, ttl=…)` |
 | socket.io Redis adapter | `APP_WS__ADAPTER=redis` |
 
@@ -139,8 +158,24 @@ fam install rabbitmq    # or redis, mqtt, kafka
 fam install all         # everything above
 ```
 
-`fam install` both installs the libraries and writes the matching variables into
-`.env`. Plain pip works too: `pip install "fastapi-modular[sqlite,rabbitmq]"`.
+`fam install` does three things: installs the libraries, writes the matching
+variables into `.env`, and **records the component in `requirements.txt`** so a
+teammate who clones the repo only needs `pip install -r requirements.txt` — the
+same job `package.json` does for `npm i`.
+
+```
+# requirements.txt, after `fam install sqlite` and `fam install redis`
+fastapi-modular[redis,sqlite]>=0.3.1
+```
+
+It records the extras, not the individual packages: the version ranges of
+`sqlalchemy`, `motor` and friends belong to fastapi-modular and change per
+release, so a flattened snapshot would go stale silently. If the project uses
+`pyproject.toml` and already lists fastapi-modular there, that line is updated
+instead and no `requirements.txt` is created. `fam install dev` goes to
+`requirements-dev.txt` — production should not have to install pytest.
+
+Plain pip works too: `pip install "fastapi-modular[sqlite,rabbitmq]"`.
 
 ## Commands
 
@@ -166,9 +201,10 @@ fam: lệnh 'm' chưa rõ — khớp với migrate, module. Gõ thêm vài chữ
 | `fam module <name> --gateway` | | plus a WebSocket gateway (`--consumer` for RabbitMQ) |
 | `fam module <name> --gateway-only` | | add a gateway to an **existing** module (`--consumer-only` for RabbitMQ) |
 | `fam module <name> --entity <N>` | | set the entity class name; guessed from the module name otherwise |
+| `fam provider <family> <name>` | `fam pr` | generate a pluggable provider: capability interfaces + implementation stub |
 | `fam env <component>` | `fam e` | only write config variables into `.env` (installs nothing) |
 | `fam clean` | `fam c` | remove caches and build output (leaves `data/` alone) |
-| `fam build` · `fam publish [--test]` | `fam b` · `fam p` | build wheel/sdist · upload to PyPI |
+| `fam build` · `fam publish [--test]` | `fam b` · `fam pu` | build wheel/sdist · upload to PyPI |
 | `fam info` | `fam inf` | what it connects to, what is installed, production config warnings |
 | `fam migrate [up\|down\|history\|sql\|create]` | `fam mi` | Alembic |
 | `fam test` · `fam lint [--fix]` | `fam t` · `fam l` | pytest · ruff. Bare `fam lint` checks `src`; pass paths to check elsewhere |
@@ -177,7 +213,7 @@ fam: lệnh 'm' chưa rõ — khớp với migrate, module. Gõ thêm vài chữ
 | `fam install postgres` | `fam ins p` | PostgreSQL |
 | `fam install mongodb` | `fam ins mo` | MongoDB |
 | **Queues** | | *installs libraries **then** writes `.env`* |
-| `fam install rabbitmq` | `fam ins ra` | durable queues, retry + DLQ |
+| `fam install rabbitmq` | `fam ins ra` | 5 exchange types, durable queues, TTL, retry + DLQ |
 | `fam install redis` | `fam ins re` | cache, atomic counters, pub/sub |
 | `fam install mqtt` | `fam ins mq` | IoT devices |
 | `fam install kafka` | `fam ins k` | replayable event log |
@@ -214,8 +250,7 @@ fam env sqlite          # write .env only, install nothing
 fam info                # what it is connected to right now
 ```
 
-Details:
-[docs/database.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md).
+Details: [docs/database.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md) (SQL) · [docs/mongodb.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/mongodb.md) (MongoDB).
 
 ## Your own configuration
 
@@ -306,12 +341,125 @@ async def send_mail(self, payload: AlertCreated) -> None: ...
 @rabbitmq_subscriber("events", "alert.created", queue="alert-mailer",
                      max_retries=3, dead_letter=True)
 async def send_mail(self, payload: AlertCreated) -> None: ...
+
+# All 5 exchange types: topic (default), direct, fanout, headers, default
+@rabbitmq_subscriber("cache-events", queue=f"drop-cache-{HOSTNAME}", exchange_type="fanout")
+# hostname in the queue name -> every worker gets a copy, instead of taking turns
+async def drop_cache(self, payload: dict) -> None: ...
+
+# Time to live: per message (ttl), per queue (message_ttl), for the queue itself
+await self._mq.publish("events", "car.position", {"lat": 21.0}, ttl=5)
 ```
 
 Not installed and not enabled means it behaves as if it never existed. If the
 broker goes down the app keeps serving and reconnects on its own. Details:
 [docs/rabbitmq.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/rabbitmq.md).
 
+## Background work
+
+Four different things, none of which needs any infrastructure:
+
+```python
+# on a SCHEDULE — @nestjs/schedule
+@interval(seconds=5)
+async def update_cameras(self) -> None: ...
+
+@cron("0 3 * * *", timezone="Asia/Ho_Chi_Minh")     # defaults to UTC!
+async def clean_logs(self) -> None: ...
+
+# on DEMAND — an in-process asyncio.Queue, processed in order
+@job("detect", thread=True)            # thread: runs in a thread, for YOLO
+def detect(self, payload: dict, ctx: WorkerContext) -> None:
+    ctx.run(self._db.save(...))        # write to the DB from inside the thread
+
+await self._jobs.submit("detect", {"path": p})      # returns immediately
+
+# a LONG-RUNNING LOOP — N instances, one per key
+@worker("camera")
+async def watch(self, data: dict, ctx: WorkerContext) -> None:
+    cap = await ctx.blocking(cv2.VideoCapture, data["ip"])   # setup, OUTSIDE the loop
+    while ctx.running:
+        frame = await ctx.blocking(cap.read)                 # blocking call -> a thread
+        await self._db.save(...)                             # plain await
+
+for camera in cameras:
+    await service.watch(camera.id, {"ip": camera.ip})   # key + data at call time
+
+await self.watch.stop(camera.id)       # stops ONE instance, waits for its cleanup
+
+# FANOUT inside the process — one event, N listeners, in PARALLEL
+@on_event("order.paid")                       # also "order.*" / "camera.#"
+async def send_receipt(self, data: dict) -> None: ...
+
+@on_event("order.paid")                       # a second listener is normal here
+async def update_stats(self, data: dict) -> None: ...
+
+await self._events.emit("order.paid", {"id": id})   # waits for all of them
+self._events.dispatch("order.paid", {"id": id})     # returns immediately
+```
+
+All five decorators come in two shapes: `async def` (the default) and
+`thread=True` for bodies that are all blocking calls. `ctx` is optional — take
+it when you need `ctx.running` to leave a loop, `ctx.blocking(...)` to call
+blocking code, or `ctx.run(...)` to write to the DB from inside a thread.
+
+`@on_event` covers what `@job` cannot: `@job` is one name, **one** handler,
+processed in order — a work queue. `@on_event` is one event, **many** handlers,
+running in parallel — nobody owns the work, and the emitter doesn't know who is
+listening. One listener raising doesn't stop the others. It is `fanout` /
+`EventEmitter`, but in-process only: with `fam run --workers 4` an event does
+not cross to the other three processes.
+
+`@worker` covers what `@interval` and `@job` cannot: a setup phase **before**
+the loop (open the camera, load the model) and a body that runs until you stop
+it. Crashes restart with backoff; calling it again with the same `key` returns
+the running instance instead of opening a second stream.
+
+`stop()` waits for the loop's `finally:` to finish, so anything you write after
+it runs with the camera already closed — put resource cleanup in `finally:` and
+business cleanup after the call.
+
+Write `while ctx.running:`, not `while True:` — a loop that never checks makes
+Ctrl+C look dead for the whole shutdown timeout. The framework says so at
+startup (`worker.endless_loop`) rather than letting you find out at 2am.
+
+`fam run` starts 4 workers, so a hand-written `while True: sleep(5)` runs
+**four times**. `single=True` (the default) locks it down: measured 5 runs
+across 1 process, versus 20 runs across 4 with the lock off. The lock is
+`flock` (one machine) or Redis (many), picked automatically.
+
+The `@job` queue lives in RAM — **shutdown loses whatever hasn't run**, and the
+framework logs that count instead of hiding it. Work that must not be lost
+belongs in `@rabbitmq_subscriber`. Details:
+[docs/background.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/background.md).
+
+## Request/response, NestJS-compatible
+
+`publish`/`emit` fire and forget. `send` waits for an answer — the NestJS
+`client.send()` / `@MessagePattern()` pair, same wire format:
+
+```python
+# the side that answers — a normal service that happens to `return`
+@rabbitmq_responder("sum", queue="math")
+async def add(self, data: list[int]) -> int:
+    return sum(data)
+
+# the side that calls
+total = await self._mq.send("sum", [1, 2, 3, 4], queue="math")   # -> 10
+```
+
+Available on **all four**: `@rabbitmq_responder`, `@redis_responder`,
+`@mqtt_responder`, `@kafka_responder`.
+
+The packet layout is taken from `@nestjs/microservices` source, so a NestJS
+microservice and a service built on this library talk to each other with no
+translation layer — verified both ways, on all four transports, against NestJS
+11.2.1. Object patterns (`{"cmd": "sum"}`) included, key ordering and all.
+
+`send` turns a queue into a network call, which brings back everything queues
+exist to avoid — [docs/rpc.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/rpc.md)
+says when not to use it.
+
 ## Redis, MQTT, Kafka (also optional)
 
 Same shape as RabbitMQ: one package under `infrastructure/`, one `APP_<NAME>__*`
@@ -354,8 +502,8 @@ Guards, circuit breaker, metrics and tracing:
 fastapi_modular/    THE LIBRARY — what gets packaged and installed
   core/             DI, controllers, config, WebSocket, guards, metrics
   infrastructure/   database, rabbitmq, redis, mqtt, kafka (one package each)
-  cli/              init · new · module · dev · run · install · env · info
-                    migrate · test · lint · clean · build · publish
+  cli/              init · new · module · provider · dev · run · install · env
+                    info · migrate · test · lint · clean · build · publish
   factory.py        create_app()
   discovery.py      scans the application package and builds routers
 src/                SAMPLE APPLICATION — not shipped in the package; delete freely
@@ -363,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/              341 tests that need no infrastructure, 40 more when servers exist
+tests/              1101 tests that need no infrastructure, 292 more with real drivers/servers
 docs/               reference documentation (Vietnamese)
 ```
 
@@ -402,11 +550,15 @@ Written in Vietnamese, organised for reference rather than reading front to back
 
 - [docs/architecture.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/architecture.md) — module layout, DI, the NestJS comparison
 - [docs/config.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/config.md) — Settings, precedence, adding your own variables
-- [docs/database.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md) — memory / SQLite / PostgreSQL / MongoDB
+- [docs/database.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md) — SQL: memory / SQLite / PostgreSQL — entities, foreign keys, query builder, transactions
+- [docs/mongodb.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/mongodb.md) — MongoDB: queries, nested data, and what is not there (no JOIN, no transactions)
 - [docs/migrations.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/migrations.md) — Alembic: generate, run, roll back
 - [docs/websocket.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/websocket.md) — WebSocket gateway, rooms, Postman, Next.js
-- [docs/rabbitmq.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/rabbitmq.md) — exchanges, topics, background consumers, `.retry` / `.dlq`
+- [docs/rabbitmq.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/rabbitmq.md) — all 5 exchange types, TTL, background consumers, `.retry` / `.dlq`
+- [docs/background.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/background.md) — scheduled work (`@interval`/`@cron`/`@timeout`), an in-process job queue (`@job`), long-running loops (`@worker`) and in-process fanout (`@on_event`)
+- [docs/rpc.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/rpc.md) — `emit` / `send` / `@rabbitmq_responder`, NestJS-compatible wire format
 - [docs/redis.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/redis.md) — cache, atomic counters, pub/sub
 - [docs/mqtt.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/mqtt.md) — QoS, retain, `+` and `#` topic matching
 - [docs/kafka.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/kafka.md) — consumer groups, partitions, `.dlt`
+- [docs/providers.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/providers.md) — pluggable providers: pick an implementation by name at runtime
 - [docs/operations.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/operations.md) — guards, circuit breaker, metrics, tracing