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

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

@@ -5,6 +5,34 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.45.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]`, `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` |

{tempest_fastapi_sdk-0.45.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]`, `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` |

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

@@ -26,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.45.0 → tempest_fastapi_sdk-0.46.0}/docs/recipes/index.md

@@ -26,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.45.0 → tempest_fastapi_sdk-0.46.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.46.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.46.0}/pyproject.toml

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

{tempest_fastapi_sdk-0.45.0 → tempest_fastapi_sdk-0.46.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.46.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.46.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.46.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",

tempest_fastapi_sdk-0.46.0/tempest_fastapi_sdk/api/middlewares/graceful.py

@@ -0,0 +1,225 @@
+"""Graceful-shutdown helper: drain in-flight requests before exit.
+
+When an orchestrator (Kubernetes, a process manager) wants a replica
+gone, it sends ``SIGTERM`` and, after a grace period, ``SIGKILL``. If a
+request is still mid-flight when the worker dies, that request is
+severed — a 502 the client sees as a flaky API.
+
+``GracefulShutdownMiddleware`` smooths the window:
+
+1. Once **draining**, new requests get ``503 Service Unavailable`` with a
+   ``Retry-After`` header, so a load balancer in front quickly stops
+   routing here and the client retries elsewhere.
+2. In-flight requests are **counted**; :meth:`wait_drained` blocks until
+   they finish (or a timeout), so shutdown can wait them out instead of
+   severing them.
+
+You hold the instance and wire its :meth:`dispatch` into the app, then
+drive it from the lifespan shutdown (which uvicorn runs on ``SIGTERM``,
+and uvicorn owns the signal handling):
+
+    from contextlib import asynccontextmanager
+
+    from fastapi import FastAPI
+    from starlette.middleware.base import BaseHTTPMiddleware
+
+    from tempest_fastapi_sdk.api.middlewares.graceful import (
+        GracefulShutdownMiddleware,
+    )
+
+    shutdown = GracefulShutdownMiddleware(drain_timeout=25.0)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        yield
+        shutdown.begin_drain()
+        await shutdown.wait_drained()
+
+    app = 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 "Signal handling belongs to your server"
+    uvicorn already installs ``SIGTERM`` handlers and triggers the
+    lifespan shutdown — drive draining from there. The opt-in
+    :meth:`install_signal_handlers` is only for servers that do **not**
+    manage signals themselves; it chains the previous handler via
+    :func:`signal.signal` and is a no-op off the main thread.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import signal
+from typing import TYPE_CHECKING, Any
+
+from starlette.responses import JSONResponse
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Sequence
+
+    from starlette.requests import Request
+    from starlette.responses import Response
+
+logger = logging.getLogger("tempest_fastapi_sdk.api.graceful")
+
+
+class GracefulShutdownMiddleware:
+    """Track in-flight requests and reject new ones with 503 while draining.
+
+    Wire :meth:`dispatch` via
+    ``app.add_middleware(BaseHTTPMiddleware, dispatch=shutdown.dispatch)``
+    and call :meth:`begin_drain` / :meth:`wait_drained` from the
+    lifespan shutdown.
+
+    Attributes:
+        drain_timeout (float): Seconds :meth:`wait_drained` waits for
+            in-flight requests before giving up.
+        retry_after (int): ``Retry-After`` header value on the 503s
+            served while draining.
+    """
+
+    def __init__(
+        self,
+        *,
+        drain_timeout: float = 30.0,
+        retry_after: int = 5,
+        exempt_paths: Sequence[str] = (),
+    ) -> None:
+        """Initialize the helper.
+
+        Args:
+            drain_timeout (float): Max seconds to wait for in-flight
+                requests in :meth:`wait_drained`. Defaults to ``30.0``.
+            retry_after (int): ``Retry-After`` seconds advertised on the
+                503 served while draining. Defaults to ``5``.
+            exempt_paths (Sequence[str]): Paths that keep being served
+                during drain. Usually unnecessary — letting health
+                endpoints return 503 is what makes a load balancer
+                deregister the instance. Defaults to none.
+        """
+        self.drain_timeout: float = drain_timeout
+        self.retry_after: int = retry_after
+        self._exempt: frozenset[str] = frozenset(exempt_paths)
+        self._in_flight: int = 0
+        self._draining: bool = False
+        self._idle: asyncio.Event = asyncio.Event()
+        self._idle.set()
+
+    @property
+    def in_flight(self) -> int:
+        """Return the number of requests currently being served.
+
+        Returns:
+            int: The in-flight request count.
+        """
+        return self._in_flight
+
+    @property
+    def is_draining(self) -> bool:
+        """Return whether draining has begun.
+
+        Returns:
+            bool: ``True`` once :meth:`begin_drain` (or a signal) fired.
+        """
+        return self._draining
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: Callable[[Request], Awaitable[Response]],
+    ) -> Response:
+        """Starlette ``BaseHTTPMiddleware`` dispatch hook.
+
+        Serves ``503`` for new non-exempt requests once draining;
+        otherwise counts the request as in-flight while it runs.
+
+        Args:
+            request (Request): The incoming request.
+            call_next (Callable[[Request], Awaitable[Response]]): The
+                downstream handler.
+
+        Returns:
+            Response: The downstream response, or a ``503`` while
+            draining.
+        """
+        if self._draining and request.url.path not in self._exempt:
+            return JSONResponse(
+                {"detail": "Server is shutting down."},
+                status_code=503,
+                headers={
+                    "Retry-After": str(self.retry_after),
+                    "Connection": "close",
+                },
+            )
+        self._in_flight += 1
+        self._idle.clear()
+        try:
+            return await call_next(request)
+        finally:
+            self._in_flight -= 1
+            if self._in_flight == 0:
+                self._idle.set()
+
+    def begin_drain(self) -> None:
+        """Flip into draining mode (idempotent).
+
+        New non-exempt requests get ``503`` from now on. Call from the
+        lifespan shutdown hook.
+        """
+        if not self._draining:
+            self._draining = True
+            logger.info("graceful shutdown: draining (in-flight=%d)", self._in_flight)
+
+    async def wait_drained(self) -> bool:
+        """Wait until in-flight requests finish or the timeout elapses.
+
+        Returns:
+            bool: ``True`` if everything drained in time, ``False`` if
+            :attr:`drain_timeout` elapsed with requests still running.
+        """
+        if self._in_flight == 0:
+            return True
+        try:
+            await asyncio.wait_for(self._idle.wait(), timeout=self.drain_timeout)
+            return True
+        except TimeoutError:
+            logger.warning(
+                "graceful shutdown: drain timed out with %d request(s) in flight",
+                self._in_flight,
+            )
+            return False
+
+    def install_signal_handlers(
+        self, signals: Sequence[int] = (signal.SIGTERM, signal.SIGINT)
+    ) -> None:
+        """Chain a drain trigger onto the given signals via ``signal.signal``.
+
+        Only for servers that do **not** manage signals themselves —
+        uvicorn does, so prefer the lifespan hook. Best-effort: a no-op
+        when called off the main thread.
+
+        Args:
+            signals (Sequence[int]): Signals to hook. Defaults to
+                ``SIGTERM`` and ``SIGINT``.
+        """
+        for sig in signals:
+            previous = signal.getsignal(sig)
+
+            def _handler(signum: int, frame: Any, _previous: Any = previous) -> None:
+                self.begin_drain()
+                if callable(_previous):
+                    _previous(signum, frame)
+
+            try:
+                signal.signal(sig, _handler)
+            except (ValueError, OSError):  # pragma: no cover - non-main thread
+                logger.debug("could not install handler for signal %s", sig)
+
+
+__all__: list[str] = [
+    "GracefulShutdownMiddleware",
+]