reference.md

Filter Reference

Built-in filters organized by protocol and category.

HTTP / Observability

Filter	Feature	Description
access_log	-	Logs structured access records for each request and response.
request_id	-	Ensures every request carries a correlation ID.

HTTP / Payload Processing

Filter	Feature	Description
compression	-	Enables Pingora's built-in response compression when present in a filter chain.
json_body_field	-	Extracts top-level fields from a JSON request body and promotes their values to request headers using [StreamBuffer] mode.
json_rpc	-	Extracts JSON-RPC 2.0 envelope metadata from request bodies and promotes method, id, and kind to request headers and filter results for routing.

HTTP / Security

Filter	Feature	Description
basic_auth	-	HTTP Basic Authentication filter (RFC 7617).
cors	-	Spec-compliant CORS filter implementing origin validation, preflight handling, and response header injection.
credential_injection	-	Injects per-cluster API credentials into upstream requests.
csrf	-	CSRF protection filter that validates request origins against a trusted allowlist.
forwarded_headers	-	Injects X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host headers into upstream requests.
guardrails	-	Rejects requests matching string, regex, or PII rules against headers and/or body content.
ip_acl	-	IP-based access control filter.
peer_identity_trust	-	Validates that the downstream mTLS peer identity matches a configured trusted peer before allowing the request to continue.
policy	-	Embeds the CPEX policy engine in-process to enforce multi-source JWT identity, APL route policy, RFC 8693 token exchange, PII scanning, audit emission, and (under body_access: read_write) request / response body rewriting.

HTTP / Traffic Management

Filter	Feature	Description
circuit_breaker	-	Rejects requests to clusters whose circuit is open.
endpoint_selector	-	Selects an upstream endpoint from a trusted mutation source.
grpc_detection	-	Detects gRPC requests from the content-type header and promotes the variant to filter metadata and results for downstream routing.
iterative_request_router	-	Framework-level filter for iterative sub-request execution.
load_balancer	-	Selects an upstream endpoint using the cluster's configured strategy.
rate_limit	-	Token bucket rate limiter that rejects excess traffic with 429.
redirect	-	Returns a redirect response without contacting any upstream.
router	-	Routes requests to clusters based on path prefix and host header.
static_response	-	Returns a fixed response without contacting any upstream.
timeout	-	Enforces a maximum end-to-end latency from request receipt to response headers.

HTTP / Transformation

Filter	Feature	Description
headers	-	Adds, sets, or removes headers on upstream requests and downstream responses.
path_rewrite	-	Rewrites the request path before forwarding to the upstream.
url_rewrite	-	Rewrites request URLs using regex substitution and query parameter manipulation before the request reaches upstream.

TCP / Observability

Filter	Feature	Description
tcp_access_log	-	Logs TCP connection events.

TCP / Traffic Management

Filter	Feature	Description
sni_router	-	Routes TCP connections by SNI hostname.
tcp_load_balancer	-	Selects an upstream TCP endpoint using the cluster's configured strategy.