tempest-fastapi-sdk 0.53.0__tar.gz → 0.55.0__tar.gz

{tempest_fastapi_sdk-0.53.0 → tempest_fastapi_sdk-0.55.0}/CHANGELOG.md

@@ -5,6 +5,62 @@ 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.55.0] — 2026-06-14
+
+### Added
+
+- **Localized error envelopes (i18n) for `AppException`** — the error
+  `detail` can now be resolved per request locale instead of being
+  English-only, without callers hand-translating each `raise`.
+    - **`MessageCatalog`** — maps `(locale, key) -> template`, with
+      case-insensitive locale matching and primary-subtag fallback
+      (a catalog holding `pt-BR` answers `pt`, and vice versa).
+      `resolve()` interpolates `message_params` via `str.format`
+      (a missing param returns the template instead of raising);
+      `negotiate()` picks the best locale from an `Accept-Language`
+      header; `merge()` overlays domain codes / new locales onto a
+      base catalog without mutating it.
+    - **`default_message_catalog()`** — PT-BR (default) + EN-US strings
+      for every built-in exception code (`NOT_FOUND`, `CONFLICT`,
+      `UNAUTHORIZED`, `FORBIDDEN`, `VALIDATION_ERROR`,
+      `TOO_MANY_REQUESTS`, `INVALID_TOKEN`, `TOKEN_EXPIRED`,
+      `FILE_TOO_LARGE`, `INVALID_FILE_TYPE`, `INTERNAL_SERVER_ERROR`).
+    - **`parse_accept_language()`** + **`DEFAULT_LOCALE`** (`"pt-BR"`).
+    - **`AppException` gains `message_key` / `message_params`** — the
+      catalog key (defaults to the exception `code`) and template
+      values. **`register_exception_handlers(app, catalog=...,
+      default_locale=...)`** and `make_app_exception_handler` accept the
+      catalog and localize `detail` from the negotiated locale.
+    - Fully backward compatible: with no `catalog` the literal
+      `message` is used exactly as before; a missing translation falls
+      back to the exception's own `detail`. All new symbols are
+      exported at the package top level.
+
+## [0.54.0] — 2026-06-14
+
+### Added
+
+- **Per-principal & distributed rate limiting** — `RateLimitMiddleware`
+  gains a pluggable store and ready-made key extractors, so limits can
+  be per user / tenant / API key and shared across replicas.
+    - **Pluggable store** — `RateLimitStore` protocol with
+      `MemoryRateLimitStore` (default, in-process) and
+      `RedisRateLimitStore` (distributed). The Redis store uses an
+      atomic Lua sliding-window log over a sorted set — no race between
+      count and add — and `fail_open=True` (default) allows the request
+      on a transient Redis error. `RateLimitResult` carries the
+      `allowed` / `remaining` / `retry_after` decision.
+    - **Key extractors** — `key_by_ip`, `key_by_jwt_subject`
+      (per-user via the `sub` claim), `key_by_jwt_claim` (per arbitrary
+      claim, e.g. `tenant_id`) and `key_by_header` (e.g. an API key).
+      Because the middleware runs before FastAPI dependencies, the
+      `key_by_jwt_*` factories decode the bearer from the raw request
+      (`decode_or_none`) and fall back to the client IP for anonymous
+      traffic.
+    - Fully backward compatible: the default behavior (in-process,
+      per-IP) is unchanged; `store=` and the `key_by_*` factories are
+      opt-in. All new symbols are exported at the package top level.
+
 ## [0.53.0] — 2026-06-13
 
 ### Added

{tempest_fastapi_sdk-0.53.0 → tempest_fastapi_sdk-0.55.0}/CLAUDE.md

@@ -99,63 +99,62 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
 - **Cache** — Redis manager + `@cached`.
 - **Queue / tasks** — FastStream + TaskIQ wrappers.
 - **BR validators** — CPF/CNPJ/CEP/phone.
+- **BR localities** — `UF` (StrEnum, 27 siglas) + `Region`
+  (5 macro-regiões IBGE), `StateBR`/`CityBR` schemas, offline
+  dataset of 27 states + 5606 municipalities (IBGE-derived,
+  DF as 36 administrative regions), `list_states`/`get_state`/
+  `cities_by_uf`/`states_by_region`, `is_valid_uf`/`normalize_uf`,
+  `is_valid_city`/`normalize_city` (accent/case-insensitive),
+  `UFField`/`CityNameField`.
 - **Admin panel** — Jinja + HTMX (`AdminSite`, `AdminModel`,
   `make_admin_router`).
 - **CLI** — `tempest new` (scaffolds layered service +
   docker-compose), `tempest generate --docker` (regen compose),
-  `tempest db init/revision/upgrade/downgrade/current/history`,
-  `tempest user create [--admin] / list`, plus quality gates
-  (`lint`, `fix`, `format`, `fmt-check`, `type`, `test`,
-  `check`).
-
-The list below is the deliberate next-version plan. Each tier is
-ordered by impact for a typical production FastAPI service.
-
-### Tier S — every serious API needs these
-
-| Feature | Why it matters |
-|---------|----------------|
-| **`IdempotencyMiddleware`** + `idempotency_keys` table | Required header for POST on payment/webhook/retry paths. Without it, retried requests duplicate rows. Stripe/AWS pattern. |
-| **`UploadUtils` pluggable backends** (`LocalBackend`, `S3Backend(bucket, region)`, `GCSBackend`) | Today only writes to local disk — unusable in any multi-replica deploy. |
-| **OpenTelemetry tracing** — `setup_tracing(app, otlp_endpoint=…)` | `RequestIDMiddleware` correlates logs but doesn't give cross-service spans. Needs auto-instrumentation for FastAPI/SQLAlchemy/httpx. |
-| **`HTTPClient` (typed httpx wrapper)** | Retry + backoff, `X-Request-ID` propagation, circuit breaker, default timeouts. Today every service rolls raw httpx. |
-| **Outbox pattern** — `BaseRepository.save_with_outbox(model, event)` | Persists event in the same tx as the INSERT; `AsyncBrokerManager` drains it. Without this, events are lost when the broker fails after commit. |
-
-### Tier A — common in SaaS backends
-
-| Feature | Why it matters |
-|---------|----------------|
-| **`EmailUtils.render_template(path, ctx)`** with Jinja2 | Welcome / reset / verify emails — today SMTP only accepts raw strings. |
-| **OAuth2 / OIDC providers** — `GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider(discovery_url)` | `JWTUtils` only signs our own tokens; we have no social-login glue. |
-| **`CSRFMiddleware` + `BodySizeLimitMiddleware`** | Admin module currently has no CSRF token; no body limit means DoS via giant upload before `UploadUtils.max_size_bytes` is checked. |
-| **`BaseRepository.bulk_create / bulk_update / bulk_upsert`** | Row-by-row inserts are the #1 N+1 bottleneck. SQLAlchemy 2.0 has `insert().values([...])` + `on_conflict_do_update`. |
-| **Prometheus `/metrics` endpoint** | `MetricsUtils` already collects the data — needs the Prometheus exposition format for oncall scrape. |
-| **Admin CSRF token + `make_csrf_token_dependency`** | Admin accepts POST without a token today. |
-
-### Tier B — when the service grows
-
-- **2FA / TOTP** (`pyotp` wrapper + optional `AdminModel.totp_secret`)
-- **Multi-tenant scope** — `TenantScopedRepository(tenant_id)` auto-injects `WHERE tenant_id = …` on every query
-- **`SlowQueryLogger`** — SQLAlchemy event logging queries > N ms with EXPLAIN
-- **`AlembicHelper.safe_upgrade()`** — block destructive migrations (DROP COLUMN/TABLE) without `--force`
-- **Graceful shutdown** — drain in-flight requests on SIGTERM before uvicorn dies
-- **`make_websocket_router`** — bearer auth, heartbeat, broadcast (today SSE only)
-- **CLI:** `tempest db seed`, `tempest user create-admin`, `tempest secrets rotate`
-
-### Planned release cadence
-
-- **v0.23.0 — observability + retries** (high return, low cost)
-    - `setup_tracing(app, otlp_endpoint=…)` with OTel auto-instrumentation
-    - `HTTPClient` (typed httpx wrapper)
-    - Prometheus `/metrics` endpoint
-- **v0.24.0 — cloud uploads + idempotency** (unblocks multi-replica deploys)
-    - `UploadUtils` with pluggable backends + `S3Backend`
-    - `IdempotencyMiddleware` + `idempotency_keys` table on `BaseModel`
-    - `EmailUtils.render_template`
-
-Anything beyond v0.24.0 is bumped from the roadmap when business
-pressure picks the next item — keep the roadmap honest, not
-aspirational.
+  `tempest db init/revision/upgrade/downgrade/current/history/seed`,
+  `tempest user create [--admin] / list`, `tempest secrets rotate`,
+  plus quality gates (`lint`, `fix`, `format`, `fmt-check`, `type`,
+  `test`, `check`).
+
+The whole Tier S / Tier A / Tier B backlog that used to live here is
+**shipped** — idempotency, cloud uploads, OTel tracing, `HTTPClient`,
+the outbox pattern, `EmailUtils.render_template`, OAuth2/OIDC, CSRF +
+body-size middleware, bulk repo ops, the Prometheus endpoint, TOTP/MFA,
+`TenantScopedRepository`, `SlowQueryLogger`, `AlembicHelper.safe_upgrade`,
+graceful shutdown, `make_websocket_router`, and the `db seed` /
+`secrets rotate` CLI commands all exist today. The covers list above is
+the source of truth; don't re-plan finished work.
+
+### Next-version plan
+
+Ordered by the priority the user set. Each item is the next minor
+bump (`feat: vX.Y+1.0`) when picked up. Keep this honest — move an
+item up to the covers list the moment it ships, and only add a new
+entry when business pressure actually selects it.
+
+1. **Rate-limit per user / scope** — `RateLimitMiddleware` keys on
+   client IP today. Add a pluggable key extractor (authenticated
+   user id, API key, tenant, or a custom callable) so limits can be
+   per-principal instead of per-IP, with the same memory + Redis
+   backends. Shared NAT / proxy clients stop sharing one bucket.
+2. **i18n / localized `AppException` messages** — error envelopes are
+   English-only. Let each `AppException` carry a message key + params
+   resolved against per-locale catalogs (PT-BR default + EN), picked
+   from `Accept-Language` or an explicit override, so `register_
+   exception_handlers` emits the localized `message` without callers
+   hand-translating.
+3. **`@cached` tag / namespace invalidation** — the cache decorator
+   only expires by TTL. Add tag/namespace tagging on write plus an
+   `invalidate(tag|namespace)` call so a mutation can drop every
+   dependent entry at once instead of waiting out the TTL.
+4. **Feature flags** — `FeatureFlag` with env + Redis backends
+   (Redis for runtime toggles, env for static), a dependency/guard to
+   gate routes and a helper to branch in services, so rollouts and
+   kill-switches don't require a redeploy.
+5. **Audit trail** — beyond `AuditMixin` (timestamps), a per-entity
+   mutation log capturing actor, action, before/after diff on
+   create/update/delete, written in the same transaction as the
+   change (reuse the outbox machinery), with a `BaseRepository` hook
+   so services opt in per model.
 
 ## Conventions specific to this repo
 

{tempest_fastapi_sdk-0.53.0 → tempest_fastapi_sdk-0.55.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.53.0
+Version: 0.55.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
@@ -239,9 +239,9 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | --- | --- |
 | `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` (+ `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.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException`, i18n (`MessageCatalog`, `default_message_catalog`, `parse_accept_language`, `DEFAULT_LOCALE`) |
 | `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`, `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.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` (+ `RateLimitStore`/`MemoryRateLimitStore`/`RedisRateLimitStore`/`RateLimitResult` and `key_by_ip`/`key_by_jwt_subject`/`key_by_jwt_claim`/`key_by_header`), `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` |
@@ -2994,7 +2994,7 @@ Tweak `page_param=` / `size_param=` when your service uses non-standard query pa
 
 ### Rate limit middleware recipe
 
-`RateLimitMiddleware` is a lightweight in-process sliding-window limiter — each unique key (client IP by default) is allowed at most `max_requests` requests inside every `window_seconds` window. Exceeded requests get a `429 Too Many Requests` with a `Retry-After` header.
+`RateLimitMiddleware` is a sliding-window limiter — each unique key (client IP by default) is allowed at most `max_requests` requests inside every `window_seconds` window. Exceeded requests get a `429 Too Many Requests` with a `Retry-After` header. Two axes are pluggable: the **store** (memory or Redis) and the **key** (IP, user, tenant, API key).
 
 ```python
 # src/api/app.py
@@ -3012,35 +3012,53 @@ def create_app() -> FastAPI:
     ...
 ```
 
-Pass `key_func=` to partition state by tenant header, authenticated user, or any request attribute. The full app factory then looks like:
+**Limit per principal.** By default the key is the client IP. The
+`key_by_*` factories key on the authenticated user, an arbitrary token
+claim or a header instead. Because the middleware runs *before* FastAPI
+dependencies resolve, the `key_by_jwt_*` factories decode the bearer
+from the raw request (`decode_or_none`) and fall back to the IP for
+anonymous traffic:
+
+| Factory | Key produced | Use |
+| --- | --- | --- |
+| `key_by_ip(trusted_header=...)` | `ip:<addr>` | Per IP (default). |
+| `key_by_jwt_subject(jwt)` | `user:<sub>` | Per authenticated user. |
+| `key_by_jwt_claim(jwt, "tenant_id", scope="tenant")` | `tenant:<id>` | Per token claim. |
+| `key_by_header("x-api-key", scope="apikey")` | `apikey:<value>` | Per header value. |
+
+**Share state across replicas.** The default `MemoryRateLimitStore`
+counts in-process (single worker). Pass `RedisRateLimitStore(redis)` for
+multi-replica deploys — an atomic Lua sliding-window log over a sorted
+set, `fail_open=True` by default:
 
 ```python
 # src/api/app.py
-from fastapi import FastAPI, Request
-
-from tempest_fastapi_sdk import RateLimitMiddleware
+from redis.asyncio import Redis
 
+from tempest_fastapi_sdk import (
+    RateLimitMiddleware,
+    RedisRateLimitStore,
+    key_by_jwt_subject,
+)
 
-def by_tenant(request: Request) -> str:
-    """Bucket every request under its tenant header, falling back to IP."""
-    return request.headers.get("X-Tenant", request.client.host or "anon")
+from src.api.dependencies.resources import get_jwt_utils
 
 
 def create_app() -> FastAPI:
+    redis: Redis = Redis.from_url("redis://localhost:6379/0")
     app = FastAPI(...)
     app.add_middleware(
         RateLimitMiddleware,
         max_requests=600,
         window_seconds=60.0,
-        key_func=by_tenant,                                  # ← swap the default IP key
+        key_func=key_by_jwt_subject(get_jwt_utils()),        # ← per-user buckets
+        store=RedisRateLimitStore(redis),                    # ← shared across replicas
         exempt_paths=("/health/liveness", "/health/readiness"),
     )
     return app
 ```
 
-The two highlighted pieces — the `by_tenant` helper and the `key_func=by_tenant` wiring — are the only diff against the default snippet above.
-
-The state is held **in-process** — for multi-worker deployments either run a single uvicorn worker behind a single reverse-proxy node, or push rate limiting to the edge (nginx / Cloudflare / AWS WAF). The middleware is intentionally simple; a Redis-backed sliding-window limiter is one issue away if it shows up as a real need.
+The sliding-window semantics are identical across both stores; only where the counters live changes. You can still push rate limiting to the edge (nginx / Cloudflare / AWS WAF) when you prefer.
 
 ### Outbox dispatcher pattern recipe
 

{tempest_fastapi_sdk-0.53.0 → tempest_fastapi_sdk-0.55.0}/README.md

@@ -137,9 +137,9 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | --- | --- |
 | `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` (+ `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.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException`, i18n (`MessageCatalog`, `default_message_catalog`, `parse_accept_language`, `DEFAULT_LOCALE`) |
 | `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`, `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.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` (+ `RateLimitStore`/`MemoryRateLimitStore`/`RedisRateLimitStore`/`RateLimitResult` and `key_by_ip`/`key_by_jwt_subject`/`key_by_jwt_claim`/`key_by_header`), `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` |
@@ -2892,7 +2892,7 @@ Tweak `page_param=` / `size_param=` when your service uses non-standard query pa
 
 ### Rate limit middleware recipe
 
-`RateLimitMiddleware` is a lightweight in-process sliding-window limiter — each unique key (client IP by default) is allowed at most `max_requests` requests inside every `window_seconds` window. Exceeded requests get a `429 Too Many Requests` with a `Retry-After` header.
+`RateLimitMiddleware` is a sliding-window limiter — each unique key (client IP by default) is allowed at most `max_requests` requests inside every `window_seconds` window. Exceeded requests get a `429 Too Many Requests` with a `Retry-After` header. Two axes are pluggable: the **store** (memory or Redis) and the **key** (IP, user, tenant, API key).
 
 ```python
 # src/api/app.py
@@ -2910,35 +2910,53 @@ def create_app() -> FastAPI:
     ...
 ```
 
-Pass `key_func=` to partition state by tenant header, authenticated user, or any request attribute. The full app factory then looks like:
+**Limit per principal.** By default the key is the client IP. The
+`key_by_*` factories key on the authenticated user, an arbitrary token
+claim or a header instead. Because the middleware runs *before* FastAPI
+dependencies resolve, the `key_by_jwt_*` factories decode the bearer
+from the raw request (`decode_or_none`) and fall back to the IP for
+anonymous traffic:
+
+| Factory | Key produced | Use |
+| --- | --- | --- |
+| `key_by_ip(trusted_header=...)` | `ip:<addr>` | Per IP (default). |
+| `key_by_jwt_subject(jwt)` | `user:<sub>` | Per authenticated user. |
+| `key_by_jwt_claim(jwt, "tenant_id", scope="tenant")` | `tenant:<id>` | Per token claim. |
+| `key_by_header("x-api-key", scope="apikey")` | `apikey:<value>` | Per header value. |
+
+**Share state across replicas.** The default `MemoryRateLimitStore`
+counts in-process (single worker). Pass `RedisRateLimitStore(redis)` for
+multi-replica deploys — an atomic Lua sliding-window log over a sorted
+set, `fail_open=True` by default:
 
 ```python
 # src/api/app.py
-from fastapi import FastAPI, Request
-
-from tempest_fastapi_sdk import RateLimitMiddleware
+from redis.asyncio import Redis
 
+from tempest_fastapi_sdk import (
+    RateLimitMiddleware,
+    RedisRateLimitStore,
+    key_by_jwt_subject,
+)
 
-def by_tenant(request: Request) -> str:
-    """Bucket every request under its tenant header, falling back to IP."""
-    return request.headers.get("X-Tenant", request.client.host or "anon")
+from src.api.dependencies.resources import get_jwt_utils
 
 
 def create_app() -> FastAPI:
+    redis: Redis = Redis.from_url("redis://localhost:6379/0")
     app = FastAPI(...)
     app.add_middleware(
         RateLimitMiddleware,
         max_requests=600,
         window_seconds=60.0,
-        key_func=by_tenant,                                  # ← swap the default IP key
+        key_func=key_by_jwt_subject(get_jwt_utils()),        # ← per-user buckets
+        store=RedisRateLimitStore(redis),                    # ← shared across replicas
         exempt_paths=("/health/liveness", "/health/readiness"),
     )
     return app
 ```
 
-The two highlighted pieces — the `by_tenant` helper and the `key_func=by_tenant` wiring — are the only diff against the default snippet above.
-
-The state is held **in-process** — for multi-worker deployments either run a single uvicorn worker behind a single reverse-proxy node, or push rate limiting to the edge (nginx / Cloudflare / AWS WAF). The middleware is intentionally simple; a Redis-backed sliding-window limiter is one issue away if it shows up as a real need.
+The sliding-window semantics are identical across both stores; only where the counters live changes. You can still push rate limiting to the edge (nginx / Cloudflare / AWS WAF) when you prefer.
 
 ### Outbox dispatcher pattern recipe
 

{tempest_fastapi_sdk-0.53.0 → tempest_fastapi_sdk-0.55.0}/docs/recipes/http.en.md

@@ -102,6 +102,73 @@ Key points:
 - `make_token_dependency(secret)` returns an async dependency that validates `X-Token` via `hmac.compare_digest`; pass an empty string to disable in dev. The dependency lives next to the rest of the auth glue in `src/api/dependencies/auth.py` once it grows beyond the one-liner above.
 
 
+### Localized error messages (i18n)
+
+By default the envelope `detail` is the exception's literal message (English for the built-ins). To return the message **in the client's language** without translating at each `raise`, pass a `MessageCatalog` to `register_exception_handlers`:
+
+```python
+# src/api/app.py
+from tempest_fastapi_sdk import default_message_catalog, register_exception_handlers
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(...)
+    register_exception_handlers(
+        app,
+        catalog=default_message_catalog(),                   # ← bundled PT-BR + EN-US
+        default_locale="pt-BR",
+    )
+    ...
+```
+
+The handler negotiates the locale from the `Accept-Language` header (ordered by `q`), falls back to `default_locale` when nothing matches, and resolves the exception **key** — `message_key` if set, else the `code` — against the catalog. With no catalog, or when the key is unknown, the literal `detail` is kept (zero breakage).
+
+```python
+# Same NotFoundException, language decided by the client's Accept-Language:
+#   Accept-Language: pt-BR  →  {"detail": "Recurso não encontrado", "code": "NOT_FOUND"}
+#   Accept-Language: en-US  →  {"detail": "Resource not found",     "code": "NOT_FOUND"}
+```
+
+For domain codes (and messages with parameters), extend the catalog with `merge` and pass `message_params` at the `raise`:
+
+```python
+# src/core/i18n.py
+from tempest_fastapi_sdk import MessageCatalog, default_message_catalog
+
+CATALOG: MessageCatalog = default_message_catalog().merge(
+    {
+        "pt-BR": {"USER_NOT_FOUND": "Usuário {email} não encontrado"},
+        "en-US": {"USER_NOT_FOUND": "User {email} not found"},
+    }
+)
+```
+
+```python
+# src/services/user.py
+from tempest_fastapi_sdk import NotFoundException
+
+
+def require_user(email: str) -> None:
+    """Raise a localized 404 carrying the offending e-mail.
+
+    Args:
+        email (str): The e-mail that was not found.
+
+    Raises:
+        NotFoundException: Always — keyed to ``USER_NOT_FOUND`` so the
+            handler localizes it from the request locale.
+    """
+    raise NotFoundException(
+        "User not found",                                    # literal fallback
+        code="USER_NOT_FOUND",
+        message_params={"email": email},
+    )
+```
+
+!!! tip "The key defaults to the `code`"
+    You rarely pass `message_key` — it falls back to the exception's `code`. Set `message_key` only to decouple the translated string from the error code. A template referencing a missing param is returned uninterpolated rather than raising.
+
+
 ## JWT bearer / current-user / role dependencies
 
 
@@ -193,7 +260,7 @@ async def update_perms(user_id: UUID) -> None:
 ## Rate limit middleware
 
 
-`RateLimitMiddleware` is a lightweight in-process sliding-window limiter — each unique key (client IP by default) is allowed at most `max_requests` requests inside every `window_seconds` window. Exceeded requests get a `429 Too Many Requests` with a `Retry-After` header.
+`RateLimitMiddleware` is a sliding-window limiter — each unique key (client IP by default) is allowed at most `max_requests` requests inside every `window_seconds` window. Exceeded requests get a `429 Too Many Requests` with a `Retry-After` header. Two axes are pluggable: the **store** (memory or Redis) and the **key** (IP, user, tenant, API key) — see below.
 
 ```python
 # src/api/app.py
@@ -211,38 +278,73 @@ def create_app() -> FastAPI:
     ...
 ```
 
-Pass `key_func=` to partition state by tenant header, authenticated user, or any request attribute. The full app factory then looks like:
+### Limit per user / tenant / API key
+
+By default the key is the client IP. To limit **per principal** (authenticated user, tenant, API key), pass a `key_func`. The SDK ships ready-made factories:
+
+| Factory | Key produced | Use |
+| --- | --- | --- |
+| `key_by_ip(trusted_header=...)` | `ip:<addr>` | Per IP (default). |
+| `key_by_jwt_subject(jwt)` | `user:<sub>` | Per authenticated user (`sub` claim). |
+| `key_by_jwt_claim(jwt, "tenant_id", scope="tenant")` | `tenant:<id>` | Per arbitrary token claim. |
+| `key_by_header("x-api-key", scope="apikey")` | `apikey:<value>` | Per header value. |
+
+!!! warning "The middleware runs before dependencies"
+    `RateLimitMiddleware` runs **before** FastAPI `Depends` resolve — so the user authenticated by your auth dependency does not exist yet when the key is computed. That is why the `key_by_jwt_*` factories decode the bearer **from the raw request** (via `JWTUtils.decode_or_none`, no exception raised). Anonymous traffic falls back to the IP, so it stays limited.
 
 ```python
 # src/api/app.py
-from fastapi import FastAPI, Request
+from fastapi import FastAPI
 
-from tempest_fastapi_sdk import RateLimitMiddleware
+from tempest_fastapi_sdk import RateLimitMiddleware, key_by_jwt_subject
+
+from src.api.dependencies.resources import get_jwt_utils
 
 
-def by_tenant(request: Request) -> str:
-    """Bucket every request under its tenant header, falling back to IP."""
-    return request.headers.get(
-        "X-Tenant",
-        request.client.host if request.client else "anon",
+def create_app() -> FastAPI:
+    app = FastAPI(...)
+    app.add_middleware(
+        RateLimitMiddleware,
+        max_requests=600,
+        window_seconds=60.0,
+        key_func=key_by_jwt_subject(get_jwt_utils()),        # ← limit per user
+        exempt_paths=("/health/liveness", "/health/readiness"),
     )
+    return app
+```
+
+### Distributed state with Redis
+
+The default store (`MemoryRateLimitStore`) counts **in-process** — correct for a single worker. For multi-replica deployments, pass `store=RedisRateLimitStore(redis)`: each key becomes a sorted set and a single Lua script prunes expired members, counts, and adds the new hit **atomically** (no race between count and add). On a Redis error, `fail_open=True` (default) allows the request rather than locking everyone out.
+
+```python
+# src/api/app.py
+from redis.asyncio import Redis
+
+from tempest_fastapi_sdk import (
+    RateLimitMiddleware,
+    RedisRateLimitStore,
+    key_by_jwt_subject,
+)
+
+from src.api.dependencies.resources import get_jwt_utils
 
 
 def create_app() -> FastAPI:
+    redis: Redis = Redis.from_url("redis://localhost:6379/0")
     app = FastAPI(...)
     app.add_middleware(
         RateLimitMiddleware,
         max_requests=600,
         window_seconds=60.0,
-        key_func=by_tenant,                                  # ← swap the default IP key
+        key_func=key_by_jwt_subject(get_jwt_utils()),
+        store=RedisRateLimitStore(redis),                    # ← shared across replicas
         exempt_paths=("/health/liveness", "/health/readiness"),
     )
     return app
 ```
 
-The two highlighted pieces — the `by_tenant` helper and the `key_func=by_tenant` wiring — are the only diff against the default snippet above.
-
-The state is held **in-process** — for multi-worker deployments either run a single uvicorn worker behind a single reverse-proxy node, or push rate limiting to the edge (nginx / Cloudflare / AWS WAF). The middleware is intentionally simple; a Redis-backed sliding-window limiter is one issue away if it shows up as a real need.
+The sliding-window semantics are identical across both stores; only where the counters live changes. You can still push rate limiting to the edge (nginx / Cloudflare / AWS WAF) when you prefer.
 
 
 ## Webhook signature verification