tempest-fastapi-sdk 0.44.0__tar.gz → 0.46.0__tar.gz

{tempest_fastapi_sdk-0.44.0 → tempest_fastapi_sdk-0.46.0}/CHANGELOG.md

@@ -5,6 +5,56 @@ 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.46.0] — 2026-06-11
+
+### Added
+
+- **`AlembicHelper.safe_upgrade(revision="head", *, force=False)`** —
+  runs the upgrade only after scanning each pending migration's
+  `upgrade()` for data-destroying calls (`op.drop_table` /
+  `op.drop_column` / `op.drop_constraint` and `batch_op` variants). When
+  any are found it raises **`DestructiveMigrationError`** (carrying the
+  offending `(revision, operation)` pairs) and leaves the database
+  untouched; `force=True` logs and proceeds. Source-based scanning is
+  dialect-agnostic (no false positives on SQLite batch rebuilds) and
+  ignores drops in `downgrade()`. `pending_destructive_ops()` exposes the
+  scan without running anything (CI-friendly).
+- **`GracefulShutdownMiddleware`** — tracks in-flight requests and, once
+  draining, replies `503` + `Retry-After` to new requests so a load
+  balancer deregisters the instance. `begin_drain()` / `wait_drained()`
+  (bounded by `drain_timeout`) are driven from the lifespan shutdown
+  (uvicorn owns `SIGTERM`); an opt-in `install_signal_handlers()` chains
+  the previous handler for servers that manage signals themselves. Wired
+  via `app.add_middleware(BaseHTTPMiddleware, dispatch=shutdown.dispatch)`.
+
+### Docs
+
+- New bilingual recipe **Deploy seguro / Safe deploys** covering
+  `safe_upgrade` and `GracefulShutdownMiddleware`, added to the nav, the
+  recipes index, and the API reference.
+
+## [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

{tempest_fastapi_sdk-0.44.0 → tempest_fastapi_sdk-0.46.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.44.0
+Version: 0.46.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,10 +238,10 @@ 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`, `BaseOutboxModel`, `OutboxRelay`, `OutboxStatus`, `BaseRepository.save_with_outbox` |
+| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `TenantScopedRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper` (+ `safe_upgrade`), `DestructiveMigrationError`, `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.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`, `GracefulShutdownMiddleware`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |
 | `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`) — signup/activate/login/reset + TOTP 2FA out of the box |
 | `tempest_fastapi_sdk.controllers` | `BaseController` |
 | `tempest_fastapi_sdk.services` | `BaseService` |

{tempest_fastapi_sdk-0.44.0 → tempest_fastapi_sdk-0.46.0}/README.md

@@ -136,10 +136,10 @@ 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`, `BaseOutboxModel`, `OutboxRelay`, `OutboxStatus`, `BaseRepository.save_with_outbox` |
+| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `TenantScopedRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper` (+ `safe_upgrade`), `DestructiveMigrationError`, `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.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`, `GracefulShutdownMiddleware`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |
 | `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`) — signup/activate/login/reset + TOTP 2FA out of the box |
 | `tempest_fastapi_sdk.controllers` | `BaseController` |
 | `tempest_fastapi_sdk.services` | `BaseService` |

tempest_fastapi_sdk-0.46.0/docs/recipes/deploy-safety.en.md

@@ -0,0 +1,111 @@
+# Safe deploys (migrations + graceful shutdown)
+
+Two classic deploy risks: a migration that **deletes data** by accident,
+and a rollout that **severs in-flight requests** when the old pod dies.
+This recipe covers the two defenses the SDK ships.
+
+## Safe migrations: `safe_upgrade`
+
+`AlembicHelper.safe_upgrade()` runs the upgrade **only if** no pending
+migration is destructive. It scans each pending revision's `def upgrade()`
+for data-deleting calls — `op.drop_table`, `op.drop_column`,
+`op.drop_constraint` (and `batch_op` variants) — and, if it finds one,
+raises `DestructiveMigrationError` **without touching the database**.
+
+```python
+from tempest_fastapi_sdk import AlembicHelper, DestructiveMigrationError
+
+
+def deploy_migrations() -> None:
+    """Apply migrations on deploy, blocking accidental DROPs."""
+    helper: AlembicHelper = AlembicHelper(db_url="postgresql+asyncpg://...")
+    try:
+        helper.safe_upgrade("head")
+    except DestructiveMigrationError as exc:
+        # CI/CD fails here — someone must review and unblock with force.
+        for revision, op in exc.offences:
+            print(f"blocked: {revision} → {op}")
+        raise
+```
+
+The scan looks at the migration **code**, not the generated SQL — so it
+never false-positives on the table rebuild SQLite does in batch mode. A
+`drop_*` in `downgrade()` (the normal, expected path) is ignored.
+
+### Allowing an intentional DROP
+
+When the DROP is intentional (you took a backup, you reviewed it), pass
+`force=True` — the destructive operations are logged and the upgrade runs:
+
+```python
+from tempest_fastapi_sdk import AlembicHelper
+
+helper: AlembicHelper = AlembicHelper(db_url="postgresql+asyncpg://...")
+helper.safe_upgrade("head", force=True)  # I know what I'm doing
+```
+
+!!! tip "Inspect only"
+    `helper.pending_destructive_ops("head")` returns the list of
+    `(revision, operation)` without running anything — handy for a CI step
+    that only reports.
+
+!!! danger "force=True deletes data"
+    `DROP COLUMN` / `DROP TABLE` are irreversible. Only use `force=True`
+    after a backup and human review.
+
+## Graceful shutdown: drain in-flight requests
+
+On a rollout the orchestrator sends `SIGTERM` and, after a grace period,
+`SIGKILL`. If a request is still running when the worker dies, it's
+severed — an intermittent 502. `GracefulShutdownMiddleware`:
+
+1. Once **draining**, replies `503` + `Retry-After` to new requests, so
+   the load balancer stops routing to this pod.
+2. **Counts** in-flight requests; `wait_drained()` waits for them to
+   finish (with a timeout) before the process exits.
+
+You hold the instance and drive draining from the `lifespan` (uvicorn runs
+the lifespan shutdown on `SIGTERM` — and it owns the signal handling):
+
+```python
+from contextlib import asynccontextmanager
+from collections.abc import AsyncIterator
+
+from fastapi import FastAPI
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from tempest_fastapi_sdk import GracefulShutdownMiddleware
+
+shutdown: GracefulShutdownMiddleware = GracefulShutdownMiddleware(drain_timeout=25.0)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Drain in-flight requests on shutdown."""
+    yield
+    shutdown.begin_drain()
+    await shutdown.wait_drained()
+
+
+app: FastAPI = FastAPI(lifespan=lifespan)
+app.add_middleware(BaseHTTPMiddleware, dispatch=shutdown.dispatch)
+```
+
+Set the orchestrator's grace period a little **above** `drain_timeout`,
+and uvicorn's `--timeout-graceful-shutdown` to match.
+
+!!! warning "The signal belongs to your server"
+    uvicorn already installs `SIGTERM` handlers and triggers the lifespan
+    shutdown — drive draining from there. The opt-in
+    `install_signal_handlers()` is only for servers that do **not** manage
+    signals themselves; it chains the previous handler and is a no-op off
+    the main thread.
+
+## Recap
+
+- `AlembicHelper.safe_upgrade()` refuses destructive migrations
+  (`DestructiveMigrationError`); `force=True` allows them;
+  `pending_destructive_ops()` only inspects.
+- `GracefulShutdownMiddleware` replies `503` while draining and
+  `wait_drained()` waits for in-flight requests — driven from the
+  `lifespan`.

tempest_fastapi_sdk-0.46.0/docs/recipes/deploy-safety.md

@@ -0,0 +1,110 @@
+# Deploy seguro (migrações + graceful shutdown)
+
+Dois riscos clássicos de deploy: uma migration que **apaga dados** sem
+querer, e um rollout que **corta requests no meio** quando o pod velho
+morre. Esta receita cobre as duas defesas que o SDK traz.
+
+## Migrações seguras: `safe_upgrade`
+
+`AlembicHelper.safe_upgrade()` roda o upgrade **só se** nenhuma migration
+pendente for destrutiva. Ele varre o `def upgrade()` de cada revision
+pendente atrás de chamadas que apagam dados — `op.drop_table`,
+`op.drop_column`, `op.drop_constraint` (e variantes `batch_op`) — e, se
+achar alguma, levanta `DestructiveMigrationError` **sem tocar no banco**.
+
+```python
+from tempest_fastapi_sdk import AlembicHelper, DestructiveMigrationError
+
+
+def deploy_migrations() -> None:
+    """Aplica migrations no deploy, barrando DROPs acidentais."""
+    helper: AlembicHelper = AlembicHelper(db_url="postgresql+asyncpg://...")
+    try:
+        helper.safe_upgrade("head")
+    except DestructiveMigrationError as exc:
+        # CI/CD falha aqui — alguém precisa revisar e liberar com force.
+        for revision, op in exc.offences:
+            print(f"bloqueado: {revision} → {op}")
+        raise
+```
+
+A varredura olha o **código** da migration, não o SQL gerado — então não
+dá falso-positivo no rebuild de tabela que o SQLite faz em batch mode. Um
+`drop_*` no `downgrade()` (o caminho normal e esperado) é ignorado.
+
+### Liberando um DROP intencional
+
+Quando o DROP é proposital (você já fez backup, já validou), passe
+`force=True` — as operações destrutivas são logadas e o upgrade roda:
+
+```python
+from tempest_fastapi_sdk import AlembicHelper
+
+helper: AlembicHelper = AlembicHelper(db_url="postgresql+asyncpg://...")
+helper.safe_upgrade("head", force=True)  # eu sei o que estou fazendo
+```
+
+!!! tip "Só inspecionar"
+    `helper.pending_destructive_ops("head")` devolve a lista de
+    `(revision, operação)` sem rodar nada — útil pra um passo de CI que só
+    reporta.
+
+!!! danger "force=True apaga dados"
+    `DROP COLUMN` / `DROP TABLE` são irreversíveis. Só use `force=True`
+    depois de backup e revisão humana.
+
+## Graceful shutdown: drenar requests em voo
+
+No rollout, o orquestrador manda `SIGTERM` e, depois de um tempo,
+`SIGKILL`. Se uma request ainda estiver rodando quando o worker morre, ela
+é cortada — vira um 502 intermitente. `GracefulShutdownMiddleware`:
+
+1. Ao entrar em **drenagem**, responde `503` + `Retry-After` pra requests
+   novas, então o load balancer para de rotear pra esse pod.
+2. **Conta** as requests em voo; `wait_drained()` espera elas terminarem
+   (com timeout) antes do processo sair.
+
+Você segura a instância e dirige a drenagem pelo `lifespan` (o uvicorn
+roda o shutdown do lifespan no `SIGTERM` — e é ele quem cuida do sinal):
+
+```python
+from contextlib import asynccontextmanager
+from collections.abc import AsyncIterator
+
+from fastapi import FastAPI
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from tempest_fastapi_sdk import GracefulShutdownMiddleware
+
+shutdown: GracefulShutdownMiddleware = GracefulShutdownMiddleware(drain_timeout=25.0)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Drena as requests em voo no shutdown."""
+    yield
+    shutdown.begin_drain()
+    await shutdown.wait_drained()
+
+
+app: FastAPI = FastAPI(lifespan=lifespan)
+app.add_middleware(BaseHTTPMiddleware, dispatch=shutdown.dispatch)
+```
+
+Configure o grace period do orquestrador um pouco **acima** do
+`drain_timeout`, e o `--timeout-graceful-shutdown` do uvicorn pra casar.
+
+!!! warning "O sinal é do seu servidor"
+    O uvicorn já instala handlers de `SIGTERM` e dispara o shutdown do
+    lifespan — dirija a drenagem por lá. O método opt-in
+    `install_signal_handlers()` só serve pra servidores que **não**
+    gerenciam sinais sozinhos; ele encadeia o handler anterior e é no-op
+    fora da thread principal.
+
+## Recap
+
+- `AlembicHelper.safe_upgrade()` recusa migrations destrutivas
+  (`DestructiveMigrationError`); `force=True` libera; `pending_destructive_ops()`
+  só inspeciona.
+- `GracefulShutdownMiddleware` responde `503` durante a drenagem e
+  `wait_drained()` espera as requests em voo — dirigido pelo `lifespan`.

{tempest_fastapi_sdk-0.44.0 → tempest_fastapi_sdk-0.46.0}/docs/recipes/index.en.md

@@ -10,6 +10,7 @@ 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 |
@@ -25,6 +26,7 @@ Bite-sized "I want to wire X" walkthroughs. Each page starts with **what problem
 | **[Downloads »](downloads.md)** | `DownloadUtils` — `file_response`, `stream`, `build_content_disposition`, path-traversal safe |
 | **[Utilities »](utilities.md)** | `utcnow`/`to_utc`, `modify_dict`, `get_client_ip`, opaque tokens (`generate_opaque_token`) |
 | **[Testing »](testing.md)** | `test_session`, `test_database`, in-memory SQLite, pytest fixtures |
+| **[Safe deploys »](deploy-safety.md)** | `AlembicHelper.safe_upgrade` (blocks DROPs), `GracefulShutdownMiddleware` |
 | **[CLI »](cli.md)** | `tempest new` / `lint` / `fix` / `format` / `type` / `test` / `check` |
 | **[Security »](security.md)** | `AttemptThrottle`, opaque-token helpers, `HardenedStaticFiles`, security headers |
 | **[Brazilian helpers »](br-helpers.md)** | CPF / CNPJ / CEP / phone validation + normalization |

{tempest_fastapi_sdk-0.44.0 → tempest_fastapi_sdk-0.46.0}/docs/recipes/index.md

@@ -10,6 +10,7 @@ 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` |
@@ -25,6 +26,7 @@ Passo a passo curtos no estilo "quero conectar X". Cada página começa com **qu
 | **[Downloads »](downloads.md)** | `DownloadUtils` — `file_response`, `stream`, `build_content_disposition`, anti path-traversal |
 | **[Utilitários »](utilities.md)** | `utcnow`/`to_utc`, `modify_dict`, `get_client_ip`, tokens opacos (`generate_opaque_token`) |
 | **[Testes »](testing.md)** | `test_session`, `test_database`, SQLite em memória, fixtures pytest |
+| **[Deploy seguro »](deploy-safety.md)** | `AlembicHelper.safe_upgrade` (barra DROPs), `GracefulShutdownMiddleware` |
 | **[CLI »](cli.md)** | `tempest new` / `lint` / `fix` / `format` / `type` / `test` / `check` |
 | **[Segurança »](security.md)** | `AttemptThrottle`, helpers de token opaco, `HardenedStaticFiles`, headers de segurança |
 | **[Helpers brasileiros »](br-helpers.md)** | validação + normalização de CPF / CNPJ / CEP / telefone |

tempest_fastapi_sdk-0.46.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.46.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.44.0 → tempest_fastapi_sdk-0.46.0}/docs/reference.md

@@ -31,6 +31,7 @@ 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
@@ -40,6 +41,7 @@ Gerada automaticamente a partir das docstrings do SDK via [`mkdocstrings`](https
 ::: tempest_fastapi_sdk.db.outbox.BaseOutboxModel
 ::: tempest_fastapi_sdk.db.outbox.OutboxRelay
 ::: tempest_fastapi_sdk.db.outbox.OutboxStatus
+::: tempest_fastapi_sdk.db.migrations.DestructiveMigrationError
 
 ---
 
@@ -95,6 +97,7 @@ Gerada automaticamente a partir das docstrings do SDK via [`mkdocstrings`](https
 ::: tempest_fastapi_sdk.api.middlewares.idempotency.MemoryIdempotencyStore
 ::: tempest_fastapi_sdk.api.middlewares.idempotency.RedisIdempotencyStore
 ::: tempest_fastapi_sdk.api.middlewares.body_size.BodySizeLimitMiddleware
+::: tempest_fastapi_sdk.api.middlewares.graceful.GracefulShutdownMiddleware
 ::: tempest_fastapi_sdk.api.middlewares.csrf.CSRFMiddleware
 ::: tempest_fastapi_sdk.api.middlewares.csrf.make_csrf_token_dependency
 ::: tempest_fastapi_sdk.api.middlewares.csrf.generate_csrf_token

{tempest_fastapi_sdk-0.44.0 → tempest_fastapi_sdk-0.46.0}/mkdocs.yml

@@ -86,6 +86,7 @@ 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
@@ -106,6 +107,7 @@ plugins:
             Métricas: Metrics
             Painel admin: Admin site
             Testes: Testing
+            "Deploy seguro (migrations + shutdown)": "Safe deploys (migrations + shutdown)"
             CLI: CLI
             Segurança: Security
             Utilitários: Utilities
@@ -200,6 +202,7 @@ 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
@@ -221,6 +224,7 @@ nav:
       - Métricas: recipes/metrics.md
       - Painel admin: recipes/admin.md
       - Testes: recipes/testing.md
+      - "Deploy seguro (migrations + shutdown)": recipes/deploy-safety.md
       - CLI: recipes/cli.md
       - Segurança: recipes/security.md
       - Utilitários: recipes/utilities.md

{tempest_fastapi_sdk-0.44.0 → tempest_fastapi_sdk-0.46.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.44.0"
+version = "0.46.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"