Praxis Proxy

Architecture Overview — v0.3.1

High-Level Architecture

CLIENTS praxis server binary · CLI · Config · Hot-Reload BIN PRAXIS FRAMEWORK protocol HTTP/TCP Adapters · Health · Admin · Metrics filter Pipeline · Registry · 33 Built-in Filters core Config · Health · KV · Errors tls SNI · Certs · Reload EXTERNAL FOUNDATIONS Pingora Rustls Tokio TESTING test-utils · Shared Harness integration (94) conformance security resilience schema smoke PERFORMANCE & TOOLING Microbenchmarks (6) Comparison (vs Envoy · NGINX · HAProxy) xtask echo · debug · benchmark · lint-deps proto — Envoy ExtProc (optional)
Server (binary)
Protocol
Filter
Core
TLS
Tests
Benchmarks
xtask
External

Detailed Architecture

HTTP Request Lifecycle

Client Listener TCP accept Protocol HTTP/TCP adapter on_request filter pipeline Upstream connect + proxy on_response filter pipeline Client request phase response phase

server

praxis binary

Entry point. CLI parsing, config loading, pipeline resolution, and runtime orchestration.

main run_server commands pipelines reload watcher dump

protocol

praxis_protocol lib

Thin adapters translating Pingora callbacks into filter pipeline invocations. ArcSwap for hot-reload.

Protocol trait ListenerPipelines
http/pingora handler health metrics listener
tcp/proxy tls_setup connections

filter

praxis_filter lib

Filter pipeline engine, condition evaluation, body access, and all 33 built-in filter implementations.

HttpFilter trait TcpFilter trait FilterPipeline FilterRegistry FilterAction HttpFilterContext Rejection
pipeline/evaluate pipeline/branch pipeline/body condition factory results
Traffic Mgmt (8)
router load_balancer rate_limit circuit_breaker timeout redirect static_response grpc_detection
Security (6)
cors csrf ip_acl forwarded_headers credential_injection guardrails
AI / Inference (9)
a2a anthropic_messages_format json_rpc mcp model_to_header openai_response_store openai_responses_format openai_responses_validate prompt_enrich
Observability (2)
access_log request_id
Payload (2)
compression json_body_field
Transform (3)
header path_rewrite url_rewrite
TCP (3)
sni_router tcp_load_balancer tcp_access_log

core

praxis_core lib

Shared foundation: YAML config, validation, error types, health state, KV stores, ID generation.

Config ProxyError KvStoreRegistry
config/listener config/cluster config/filter_chain config/branch_chain
validate health kv errors id time logging connectivity

tls

praxis_tls lib

TLS configuration, certificate loading, SNI-based selection, mTLS, and certificate hot-reload.

ListenerTls ClusterTls CachedClusterTls
sni setup watcher cached client_auth

Dynamic Configuration Reload

File Watcher notify (500ms debounce) Config Parse serde_yaml Validate reject invalid Pipeline Rebuild FilterRegistry ArcSwap atomic pointer swap in-flight requests use old pipeline · new requests use new pipeline

Test Infrastructure

Shared Harness
test-utils ProxyGuard · free_port · backends · HTTP clients · TLS certs · agentic mocks
Test Suites
integration 94 test files — end-to-end filter + proxy behavior
conformance HTTP/2 (h2spec) · RFC semantics · CORS spec
security Smuggling · header injection · filter isolation
resilience Throughput · fault tolerance · recovery
schema Config parsing · example validation (8 categories)
smoke Quick startup + round-trip sanity
Fuzzing
fuzz 7 targets: config · pipeline · body · path · SNI · headers · CIDR

Performance & Tooling

Microbenchmarks (Criterion)
6 benches condition_eval · config_parsing · filter_pipeline · headers · load_balancer · router_lookup
Comparison Benchmarks
Docker vs Envoy · NGINX · HAProxy (Vegeta + Fortio)
Dev Tooling (xtask)
echo Quick HTTP test server for manual testing
debug Run proxy single-threaded with debug logging
benchmark Orchestrate · compare · visualize · flamegraph
lint-deps Verify three-component semver in workspace
lint-examples Ensure every example config has an integration test