ferryman

Small L7 reverse proxy in Rust — prefix routing, per-upstream circuit breakers, active health checks, hot-reloaded TOML config. Pingora-pattern at miniature scale. Built to be readable in one sitting.

The problem

Typical self-hosted setups expose services on direct ports or tunnels with no L7 in front. Real teams put L7 proxies between clients and origin: routing, health checks, observability, TLS termination. ferryman is a hyper-based reverse proxy that does the boring parts well and exposes the interesting tradeoffs — circuit-breaker state machine, atomic config hot-reload, prefix-longest-match routing — in code small enough to read top-to-bottom.

Architecture

                    +-----------------------------+
                    |    ferryman :443/:80        |
                    |  hyper 1.x + tower stack    |
                    +--+--------------------------+
                       |
                       |  1. parse req.uri.path
                       |  2. longest prefix match on a path-segment
                       |     boundary (no match -> 404)
                       |  3. ask the upstream's breaker (open -> 503)
                       |  4. rebuild URI, stream via hyper client
                       v
       +---------------+---------+----------+
       |               |         |          |
   svc-A:8001     svc-B:8002  svc-C:8003  ...
       ^               ^         ^
       |               |         |
       +-------+-------+---------+
               |
        Background task:
        - active /health every 5s (any answer < 500 = up)
        - lock-free closed / open / half-open breaker
        - N consecutive failures: open for cooldown (30s)
        - after cooldown: exactly one half-open probe
        - health success: close immediately

Routing rules: TOML, hot-reloaded via `notify` filesystem watch + arc-swap.

Stack

Full pinned versions live in Cargo.toml. Default routing rules: config.toml.

Quick start

# Install the binary from crates.io:
cargo install --locked ferryman
ferryman --config config.toml

# Build and run against the example config (2 upstreams, 5s health interval).
cargo run -p ferryman -- --config config.toml

# Optional: local upstreams that answer 200 on every path.
cargo run --release -p ferryman --example echo_upstream -- 127.0.0.1:8001 &

# In another shell, hit a route:
curl -i http://localhost:8080/svc-a/hello
# HTTP/1.1 502 bad gateway          (no svc-a:8001 listening yet)
# HTTP/1.1 503 upstream unavailable (once its circuit has opened)
curl -i http://localhost:8080/no-such-route
# HTTP/1.1 404 no route

# Optional TLS termination (HTTP/2 via ALPN):
cargo run -p ferryman -- --config config.toml \
    --tls-cert cert.pem --tls-key key.pem

# Scrape Prometheus metrics:
curl -s http://localhost:9090/metrics | head

Edit config.toml while ferryman is running — the routing table reloads atomically without dropping live connections.

Configuration

See config.toml. Unknown keys are rejected, so typos fail loudly instead of silently falling back to defaults.

Routes pointing at the same host:port share one circuit breaker. A hot reload keeps each surviving upstream's breaker, so an open circuit stays open across a config edit. An invalid config on reload is logged and the old table stays live.

CLI flags (env var in brackets): --config (FERRYMAN_CONFIG), --bind (FERRYMAN_BIND, 0.0.0.0:8080), --metrics-bind (FERRYMAN_METRICS_BIND, 0.0.0.0:9090), --tls-cert / --tls-key (FERRYMAN_TLS_CERT / FERRYMAN_TLS_KEY).

Behaviour

Request and response bodies are streamed, never buffered. Hop-by-hop headers are stripped both ways; x-forwarded-for and x-forwarded-proto are set; the client's Host is kept (HTTP/2 :authority becomes Host). Upstreams always get HTTP/1.1. Slow clients are cut off after 10s of header reading or TLS handshake. SIGINT/SIGTERM stop accepting and drain in-flight connections for up to 25s.

Metrics endpoints

The Prometheus exporter binds a separate listener (default :9090). Surface:

route is the configured prefix and upstream is host:port, so label cardinality is bounded by the config, never by client input.

Bench targets (per projects-l3-l4.md § P2)

Run with benches/wrk2.lua:

wrk2 -c 1000 -t 16 -R 50000 -d 60s \
     -s benches/wrk2.lua \
     http://localhost:8080/svc-a/echo

Repository layout

ferryman/
  Cargo.toml                 # workspace
  config.toml                # example routing config
  crates/
    core/                    # breaker, RouteTable, health loop, TOML schema
      benches/lookup.rs      # criterion bench for RouteTable::lookup
    server/                  # serve loop, proxy handler, TLS, reload watcher
      tests/proxy.rs         # end-to-end tests on real sockets
  benches/wrk2.lua           # wrk2 harness for the throughput target
  benches/bench.toml         # routing config for the compose fixture
  docker-compose.bench.yml   # ferryman + two http-echo upstreams
  scripts/wrk2-smoke.sh      # boots the compose fixture and runs wrk2
  Dockerfile                 # cargo-chef multi-stage, scratch final (musl)
  fly.toml                   # Fly.io 2-region (sin + iad)
  deny.toml                  # cargo-deny config
  rust-toolchain.toml        # stable channel
  .github/workflows/ci.yml   # nextest + clippy + fmt + deny + bench + wrk2
  docs/
    architecture.md          # internals: request path, breaker, reload
    specs/2026-05-28-ferryman-design.md
    plans/2026-05-28-ferryman-phase-1-scaffold.md
    plans/2026-09-26-ferryman-phase-2.md
  PROGRESS.md

Limitations

• Upstreams are plain HTTP only; https:// upstreams are rejected.
• No WebSocket / Upgrade passthrough (501).
• No per-upstream load balancing: one route, one upstream.
• Kubernetes ConfigMap mounts update via a ..data symlink swap that the file watcher does not see; restart the pod after a ConfigMap edit.
• The response body has no idle timeout once headers have arrived.

Roadmap

How it works inside: docs/architecture.md.

Phases and bench numbers are tracked in PROGRESS.md. P4 (ferryman-edge) layers mTLS + JWT + cert hot-reload on top of this base; see projects-l3-l4.md § P4.

License

Dual-licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.