api-shield 0.2.0__tar.gz → 0.3.0__tar.gz

api_shield-0.3.0/FEATURES.md

@@ -0,0 +1,356 @@
+# api-shield — Feature Roadmap
+
+This document captures the full set of proposed features across decorators, SaaS infrastructure, AI-powered analytics, and integrations.
+
+---
+
+## Additional Decorators
+
+### Access Control
+
+#### `@ip_allowlist(*cidrs)`
+Only allow requests from specific IP ranges. Requests from outside receive a silent 403 or 404.
+```python
+@router.get("/admin/reports")
+@ip_allowlist("10.0.0.0/8", "192.168.1.0/24")
+async def admin_reports(): ...
+```
+
+#### `@ip_blocklist(*cidrs)`
+Inverse of `@ip_allowlist` — block specific IPs or ranges, allow everything else. Useful for abuse mitigation without touching the route handler.
+
+#### `@geo_only(*country_codes)`
+Restrict a route to specific countries based on IP geolocation. Returns a silent 404 elsewhere — same treatment as `@env_only` to avoid leaking that the route exists.
+```python
+@router.get("/checkout")
+@geo_only("US", "CA", "GB")
+async def checkout(): ...
+```
+
+#### `@requires_role(*roles)`
+Gate a route behind a role check. Reads `request.state.user_roles` (populated by your auth middleware). Returns 403 if the role is absent.
+```python
+@router.delete("/users/{id}")
+@requires_role("admin", "superuser")
+async def delete_user(id: int): ...
+```
+
+#### `@requires_header(name, value=None)`
+Block requests missing a required header. Optionally assert an exact value. Useful for internal service-to-service APIs that should never be called by public clients.
+```python
+@router.post("/internal/sync")
+@requires_header("X-Internal-Token")
+async def internal_sync(): ...
+```
+
+---
+
+### Traffic & Load Management
+
+#### `@rate_limit(requests, window)`
+Cap how many times a route can be called within a rolling time window. Exceeding the limit returns 429 with a `Retry-After` header. Window accepts human-readable strings (`"1m"`, `"1h"`, `"1d"`).
+```python
+@router.post("/auth/login")
+@rate_limit(requests=5, window="1m")
+async def login(): ...
+```
+
+#### `@quota(calls, period, per)`
+Per-identity call quota — scoped to `"api_key"`, `"user_id"`, or `"ip"`. Resets at the end of each period (`"day"`, `"month"`). Returns 429 with remaining quota headers when exhausted.
+```python
+@router.post("/ai/generate")
+@quota(calls=100, period="day", per="api_key")
+async def generate(): ...
+```
+
+#### `@circuit_breaker(threshold, timeout)`
+Automatically disables a route after `threshold` consecutive errors, then re-enables it after `timeout` seconds. Prevents a struggling downstream service from cascading failures across the API.
+```python
+@router.get("/payments/status")
+@circuit_breaker(threshold=5, timeout=30)
+async def payment_status(): ...
+```
+
+#### `@shed_load(above)`
+Drop a configurable percentage of requests when a system health signal (CPU, memory, or custom) exceeds a threshold. Returns 503. The route remains "active" in shield state but sheds excess traffic automatically.
+```python
+@router.get("/recommendations")
+@shed_load(above=0.8)
+async def recommendations(): ...
+```
+
+---
+
+### Time & Scheduling
+
+#### `@available_between(start, end, tz, days)`
+Route only responds during specified hours on specified days. Outside the window it returns 503 with a `Retry-After` pointing to the next available open time. Ideal for business-hours-only endpoints.
+```python
+@router.post("/support/ticket")
+@available_between(start="09:00", end="17:00", tz="America/New_York", days=["mon","tue","wed","thu","fri"])
+async def create_ticket(): ...
+```
+
+#### `@sunset(date)`
+Hard end-of-life — unlike `@deprecated` which warns, this blocks the route entirely (503) after the given date. Clients that ignored deprecation headers now receive a hard stop.
+```python
+@router.get("/v1/users")
+@sunset(date="2026-01-01")
+async def v1_users(): ...
+```
+
+#### `@cooldown(duration)`
+After a maintenance window ends, keep traffic throttled for a warmup period before returning to full capacity. Useful when the backend needs time to rebuild caches or warm up database connections.
+```python
+@router.get("/search")
+@maintenance(reason="Index rebuild")
+@cooldown(duration="10m")
+async def search(): ...
+```
+
+---
+
+### Observability & Debugging
+
+#### `@mock(response, status_code)`
+Return a static mock response instead of running the handler. Zero backend calls. Invaluable for frontend teams when the real endpoint is not ready, or for chaos testing.
+```python
+@router.get("/recommendations")
+@mock(response={"items": []}, status_code=200)
+async def recommendations(): ...
+```
+
+#### `@latency(min_ms, max_ms)`
+Inject artificial latency (random value within range) on every request. Useful for testing client timeout handling and loading states. Should be combined with `@env_only("dev", "staging")` to prevent accidental use in production.
+```python
+@router.get("/slow-service")
+@env_only("dev", "staging")
+@latency(min_ms=200, max_ms=800)
+async def slow_service(): ...
+```
+
+#### `@audit_request(actor_from)`
+Enhanced per-route audit logging — records full request metadata, response status, and actor identity. More granular than the engine-level audit log which only tracks state changes.
+```python
+@router.delete("/accounts/{id}")
+@audit_request(actor_from="header:X-User-ID")
+async def delete_account(id: int): ...
+```
+
+---
+
+### Feature Flagging & Experimentation
+
+#### `@feature_flag(flag_name, provider)`
+Route is only active when the named flag is enabled in an external feature flag system (LaunchDarkly, Unleash, or a local config dict). Integrates with the engine so it is controllable at runtime without redeployment.
+```python
+@router.get("/new-checkout")
+@feature_flag("new_checkout_v2")
+async def new_checkout(): ...
+```
+
+#### `@ab_test(variant, allocation)`
+Serve this route handler to a specific slice of traffic as variant B. Pairs with a variant A handler on the same path. The engine tracks which sessions see which variant for analysis.
+```python
+@router.get("/pricing")
+@ab_test(variant="B", allocation=0.3)
+async def pricing_v2(): ...
+```
+
+#### `@beta(opt_in_header)`
+Route is only reachable when the request includes a specific opt-in header. Everyone else receives a 404. Clean way to run an invite-only beta without a separate deployment or feature flag service.
+```python
+@router.get("/ai-search")
+@beta(opt_in_header="X-Beta-Features")
+async def ai_search(): ...
+```
+
+---
+
+### Data & Compliance
+
+#### `@read_only`
+Block all mutating methods (POST, PUT, PATCH, DELETE) on a route — only GET and HEAD pass through. Returns 405. Useful during live data migrations when reads must continue but writes must be frozen.
+```python
+@router.post("/orders")
+@read_only
+async def create_order(): ...
+```
+
+#### `@requires_consent(policy)`
+Check that the requesting user has accepted a named policy before serving the response. Reads from `request.state.user_consents`. Returns 451 (Unavailable For Legal Reasons) if consent is missing.
+```python
+@router.get("/analytics/personal")
+@requires_consent("gdpr_v2")
+async def personal_analytics(): ...
+```
+
+#### `@pii_scrub(fields)`
+Automatically redact specified fields from request logs and the audit trail for this route. The middleware strips listed fields before they reach the audit logger — they never appear in any log.
+```python
+@router.post("/users")
+@pii_scrub(fields=["email", "phone", "ssn"])
+async def create_user(): ...
+```
+
+---
+
+### Decorator Summary
+
+| Category | Decorator | HTTP Response |
+|---|---|---|
+| Access | `@ip_allowlist(*cidrs)` | 403/404 if blocked |
+| Access | `@ip_blocklist(*cidrs)` | 403 if blocked |
+| Access | `@geo_only(*countries)` | 404 outside allowed countries |
+| Access | `@requires_role(*roles)` | 403 if role missing |
+| Access | `@requires_header(name, value)` | 400 if header missing |
+| Traffic | `@rate_limit(requests, window)` | 429 + `Retry-After` |
+| Traffic | `@quota(calls, period, per)` | 429 when exhausted |
+| Traffic | `@circuit_breaker(threshold, timeout)` | 503 when open |
+| Traffic | `@shed_load(above)` | 503 under stress |
+| Time | `@available_between(start, end, tz, days)` | 503 + `Retry-After` |
+| Time | `@sunset(date)` | 503 after date |
+| Time | `@cooldown(duration)` | throttled after maintenance |
+| Debug | `@mock(response, status_code)` | configurable |
+| Debug | `@latency(min_ms, max_ms)` | normal response, delayed |
+| Debug | `@audit_request(actor_from)` | normal response, extra logging |
+| Experimentation | `@feature_flag(flag_name, provider)` | 503 if flag off |
+| Experimentation | `@ab_test(variant, allocation)` | normal response |
+| Experimentation | `@beta(opt_in_header)` | 404 without opt-in header |
+| Compliance | `@read_only` | 405 on mutating methods |
+| Compliance | `@requires_consent(policy)` | 451 if no consent |
+| Compliance | `@pii_scrub(fields)` | normal response, scrubbed logs |
+
+---
+
+## SaaS Infrastructure
+
+### Multi-tenancy
+- Organizations and workspaces — one account manages multiple apps and environments
+- Team roles: Owner, Admin, Viewer — scoped per workspace with granular permissions
+- Per-workspace API keys replacing the single shared admin token
+- Billing tiers:
+  - **Free**: memory backend, up to 5 routes, single user
+  - **Pro**: Redis backend, unlimited routes, team access, metrics history
+  - **Enterprise**: SSO/SAML, SLA, custom retention, on-premise deployment
+
+### Cloud-hosted Backend
+- Managed Redis or Postgres as the shield backend — users provision nothing
+- CLI and ShieldAdmin point at the SaaS control plane, not their own server
+- Local middleware reads state from the cloud backend; latency added is sub-millisecond via edge caching
+- Fail-open guarantee preserved — if the cloud is unreachable, all routes pass through
+
+### User & API Key Management
+- Invite team members by email with role assignment
+- Personal access tokens for CI/CD pipelines and automation
+- Token scopes: `routes:read`, `routes:write`, `audit:read`, `admin`
+- Token expiry and rotation policies
+- Activity log per token
+
+---
+
+## AI-Powered Analytics
+
+### Metrics Collection
+Before AI analysis is possible, `ShieldMiddleware` needs to emit structured metrics on every request:
+
+- Request count per route (total, passed, blocked)
+- Block reason distribution per route (maintenance / disabled / env-gated / rate-limited)
+- Latency percentiles per route (p50, p95, p99)
+- Requests blocked during a maintenance window (impact count)
+- Traffic volume by hour-of-day and day-of-week (pattern data for scheduling AI)
+
+Metrics are written to a time-series store (ClickHouse, TimescaleDB, or Postgres with partitioning) alongside the existing audit log.
+
+---
+
+### AI Features
+
+#### Optimal Maintenance Window Suggestions
+Analyse historical traffic patterns per route and recommend the lowest-impact maintenance window.
+> *"Route `GET /payments` sees its lowest traffic between 02:00–04:00 UTC on Sundays. Suggested window: Sunday 02:00–03:00 UTC."*
+
+#### Anomaly Detection
+Compare the current request rate against the historical baseline for each route and alert when:
+- A route that normally receives 500 req/min drops to 0 — silent breakage
+- A disabled route is being hammered — clients ignoring 503 responses
+- A deprecated route traffic has not declined — clients not migrating to the successor
+
+#### Rollout Safety Advisor
+During a `@rollout(percentage=N)` deployment, continuously monitor the error rate on the canary slice vs the stable slice and surface actionable recommendations:
+> *"Canary error rate is 4.2% vs stable baseline 0.3%. Recommend halting rollout and investigating before increasing traffic."*
+
+#### Deprecation Candidate Detection
+Scan routes with `ACTIVE` status and flag ones with steadily declining traffic over 30, 60, or 90 day windows as candidates for `@deprecated`. Surfaces the suggestion in the dashboard with traffic charts as evidence.
+
+#### Impact Analysis Before State Changes
+Before a route is disabled, surface estimated blast radius:
+> *"`GET /auth/token` received 12,400 requests in the last hour. Disabling it will affect an estimated 8,200 active sessions and 3 dependent routes."*
+
+#### Natural Language CLI Interface
+Execute shield operations in plain English via a Claude-powered command:
+```bash
+shield ask "which routes have the most blocked traffic this week?"
+shield ask "schedule maintenance on /payments for the quietest window this weekend"
+shield ask "show me routes that haven't had any traffic in 30 days"
+```
+Backed by a Claude API call with current route state and metrics as context.
+
+#### Incident Correlation
+Cross-reference audit log entries (state changes) with error rate spikes automatically. Surfaces probable causes in the dashboard:
+> *"Error rate on `GET /orders` spiked 340% at 14:22 UTC. `POST /inventory` was put in maintenance at 14:19 — likely cause."*
+
+#### Route Health Scoring
+Assign each route a health score (0–100) combining:
+- Uptime percentage over the last 30 days
+- Error rate trend
+- Traffic volume trend
+- Number of unplanned maintenance windows
+- Time since last state change
+
+---
+
+## Dashboard Enhancements
+
+| Enhancement | Description |
+|---|---|
+| Traffic sparklines | Inline 24h traffic chart per route row — no need to drill into a detail page |
+| Maintenance impact counter | "Blocked 1,204 requests during last window" shown per route |
+| Alert rules UI | Configure per-route alerts: notify Slack if error rate exceeds N% |
+| Route health score | 0–100 score badge per route in the route table |
+| Dependency graph | Visual map of which routes depend on which via FastAPI `Depends()` |
+| Metrics detail page | Per-route page with full p50/p95/p99 latency, traffic, and block reason charts |
+| Audit log filters | Filter by actor, action type, date range, and route directly in the UI |
+| Scheduled window calendar | Calendar view of all upcoming maintenance windows across all routes |
+
+---
+
+## Integrations
+
+| Integration | Value |
+|---|---|
+| **Prometheus** `/metrics` endpoint | Drop into any existing observability stack — Grafana dashboards work immediately |
+| **Datadog** | Push route state and metrics as custom metrics and events |
+| **Grafana** | Pre-built dashboard JSON for route health and traffic |
+| **PagerDuty / OpsGenie** | Auto-page on anomaly detection alerts or unexpected route state changes |
+| **Slack / Teams** | Rich formatted messages on state changes (webhook foundation already exists) |
+| **GitHub Actions** | `shield disable` as a pre-deploy step, `shield enable` on success — zero-downtime deploys |
+| **Terraform provider** | Declare route states as infrastructure-as-code alongside the rest of your infrastructure |
+| **LaunchDarkly / Unleash** | Power `@feature_flag` with your existing flag provider |
+| **Sentry** | Correlate shield state changes with error spikes in Sentry issues automatically |
+
+---
+
+## Suggested Build Priority
+
+| Priority | Feature | Reason |
+|---|---|---|
+| 1 | Metrics collection in middleware | Everything else depends on this data existing |
+| 2 | `@rate_limit` and `@circuit_breaker` | Highest immediate practical value for production APIs |
+| 3 | `@available_between` and `@mock` | Common requests, low implementation complexity |
+| 4 | Time-series metrics storage | Required before any AI feature ships |
+| 5 | Dashboard traffic sparklines | Immediate visible value from metrics data |
+| 6 | Optimal maintenance window AI | First AI feature — straightforward pattern analysis |
+| 7 | Anomaly detection + alerts | The feature teams will pay for in a SaaS model |
+| 8 | Multi-tenancy + billing | Once core AI value is proven |
+| 9 | Natural language CLI | High delight factor, builds on all prior AI work |

{api_shield-0.2.0 → api_shield-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: api-shield
-Version: 0.2.0
+Version: 0.3.0
 Summary: Route lifecycle management for APIs — maintenance mode, env gating, deprecation, and more
 Project-URL: Homepage, https://github.com/Attakay78/api-shield
 Project-URL: Repository, https://github.com/Attakay78/api-shield
@@ -32,6 +32,7 @@ Requires-Dist: aiofiles>=23.0; extra == 'all'
 Requires-Dist: fastapi>=0.100; extra == 'all'
 Requires-Dist: httpx>=0.27; extra == 'all'
 Requires-Dist: jinja2>=3.1; extra == 'all'
+Requires-Dist: limits>=5.8.0; extra == 'all'
 Requires-Dist: python-multipart>=0.0.22; extra == 'all'
 Requires-Dist: pyyaml>=6.0; extra == 'all'
 Requires-Dist: redis[asyncio]>=5.0; extra == 'all'
@@ -51,6 +52,7 @@ Requires-Dist: aiofiles>=23.0; extra == 'dev'
 Requires-Dist: anyio[trio]; extra == 'dev'
 Requires-Dist: fastapi>=0.100; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: limits>=5.8.0; extra == 'dev'
 Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2; extra == 'dev'
 Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
 Requires-Dist: mkdocstrings[python]>=0.25; extra == 'dev'
@@ -67,6 +69,8 @@ Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
 Provides-Extra: fastapi
 Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: rate-limit
+Requires-Dist: limits>=5.8.0; extra == 'rate-limit'
 Provides-Extra: redis
 Requires-Dist: redis[asyncio]>=5.0; extra == 'redis'
 Provides-Extra: toml
@@ -78,15 +82,39 @@ Description-Content-Type: text/markdown
 <div align="center">
   <img src="api-shield-logo.svg" alt="API Shield" width="600"/>
 
-  <p><strong>Route lifecycle management for Python web frameworks — maintenance mode, environment gating, deprecation, admin panels, and more. No restarts required.</strong></p>
+  <p><strong>Route(API) lifecycle management for Python web frameworks — maintenance mode, environment gating, deprecation, rate limiting, admin panels, and more. No restarts required.</strong></p>
 
-  <a href="https://pypi.org/project/api-shield"><img src="https://img.shields.io/pypi/v/api-shield?color=F59E0B&label=pypi" alt="PyPI"></a>
+  <a href="https://pypi.org/project/api-shield"><img src="https://img.shields.io/pypi/v/api-shield?color=F59E0B&label=pypi&cacheSeconds=300" alt="PyPI"></a>
   <a href="https://pypi.org/project/api-shield"><img src="https://img.shields.io/pypi/pyversions/api-shield?color=F59E0B" alt="Python versions"></a>
   <a href="LICENSE"><img src="https://img.shields.io/github/license/Attakay78/api-shield?color=F59E0B" alt="License"></a>
 </div>
 
 ---
 
+> [!WARNING]
+> **Early Access** — `api-shield` is fully functional and ready to use. We are actively building on top of a solid foundation and your real-world experience is invaluable at this stage. If you have feedback, feature ideas, or suggestions, please [open an issue](https://github.com/Attakay78/api-shield/issues) — every voice helps shape the roadmap.
+
+---
+
+## Key features
+
+| Feature | Description |
+|---|---|
+| 🎨 **Decorator-first DX** | Route state lives next to the route definition, not in a separate config file |
+| ⚡ **Zero-restart control** | State changes take effect immediately — no redeployment or server restart needed |
+| 🛡️ **Fail-open by default** | If the backend is unreachable, requests pass through. Shield never takes down your API |
+| 🔌 **Pluggable backends** | In-memory (default), file-based JSON, or Redis for multi-instance deployments |
+| 🖥️ **Admin dashboard** | HTMX-powered UI with live SSE updates — no JS framework required |
+| 🖱️ **REST API + CLI** | Full programmatic control from the terminal or CI pipelines — works over HTTPS remotely |
+| 📄 **OpenAPI integration** | Disabled / env-gated routes hidden from `/docs`; deprecated routes flagged automatically |
+| 📋 **Audit log** | Every state change is recorded: who, when, what route, old status → new status |
+| ⏰ **Scheduled windows** | `asyncio`-native scheduler — maintenance windows activate and deactivate automatically |
+| 🔔 **Webhooks** | Fire HTTP POST on every state change — built-in Slack formatter and custom formatters supported |
+| 🎨 **Custom responses** | Return HTML, redirects, or any response shape for blocked routes — per-route or app-wide default |
+| 🚦 **Rate limiting** | Per-IP, per-user, per-API-key, or global counters — tiered limits, burst allowance, runtime mutation |
+
+---
+
 ## Install
 
 ```bash
@@ -147,6 +175,86 @@ shield global enable --reason "Deploying v2" --exempt /health
 | `@env_only("dev", "staging")` | Restricted to named environments | 404 elsewhere |
 | `@deprecated(sunset, use_instead)` | Still works, injects deprecation headers | 200 |
 | `@force_active` | Bypasses all shield checks | Always 200 |
+| `@rate_limit("100/minute")` | Cap requests per IP, user, API key, or globally | 429 |
+### Custom responses
+
+By default, blocked routes return a structured JSON error body. You can replace it with anything — HTML, a redirect, plain text, or your own JSON — in two ways:
+
+**Per-route** — pass `response=` directly on the decorator:
+
+```python
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, RedirectResponse
+from shield.fastapi import maintenance, disabled
+
+def maintenance_page(request: Request, exc: Exception) -> HTMLResponse:
+    return HTMLResponse(
+        f"<h1>Down for maintenance</h1><p>{exc.reason}</p>", status_code=503
+    )
+
+@router.get("/payments")
+@maintenance(reason="DB migration", response=maintenance_page)
+async def payments():
+    return {"payments": []}
+
+@router.get("/orders")
+@maintenance(reason="Upgrade in progress", response=lambda *_: RedirectResponse("/status"))
+async def orders():
+    return {"orders": []}
+```
+
+**Global default** — set once on `ShieldMiddleware`, applies to every route without a per-route factory:
+
+```python
+app.add_middleware(
+    ShieldMiddleware,
+    engine=engine,
+    responses={
+        "maintenance": maintenance_page,   # all maintenance routes
+        "disabled": lambda req, exc: HTMLResponse(
+            f"<h1>Gone</h1><p>{exc.reason}</p>", status_code=503
+        ),
+    },
+)
+```
+
+Resolution order: **per-route `response=`** → **global `responses[...]`** → **built-in JSON**. The factory can be sync or async and receives the live `Request` and the `ShieldException` that triggered the block.
+
+## Rate limiting
+
+```python
+from shield.fastapi.decorators import rate_limit
+
+@router.get("/public/posts")
+@rate_limit("10/minute")               # 10 req/min per IP
+async def list_posts():
+    return {"posts": [...]}
+
+@router.get("/users/me")
+@rate_limit("100/minute", key="user")  # per authenticated user
+async def get_current_user():
+    ...
+
+@router.get("/reports")
+@rate_limit(                           # tiered limits
+    {"free": "10/minute", "pro": "100/minute", "enterprise": "unlimited"},
+    key="user",
+)
+async def get_reports():
+    ...
+```
+
+Policies can be mutated at runtime without redeploying (`shield rl` and `shield rate-limits` are aliases):
+
+```bash
+shield rl set GET:/public/posts 20/minute   # raise the limit live
+shield rl reset GET:/public/posts           # clear counters
+shield rl hits                              # blocked requests log
+```
+
+Requires `api-shield[rate-limit]`. Powered by [limits](https://limits.readthedocs.io/en/stable/).
+
+---
 
 ## Backends
 
@@ -156,6 +264,8 @@ shield global enable --reason "Deploying v2" --exempt /health
 | `FileBackend` | Yes | No |
 | `RedisBackend` | Yes | Yes |
 
+For rate limiting in multi-worker deployments, use `RedisBackend` — counters are atomic and shared across all processes.
+
 ---
 
 ## Documentation
@@ -166,6 +276,7 @@ Full documentation at **[attakay78.github.io/api-shield](https://attakay78.githu
 |---|---|
 | [Tutorial](https://attakay78.github.io/api-shield/tutorial/installation/) | Get started in 5 minutes |
 | [Decorators reference](https://attakay78.github.io/api-shield/reference/decorators/) | All decorator options |
+| [Rate limiting](https://attakay78.github.io/api-shield/tutorial/rate-limiting/) | Per-IP, per-user, tiered limits |
 | [ShieldEngine reference](https://attakay78.github.io/api-shield/reference/engine/) | Programmatic control |
 | [Backends](https://attakay78.github.io/api-shield/tutorial/backends/) | Memory, File, Redis, custom |
 | [Admin dashboard](https://attakay78.github.io/api-shield/tutorial/admin-dashboard/) | Mounting ShieldAdmin |

api_shield-0.3.0/PR_DESCRIPTION.md

@@ -0,0 +1,34 @@
+# Rate Limiting
+
+Adds full rate limiting support to api-shield.
+
+## What's new
+
+**`@rate_limit` decorator**
+
+- Limit requests per IP, user, API key, or globally with a single decorator
+- Tiered limits (`{"free": "10/min", "pro": "100/min"}`) resolved from request state
+- Burst allowance, exempt IPs, exempt roles
+- Custom 429 response factory — per-route via `response=` or app-wide via `ShieldMiddleware(responses={"rate_limited": ...})`
+- Works as `Depends()` without middleware
+- Sync and async custom key functions supported
+
+**Algorithms** — `fixed_window`, `sliding_window`, `moving_window`, `token_bucket` (via [limits](https://limits.readthedocs.io/en/stable/) >= 5.8.0)
+
+**Storage** — auto-selected from the active backend: `MemoryRateLimitStorage`, `FileRateLimitStorage`, `RedisRateLimitStorage`. Pass `rate_limit_backend=` to use a different backend for counters.
+
+**Dashboard** — Rate Limits tab at `/shield/rate-limits` with reset, edit, delete actions. Blocked requests log at `/shield/blocked`.
+
+**CLI** — `shield rl list|set|reset|delete|hits` (`shield rate-limits` is an alias).
+
+**Audit log** — policy changes recorded with action badges: `set`, `update`, `reset`, `delete`.
+
+**Response headers** — `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` on every request; `Retry-After` on 429s.
+
+## Other changes
+
+- `mypy --strict` passes across all 36 source files
+- `ruff check` passes with no errors
+- `limits` version constraint updated to `>=5.8.0`
+- Dependency injection example corrected — decorator and `Depends()` are mutually exclusive patterns, not combined
+- Full documentation added: rate limiting tutorial, reference, and updates to all relevant pages (README, adapters, CLI, dashboard, backends, changelog)