Metadata-Version: 2.5
Name: ratelane-sdk
Version: 0.2.2
Summary: API observability and live policy control plane middleware for FastAPI
License: Proprietary
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Requires-Dist: starlette>=0.37
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# ratelane-sdk

API observability and live policy control plane middleware for FastAPI.

Ratelane gives you fleet-wide visibility and real-time policy enforcement — rate limits, route enable/disable, per-route timeouts, CORS, IP rules, circuit breakers, and request size limits — without redeploying your app. Policy changes push to all instances within 10 seconds.

## Installation

```bash
pip install ratelane-sdk
```

## Quick start

```python
from fastapi import FastAPI
from ratelane import RatelaneConfig, RatelaneMiddleware

app = FastAPI()

app.add_middleware(
    RatelaneMiddleware,
    config=RatelaneConfig(
        api_key="your_api_key",
        collector_url="https://api.ratelane.dev",
        fastapi_app=app,
        # instance_version="1.0.0",  # optional: your app version
        # framework="fastapi",        # optional: override auto-detection
    )
)
```

## Features

- **Rate limiting** — global and per-route, enforced locally with no network call on the hot path
- **Route control** — enable/disable routes with custom status codes and messages
- **Per-route timeouts** — automatic 504 on slow downstream responses
- **CORS** — dynamic allowed origins pushed from the dashboard
- **IP allowlist / denylist** — global and per-route, supports exact IPs and CIDR ranges
- **Request size limits** — Content-Length fast path + chunked stream enforcement
- **Circuit breaker** — per-route sliding window, automatic open/half-open/closed transitions
- **Emergency Profile** — automatic fallback policy when the policy server is unreachable, auto-reverts on reconnect
- **Fleet visibility** — per-instance sync status, runtime info, SDK version, and policy signature in the dashboard

## Configuration

| Field | Type | Default | Description |
|---|---|---|---|
| `api_key` | `str` | required | Your Ratelane API key |
| `collector_url` | `str` | required | Your Ratelane backend URL |
| `fastapi_app` | `FastAPI` | `None` | App reference for route discovery |
| `instance_version` | `str` | `None` | Your app's version, shown in the dashboard |
| `framework` | `str` | `"fastapi"` | Override framework label sent to the dashboard |
| `poll_interval_seconds` | `int` | `3` | How often to poll for policy updates |
| `ep_enabled` | `bool` | `True` | Enable Emergency Profile fallback |
| `ep_trigger_after_seconds` | `int` | `86400` | Seconds before EP activates |
| `request_timeout_seconds` | `float` | `5.0` | HTTP timeout for SDK requests |

## CLI

```bash
# Clear state for this project
ratelane clear --collector-url https://api.ratelane.dev --api-key sk_live_...

# Clear all Ratelane state on this machine
ratelane clear --all
```

## License

Copyright 2026 Ratelane. All Rights Reserved.