Python: FastAPI, Django, Flask

camada on PyPI enforces your snapshot inside a Python process: your ordered custom rules, then allow, block and challenge, decided in-process, with events shipped off the request path. One package, with an ASGI middleware, a WSGI middleware, and integrations for FastAPI, Django and Flask.

Install

pip install camada

Python 3.10 or newer. No runtime dependencies.

Mount it

from fastapi import FastAPI
from camada.fastapi import CamadaMiddleware

app = FastAPI()
app.add_middleware(CamadaMiddleware)   # key, ingest and snapshot URLs come from the environment

# settings.py
MIDDLEWARE = [
    "camada.django.CamadaMiddleware",   # first, so it answers before anything else runs
    *MIDDLEWARE,
]

from flask import Flask
from camada.flask import init_app

app = Flask(__name__)
init_app(app)   # wraps app.wsgi_app, so camada answers before routing

from camada.asgi import CamadaASGI   # any ASGI 3 app
from camada.wsgi import CamadaWSGI   # any WSGI app

application = CamadaASGI(application)

The engine is built from the environment on the first request it sees:

export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest

Set these as environment variables: export them in the shell that starts your app, or add them in your host's settings. Python reads no .env file on its own.

An app that reads its own configuration can build the engine itself and hand it to the integration:

from camada import Camada
from camada.fastapi import CamadaMiddleware

engine = Camada(env={"CAMADA_KEY": MY_KEY, "CAMADA_INGEST_URL": MY_INGEST}, challenge_path="/api/__camada/challenge")
app.add_middleware(CamadaMiddleware, engine=engine)

Quickstarts: FastAPI, Django, Flask.

The options you will use

Environment: CAMADA_KEY, CAMADA_INGEST_URL, CAMADA_SNAPSHOT_URL, CAMADA_TRUSTED_PROXY, CAMADA_SERVERLESS=1 (lazy refresh, no poll thread), CAMADA_CHALLENGE=0, and the kill switch CAMADA_DISABLED=1, checked per request. The docs index lists what each one means.

What it does per request

1. Keeps the snapshot fresh off the request path: a daemon thread polls at the cadence your tenant config sets (gzip on the wire, 304 when nothing changed), and asks for snapshot v5, the container that carries your ordered custom rules. CAMADA_SERVERLESS=1 refreshes lazily instead.
2. Resolves the client from the socket peer, combined with X-Forwarded-For only under your trusted-proxy setting. A raw forwarded header is never trusted without one.
3. Runs your ordered custom rules, then the allow, block and challenge lists. A blocked request gets 403 with x-block-reason (and x-block-rule when a rule decided) before your app runs. The event still ships, marked as an SDK block so it is not confused with your own 403s.
4. A challenged browser gets the proof-of-work page; an API call reaches your app, and its response carries x-camada-challenge: 1 for your frontend to act on. A request whose IP cannot be resolved is let through. See challenge.
5. Serves the beacon endpoints, then runs your app with x-rid and the _sfp session cookie on its response, and ships one batched, redacted event with its real status and latency when the response is done. An exception in your app ships as st: 500 and propagates unchanged.

Add the beacon

Bots that never run JavaScript are the cheapest to catch. Put the tag in the <head> of the pages you render and the middleware does the rest:

from camada.fastapi import script_tag

@app.get("/", response_class=HTMLResponse)
async def home(request: Request):
    return f"<html><head>{script_tag(request)}</head><body>…</body></html>"

script_tag(request) (Flask: script_tag()) returns a <script src="/_cam/b.js?r=…" async> tag carrying this request's event id, so the beacon is joined to the page view it came from. The middleware serves the script at GET /_cam/b.js (cacheable for an hour) and relays POST /_cam/fp onto the event batch, stamped with the client address camada resolved — never the one the body claims. Both endpoints sit behind the verdict, so a blocked client gets 403 there too. Turn the beacon off in the project's settings and the tag becomes empty and both endpoints fall through to your app.

Report what your app knows

The wire shows a POST /login; only your handler knows whether it failed. Tell camada from the handler:

from camada.fastapi import track

@app.post("/login")
async def login(request: Request, form: LoginForm):
    ok = await sign_in(form)
    if not ok:
        track(request, "login_failed", user=form.email)   # hashed in-process; never raises
    return RedirectResponse("/") if ok else JSONResponse({"error": "invalid"}, 401)

track(request, event, user=…) (Django the same; Flask track(event, user=…)) ships the outcome joined to this request's event and session. The user identifier is hashed in-process with your ingest token before it is queued — the raw value never leaves the process. It never raises. The event name is free-form; the analyst's rules read this vocabulary:

A route you want to gate yourself can serve the challenge on demand:

from camada.fastapi import serve_challenge   # Django: camada.django, Flask: camada.flask

@app.get("/export")
async def export(request: Request):
    if answer := serve_challenge(request):
        return answer          # the proof-of-work page (or 403 JSON) until this browser holds a valid _cch
    return big_file()

What this position sees

The same position as @camada/node, in a Python process: the final status and latency, the session, the beacon's browser signals and your app's outcomes. Under ASGI (FastAPI, Starlette, async Django) the event also carries the wire's header order; WSGI (Flask, sync Django) loses it, which is why the plan calls ASGI the first-class tier — camada knows what this tap can see from the position itself and never scores the absence of header order as evidence against a request. No ASN, country or TLS fingerprint reaches a Python process, so those conditions fail open in-app and the analyst resolves ASN and country itself. What a rule can key on is on rules and list entries.

Deploying it

• Every worker process polls its own snapshot (about 5 MB resident each) and ships its own batches; the tenant's poll_seconds keeps the cadence honest across a fleet.
• Threads do not survive a fork. Under gunicorn --preload or uWSGI the SDK notices the fork and restarts its poll and flush threads in each worker.
• Pending events drain at interpreter exit within half a second. The SDK installs no signal handlers — an app owns its own shutdown — so a worker killed by SIGTERM without one may drop its last batch.
• Serverless hosts: CAMADA_SERVERLESS=1. A cold invocation fails open and catches up on the next request.

It fails open

Without a key the middleware is inert: one log line, no requests, no enforcement, so an unprovisioned environment behaves exactly as if camada were not installed. Beyond that, a dead ingest, a corrupt snapshot or a bug in the package costs you the telemetry, never the request — camada can never turn one of your responses into a 5xx. The whole stance is on the security page.