Dispatch flow
Every request goes through the same pipeline. Knowing the order makes it obvious where to plug in custom logic.
Pipeline
- Client IP —
get_client_ip(request)readsREMOTE_ADDR. If the proxy is inTRUSTED_PROXIES, falls back toX-Real-IPthenX-Forwarded-For. - Rate limit / abuse —
_enforce_rate_limit. Blocks IPs already flagged, applies the per-route limits and triggers a 24h block on abuse. - Authentication —
_authenticate. TriesAuthorization: Bearerfirst (whenBEARER_RESOLVERis configured), thenX-Api-Key, then session cookie. Setsself.userandself.account. - Token (optional) —
_enforce_token. Only whenENFORCE_TOKEN=True, validatesX-Tokenagainst the session token. - Origin (optional) —
get_allowed_domain. WhenALLOWED_ORIGINSis set, requires the requestOrigin(withRefererfallback) to match. - Tenant —
aset_tenant(account_id)switches the active database connection. - Method resolution —
get_methodlooks atroutesfor a custom match; falls back to standard CRUD. - Cache — when
cache=Trueand method is GET, builds key + namespace, runsbefore_cache, checks Redis. On hit, returns immediately. - pre_process — your hook to run anything before the body is parsed.
- Body parsing — for POST/PATCH, parses JSON; if a Pydantic schema is set, validates and replaces
self.bodywith the validated dict. - Filters / pagination / ordering — for list GET only.
- Handler — the chosen method (
get/post/patch/deleteor custom route). - Serialize — runs
dehydrate, applieslist_schemaif any, runspost_process, writes the response and saves to cache.
Full flow (ASCII)
Side-arrows ─► mark override points — methods you can replace on your resource. The dotted box shows the methods called underneath, so you see where to plug in.
┌──────────────────────────┐
│ incoming request │
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ SecurityMiddleware │ ← scanner / UA / 4xx-flood
│ blocks → 403 (24h) │ instant block
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ AuthMiddleware │ ← cookie → request.user
│ (non-resource views) │ for templates etc.
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ BaseResource.dispatch │
└────────────┬─────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
[1] get_client_ip [2] _enforce_rate_limit [3] _authenticate
REMOTE_ADDR abuse → 403 24h Bearer (opt-in)
+ X-Real-IP 429 if too fast → X-Api-Key
if proxy trusted → cookie
→ self.user
→ self.account
│
▼
┌──────────────────────────┐
│ authenticated=True │ no session → 401
│ but no session? │
└────────────┬─────────────┘
│
▼
[4] _enforce_token (X-Token HMAC, when ENFORCE_TOKEN)
[5] get_allowed_domain (Origin/Referer, when ALLOWED_ORIGINS)
[6] aset_tenant(account.id) ← switch tenant DB
│
▼
┌──────────────────────────┐
│ get_method (routes) │ → custom handler
│ │ OR default get/post/...
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ method allowed? │ → 405 if not
└────────────┬─────────────┘
│
▼
┌──────────────────────────────┐
│ GET + cache=True ? │
└─┬──────────────────────────┬─┘
│ yes │ no
▼ │
┌──────────────────────────┐ │
│ before_cache(request) │ │
│ build cache_key + ns │ │
│ Redis GET │ │
└─────┬─────────────┬──────┘ │
│ HIT │ MISS │
▼ ▼ ▼
return cached └──────┬────────────┘
│
▼
┌──────────────────────────┐
│ pre_process(request) │ ← your hook
└────────────┬─────────────┘
│
▼
┌──────────────────────────────┐
│ POST/PATCH ? │
└─┬──────────────────────────┬─┘
│ yes │ no
▼ │
┌──────────────────────────┐ │
│ parse JSON body │ │
│ Pydantic validate │ │
│ (create/update_schema) │ │
│ → 422 on failure │ │
│ hydrate(body) hook │ │
└────────────┬─────────────┘ │
│ │
└──────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ GET list (no id) ? │
└─┬──────────────────────────┬─┘
│ yes │ no
▼ │
┌──────────────────────────┐ │
│ build_filters(request) │ │
│ get_filters(request) │ ?filter= │
│ paginate(request) │ │
│ ordenate(request) │ │
└────────────┬─────────────┘ │
│ │
└──────────┬───────────────┘
│
▼
┌──────────────────────────┐
│ apply queryset_filter │
└────────────┬─────────────┘
│
▼
┌───────────────────────────────────┴───────────────────────────────────┐
│ handler runs │
│ │
│ ┌─────────────┐ ┌──────────────┐ │
│ │ GET │ ─► │ get(request) │ override to replace entirely │
│ └──────┬──────┘ └──────┬───────┘ │
│ │ │ │
│ │ ┌─────────┴───────────┐ │
│ │ ▼ ▼ │
│ │ has self.id? no id │
│ │ │ │ │
│ │ ▼ ▼ │
│ │ ┌──────────────┐ ┌─────────────┐ │
│ │ │ get_obj(id) │ ─► │ get_objs │ ─► override for │
│ │ └──────┬───────┘ │ (request) │ custom listing, │
│ │ │ └──────┬──────┘ aggregations, │
│ │ ▼ ▼ non-ORM source │
│ │ ┌──────────────┐ ┌─────────────┐ │
│ │ │ alter_detail │ ─► │alter_list │ ─► reshape result │
│ │ └──────────────┘ └─────────────┘ │
│ │
│ ┌─────────────┐ ┌──────────────┐ │
│ │ POST │ ─► │ post(request)│ │
│ └──────┬──────┘ └──────┬───────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌────────────────────┐ │
│ │ │ create_obj(req, │ ─► override for side │
│ │ │ body) │ effects (email, │
│ │ ├────────────────────┤ webhook), or replace │
│ │ │ • create_fields ✓ │ when no model exists │
│ │ │ • auto-fill │ │
│ │ │ created_by / │ │
│ │ │ updated_by / │ │
│ │ │ owner_id │ │
│ │ │ • blank/null check │ │
│ │ │ • acreate │ │
│ │ │ • custom_* save │ │
│ │ │ • m2m save │ │
│ │ │ • get_obj(new_id) │ ─► uses your get_obj │
│ │ └────────────────────┘ │
│ │
│ ┌─────────────┐ ┌──────────────┐ │
│ │ PATCH │ ─► │ patch(request)│ │
│ └──────┬──────┘ └──────┬───────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌────────────────────┐ │
│ │ │ update_obj(id,body)│ ─► override to enforce │
│ │ ├────────────────────┤ field-level rules, │
│ │ │ • update_fields ✓ │ or replace entirely │
│ │ │ • aget(pk=id) │ │
│ │ │ • self.diff[k] = │ │
│ │ │ {old, new} │ │
│ │ │ • aupdate(...) │ │
│ │ │ • get_obj(id) │ │
│ │ └────────────────────┘ │
│ │
│ ┌─────────────┐ ┌──────────────┐ │
│ │ DELETE │ ─► │delete(request)│ │
│ └──────┬──────┘ └──────┬───────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌────────────────────┐ │
│ │ │ delete_obj(id) │ ─► override for │
│ │ ├────────────────────┤ soft-delete, cascade, │
│ │ │ • _ownership_filter│ audit │
│ │ │ • adelete │ │
│ │ └────────────────────┘ │
└───────────────────────────────────┬───────────────────────────────────┘
│
▼
exception? ──yes──▶ HTTPException → render JSON
│ any other → log +
│ sanitized 500
│ (DEBUG=False)
▼
┌──────────────────────────────────────────────────────────────────────┐
│ serialize(result) │
│ │
│ for each row in result: │
│ ┌──────────────────┐ │
│ │ dehydrate(row) │ ─► override to strip secrets, add computed │
│ └──────────────────┘ fields, format dates │
│ │
│ ┌──────────────────┐ │
│ │ list_schema │ ─► Pydantic-shape every row (drops extras, │
│ │ (if set) │ coerces types) — set list_schema attribute │
│ └──────────────────┘ │
│ │
│ ┌──────────────────┐ │
│ │ post_process │ ─► override for last-chance modification │
│ │ (response) │ (audit logs from self.diff, etc.) │
│ └──────────────────┘ │
│ │
│ ┌──────────────────┐ │
│ │ save_cache │ ─► only when cache=True and method=GET │
│ │ (if cache=True) │ override to change TTL / namespace │
│ └──────────────────┘ │
│ │
│ JsonResponse(... encoder=CustomJSONEncoder ...) │
└────────────────────────────────┬──────────────────────────────────────┘
│
▼
┌──────────────────────────┐
│ invalidate_cache │ ← writes only
│ (POST/PATCH/DELETE) │ by namespace
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ ExceptionMiddleware │ ← if HTTPException
│ renders JSON │ escaped
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ JSON response │
└──────────────────────────┘Where to hook
| Need | Hook |
|---|---|
| Inject context, fetch related data | pre_process(request) |
| Add request data into the cache key | before_cache(request) — mutate self.cache_key |
| Mutate request body before validation | hydrate(body) |
| Mutate one row before response | dehydrate(row) |
| Reshape the whole list | alter_list(results) |
| Reshape the whole detail | alter_detail(result) |
| Last-chance modification | post_process(response) |
Sanitized 500
In production (DEBUG=False), unhandled exceptions inside the handler are caught and turned into a JSON 500 with no stack trace. HTTPException is always re-raised because it is the controlled-error mechanism.
0-mcp by Stamatios Stamou Jr — github.com/ssjunior/0-mcp