tempest-fastapi-sdk 0.43.0__tar.gz → 0.45.0__tar.gz

{tempest_fastapi_sdk-0.43.0 → tempest_fastapi_sdk-0.45.0}/CHANGELOG.md

@@ -5,6 +5,58 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.45.0] — 2026-06-11
+
+### Added
+
+- **`TenantScopedRepository[ModelType]`** — a `BaseRepository` locked
+  to a single tenant for shared-schema multi-tenancy. Bind a
+  `tenant_id` (and optional `tenant_field`, default `"tenant_id"`) at
+  construction; it injects `WHERE tenant_id = ?` into **every** read
+  (`get`/`get_or_none`/`get_by_id`/`exists`/`first`/`list`/`count`/
+  `paginate`/`cursor_paginate`/`delete_many`) and stamps the tenant id
+  onto **every** write (`add`/`add_all`). `delete` / `delete_batch` add
+  the tenant predicate to the `DELETE` so a guessed id from another
+  tenant matches nothing — cross-tenant access (even probing existence
+  by id) is impossible through the repository. The constructor raises
+  `AttributeError` at boot if the model lacks the tenant column.
+  `tenant_column` property exposes the mapped column for custom queries.
+
+### Docs
+
+- New bilingual recipe **Multi-tenant**, added to the nav (under
+  Database), the recipes index, and the API reference.
+
+## [0.44.0] — 2026-06-11
+
+### Added
+
+- **Transactional outbox.** New `BaseOutboxModel` (abstract — the
+  project subclasses it and picks `__tablename__`) carrying `topic`,
+  `payload` (JSON), `status`, `attempts` / `max_attempts`,
+  `available_at`, `sent_at` and `last_error`. `OutboxModel.new_event(
+  topic, payload)` builds a pending row.
+- **`BaseRepository.save_with_outbox(model, event)`** inserts the
+  business row and the outbox event in the **same transaction**, so an
+  event can never reference a rolled-back row (and a committed row
+  always has its event durably queued) — the fix for the dual-write
+  problem.
+- **`OutboxRelay`** drains pending rows and publishes them through a
+  caller-supplied async `publish` callable (no hard broker dependency
+  — works with `AsyncBrokerManager`, a webhook, a test spy). Marks each
+  row `sent`; on failure increments `attempts`, records `last_error`,
+  reschedules with exponential backoff, and marks `failed` once the
+  attempt budget is spent. Locks the batch with `FOR UPDATE SKIP
+  LOCKED` on PostgreSQL/MySQL (multi-worker safe), falling back to a
+  plain select on SQLite. `drain_once()` for one batch (tests/cron),
+  `run(poll_interval=...)` for the loop.
+- **`OutboxStatus`** enum (`pending` / `sent` / `failed`).
+
+### Docs
+
+- New bilingual recipe **Outbox transacional / Transactional outbox**,
+  added to the nav, the recipes index, and the API reference.
+
 ## [0.43.0] — 2026-06-11
 
 ### Added

{tempest_fastapi_sdk-0.43.0 → tempest_fastapi_sdk-0.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.43.0
+Version: 0.45.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
@@ -238,7 +238,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | Module | Exports |
 | --- | --- |
 | `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
-| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger` |
+| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `TenantScopedRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger`, `BaseOutboxModel`, `OutboxRelay`, `OutboxStatus`, `BaseRepository.save_with_outbox` |
 | `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException` |
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings`, `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
 | `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware`, `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |

{tempest_fastapi_sdk-0.43.0 → tempest_fastapi_sdk-0.45.0}/README.md

@@ -136,7 +136,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | Module | Exports |
 | --- | --- |
 | `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
-| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger` |
+| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `TenantScopedRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger`, `BaseOutboxModel`, `OutboxRelay`, `OutboxStatus`, `BaseRepository.save_with_outbox` |
 | `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException` |
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings`, `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
 | `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware`, `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |

{tempest_fastapi_sdk-0.43.0 → tempest_fastapi_sdk-0.45.0}/docs/recipes/index.en.md

@@ -10,11 +10,13 @@ Bite-sized "I want to wire X" walkthroughs. Each page starts with **what problem
 | Theme | Covers |
 | --- | --- |
 | **[Database »](database.md)** | `BaseRepository`, `BaseModel`, `AuditMixin` / `SoftDeleteMixin`, cursor pagination, Alembic helper |
+| **[Multi-tenant »](multi-tenant.md)** | `TenantScopedRepository` — `tenant_id` isolation on every query |
 | **[HTTP layer »](http.md)** | `apply_cors`, `RequestIDMiddleware`, `RateLimitMiddleware`, `make_health_router`, JWT / role / permission dependencies, webhook signature verifier, pagination Link headers, tool-spec router |
 | **[HTTP client (outbound) »](http-client.md)** | `HTTPClient` — typed httpx with retry/backoff, circuit-breaker, X-Request-ID; `RetryPolicy`, `CircuitOpenError` |
 | **[Cache »](cache.md)** | `AsyncRedisManager`, `@cached` decorator |
 | **[Real-time »](realtime.md)** | Server-Sent Events (`EventStream`, `sse_response`) |
 | **[Queue & Tasks »](queue-tasks.md)** | FastStream (`AsyncBrokerManager`), TaskIQ (`AsyncTaskBrokerManager`), `AsyncTaskScheduler`, transactional outbox |
+| **[Transactional outbox »](outbox.md)** | `BaseOutboxModel`, `OutboxRelay`, `save_with_outbox` — reliable events |
 | **[Transactional email »](email.md)** | `EmailUtils` — SMTP, text/HTML body, attachments, Jinja2 templates |
 | **[Web Push »](webpush.md)** | `WebPushDispatcher`, VAPID schemas, broadcast with pruning |
 | **[Logging »](logging.md)** | `LogUtils`, structured JSON logging, request-ID propagation |

{tempest_fastapi_sdk-0.43.0 → tempest_fastapi_sdk-0.45.0}/docs/recipes/index.md

@@ -10,11 +10,13 @@ Passo a passo curtos no estilo "quero conectar X". Cada página começa com **qu
 | Tema | Cobre |
 | --- | --- |
 | **[Banco de dados »](database.md)** | `BaseRepository`, `BaseModel`, `AuditMixin` / `SoftDeleteMixin`, paginação por cursor, helper de Alembic |
+| **[Multi-tenant »](multi-tenant.md)** | `TenantScopedRepository` — isolamento por `tenant_id` em toda query |
 | **[Camada HTTP »](http.md)** | `apply_cors`, `RequestIDMiddleware`, `RateLimitMiddleware`, `make_health_router`, dependências de JWT / role / permissão, verificador de assinatura de webhook, headers Link de paginação, router de tool-spec |
 | **[HTTP client (saída) »](http-client.md)** | `HTTPClient` — httpx tipado com retry/backoff, circuit-breaker, X-Request-ID; `RetryPolicy`, `CircuitOpenError` |
 | **[Cache »](cache.md)** | `AsyncRedisManager`, decorator `@cached` |
 | **[Tempo real »](realtime.md)** | Server-Sent Events (`EventStream`, `sse_response`) |
 | **[Fila e Tarefas »](queue-tasks.md)** | FastStream (`AsyncBrokerManager`), TaskIQ (`AsyncTaskBrokerManager`), `AsyncTaskScheduler`, outbox transacional |
+| **[Outbox transacional »](outbox.md)** | `BaseOutboxModel`, `OutboxRelay`, `save_with_outbox` — eventos confiáveis |
 | **[Email transacional »](email.md)** | `EmailUtils` — SMTP, corpo texto/HTML, anexos, templates Jinja2 |
 | **[Web Push »](webpush.md)** | `WebPushDispatcher`, schemas VAPID, broadcast com poda |
 | **[Logging »](logging.md)** | `LogUtils`, logging JSON estruturado, propagação de request-ID |

tempest_fastapi_sdk-0.45.0/docs/recipes/multi-tenant.en.md

@@ -0,0 +1,120 @@
+# Multi-tenant (TenantScopedRepository)
+
+In a **shared-schema** multi-tenant database, every tenant's rows live in
+the same table, told apart by a `tenant_id` column. The danger is obvious:
+forget **one** `WHERE tenant_id = ?` and tenant A reads (or deletes)
+tenant B's data. `TenantScopedRepository` takes that risk off the table —
+you bind the `tenant_id` at construction and it injects the filter into
+**every** read and stamps it onto **every** write. Call sites can't get it
+wrong.
+
+!!! info "Where this fits"
+    It's a `BaseRepository` that behaves identically — same API
+    ([Database](database.md)). The difference is invisible to the caller:
+    tenant scoping is automatic.
+
+## 1. The model needs a tenant column
+
+```python
+from uuid import UUID
+
+from sqlalchemy import String, Uuid
+from sqlalchemy.orm import Mapped, mapped_column
+
+from tempest_fastapi_sdk import BaseModel
+
+
+class OrderModel(BaseModel):
+    """Order — isolated per tenant."""
+
+    __tablename__ = "order"
+
+    tenant_id: Mapped[UUID] = mapped_column(Uuid(), nullable=False, index=True)
+    total: Mapped[int] = mapped_column(nullable=False)
+```
+
+## 2. Build the repository bound to the tenant
+
+The `tenant_id` usually comes from the request's JWT / session / header:
+
+```python
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from tempest_fastapi_sdk import TenantScopedRepository
+
+from src.db.models import OrderModel
+
+
+def get_order_repo(
+    session: AsyncSession, tenant_id: UUID
+) -> TenantScopedRepository[OrderModel]:
+    """Order repository locked to the request's tenant."""
+    return TenantScopedRepository(session, model=OrderModel, tenant_id=tenant_id)
+```
+
+If the model has no `tenant_id` column, the constructor raises
+`AttributeError` immediately — you catch the mistake at boot, not in
+production. Different column name? Pass `tenant_field="org_id"`.
+
+## 3. Use it like any repository
+
+Every read comes filtered; every write comes stamped:
+
+```python
+from uuid import UUID
+
+from tempest_fastapi_sdk import TenantScopedRepository
+
+from src.db.models import OrderModel
+
+
+async def list_orders(repo: TenantScopedRepository[OrderModel]) -> list[OrderModel]:
+    """Only THIS tenant's orders — no manual WHERE."""
+    return await repo.list()  # WHERE tenant_id = <bound tenant>
+
+
+async def create_order(
+    repo: TenantScopedRepository[OrderModel], total: int
+) -> OrderModel:
+    """tenant_id is stamped automatically on insert."""
+    return await repo.add(OrderModel(total=total))
+```
+
+### Cross-tenant access is impossible, even by id
+
+`get_by_id`, `delete` and `delete_batch` are scoped too. An id from another
+tenant simply **doesn't match** — indistinguishable from a row that never
+existed:
+
+```python
+from uuid import UUID
+
+from tempest_fastapi_sdk import TenantScopedRepository
+
+from src.db.models import OrderModel
+
+
+async def fetch(repo: TenantScopedRepository[OrderModel], order_id: UUID) -> OrderModel:
+    """Raises NotFound if the order belongs to ANOTHER tenant — no existence leak."""
+    return await repo.get_by_id(order_id)
+```
+
+`delete_many({})` deletes only **this** tenant's rows, never the whole
+table — the tenant predicate is always added.
+
+!!! warning "Raw queries are your responsibility"
+    A subclass that builds its own `select(...)` without going through
+    `_apply_filters` — or a pre-built `query=` passed to `paginate` — is
+    **not** auto-scoped. In those cases, add
+    `.where(self.tenant_column == self.tenant_id)` yourself.
+
+## Recap
+
+- The model declares `tenant_id` (or another column, via `tenant_field=`).
+- `TenantScopedRepository(session, model=..., tenant_id=...)` injects the
+  filter into every read and stamps every write.
+- `get_by_id` / `delete` / `delete_batch` / `delete_many` are scoped —
+  cross-tenant access is impossible through the repository methods.
+- The constructor validates the tenant column exists at boot.

tempest_fastapi_sdk-0.45.0/docs/recipes/multi-tenant.md

@@ -0,0 +1,120 @@
+# Multi-tenant (TenantScopedRepository)
+
+Num banco multi-tenant de **schema compartilhado**, as linhas de todos os
+tenants moram na mesma tabela, separadas por uma coluna `tenant_id`. O
+perigo é claro: esquecer **um** `WHERE tenant_id = ?` e o tenant A lê (ou
+apaga) os dados do tenant B. `TenantScopedRepository` tira esse risco da
+mesa — você amarra o `tenant_id` na construção e ele injeta o filtro em
+**toda** leitura e carimba em **toda** escrita. Os call sites não têm como
+errar.
+
+!!! info "Onde isso encaixa"
+    É um `BaseRepository` que se comporta igualzinho — mesma API
+    ([Banco de dados](database.md)). A diferença é invisível pro chamador:
+    o escopo de tenant é automático.
+
+## 1. O modelo precisa da coluna de tenant
+
+```python
+from uuid import UUID
+
+from sqlalchemy import String, Uuid
+from sqlalchemy.orm import Mapped, mapped_column
+
+from tempest_fastapi_sdk import BaseModel
+
+
+class OrderModel(BaseModel):
+    """Pedido — isolado por tenant."""
+
+    __tablename__ = "order"
+
+    tenant_id: Mapped[UUID] = mapped_column(Uuid(), nullable=False, index=True)
+    total: Mapped[int] = mapped_column(nullable=False)
+```
+
+## 2. Construa o repositório amarrado ao tenant
+
+O `tenant_id` normalmente vem do JWT / sessão / header do request:
+
+```python
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from tempest_fastapi_sdk import TenantScopedRepository
+
+from src.db.models import OrderModel
+
+
+def get_order_repo(
+    session: AsyncSession, tenant_id: UUID
+) -> TenantScopedRepository[OrderModel]:
+    """Repositório de pedidos travado no tenant do request."""
+    return TenantScopedRepository(session, model=OrderModel, tenant_id=tenant_id)
+```
+
+Se o modelo não tiver a coluna `tenant_id`, o construtor levanta
+`AttributeError` na hora — você descobre o erro no boot, não em produção.
+Coluna com outro nome? Passe `tenant_field="org_id"`.
+
+## 3. Use como qualquer repositório
+
+Toda leitura já vem filtrada; toda escrita já vem carimbada:
+
+```python
+from uuid import UUID
+
+from tempest_fastapi_sdk import TenantScopedRepository
+
+from src.db.models import OrderModel
+
+
+async def list_orders(repo: TenantScopedRepository[OrderModel]) -> list[OrderModel]:
+    """Só os pedidos DESTE tenant — sem WHERE manual."""
+    return await repo.list()  # WHERE tenant_id = <tenant amarrado>
+
+
+async def create_order(
+    repo: TenantScopedRepository[OrderModel], total: int
+) -> OrderModel:
+    """tenant_id é carimbado automaticamente no insert."""
+    return await repo.add(OrderModel(total=total))
+```
+
+### Acesso cruzado é impossível, mesmo por id
+
+`get_by_id`, `delete` e `delete_batch` também são escopados. Um id de outro
+tenant simplesmente **não casa** — é indistinguível de uma linha que nunca
+existiu:
+
+```python
+from uuid import UUID
+
+from tempest_fastapi_sdk import TenantScopedRepository
+
+from src.db.models import OrderModel
+
+
+async def fetch(repo: TenantScopedRepository[OrderModel], order_id: UUID) -> OrderModel:
+    """Levanta NotFound se o pedido for de OUTRO tenant — sem vazar existência."""
+    return await repo.get_by_id(order_id)
+```
+
+`delete_many({})` apaga só as linhas **deste** tenant, nunca a tabela
+inteira — o predicado de tenant é sempre adicionado.
+
+!!! warning "Queries cruas são responsabilidade sua"
+    Uma subclasse que monta o próprio `select(...)` sem passar por
+    `_apply_filters` — ou um `query=` pré-montado passado pro `paginate` —
+    **não** é escopado automaticamente. Nesses casos, adicione
+    `.where(self.tenant_column == self.tenant_id)` você mesmo.
+
+## Recap
+
+- O modelo declara `tenant_id` (ou outra coluna, via `tenant_field=`).
+- `TenantScopedRepository(session, model=..., tenant_id=...)` injeta o
+  filtro em toda leitura e carimba toda escrita.
+- `get_by_id` / `delete` / `delete_batch` / `delete_many` são escopados —
+  acesso cruzado entre tenants é impossível pelos métodos do repositório.
+- Construtor valida a existência da coluna de tenant no boot.

tempest_fastapi_sdk-0.45.0/docs/recipes/outbox.en.md

@@ -0,0 +1,121 @@
+# Transactional outbox (reliable events)
+
+When a handler **writes a row** and **publishes an event**, doing the two
+as independent operations is fragile: if the process dies *after* the
+commit but *before* the publish, the event is lost; if it dies after the
+publish but before the commit, a phantom event references a row that never
+existed. This is the **dual-write problem**.
+
+The **outbox** pattern fixes it: write the business row **and** an
+`outbox` row in the **same transaction**. Either both commit or neither
+does. A separate *relay* reads the pending rows and publishes them to the
+broker, marking each one sent. The broker can be down for minutes — the
+events wait, durably, in the table.
+
+!!! info "Where this fits"
+    It complements the [`AsyncBrokerManager`](queue-tasks.md): the broker
+    *publishes*, the outbox *guarantees* the event exists to be published.
+    The relay takes any publish callable — so it works with FastStream, a
+    webhook, whatever.
+
+## 1. The outbox table
+
+`BaseOutboxModel` is abstract — the project creates the concrete table
+(just like `BaseUserModel`):
+
+```python
+from tempest_fastapi_sdk import BaseOutboxModel
+
+
+class OutboxModel(BaseOutboxModel):
+    """The service's pending-events table."""
+
+    __tablename__ = "outbox"
+```
+
+It ships `topic`, `payload` (JSON), `status`, `attempts`, `max_attempts`,
+`available_at`, `sent_at` and `last_error` — on top of `BaseModel`'s four
+canonical columns (`id` / `is_active` / `created_at` / `updated_at`).
+Generate the migration with the [`AlembicHelper`](database.md) like any
+other table.
+
+## 2. Write atomically
+
+In the service/repository, use `save_with_outbox` instead of `add`: it
+inserts the business model **and** the event in one transaction.
+
+```python
+from tempest_fastapi_sdk import BaseRepository
+
+from src.db.models import OrderModel, OutboxModel
+
+
+async def place_order(repo: BaseRepository[OrderModel], data: dict[str, object]) -> OrderModel:
+    """Create the order and queue the event in the same transaction."""
+    order = OrderModel(**data)
+    event = OutboxModel.new_event("orders.created", {"order": data})
+    return await repo.save_with_outbox(order, event)
+```
+
+If the `commit` fails (e.g. a unique constraint), **both** rows are rolled
+back — no orphan event is ever left behind.
+
+## 3. Drain and publish (the relay)
+
+`OutboxRelay` reads pending rows and calls your publish callable. It does
+not import any specific broker — you pass the function:
+
+```python
+import asyncio
+
+from tempest_fastapi_sdk import AsyncDatabaseManager, BaseOutboxModel, OutboxRelay
+
+from src.db.models import OutboxModel
+
+
+async def run_relay(db: AsyncDatabaseManager, broker: object) -> None:
+    """Publish pending events continuously."""
+
+    async def publish(event: BaseOutboxModel) -> None:
+        """Forward one event to the broker."""
+        await broker.publish(event.payload, event.topic)  # type: ignore[attr-defined]
+
+    relay: OutboxRelay = OutboxRelay(db, model=OutboxModel, publish=publish)
+    await relay.run(poll_interval=1.0)  # loops until the task is cancelled
+```
+
+Run the relay as a separate process/worker (or a task in the lifespan).
+Each published event becomes `status="sent"` with `sent_at` set.
+
+### Failures and retry
+
+If `publish` raises, the relay does **not** mark the event sent: it
+increments `attempts`, records the error in `last_error`, and reschedules
+the event with exponential backoff (`available_at` in the future). Once
+`attempts` reaches `max_attempts`, the row becomes `status="failed"` and
+stays in the table for manual inspection (never auto-retried again).
+
+!!! tip "Multiple workers"
+    On PostgreSQL/MySQL the relay locks the batch with `FOR UPDATE SKIP
+    LOCKED`, so you can run **several** relay workers without publishing
+    the same event twice. On SQLite (no row locks) it falls back to a
+    plain `SELECT` — use a single worker.
+
+### Drain once (tests / cron)
+
+For loop-free scenarios (a test, a cron job), call `drain_once()`, which
+returns how many events were published:
+
+```python
+published: int = await relay.drain_once()
+```
+
+## Recap
+
+- `BaseOutboxModel` → concrete `OutboxModel(__tablename__="outbox")`.
+- `repo.save_with_outbox(model, event)` writes business + event
+  **atomically**.
+- `OutboxRelay(db, model=..., publish=...).run()` publishes pending rows,
+  with retry/backoff and `sent` / `failed` marking.
+- `OutboxModel.new_event(topic, payload)` builds the event; `drain_once()`
+  drains one batch for tests/cron.

tempest_fastapi_sdk-0.45.0/docs/recipes/outbox.md

@@ -0,0 +1,120 @@
+# Outbox transacional (eventos confiáveis)
+
+Quando um handler **grava uma linha** e **publica um evento**, fazer as
+duas coisas como operações independentes é frágil: se o processo morre
+*depois* do commit mas *antes* do publish, o evento some; se morre depois
+do publish mas antes do commit, sobra um evento fantasma apontando pra uma
+linha que nunca existiu. Isso é o **dual-write problem**.
+
+O padrão **outbox** resolve: grave a linha de negócio **e** uma linha
+`outbox` na **mesma transação**. Ou as duas comitam, ou nenhuma. Um
+*relay* separado lê as linhas pendentes e publica no broker, marcando cada
+uma como enviada. O broker pode ficar minutos fora do ar — os eventos
+esperam, duráveis, na tabela.
+
+!!! info "Onde isso encaixa"
+    Complementa o [`AsyncBrokerManager`](queue-tasks.md): o broker
+    *publica*, o outbox *garante* que o evento existe pra ser publicado. O
+    relay usa qualquer callable de publish — então funciona com FastStream,
+    webhook, o que for.
+
+## 1. A tabela outbox
+
+`BaseOutboxModel` é abstrata — o projeto cria a tabela concreta (igual a
+`BaseUserModel`):
+
+```python
+from tempest_fastapi_sdk import BaseOutboxModel
+
+
+class OutboxModel(BaseOutboxModel):
+    """Tabela de eventos pendentes do serviço."""
+
+    __tablename__ = "outbox"
+```
+
+Ela já traz `topic`, `payload` (JSON), `status`, `attempts`,
+`max_attempts`, `available_at`, `sent_at` e `last_error` — além das quatro
+colunas canônicas do `BaseModel` (`id` / `is_active` / `created_at` /
+`updated_at`). Gere a migration com o [`AlembicHelper`](database.md) como
+qualquer outra tabela.
+
+## 2. Gravar de forma atômica
+
+No service/repository, use `save_with_outbox` em vez de `add`: ele insere o
+modelo de negócio **e** o evento numa transação só.
+
+```python
+from tempest_fastapi_sdk import BaseRepository
+
+from src.db.models import OrderModel, OutboxModel
+
+
+async def place_order(repo: BaseRepository[OrderModel], data: dict[str, object]) -> OrderModel:
+    """Cria o pedido e enfileira o evento na mesma transação."""
+    order = OrderModel(**data)
+    event = OutboxModel.new_event("orders.created", {"order": data})
+    return await repo.save_with_outbox(order, event)
+```
+
+Se o `commit` falhar (ex.: constraint única), **as duas** linhas são
+revertidas — nunca sobra evento órfão.
+
+## 3. Drenar e publicar (o relay)
+
+`OutboxRelay` lê as linhas pendentes e chama o seu callable de publish. Ele
+não importa nenhum broker específico — você passa a função:
+
+```python
+import asyncio
+
+from tempest_fastapi_sdk import AsyncDatabaseManager, BaseOutboxModel, OutboxRelay
+
+from src.db.models import OutboxModel
+
+
+async def run_relay(db: AsyncDatabaseManager, broker: object) -> None:
+    """Publica eventos pendentes continuamente."""
+
+    async def publish(event: BaseOutboxModel) -> None:
+        """Encaminha um evento pro broker."""
+        await broker.publish(event.payload, event.topic)  # type: ignore[attr-defined]
+
+    relay: OutboxRelay = OutboxRelay(db, model=OutboxModel, publish=publish)
+    await relay.run(poll_interval=1.0)  # loop até a task ser cancelada
+```
+
+Rode o relay como um processo/worker separado (ou uma task no lifespan).
+Cada evento publicado vira `status="sent"` com `sent_at` preenchido.
+
+### Falhas e retry
+
+Se o `publish` levanta exceção, o relay **não** marca como enviado: ele
+incrementa `attempts`, guarda o erro em `last_error` e reagenda o evento
+com backoff exponencial (`available_at` no futuro). Quando `attempts`
+chega em `max_attempts`, a linha vira `status="failed"` e fica na tabela
+pra inspeção manual (nunca mais é retentada automaticamente).
+
+!!! tip "Múltiplos workers"
+    Em PostgreSQL/MySQL o relay trava o lote com `FOR UPDATE SKIP LOCKED`,
+    então você pode rodar **vários** workers de relay sem publicar o mesmo
+    evento duas vezes. Em SQLite (sem lock de linha) ele cai pra um
+    `SELECT` simples — use um worker só.
+
+### Drenar uma vez (testes / cron)
+
+Pra cenários sem loop (um teste, um cron job), chame `drain_once()`, que
+devolve quantos eventos foram publicados:
+
+```python
+published: int = await relay.drain_once()
+```
+
+## Recap
+
+- `BaseOutboxModel` → tabela concreta `OutboxModel(__tablename__="outbox")`.
+- `repo.save_with_outbox(model, event)` grava negócio + evento **atômico**.
+- `OutboxRelay(db, model=..., publish=...).run()` publica os pendentes,
+  com retry/backoff e marcação `sent` / `failed`.
+- `OutboxModel.new_event(topic, payload)` monta o evento; `drain_once()`
+  drena um lote pra testes/cron.

{tempest_fastapi_sdk-0.43.0 → tempest_fastapi_sdk-0.45.0}/docs/reference.md

@@ -31,12 +31,16 @@ Gerada automaticamente a partir das docstrings do SDK via [`mkdocstrings`](https
 ::: tempest_fastapi_sdk.db.user_recovery_code_model.BaseUserRecoveryCodeModel
 ::: tempest_fastapi_sdk.db.user_recovery_code_model.make_user_recovery_code_model
 ::: tempest_fastapi_sdk.db.repository.BaseRepository
+::: tempest_fastapi_sdk.db.tenant.TenantScopedRepository
 ::: tempest_fastapi_sdk.db.mixins.SoftDeleteMixin
 ::: tempest_fastapi_sdk.db.mixins.AuditMixin
 ::: tempest_fastapi_sdk.db.mixins.MFAMixin
 ::: tempest_fastapi_sdk.db.connection.AsyncDatabaseManager
 ::: tempest_fastapi_sdk.db.migrations.AlembicHelper
 ::: tempest_fastapi_sdk.db.slow_query.SlowQueryLogger
+::: tempest_fastapi_sdk.db.outbox.BaseOutboxModel
+::: tempest_fastapi_sdk.db.outbox.OutboxRelay
+::: tempest_fastapi_sdk.db.outbox.OutboxStatus
 
 ---
 

{tempest_fastapi_sdk-0.43.0 → tempest_fastapi_sdk-0.45.0}/mkdocs.yml

@@ -86,12 +86,14 @@ plugins:
             Tutorial: Tutorial
             Receitas: Recipes
             Banco de dados: Database
+            Multi-tenant: Multi-tenant
             Camada HTTP: HTTP layer
             "HTTP client (saída)": "HTTP client (outbound)"
             Cache: Cache
             Tempo real: Real-time
             WebSocket router: WebSocket router
             Fila e Tarefas: Queue & Tasks
+            Outbox transacional: Transactional outbox
             Email transacional: Transactional email
             Web Push: Web Push
             Logging: Logging
@@ -199,12 +201,14 @@ nav:
   - Receitas:
       - recipes/index.md
       - Banco de dados: recipes/database.md
+      - Multi-tenant: recipes/multi-tenant.md
       - Camada HTTP: recipes/http.md
       - "HTTP client (saída)": recipes/http-client.md
       - Cache: recipes/cache.md
       - Tempo real: recipes/realtime.md
       - WebSocket router: recipes/websocket.md
       - Fila e Tarefas: recipes/queue-tasks.md
+      - Outbox transacional: recipes/outbox.md
       - Email transacional: recipes/email.md
       - Web Push: recipes/webpush.md
       - Logging: recipes/logging.md

{tempest_fastapi_sdk-0.43.0 → tempest_fastapi_sdk-0.45.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.43.0"
+version = "0.45.0"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.11"