Reverse Proxy in Rust (Hyper + Tokio)

Production-style reverse proxy focused on correctness, resiliency, and observability.

Why This Project Is Recruiter-Ready

• Clear service architecture with separated stages: ingress, routing, request/response transforms, upstream client, and telemetry.
• Real operational features: health checks, readiness checks, graceful shutdown/drain, backpressure controls.
• Resilience controls implemented in code: retries with backoff and jitter, health-aware routing, per-upstream circuit breaker.
• Security hardening: trusted proxy policy for forwarded headers and optional bearer auth for /metrics.
• Automated quality gates in CI: format check, clippy (warnings denied), and full test suite.
• Integration tests validating behavior under failure and load-like conditions.

Architecture

Request flow:

Ingress -> Routing/LB -> Request modifiers -> Upstream client -> Response modifiers -> Metrics/Tracing

Core code paths:

• src/ingress/handler.rs
• src/routing/load_balancer.rs
• src/request/modifier.rs
• src/client/upstream.rs
• src/response/modifier.rs
• src/metrics/tracer.rs

Feature Set

• Reverse proxying with round-robin load balancing across multiple upstreams.
• Health-aware routing and active health probing.
• Circuit breaker (closed/open/half-open) per upstream.
• Retry policy for idempotent requests with exponential backoff and jitter.
• Connect timeout and request timeout controls.
• Backpressure via max_in_flight semaphore.
• Streaming mode for large request bodies.
• Graceful shutdown with drain mode and timeout.
• Endpoints: /healthz, /healthz?check=upstream, /readyz, /metrics.
• Request/response correctness: hop-by-hop header stripping, host rewrite, forwarded headers.
• Path normalization for metrics labels to avoid high-cardinality explosions.

Security Hardening Included

• Trusted proxy CIDRs via REVERSE_PROXY_TRUSTED_PROXIES.
• Untrusted clients cannot spoof X-Forwarded-For / X-Forwarded-Proto.
• Optional /metrics bearer token via REVERSE_PROXY_METRICS_BEARER_TOKEN.
• Debug upstream header exposure is opt-in (REVERSE_PROXY_EXPOSE_DEBUG_HEADERS).

Demo Artifacts

• Backpressure proof screenshot: docs/proof/pressure.png
• Health behavior screenshot: docs/proof/health.png
• Test run proof: docs/proof/proxy_features_output.txt
• Metrics sample: docs/proof/metrics_sample.txt

Example metrics excerpt:

# TYPE requests_total counter
requests_total{method="GET",path="/users/:id",status="502",status_class="5xx"} 2
requests_total{method="GET",path="/metrics",status="200",status_class="2xx"} 1
# TYPE request_latency_seconds summary
request_latency_seconds_sum{method="GET",path="/users/:id",status="502",status_class="5xx"} 0.012

Quick Start (PowerShell)

1. Start two upstreams:

py -m http.server 9000
py -m http.server 9001

2. In another terminal, run the proxy:

$env:REVERSE_PROXY_UPSTREAMS="http://127.0.0.1:9000,http://127.0.0.1:9001"
$env:REVERSE_PROXY_HEALTHCHECK="true"
$env:REVERSE_PROXY_TRUSTED_PROXIES="127.0.0.1/32"
cargo run

3. Verify endpoints:

curl http://127.0.0.1:8000/healthz
curl http://127.0.0.1:8000/readyz
curl http://127.0.0.1:8000/metrics

If you enable metrics auth:

$env:REVERSE_PROXY_METRICS_BEARER_TOKEN="secret-token"
curl -H "Authorization: Bearer secret-token" http://127.0.0.1:8000/metrics

Quick Start (Linux/macOS)

python3 -m http.server 9000
python3 -m http.server 9001

export REVERSE_PROXY_UPSTREAMS="http://127.0.0.1:9000,http://127.0.0.1:9001"
export REVERSE_PROXY_HEALTHCHECK=true
export REVERSE_PROXY_TRUSTED_PROXIES="127.0.0.1/32"
cargo run

curl http://127.0.0.1:8000/healthz
curl http://127.0.0.1:8000/readyz
curl http://127.0.0.1:8000/metrics

Local Validation Commands

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

Selected Configuration

• REVERSE_PROXY_UPSTREAMS: comma-separated upstream URLs.
• REVERSE_PROXY_CONNECT_TIMEOUT_MS: upstream connect timeout.
• REVERSE_PROXY_MAX_IN_FLIGHT: max concurrent in-flight requests.
• REVERSE_PROXY_STREAM_LARGE_BODIES: enable streaming for large bodies.
• REVERSE_PROXY_STREAM_THRESHOLD_BYTES: streaming threshold.
• REVERSE_PROXY_HEALTHCHECK: enable active health checks.
• REVERSE_PROXY_HEALTHCHECK_INTERVAL_SECS: health check interval.
• REVERSE_PROXY_SHUTDOWN_GRACE_SECONDS: graceful drain timeout.
• REVERSE_PROXY_CIRCUIT_BREAKER: enable per-upstream breaker.
• REVERSE_PROXY_CIRCUIT_BREAKER_FAILURE_THRESHOLD: failures before open.
• REVERSE_PROXY_CIRCUIT_BREAKER_OPEN_MS: open-state duration.
• REVERSE_PROXY_RETRY_BACKOFF_BASE_MS: retry backoff base.
• REVERSE_PROXY_RETRY_BACKOFF_MAX_MS: retry backoff cap.
• REVERSE_PROXY_TRUSTED_PROXIES: trusted proxy IP/CIDR list.
• REVERSE_PROXY_METRICS_BEARER_TOKEN: optional bearer token for /metrics.
• REVERSE_PROXY_EXPOSE_DEBUG_HEADERS: expose internal debug headers.

CI

Workflow: .github/workflows/ci.yml

• cargo fmt --all -- --check
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test --all --all-features
• Runs on Ubuntu and Windows