Skip to content

4.15.0 — 2026-07-13

← 4.16.0 | 4.14.0 → | ↑ 4.x series

Added

Configs

  • FastAPI Rate Limit Settings - Added FastAPIRateLimitConfig and the BaseConfig.FASTAPI_RATE_LIMIT attribute, centralizing trusted-proxy resolution, Redis key layout, fail-open/closed behavior, X-RateLimit-* headers, and JWT-based identity for FastAPIRestRateLimitHandler.
    • New .env variables: FASTAPI_RATE_LIMIT__TRUSTED_PROXY_IPS, ALLOW_PRIVATE_IPS, KEY_PREFIX, FAIL_CLOSED, SKIP_METHODS, HASH_QUERY_PARAM_VALUES, REQUIRE_IDENTIFIER_FOR_QUERY_PARAMS, REJECT_UNKNOWN_CLIENT, RATE_LIMIT_HEADERS, IDENTITY_FROM_ACCESS_TOKEN.
  • gRPC Rate Limit Settings - Added GrpcRateLimitConfig and the BaseConfig.GRPC_RATE_LIMIT attribute, controlling Redis key layout, fail-open/closed behavior, skipped health-check methods, and JWT-based identity for the new gRPC rate-limit interceptors.
    • New .env variables: GRPC_RATE_LIMIT__IS_ENABLED, FAIL_CLOSED, IDENTITY_FROM_ACCESS_TOKEN.
    • When IS_ENABLED is True, AppUtils.create_grpc_app and AppUtils.create_async_grpc_app register the matching interceptor automatically.

Models - DTOs

  • Rate Limit Window DTO - Added RateLimitWindowDTO (calls_count, window_ms) with a key_suffix property producing a stable Redis key segment per tier. Shared by the FastAPI handler and both gRPC interceptors.

Helpers - Decorators

  • gRPC Rate Limit Decorator - Added grpc_rate_limit_decorator, attaching one or more rate-limit windows to a servicer method without wrapping it. Stacking the decorator declares independent burst and sustained tiers, all enforced in declaration order by GrpcServerRateLimitInterceptor.

Helpers - Utils

  • Rate Limit Utils - Added RateLimitUtils with compute_rate_limit_window (validates calls_count >= 1 and a positive combined window) and get_rate_limit_windows_from_callable (reads stacked windows off a function or bound method).
  • gRPC Interceptor Auto-Registration - Added GrpcAPIUtils.setup_rate_limit_interceptor and AsyncGrpcAPIUtils.setup_rate_limit_interceptor, wired into AppUtils.create_grpc_app / create_async_grpc_app to append the sync or async rate-limit interceptor when GRPC_RATE_LIMIT.IS_ENABLED is True.

Helpers - Interceptors

  • gRPC Rate Limit Interceptors - Added GrpcServerRateLimitInterceptor and AsyncGrpcServerRateLimitInterceptor, enforcing decorator-declared Redis-backed windows per RPC.
    • Uses atomic INCREX (saturate=True, enx=True, millisecond px expiry) to avoid check-then-act races.
    • Identity resolution: custom identifier_fn, JWT sub claim from a Bearer token in invocation metadata (IDENTITY_FROM_ACCESS_TOKEN), falling back to parsed peer host (ipv4:/ipv6:/unix: prefixes handled).
    • Breached windows abort with RESOURCE_EXHAUSTED (via RateLimitExceededError) including a computed retry_after; Redis/identity failures abort with UNAVAILABLE (via UnavailableError) when FAIL_CLOSED is True.
    • SKIP_METHODS excludes full gRPC method names (health checks by default) from rate limiting.
  • gRPC Identity Helpers - Added archipy.helpers.interceptors.grpc.rate_limit.identifiers with invocation_metadata_to_dict, extract_bearer_token_from_metadata, and resolve_jwt_access_token_sub_from_metadata, verifying Bearer tokens via JWTUtils and returning the sub claim.
  • FastAPI Identity Helpers - Added archipy.helpers.interceptors.fastapi.rate_limit.identifiers with extract_bearer_token and resolve_jwt_access_token_sub, used by FastAPIRestRateLimitHandler to bucket authenticated requests by user instead of IP.

Changed

Helpers - FastAPI Rate Limit

  • Handler Rewrite - FastAPIRestRateLimitHandler gained config-driven behavior sourced from FastAPIRateLimitConfig, with per-instance overrides for every setting.
    • Trusted Proxy Chain Resolution - Client IP is only taken from forwarded headers (Forwarded, X-Forwarded-For, X-Real-IP, CF-Connecting-IP, True-Client-IP) when the immediate peer is a configured trusted proxy (TRUSTED_PROXY_IPS, CIDR or exact match, or * to trust all peers). X-Forwarded-For is walked right-to-left with nginx real_ip_recursive semantics, skipping trusted hops and stripping port suffixes.
    • JWT-Based Identity - identity_from_access_token (default True) verifies a Bearer token via JWTUtils and buckets by sub, falling back to client IP when the token is missing or invalid.
    • Stacked Windows - New additional_windows parameter enforces extra RateLimitWindowDTO tiers alongside the primary window; all tiers must pass, and the most constrained remaining quota is reported in headers.
    • Rate Limit Headers - rate_limit_headers (default True) attaches X-RateLimit-Limit / X-RateLimit-Remaining on allowed responses and adds Retry-After on 429s.
    • Unknown Client Handling - reject_unknown_client (default True) returns 503 when no client identity can be resolved instead of silently allowing the request.
    • Query Param Safety - require_identifier_for_query_params (default True) raises InvalidArgumentError at construction when query_params is set without identifier_fn or identity_from_access_token, preventing client-controlled per-user quota targeting.
    • Redis Failure Handling - fail_closed (default True) returns 503 on Redis connection errors instead of allowing requests through.

Tests

Tests - gRPC Rate Limit

  • New Feature Suite - Added features/grpc_rate_limit.feature and features/steps/grpc_rate_limit_steps.py covering sync and async interceptor modes: within-limit success, over-limit RESOURCE_EXHAUSTED rejection, undecorated methods bypassing limits, stacked burst/sustained windows, per-JWT-user isolation, UNAVAILABLE abort when Redis is down and fail-closed, and InvalidArgumentError on invalid window construction.

Tests - FastAPI Rate Limit

  • Expanded Scenario Coverage - Extended features/fastapi_rate_limit.feature and features/steps/fastapi_rate_limit_steps.py.
    • X-RateLimit-Limit / X-RateLimit-Remaining header assertions on allowed and rejected responses.
    • Spoofed X-Real-IP is ignored without a configured trusted proxy; distinct clients are isolated only behind trusted proxies.
    • Multi-hop X-Forwarded-For chains, injected entries ahead of the real client, port-suffix stripping, and multiple X-Forwarded-For header fields combined per RFC 9110.
    • X-Real-IP precedence rules when X-Forwarded-For is also present.
    • 503 on Redis unavailability with fail_closed; InvalidArgumentError when query_params is set without an identifier.
    • JWT-based user isolation, fallback to client IP when a JWT is missing or invalid/expired.

Documentation

Tutorials - Decorators

  • gRPC Rate Limit Decorator - Added usage guide for grpc_rate_limit_decorator, including stacked burst/sustained window examples and interceptor registration.

Tutorials - Interceptors

  • gRPC Rate Limiting - Added a GrpcServerRateLimitInterceptor / AsyncGrpcServerRateLimitInterceptor guide covering GRPC_RATE_LIMIT config, automatic registration via AppUtils, JWT-based identity, and health-check exclusions.
  • FastAPI Rate Limiting - Expanded the FastAPIRestRateLimitHandler guide with trusted-proxy configuration, JWT identity, stacked additional_windows, and rate-limit header reference.

Getting Started

  • Complete User Example / Project Structure - Updated to reference the new rate-limiting configuration and helper modules.

API Reference

  • Added mkdocstrings entries for FastAPIRateLimitConfig, GrpcRateLimitConfig, grpc_rate_limit decorator, grpc.rate_limit interceptors and identifiers, RateLimitUtils, and RateLimitWindowDTO.