A configurable TLS-terminating reverse proxy built on Cloudflare's Pingora.
It listens on a single address, terminates TLS per hostname (SNI), routes requests to upstream backends by Host header, and runs a pluggable chain of request filters per host before proxying.
- SNI-based TLS termination. One listener serves many hostnames, each with its own certificate.
- Host-header routing. Each request is matched to an upstream by its
Hostheader. - Pluggable filter chain. Per-host filters run before the upstream call. Any filter can short-circuit the request and write its own response.
- Upstream TLS. Toggle
proxy_tlsper host to proxy to HTTPS or plain HTTP backends. - Header rewriting. Replaces the
Serverheader withCloudflareand stripsalt-svc(Pingora does not speak HTTP/3 to clients).
A request flows through five stages:
- TLS handshake (
services/service.rs). ACallbackpreloads each host's cert and key at startup. On each handshake, it reads the SNI, finds the matching entry, and sets that cert and key on the connection. One listener thus serves many hostnames. - Request filter (
services/proxy.rs::ProxyService::request_filter). Extracts theHostheader, looks up the matchingHostConfig, stashes it and the request path inProxyCtx, then runs each filter in order. A filter returningOk(true)writes its own response and stops the pipeline. Unknown hosts get400 Bad Request. - Upstream peer (
ProxyService::upstream_peer). Builds anHttpPeerfromctx.host_config— the upstream address, TLS flag, and SNI/Host to send upstream. - Response filter (
ProxyService::response_filter). Rewrites the upstream response: setsServer: Cloudflare, removesalt-svc. - Logging (
ProxyService::logging). Logs the response code and a request summary.
client
│ TLS (SNI selects cert)
▼
request_filter ── Host header → HostConfig lookup → filter chain
│
▼
upstream_peer ── proxy_addr, proxy_tls, proxy_hostname
│
▼
upstream
│
▼
response_filter ── rewrite Server, strip alt-svc
│
▼
client
src/
main.rs entry point: load config, build HostConfigs, register the proxy service
config.rs TOML schema + Filter enum (serde tag = "type", content = "args")
prelude.rs Result alias + W<T> wrapper
services/
mod.rs HostConfig / HostConfigs (HashMap<hostname, HostConfig>)
service.rs TLS callback + proxy_service_tls wiring
proxy.rs ProxyService implementing pingora::ProxyHttp
request_filter.rs FilterRequest trait + built-in filters
Configure the gateway with a TOML file (default path: config.toml next to the binary, or set CARGO_MANIFEST_DIR).
[proxy_service]
listen_addr = "0.0.0.0:8999"
# Optional: trusted root CA for verifying upstream TLS
root_cert_path = "root.pem"
# one.one.one.one
[[proxy_service.host_configs]]
proxy_addr = "1.1.1.1:443" # upstream address
proxy_tls = true # TLS to upstream
proxy_hostname = "one.one.one.one" # SNI/Host sent upstream; also the routing key
cert_path = "./keys/one.one.one.one.pem"
key_path = "./keys/one.one.one.one-key.pem"
[[proxy_service.host_configs.filters]]
type = "DefaultResponseFilter"
[[proxy_service.host_configs.filters]]
type = "SimplePathFilter"
args = "/ws"
# one.one.one.two
[[proxy_service.host_configs]]
proxy_addr = "1.1.1.2:443"
proxy_tls = false
proxy_hostname = "one.one.one.two"
cert_path = "./keys/one.one.one.two.pem"
key_path = "./keys/one.one.one.two-key.pem"
[[proxy_service.host_configs.filters]]
type = "DefaultResponseFilter"| Field | Description |
|---|---|
proxy_service.listen_addr |
Address the gateway listens on. |
proxy_service.root_cert_path |
Optional path to a trusted root CA bundle for verifying upstream TLS. |
host_configs[].proxy_addr |
Upstream host:port. |
host_configs[].proxy_tls |
Use TLS when connecting to the upstream. |
host_configs[].proxy_hostname |
Hostname sent upstream (SNI/Host); also the key for Host-header routing. |
host_configs[].cert_path |
PEM certificate for TLS termination. |
host_configs[].key_path |
PEM private key for TLS termination. |
host_configs[].filters |
Ordered list of filters (see below). |
Filters implement the FilterRequest trait. Each filter runs in order; returning Ok(true) writes the response and stops the chain.
| Filter | Args | Behavior |
|---|---|---|
DefaultResponseFilter |
none | If the path is /, respond 200 with body Connecting... and stop. Otherwise pass through. |
SimplePathFilter |
path string | Allow only requests whose path starts with path; otherwise respond 404 and stop. |
- Implement
FilterRequestinsrc/services/request_filter.rs. - Add a variant to the
Filterenum insrc/config.rswith#[serde(tag = "type", content = "args")]. - Map it to an
Arc<dyn FilterRequest>inFilter::get_filter_fn.
docker compose -f ./docker-compose-example.yaml upThe example compose file mounts config.example.toml as config.toml and a ./keys/ directory for certificates, and maps host port 8080 to the gateway's 8999.
cargo build --release
RUST_LOG=debug ./target/release/pingora-gatewayThe binary loads config.toml from CARGO_MANIFEST_DIR; override by setting that env var (the Docker image sets it to /gateway).
With the example config proxying one.one.one.one to Cloudflare's DNS endpoint:
curl --connect-to one.one.one.one:443:127.0.0.1:8080 https://one.one.one.one/ -vkMIT