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

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

@@ -5,6 +5,57 @@ 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.47.0] — 2026-06-11
+
+### Added
+
+- **`tempest db seed`** — runs a project seed callable
+  (default `src.db.seeds:seed`, dotted `module:callable`, sync or async,
+  taking one `AsyncSession`) inside a managed session: commit on
+  success, rollback on error. The SDK only wires the session lifecycle;
+  the callable owns what gets inserted. Prints the row count when the
+  callable returns an `int`.
+- **`tempest secrets rotate`** — generates fresh URL-safe secrets for
+  the keys a service signs/authenticates with (`JWT_SECRET` /
+  `TOKEN_SECRET` by default; override with `--keys`) and rewrites the
+  matching `.env` lines **in place** (existing keys replaced, missing
+  keys appended) after a `.env.bak` backup. `--print` writes nothing and
+  emits the values to stdout; `--length` sets the entropy; `--no-backup`
+  skips the backup.
+
+### Docs
+
+- CLI recipe (bilingual) gains **`db seed`** and **`secrets rotate`**
+  sections; README CLI section and recipes index updated.
+
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.45.0
+Version: 0.47.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]`, `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.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` |
@@ -3411,6 +3411,21 @@ tempest db upgrade <rev>                         # upgrade to a specific revisio
 tempest db downgrade                             # roll back one step
 tempest db current                               # print the applied revision
 tempest db history -v                            # revisions newest → oldest, verbose
+tempest db seed                                  # run src.db.seeds:seed in one session
+tempest db seed --seed src.db.fixtures:demo      # custom seed callable
+```
+
+`tempest db seed` runs a project seed callable (default `src.db.seeds:seed`, sync or async, taking one `AsyncSession`) inside a managed session — commit on success, rollback on error.
+
+#### Secrets — `tempest secrets`
+
+Generates and rotates application secrets (`JWT_SECRET` / `TOKEN_SECRET` by default), rewriting the matching `.env` lines in place after a `.env.bak` backup; `--print` writes nothing and emits the values to stdout.
+
+```bash
+tempest secrets rotate                                # rotate JWT_SECRET + TOKEN_SECRET in .env
+tempest secrets rotate --print                        # just print, write nothing
+tempest secrets rotate --keys JWT_SECRET,SESSION_SECRET --env .env.prod
+tempest secrets rotate --length 64 --no-backup
 ```
 
 #### Users — `tempest user`

{tempest_fastapi_sdk-0.45.0 → tempest_fastapi_sdk-0.47.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]`, `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.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` |
@@ -3309,6 +3309,21 @@ tempest db upgrade <rev>                         # upgrade to a specific revisio
 tempest db downgrade                             # roll back one step
 tempest db current                               # print the applied revision
 tempest db history -v                            # revisions newest → oldest, verbose
+tempest db seed                                  # run src.db.seeds:seed in one session
+tempest db seed --seed src.db.fixtures:demo      # custom seed callable
+```
+
+`tempest db seed` runs a project seed callable (default `src.db.seeds:seed`, sync or async, taking one `AsyncSession`) inside a managed session — commit on success, rollback on error.
+
+#### Secrets — `tempest secrets`
+
+Generates and rotates application secrets (`JWT_SECRET` / `TOKEN_SECRET` by default), rewriting the matching `.env` lines in place after a `.env.bak` backup; `--print` writes nothing and emits the values to stdout.
+
+```bash
+tempest secrets rotate                                # rotate JWT_SECRET + TOKEN_SECRET in .env
+tempest secrets rotate --print                        # just print, write nothing
+tempest secrets rotate --keys JWT_SECRET,SESSION_SECRET --env .env.prod
+tempest secrets rotate --length 64 --no-backup
 ```
 
 #### Users — `tempest user`

{tempest_fastapi_sdk-0.45.0 → tempest_fastapi_sdk-0.47.0}/docs/recipes/cli.en.md

@@ -140,8 +140,29 @@ tempest db downgrade <rev>                       # roll back to a specific revis
 tempest db current                               # print the applied revision
 tempest db history                               # revisions newest → oldest
 tempest db history -v                            # with full message body
+tempest db seed                                  # runs src.db.seeds:seed
+tempest db seed --seed src.db.fixtures:demo      # custom callable
 ```
 
+#### Seed the database — `tempest db seed`
+
+Runs a project seed callable inside a managed session (commit on success, rollback on error). The callable takes a positional `AsyncSession` and may be sync or async; what it inserts is up to you — the SDK only wires the session lifecycle. Defaults to importing `src.db.seeds:seed`.
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.db.models import CategoryModel
+
+
+async def seed(session: AsyncSession) -> int:
+    """Seed initial categories. Return the count (optional)."""
+    session.add_all([CategoryModel(name="Books"), CategoryModel(name="Games")])
+    await session.flush()
+    return 2
+```
+
+When the callable returns an `int`, the CLI prints the count: `Seeded via src.db.seeds:seed (2 rows).`
+
 ### Users — `tempest user`
 
 Seed and list users using the project's concrete ``UserModel`` (default ``src.db.models:UserModel``). Bootstraps the first admin without manual SQL.
@@ -180,6 +201,27 @@ tempest user list --admin                        # admins only
 
 ``DATABASE_URL`` resolves the same way as ``tempest db`` (env var > settings > alembic.ini).
 
+### Secrets — `tempest secrets`
+
+Generate and rotate application secrets (`JWT_SECRET` / `TOKEN_SECRET` by default), rewriting the matching `.env` lines **in place** — backing up the old file first — and leaving every other line untouched.
+
+```bash
+# Rotate JWT_SECRET and TOKEN_SECRET in .env (writes .env.bak)
+tempest secrets rotate
+
+# Just print the new values (writes nothing) — pipe into a secret manager
+tempest secrets rotate --print
+
+# Custom keys and file
+tempest secrets rotate --keys JWT_SECRET,SESSION_SECRET --env .env.prod
+
+# More entropy, no backup
+tempest secrets rotate --length 64 --no-backup
+```
+
+!!! warning
+    Rotating `JWT_SECRET` invalidates every token signed with the old value: users are logged out and pending reset/activation links stop working. Rotate during a maintenance window and restart the service to load the new values.
+
 ### Regenerating `docker-compose.yaml` in an existing project
 
 When you change installed extras (`uv add "tempest-fastapi-sdk[minio]"`) or the SDK bumps image versions, regenerate with:

{tempest_fastapi_sdk-0.45.0 → tempest_fastapi_sdk-0.47.0}/docs/recipes/cli.md

@@ -188,8 +188,29 @@ tempest db downgrade <rev>                       # rollback até rev específico
 tempest db current                               # imprime revision aplicado
 tempest db history                               # histórico de revisions
 tempest db history -v                            # com message body completo
+tempest db seed                                  # roda src.db.seeds:seed
+tempest db seed --seed src.db.fixtures:demo      # callable customizado
 ```
 
+#### Popular o banco — `tempest db seed`
+
+Roda um callable de seed do projeto dentro de uma sessão gerenciada (commit no sucesso, rollback no erro). O callable recebe uma `AsyncSession` posicional e pode ser sync ou async; o que ele insere é decisão sua — o SDK só cuida do ciclo de vida da sessão. Por padrão importa `src.db.seeds:seed`.
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.db.models import CategoryModel
+
+
+async def seed(session: AsyncSession) -> int:
+    """Popula categorias iniciais. Retorna a contagem (opcional)."""
+    session.add_all([CategoryModel(name="Livros"), CategoryModel(name="Games")])
+    await session.flush()
+    return 2
+```
+
+Quando o callable devolve um `int`, a CLI mostra a contagem: `Seeded via src.db.seeds:seed (2 rows).`
+
 ### Usuários — `tempest user`
 
 Insere/lista usuários direto no banco usando o `UserModel` concreto do projeto (default `src.db.models:UserModel`). Útil pra bootstrapear o primeiro admin sem rodar SQL manual.
@@ -228,6 +249,27 @@ tempest user list --admin                        # só admins
 
 Resolução do `DATABASE_URL` igual ao `tempest db` (env var > settings > alembic.ini).
 
+### Segredos — `tempest secrets`
+
+Gera e rotaciona os segredos da aplicação (`JWT_SECRET` / `TOKEN_SECRET` por padrão), reescrevendo as linhas correspondentes no `.env` **no lugar** — fazendo backup do arquivo antigo antes — e deixando as outras linhas intactas.
+
+```bash
+# Rotaciona JWT_SECRET e TOKEN_SECRET no .env (gera .env.bak)
+tempest secrets rotate
+
+# Só imprime os novos valores (não escreve nada) — pra pipar num secret manager
+tempest secrets rotate --print
+
+# Chaves e arquivo customizados
+tempest secrets rotate --keys JWT_SECRET,SESSION_SECRET --env .env.prod
+
+# Mais entropia, sem backup
+tempest secrets rotate --length 64 --no-backup
+```
+
+!!! warning
+    Rotacionar `JWT_SECRET` invalida todo token assinado com o valor antigo: usuários são deslogados e links de reset/ativação pendentes param de funcionar. Rotacione numa janela de manutenção e reinicie o serviço pra carregar os novos valores.
+
 #### Gates de qualidade
 
 Os comandos de lint chamam a ferramenta do projeto. Eles procuram o executável no `PATH` primeiro e, caso contrário, caem para `uv run <tool>` para que um virtualenv local do projeto funcione sem ativação manual.

tempest_fastapi_sdk-0.47.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.47.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.45.0 → tempest_fastapi_sdk-0.47.0}/docs/recipes/index.en.md

@@ -26,7 +26,8 @@ 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 |
-| **[CLI »](cli.md)** | `tempest new` / `lint` / `fix` / `format` / `type` / `test` / `check` |
+| **[Safe deploys »](deploy-safety.md)** | `AlembicHelper.safe_upgrade` (blocks DROPs), `GracefulShutdownMiddleware` |
+| **[CLI »](cli.md)** | `tempest new` / `db` (+ `seed`) / `user` / `secrets rotate` / `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.45.0 → tempest_fastapi_sdk-0.47.0}/docs/recipes/index.md

@@ -26,7 +26,8 @@ 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 |
-| **[CLI »](cli.md)** | `tempest new` / `lint` / `fix` / `format` / `type` / `test` / `check` |
+| **[Deploy seguro »](deploy-safety.md)** | `AlembicHelper.safe_upgrade` (barra DROPs), `GracefulShutdownMiddleware` |
+| **[CLI »](cli.md)** | `tempest new` / `db` (+ `seed`) / `user` / `secrets rotate` / `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.45.0 → tempest_fastapi_sdk-0.47.0}/docs/reference.md

@@ -41,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
 
 ---
 
@@ -96,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.45.0 → tempest_fastapi_sdk-0.47.0}/mkdocs.yml

@@ -107,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
@@ -223,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.45.0 → tempest_fastapi_sdk-0.47.0}/pyproject.toml

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

{tempest_fastapi_sdk-0.45.0 → tempest_fastapi_sdk-0.47.0}/tempest_fastapi_sdk/__init__.py

@@ -21,6 +21,7 @@ from tempest_fastapi_sdk.api import (
     CSRFMiddleware,
     GitHubOAuthClient,
     GoogleOAuthClient,
+    GracefulShutdownMiddleware,
     HardenedStaticFiles,
     HealthCheck,
     IdempotencyMiddleware,
@@ -104,6 +105,7 @@ from tempest_fastapi_sdk.db import (
     BaseUserModel,
     BaseUserRecoveryCodeModel,
     BaseUserTokenModel,
+    DestructiveMigrationError,
     MFAMixin,
     OutboxRelay,
     OutboxStatus,
@@ -248,7 +250,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.45.0"
+__version__: str = "0.47.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",
@@ -306,6 +308,7 @@ __all__: list[str] = [
     "CursorPaginationFilterSchema",
     "CursorPaginationSchema",
     "DatabaseSettings",
+    "DestructiveMigrationError",
     "DiskMetrics",
     "DownloadUtils",
     "EmailSettings",
@@ -318,6 +321,7 @@ __all__: list[str] = [
     "GPUMetrics",
     "GitHubOAuthClient",
     "GoogleOAuthClient",
+    "GracefulShutdownMiddleware",
     "HTTPClient",
     "HardenedStaticFiles",
     "HealthCheck",

{tempest_fastapi_sdk-0.45.0 → tempest_fastapi_sdk-0.47.0}/tempest_fastapi_sdk/api/__init__.py

@@ -27,6 +27,7 @@ from tempest_fastapi_sdk.api.middlewares import (
     BodySizeLimitMiddleware,
     CachedResponse,
     CSRFMiddleware,
+    GracefulShutdownMiddleware,
     IdempotencyMiddleware,
     IdempotencyStore,
     MemoryIdempotencyStore,
@@ -79,6 +80,7 @@ __all__: list[str] = [
     "CachedResponse",
     "GitHubOAuthClient",
     "GoogleOAuthClient",
+    "GracefulShutdownMiddleware",
     "HardenedStaticFiles",
     "HealthCheck",
     "IdempotencyMiddleware",

{tempest_fastapi_sdk-0.45.0 → tempest_fastapi_sdk-0.47.0}/tempest_fastapi_sdk/api/middlewares/__init__.py

@@ -9,6 +9,7 @@ from tempest_fastapi_sdk.api.middlewares.csrf import (
     generate_csrf_token,
     make_csrf_token_dependency,
 )
+from tempest_fastapi_sdk.api.middlewares.graceful import GracefulShutdownMiddleware
 from tempest_fastapi_sdk.api.middlewares.idempotency import (
     IDEMPOTENCY_HEADER,
     CachedResponse,
@@ -27,6 +28,7 @@ __all__: list[str] = [
     "BodySizeLimitMiddleware",
     "CSRFMiddleware",
     "CachedResponse",
+    "GracefulShutdownMiddleware",
     "IdempotencyMiddleware",
     "IdempotencyStore",
     "MemoryIdempotencyStore",