Overview
Every request SBproxy accepts runs through one pipeline: a fixed sequence of stages, each named after the Pingora callback that implements it. A rejection at any stage short-circuits the rest and writes the error response immediately. This page walks the sequence in order and names every point where a hook, an extension bundle, a script, or a plugin trait can attach.
The pipeline at a glance
request_filter
Trace context, ACME challenge, /health and /metrics
Hostname match -> origin resolution
Force-SSL redirect, allowed methods, CORS preflight
Bot detection (identity hooks attach here)
Threat protection (JSON body checks)
Authentication (auth hook attaches here)
Policy enforcement (policy + CEL/Rego hooks attach here)
Response cache lookup
on_request callbacks (webhook callback attaches here)
Forward rule matching -> action dispatch
upstream_peer (RoutingStrategy / ai_routing hook attaches here)
upstream_request_filter (request rewrite)
[ the origin call: proxy / ai_proxy / MCP / A2A / payment-gated ]
response_filter (AnomalyDetectorHook runs here, on_response callback attaches here)
response_body_filter (transform pipeline attaches here, response cache write)
logging (metrics, access log, typed event bus)Connection through dispatch
A client connects and sends a request with a Host header. SBproxy resolves the hostname against origins:, then runs a fixed sequence of pre-request checks: force-SSL redirect, allowed methods, CORS preflight, bot detection, threat protection, authentication, and policy enforcement. Every built-in auth provider (API key, JWT, basic, bearer, digest, forward-auth, mTLS, OIDC, Web Bot Auth, cap) runs at the authentication step; every policy (rate limiting, IP filtering, WAF, CSRF, DDoS protection, object authorization, and more) runs at the policy step, alongside any CEL, Rego, or extension-bundle policy hook.
A response cache hit can short-circuit everything that follows. Otherwise, on_request callbacks fire, forward rules match, and the action dispatches by type: proxy, load_balancer, ai_proxy, static, redirect, websocket, grpc, and more.
Upstream selection and the traffic-type branch
For proxy and load_balancer actions, this is where a custom RoutingStrategy can attach beyond the built-in strategies, and where an ai_routing extension-bundle hook can pick the provider and model for an ai_proxy origin on every request. The actual origin call then branches by traffic type:
- Plain HTTP - an ordinary reverse-proxy call.
- AI - a request to a hosted provider or local model. Guardrail mesh hooks and, for streaming tool calls, an
ai_tool_callhook can each release, flag, block, or rewrite content in place before the next hook runs. - MCP / A2A - a JSON-RPC tool call or an agent-to-agent envelope.
- Payment-gated - an HTTP 402 challenge and settlement round trip gates the call to the origin.
Response, transforms, and logging
On the way back, response headers, security headers, cookies, and on_response callbacks all run in response_filter. This is also where an anomaly-detection hook dispatches, not at request time as its name might suggest: it runs once every signal (TLS fingerprint, ML classification, headless detection, request rate) has been populated.
Transforms modify the response body next, in the order declared under transforms:. This is their one attachment point in the pipeline, and four of the built-in transform types are themselves a scripting hook (CEL, Lua, JavaScript, WASM), so the stage is both a fixed set of reshaping operations and its own extension point. A response cache write happens here too, on a miss.
Metrics, the structured access log, and the typed event bus close out the pipeline.
Where to attach custom logic
| You want to... | Attach at | Mechanism |
|---|---|---|
| Resolve a custom agent identity | Bot detection | Identity resolver hook |
| Authenticate with custom logic | Authentication | Extension-bundle auth hook |
| Add a custom policy | Policy enforcement | CEL, Rego, or extension-bundle policy hook |
| Fetch external data mid-request | on_request / on_response | Webhook callback |
| Pick a custom upstream | upstream_peer | RoutingStrategy trait |
| Pick an AI provider or model dynamically | upstream_peer, AI branch | ai_routing hook |
| Inspect or mutate an AI guardrail or tool call | AI origin call | Guardrail / tool-call hooks |
| Reshape a response | response_body_filter | A transform, including scripting transforms |
| Detect anomalous behavior after the fact | response_filter | Anomaly-detection hook |
| React to a lifecycle event | logging | Typed event bus |