Configuration Reference

Conduit is configured with a single file in JSON or YAML format. Both are fully equivalent — YAML is recommended because it supports comments.

conduit -c conduit.yaml          # explicit path
conduit -c conduit.json          # JSON is fine too
conduit                          # auto-discover: conduit.json → conduit.yaml → conduit.yml
conduit validate -c conduit.yaml # validate without starting

Fields accept environment variable references — "$MY_VAR" is replaced at startup. This keeps secrets out of config files.

Optional build features

The binaries and Docker images published as “standard” already include the standard feature bundle (jwt, consumers, forward-auth, cache, acme — see the standard row below). Some config sections still require an additional feature flag (or --features full):

Feature Flag Config section
jwt --features jwt jwtAuth + `` templates
consumers --features consumers consumers
forward-auth --features forward-auth forwardAuth
rhai --features rhai middleware[].type: "script"
wasm --features wasm middleware[].type: "wasm"
tcp --features tcp type: "tcp" site
upload --features upload upload
redis --features redis rateLimit.store: "redis://...", cache.store: "redis://..."
cache --features cache proxy.*.cache (implies proxy)
disk-cache --features disk-cache cache.store: "disk:/path"
acme --features acme tls.acme
fault-injection --features fault-injection faultInjection
otlp --features otlp global.otlp
tokio-metrics --features tokio-metrics conduit_eventloop_lag_ms Prometheus gauge (no config key)
kubernetes --features kubernetes --kubernetes-namespace CLI flag (not a config field)
standard --features standard Bundle: jwt + consumers + forward-auth + cache + acme
static-server --no-default-features --features static-server Bundle: static + compression + hotreload (the default set minus proxy)
gateway --no-default-features --features gateway Bundle: proxy + jwt + consumers + forward-auth + cache + acme + compression
full --features full Every optional feature above (static-server and gateway are shorthands, not extra capabilities)

Download a -full binary from GitHub Releases or build from source: cargo build --release --features full. See docs/cli.md — Build features for binary sizes and details.

Table of Contents

Background

Essentials

Routing

Reliability

Caching

Authentication

Rate Limiting & Load Shedding

Transforms

Observability

Security

Middleware

Advanced

Concepts

These sections explain how Conduit behaves — not config fields you set, but background knowledge that helps understand the rest of the reference.

Request pipeline

The order in which configured features are applied for every incoming request:

Incoming request
  │
  ├─ 1. X-Request-ID injection        — auto-generate UUID v4 if absent
  ├─ 2. IP filter                     — 403 if blocked (before any auth)
  ├─ 3. CORS preflight                — OPTIONS short-circuit
  ├─ 4. Health / ACME bypass          — skip all guards for /__health__ etc.
  ├─ 5. Inflight limit                — 503 if maxInflightRequests exceeded
  ├─ 6. Site-level rate limit         — 429 if over limit
  ├─ 7. Consumers                     — identify named client (V1/V2/V3)
  ├─ 8. Basic Auth                    — 401 if credentials missing/wrong
  ├─ 9. API Key                       — 401 if key missing/wrong
  ├─ 10. JWT Auth                     — 401 if token invalid
  ├─ 11. Forward Auth                 — delegate to external service
  ├─ 12. Redirects                    — 301/308 if path matches
  ├─ 13. Fault injection              — abort/delay (testing only)
  ├─ 14. Rhai / WASM middleware       — custom scripts in order
  │
  ├─ Route matching + per-route rate limit
  ├─ Circuit breaker check
  │
  └─ Upstream request
       ├─ X-Forwarded-For / -Proto / -Host injection
       ├─ requestTransform (setHeaders / removeHeaders)
       ├─ Path rewrite (stripPrefix / rewrite rules)
       └─ Traffic mirror (fire-and-forget)

Upstream response
  ├─ CRLF header protection
  ├─ CORS / security / custom headers injection
  ├─ responseTransform
  ├─ X-Response-Time header
  ├─ Retry-on-error decision
  └─ Error masking (5xx body replacement)

Steps 7–11 are mutually exclusive in practice — only one auth method identifies the client, but multiple may be configured as fallbacks. The consumers guard runs before basicAuth and apiKey, so a consumer match takes priority.

Forwarded headers

Conduit automatically injects these headers into every proxied upstream request. No configuration is needed — they are always present.

Header Value Notes
X-Forwarded-For Client IP Appended to existing value if already present
X-Forwarded-Proto http or https Derived from whether the site has TLS configured
X-Forwarded-Host Original Host header Lets upstreams reconstruct full URLs
X-Request-ID UUID v4 Auto-generated if absent; forwarded as-is if client sends it
Via 1.1 conduit RFC 7230 §5.7 — identifies the proxy hop; appended to existing value

To remove any of these before forwarding, use requestTransform.removeHeaders:

# conduit.yaml
requestTransform:
  removeHeaders: [X-Forwarded-For, X-Forwarded-Host]

// conduit.json
{
  "requestTransform": {
    "removeHeaders": ["X-Forwarded-For", "X-Forwarded-Host"]
  }
}

skipPaths glob syntax

Many config sections accept a skipPaths list — requests whose path matches are bypassed by that feature entirely. It is not a top-level field; it appears inside basicAuth, apiKey, jwtAuth, forwardAuth, consumers, rateLimit, and logging.

Two pattern forms are supported:

Pattern Matches
/exact/path Only that exact path
/prefix/** The prefix itself, /prefix/, and any sub-path 
# conduit.yaml — example inside jwtAuth
jwtAuth:
  secret: "$JWT_SECRET"
  skipPaths:
    - /__health__ # exact match — health check bypasses JWT
    - /public/** # /public, /public/, /public/assets/logo.png, …

// conduit.json
{
  "jwtAuth": {
    "secret": "$JWT_SECRET",
    "skipPaths": ["/__health__", "/public/**"]
  }
}

Note: only /** at the end is supported as a wildcard. Patterns like /api/*/details or /**.json are treated as exact matches (no mid-path or extension wildcards).

Port and Host

# YAML
port: 8080
host: api.example.com # optional — virtual hosting

// JSON
{ "port": 8080, "host": "api.example.com" }
Field Type Default Description
port number 80 / 443 ¹ TCP port to listen on
host string — Virtual hostname. Omit to match all Host headers (catch-all)

¹ Default port is 443 when tls is configured, 80 otherwise. When no sites are configured at all, Conduit listens on 8080 as a fallback.

Use host when running multiple sites on the same process.

TLS / HTTPS

Manual certificates

# YAML
port: 443
tls:
  cert: /etc/tls/server.crt
  key: /etc/tls/server.key
  httpRedirectPort: 80

// JSON
{
  "port": 443,
  "tls": {
    "cert": "/etc/tls/server.crt",
    "key": "/etc/tls/server.key",
    "httpRedirectPort": 80
  }
}

Auto-TLS via Let’s Encrypt

Requires cargo build --features acme

# YAML
port: 443
tls:
  acme:
    email: admin@example.com
    storage: ./certs
    challenge: http-01

// JSON
{
  "port": 443,
  "tls": {
    "acme": {
      "email": "admin@example.com",
      "storage": "./certs",
      "challenge": "http-01"
    }
  }
}

TLS field reference

Field Type Default Description
cert path — PEM certificate file
key path — PEM private key file
ca path — CA bundle for upstream verification
httpRedirectPort number — Port that redirects HTTP to HTTPS
acme.email string — Contact email for ACME account
acme.storage path — Directory for certificate persistence

versions/ciphers are not currently enforced (issue #189). The fields still parse, but the way Conduit builds its TLS listeners (through Pingora’s TlsSettings) gives no way to restrict protocol versions or cipher suites — TLS 1.2 and 1.3 are always both enabled with the default rustls cipher suite set, regardless of config. (Pingora 0.9 still exposes no way to set versions or ciphers on a listener: TlsSettings::build() hard-codes TLS 1.2 and 1.3.) Setting either field is a hard validation error (fails startup with an explanation) rather than a silent no-op, so a misconfigured expectation of TLS restriction can’t go unnoticed. | acme.challenge | string | — | "http-01" or "dns-01" | | acme.directory | string | — | Custom ACME directory URL. Use "https://acme-staging-v02.api.letsencrypt.org/directory" for Let’s Encrypt staging (rate-limit-free testing) | | clientAuth | object | — | mTLS client cert verification |

Note — single cert per port: Conduit does not support per-SNI certificate selection yet. When multiple HTTPS sites share the same port, the first registered cert is used for all. Use separate ports for different certificates. (Pingora 0.9’s rustls backend can pick a certificate per SNI hostname through a custom resolver; Conduit does not install one yet.)

HTTP/2

# YAML
port: 443
tls:
  cert: ./certs/cert.pem
  key: ./certs/key.pem
http2: {} # enable HTTP/2 with defaults

// JSON
{
  "port": 443,
  "tls": { "cert": "./certs/cert.pem", "key": "./certs/key.pem" },
  "http2": {}
}

Full config with all fields:

http2:
  maxConcurrentStreams: 100
  initialWindowSize: 65535
  h2c: false   # HTTP/2 cleartext (internal gRPC without TLS)

// JSON
{
  "http2": {
    "maxConcurrentStreams": 100,
    "initialWindowSize": 65535,
    "h2c": false
  }
}
Field Type Default Description
maxConcurrentStreams number 100 Max parallel streams per connection
initialWindowSize number 65535 Flow-control window in bytes
h2c bool false Allow HTTP/2 upgrade on plaintext connections (h2c). For TLS ports HTTP/2 is negotiated via ALPN regardless. Useful for internal gRPC without TLS.

Compression

Add Content-Encoding: br / zstd / gzip / deflate to responses. Applies to static files, the metrics endpoint, and fallback responses (JSON/text body or file) — each negotiated independently against the same minBytes/types thresholds, so a small metrics scrape or error body may stay uncompressed even with compression enabled.

# YAML — shorthand (enable with defaults)
compression: true

# YAML — fine-grained
compression:
  algorithms: [br, zstd, gzip]  # Brotli first, then Zstd, then gzip
  level: 6                       # 1 = fastest, 9 = smallest
  minBytes: 1024                 # skip responses smaller than 1 KB

// JSON — shorthand
{ "compression": true }

// JSON — fine-grained
{
  "compression": {
    "algorithms": ["br", "zstd", "gzip"],
    "level": 6,
    "minBytes": 1024
  }
}

The types field filters which response Content-Types are compressed:

compression:
  algorithms: [br, gzip]
  types:
    - "text/"
    - "application/json"
    - "application/xml"
    - "application/javascript"
    - "image/svg"
Field Type Default Description
algorithms string[] ["br", "zstd", "gzip"] Compression algorithms to offer. Supported: "br" (Brotli), "zstd" (Zstandard), "gzip", "deflate"
level number 6 Compression level (1–9)
minBytes number 1024 Minimum response size to compress (bytes)
types string[] ["text/", "application/json", "application/xml", "application/javascript", "application/xhtml", "image/svg"] Content-Type prefixes to compress. Use ["*"] to compress all types (not recommended for binary content)

Response Time Header

Inject X-Response-Time: <ms> into every response.

# YAML
responseTime: true

# With custom precision
responseTime:
  digits: 3   # decimal places in the millisecond value

// JSON
{ "responseTime": true }

// JSON
{ "responseTime": { "digits": 3 } }

Proxy

The proxy object maps URL path prefixes to upstream targets.

Single upstream (shorthand)

# YAML
proxy:
  /api: "http://backend:4000"

// JSON
{ "proxy": { "/api": "http://backend:4000" } }

Multiple targets

# YAML
proxy:
  /api:
    targets:
      - "http://backend-1:4000"
      - "http://backend-2:4000"
    strategy: round-robin
    stripPrefix: true

// JSON
{
  "proxy": {
    "/api": {
      "targets": ["http://backend-1:4000", "http://backend-2:4000"],
      "strategy": "round-robin",
      "stripPrefix": true
    }
  }
}

URL rewriting

Rewrite rules are evaluated in order. The first matching rule is applied.

# YAML
proxy:
  /api:
    targets: ["http://backend:4000"]
    stripPrefix: true
    rewrite:
      - from: "^/v[0-9]+/(.+)$" # strip version prefix
        to: "/$1"
      - from: "^/users/([0-9]+)$" # migrate legacy paths
        to: "/members/$1"

// JSON
{
  "proxy": {
    "/api": {
      "targets": ["http://backend:4000"],
      "stripPrefix": true,
      "rewrite": [
        { "from": "^/v[0-9]+/(.+)$", "to": "/$1" },
        { "from": "^/users/([0-9]+)$", "to": "/members/$1" }
      ]
    }
  }
}

Proxy route field reference

Field Type Default Description
targets string[] or object[] — Upstream URLs (plain strings or {url, weight})
strategy string round-robin Load balancing — see Load balancing
stripPrefix bool false Remove matched path prefix before forwarding
hashKey string — Key for hash-based strategies: "ip", "url", "header:X-Name"
rewrite object[] — URL rewrite rules: [{from, to}] — first match wins
http2 bool false Enable HTTP/2 for upstream connections
timeout.connectMs number 3000 TCP connect timeout
timeout.sendMs number — Request send timeout
timeout.readMs number 30000 Response read timeout
timeout.firstByteMs number — Max ms to wait for first upstream response byte (overrides readMs)
timeout.perTryMs number — Per-retry timeout
websocket bool false Allow WebSocket upgrades (101 Switching Protocols) — rejected with 502 by default
retry.attempts number 0 Number of retry attempts (0 = disabled)
retry.conditions string[] — connection_error, 5xx, timeout
retry.backoffMs number 0 Wait between retries (ms)
retry.backoffJitter bool false ±50% random spread on backoffMs to avoid thundering herd
retry.budgetPercent number — Soft cap: max % of in-flight requests that may be retries
healthCheck object — Active health probes — see Health checks
backup string — Fallback URL when all primaries are unhealthy
cache object — Response cache — see Proxy cache
pool object — Connection pool — see Connection pool
rateLimit object — Per-route rate limit — see Rate limiting
upstreamTls object — TLS for HTTPS upstreams — see Upstream TLS
mirror string — Shadow URL — see Traffic mirroring
sticky.cookie string — Cookie name for sticky sessions
sticky.secret string — HMAC-SHA256 secret — Conduit signs + verifies the cookie (prevents forgery)
sticky.strict boolean false Return 503 when the pinned upstream is down (instead of routing elsewhere)
groups object[] — Two-level LB groups: [{name, targets, strategy}]
groupStrategy string round-robin Outer strategy when groups is set
priority number (0–100) 50 Request priority for load shedding — see Priority routing

Routes

The routes array matches requests before proxy / static. First match wins.

# YAML
routes:
  # Route to dedicated API v2 server — checked first
  - match:
      path: /api/v2/**
      method: [GET, POST]
      headers:
        X-Version: "2"
    proxy:
      targets: ["http://v2-backend:4000"]

  # Write operations go to write cluster
  - match:
      path: /api/**
      method: [POST, PUT, PATCH, DELETE]
    proxy:
      targets: ["http://write-api:4001", "http://write-api:4002"]
      strategy: least-conn

  # Beta users via cookie → canary backend
  - match:
      cookies:
        beta: "1" # exact: cookie beta=1
        experiment: "blue|green" # regex: blue or green
    proxy:
      targets: ["http://canary:4000"]

  # Everything else → SPA static files
  - match:
      path: /**
    static: ./dist

// JSON
{
  "routes": [
    {
      "match": {
        "path": "/api/v2/**",
        "method": ["GET", "POST"],
        "headers": { "X-Version": "2" }
      },
      "proxy": { "targets": ["http://v2-backend:4000"] }
    },
    {
      "match": {
        "path": "/api/**",
        "method": ["POST", "PUT", "PATCH", "DELETE"]
      },
      "proxy": {
        "targets": ["http://write-api:4001", "http://write-api:4002"],
        "strategy": "least-conn"
      }
    },
    {
      "match": { "path": "/**" },
      "static": "./dist"
    }
  ]
}

Each route entry has exactly three top-level fields: match, proxy, and static. Auth, rate limiting, and other policies come from the site-level config and apply to all routes uniformly.

match field Type Description
path glob Path glob — see skipPaths glob syntax
method string[] HTTP methods to match (case-insensitive)
headers object Request headers that must match (exact or regex)
query object Query parameters that must match (exact or regex)
cookies object Cookies that must match (exact or regex)

All headers, query, and cookies values are matched as full-string regex (anchored ^…$). Plain strings like "v2" or "1" match exactly; regex patterns like "blue|green" or "Bearer .+" use regex semantics. An invalid regex falls back to exact-string comparison.

Load Balancing

Set strategy inside a proxy route. All strategies skip upstreams that are currently unhealthy (failed health probes) or ejected (outlier detection).

proxy:
  /api:
    targets: ["http://a:4000", "http://b:4000"]
    strategy: least-conn # pick a strategy

Choosing a strategy

The algorithm matters less than it looks — every strategy here already skips unhealthy/ejected upstreams (health checks, not the algorithm, are what keeps traffic off a broken backend). Pick based on your actual traffic shape:

Strategy Family Picks based on Session affinity Pool change impact Best for Weak point
round-robin (default) Static Rotation order ✗ none Homogeneous upstreams, simplest default Ignores load — a slow request still gets the next slot
weighted-round-robin Static Rotation + fixed weight ✗ none Heterogeneous capacity (big primary + small standby, canary %) Weights are static — doesn’t adapt to real-time load
random Static Uniform random pick ✗ none Very large pools where a counter is unnecessary overhead Worse uniformity than round-robin at small N
least-conn Load-aware Fewest active connections ✗ none Variable response times (mixed fast reads / slow writes) O(N) scan of the pool on every request
least-response-time Load-aware Lowest probed latency ✗ none Upstreams with different hardware/geography Needs healthCheck configured, or it’s just round-robin
p2c Load-aware 2 random samples, fewer conns wins ✗ none Large pools (10+) where least-conn’s full scan is too slow Marginally less precise than true least-conn
ip-hash Affinity hash(client IP) % N by IP remaps most clients (~N/(N+1)) whenever the healthy pool size changes, incl. health ejections Soft per-IP affinity without a cookie Remaps most of the pool on any healthy-count change, not just config changes
consistent-hash Affinity hash(configurable key) % N by key same as ip-hash — % N on the healthy count, incl. health ejections Per-tenant/per-user routing, cache locality by URL Same remap caveat as ip-hash — it’s % N, not a hash ring

Rule of thumb: start with round-robin. Move to least-conn or p2c once request cost varies noticeably. Reach for ip-hash/consistent-hash only for affinity, not performance — and prefer sticky.cookie over ip-hash when you control the client, since cookie-based affinity survives healthy-pool-size changes (including health ejections) that ip-hash’s % N doesn’t.

                         ┌─────────────┐
   client ──requests──▶  │   Conduit   │
                         │  (strategy) │
                         └──────┬──────┘
             ┌───────────────────┼───────────────────┐
             ▼                   ▼                    ▼
        upstream A          upstream B           upstream C
       (healthy)            (healthy)            (ejected ✗ — skipped
                                                   by every strategy)

   round-robin / weighted-rr / random  → pick by rotation or chance
   least-conn / least-response-time / p2c → pick by current load/latency
   ip-hash / consistent-hash          → pick by hash(key) % healthy-count

round-robin (default)

Cycles through the target list in order, one request at a time. A per-route atomic counter is incremented on each request and taken modulo the number of healthy upstreams.

Request 1 → a  Request 2 → b  Request 3 → a  …

Use when: all upstreams are homogeneous (same hardware, same capacity). Simple, predictable, zero overhead.

proxy:
  /api:
    targets: ["http://a:4000", "http://b:4000", "http://c:4000"]
    strategy: round-robin # or omit — this is the default

weighted-round-robin

Like round-robin, but each upstream gets a number of slots proportional to its weight. If A has weight 3 and B has weight 1, the pattern is A, A, A, B per four requests (exact interleaving may differ, but ratios are preserved over time).

Use when: upstreams have different capacities — e.g. a beefy primary and a smaller standby, or a canary deployment receiving a fraction of traffic.

Targets must be { url, weight } objects — plain strings use weight 1.

proxy:
  /api:
    targets:
      - { url: "http://primary:4000", weight: 9 } # 90% of traffic
      - { url: "http://canary:4000", weight: 1 } # 10% canary
    strategy: weighted-round-robin

// JSON
{
  "proxy": {
    "/api": {
      "targets": [
        { "url": "http://primary:4000", "weight": 9 },
        { "url": "http://canary:4000", "weight": 1 }
      ],
      "strategy": "weighted-round-robin"
    }
  }
}

Note: conduit upstreams weight can change weights at runtime without reloading the config.

least-conn

Routes each new request to the upstream with the fewest active in-flight connections at that instant. The connection counter is incremented before the request is forwarded and decremented when the response completes (including retries and errors).

Use when: requests have highly variable response times — e.g. a mix of fast reads and slow writes. Under uniform load it behaves like round-robin; its advantage emerges when some requests stall.

proxy:
  /api:
    targets: ["http://a:4000", "http://b:4000", "http://c:4000"]
    strategy: least-conn

Tip: combine with healthCheck.maxConnectionsPerUpstream for a circuit breaker that activates when all upstreams are saturated.

least-response-time

Routes each request to the upstream with the lowest measured latency from the most recent active health probe. Falls back to round-robin during the warm-up phase before any probe has completed.

Latency is measured by the health-check prober (HEAD request to healthCheck.path). Upstreams without probe data are ranked last (u64::MAX).

Use when: upstreams have meaningfully different hardware or geographic proximity and you want to bias traffic toward the fastest one. Requires healthCheck to be configured on the route — without probes, this strategy falls back to round-robin permanently.

proxy:
  /api:
    targets:
      - "http://us-east:4000"
      - "http://eu-west:4000"
    strategy: least-response-time
    healthCheck:
      path: /health
      intervalSecs: 10

// JSON
{
  "proxy": {
    "/api": {
      "targets": ["http://us-east:4000", "http://eu-west:4000"],
      "strategy": "least-response-time",
      "healthCheck": { "path": "/health", "intervalSecs": 10 }
    }
  }
}

ip-hash

Hashes the client IP address (FNV-1a) and maps it to an upstream via hash % pool_size. The same IP always hits the same upstream — as long as the pool size doesn’t change.

Use when: you need soft session affinity without a session cookie, e.g. legacy apps that store state per-IP, or to concentrate logs from one user on one backend.

Caveat: adding or removing an upstream changes pool_size and remaps roughly half of all clients. This is hash % N (modulo), not a consistent hash ring. Use sticky.cookie for stable, cookie-based affinity.

proxy:
  /auth:
    targets: ["http://auth1:5000", "http://auth2:5000"]
    strategy: ip-hash
    hashKey: ip # default for ip-hash; can be omitted

// JSON
{
  "proxy": {
    "/auth": {
      "targets": ["http://auth1:5000", "http://auth2:5000"],
      "strategy": "ip-hash"
    }
  }
}

consistent-hash

Hashes a configurable hashKey (IP, URL, or any request header) and maps it to an upstream via hash % pool_size. Identical to ip-hash in implementation — the distinction is purely which value is hashed.

Use when: you want to route requests by tenant, user, or any other request attribute to a dedicated upstream.

The hashKey field controls what is hashed:

hashKey value Hashes Example use case
ip Client IP Per-IP affinity
url Full request URL Cache-locality — same URL always hits same backend
header:X-Name Value of header X-Name Per-tenant or per-user routing 
proxy:
  /api:
    targets:
      ["http://shard-1:4000", "http://shard-2:4000", "http://shard-3:4000"]
    strategy: consistent-hash
    hashKey: "header:X-Tenant-ID"

// JSON
{
  "proxy": {
    "/api": {
      "targets": [
        "http://shard-1:4000",
        "http://shard-2:4000",
        "http://shard-3:4000"
      ],
      "strategy": "consistent-hash",
      "hashKey": "header:X-Tenant-ID"
    }
  }
}

Same caveat as ip-hash: pool size changes remap a large fraction of keys. This is hash % N, not a Karger consistent hash ring.

random

Selects an upstream uniformly at random on each request using a fast thread-local RNG.

Use when: you want an even distribution without any coordination overhead — useful for very large pools where maintaining a round-robin counter per route is unnecessary. In practice, round-robin is usually preferred since it provides better uniformity over small sample sizes.

proxy:
  /api:
    targets: ["http://a:4000", "http://b:4000", "http://c:4000"]
    strategy: random

p2c (Power of Two Choices)

On each request, samples two upstreams at random and forwards to the one with fewer active connections. Ties are broken in favour of the first sample.

Achieves O(log log N) maximum load imbalance — dramatically better tail latency than pure random, and competitive with least-conn at scale, with O(1) selection cost (no scan of the full pool).

With a single upstream in the pool, P2C falls back to round-robin.

Use when: the upstream pool is large (10+) and least-conn would scan the entire list on every request. Also useful as a drop-in replacement for least-conn when you want reduced coordination overhead.

proxy:
  /api:
    targets:
      - "http://a:4000"
      - "http://b:4000"
      - "http://c:4000"
      - "http://d:4000"
    strategy: p2c

// JSON
{
  "proxy": {
    "/api": {
      "targets": [
        "http://a:4000",
        "http://b:4000",
        "http://c:4000",
        "http://d:4000"
      ],
      "strategy": "p2c"
    }
  }
}

Sticky sessions

Route a client to the same upstream for the duration of a session cookie, using consistent hashing on the cookie value.

proxy:
  /app:
    targets: ["http://a:4000", "http://b:4000"]
    strategy: consistent-hash
    sticky:
      cookie: session_id

// JSON
{
  "proxy": {
    "/app": {
      "targets": ["http://a:4000", "http://b:4000"],
      "strategy": "consistent-hash",
      "sticky": { "cookie": "session_id" }
    }
  }
}

If the client presents no cookie (first request), the request is routed by the configured strategy and the upstream is recorded — no cookie is set by Conduit. The application is responsible for setting the session cookie.

HMAC-signed sticky cookies

Without a secret, the cookie value is used as a raw consistent-hash key. An attacker can craft a cookie to force routing to any backend they choose.

Set sticky.secret to make Conduit sign cookies with HMAC-SHA256 and verify them on every request. Forged cookies silently fall back to normal load-balancing rather than pinning to an attacker-controlled backend.

proxy:
  /app:
    targets: ["http://a:4000", "http://b:4000"]
    strategy: consistent-hash
    sticky:
      cookie: srv_id       # Conduit sets this cookie on every response
      secret: "$STICKY_SECRET"  # HMAC key — use an env var, never hardcode
      strict: false        # true = 503 when pinned upstream is down
Option Behaviour
No secret Cookie value is the raw consistent-hash key (legacy, no forgery protection)
secret set Conduit signs the URL with HMAC-SHA256 and injects a Set-Cookie on every response
strict: false (default) If the pinned upstream is unhealthy, fall back to the next available backend
strict: true If the pinned upstream is unhealthy, return 503 Service Unavailable immediately

The injected cookie attributes are: Path=/; HttpOnly; SameSite=Lax.

How the pin is applied. With a secret set, the verified cookie names one exact upstream, and Conduit routes to that upstream directly — the configured strategy is not consulted at all while the pin can be honored. A pin is honored whenever its upstream is healthy and below maxConnectionsPerUpstream; otherwise Conduit falls back to the strategy and:

Without a secret, there is no pinned URL to honor — the cookie value is only a hash key, and routing goes through consistent-hash as usual.

Security note: store the HMAC secret in an environment variable (secret: "$STICKY_SECRET"). Rotate by changing the value and reloading; existing cookies will silently fall through to normal load-balancing for one request and then get a new signed cookie.

Upstream groups (two-level balancing)

An outer strategy picks the group; an inner strategy balances within it. groups is an array — each entry has name, targets, and optional strategy.

proxy:
  /api:
    groups:
      - name: us-east
        targets: ["http://us-east-1:4000", "http://us-east-2:4000"]
        strategy: least-conn
      - name: eu-west
        targets: ["http://eu-west-1:4000", "http://eu-west-2:4000"]
        strategy: least-conn
    groupStrategy: ip-hash # outer: same client IP always hits same region

// JSON
{
  "proxy": {
    "/api": {
      "groups": [
        {
          "name": "us-east",
          "targets": ["http://us-east-1:4000", "http://us-east-2:4000"],
          "strategy": "least-conn"
        },
        {
          "name": "eu-west",
          "targets": ["http://eu-west-1:4000", "http://eu-west-2:4000"],
          "strategy": "least-conn"
        }
      ],
      "groupStrategy": "ip-hash"
    }
  }
}

See examples/upstream-groups.yaml

Static Files

Simple directory

# YAML
static: ./dist

// JSON
{ "static": "./dist" }

Multiple directories

# YAML
static:
  - ./dist
  - ./public

// JSON
{ "static": ["./dist", "./public"] }

Path-mapped directories

# YAML
static:
  /: ./dist
  /docs: ./docs-dist

// JSON
{ "static": { "/": "./dist", "/docs": "./docs-dist" } }

Static options

# YAML
static: ./dist
staticOptions:
  index: [index.html] # default files for directory requests
  dotFiles: ignore # "ignore" | "allow" | "deny"
  preCompressed: true # serve .br / .gz if present
  etag: true # ETag / 304 Not Modified support
  lastModified: true # Last-Modified header
  maxAge: "1y" # Cache-Control max-age (humantime: "1d", "30m", "1y")

// JSON
{
  "static": "./dist",
  "staticOptions": {
    "index": ["index.html"],
    "dotFiles": "ignore",
    "preCompressed": true,
    "etag": true,
    "lastModified": true,
    "maxAge": "1y"
  }
}
Field Type Default Description
index string[] ["index.html"] Default files for directory requests
dotFiles string "ignore" "ignore", "allow", or "deny"
preCompressed bool false Serve pre-compressed .br / .gz files
etag bool true ETag + conditional GET support
lastModified bool true Last-Modified header
maxAge string — Cache-Control: max-age — humantime duration string

Redirects

redirects is an array of redirect rules.

# YAML
redirects:
  - from: /old-path
    to: "https://example.com/new-path"
    status: 301

  - from: "/blog/(.+)" # regex capture group
    to: "https://blog.example.com/$1"
    status: 308

// JSON
{
  "redirects": [
    {
      "from": "/old-path",
      "to": "https://example.com/new-path",
      "status": 301
    },
    { "from": "/blog/(.+)", "to": "https://blog.example.com/$1", "status": 308 }
  ]
}
Field Type Default Description
from string — Path or regex pattern to match
to string — Destination URL (capture groups $1…$N are expanded)
status number 301 HTTP redirect status code

Fallback

Return a response when no route matches.

# YAML — SPA: serve index.html for all unmatched browser routes
fallback:
  file: ./dist/index.html
  status: 200

# YAML — content-type-aware fallback (Accept header negotiation)
fallback:
  byAccept:
    html:
      file: ./dist/index.html
      status: 200
    json:
      body: { "error": "Not Found", "status": 404 }
      status: 404
  status: 404
  body: "Not Found"

// JSON
{
  "fallback": {
    "file": "./dist/index.html",
    "status": 200
  }
}

// JSON
{
  "fallback": {
    "byAccept": {
      "html": { "file": "./dist/index.html", "status": 200 },
      "json": { "body": { "error": "Not Found", "status": 404 }, "status": 404 }
    },
    "status": 404,
    "body": "Not Found"
  }
}
Field Type Default Description
file path — File to serve
body any — Response body (string or JSON object)
status number 200 HTTP status code
headers object — Response headers to set
byAccept object — Content-type-aware rules keyed by Accept type (see key matching below)

byAccept keys are matched against the request’s Accept header (the header value is lowercased before matching; a configured key like xml is matched case-sensitively against it, so a literal-substring key should be written in lowercase), checked in the order they’re defined, first match wins:

Key Matches when Accept contains
html text/html
json application/json
text text/plain or text/
image image/
any other key the key itself, as a literal substring (e.g. xml matches application/xml)
* wildcard fallback, checked only after every other key has been tried

Health Checks

Active upstream probes

# YAML
proxy:
  /api:
    targets: ["http://a:4000", "http://b:4000"]
    healthCheck:
      path: /health
      intervalSecs: 10
      unhealthyThreshold: 3
      healthyThreshold: 1
      slowStartSecs: 30
      unhealthyStatus: [429, 500, 502, 503, 504] # treat these status codes as failures
      unhealthyLatencyMs: 2000 # treat responses slower than 2s as failures

// JSON
{
  "proxy": {
    "/api": {
      "targets": ["http://a:4000", "http://b:4000"],
      "healthCheck": {
        "path": "/health",
        "intervalSecs": 10,
        "unhealthyThreshold": 3,
        "healthyThreshold": 1,
        "slowStartSecs": 30,
        "unhealthyStatus": [429, 500, 502, 503, 504],
        "unhealthyLatencyMs": 2000
      }
    }
  }
}

Site health endpoint (for load balancer probes)

# YAML
healthCheck: true

healthCheck:
  path: /__health__
  includeUpstreams: true   # include per-upstream health in JSON response

// JSON
{ "healthCheck": { "includeUpstreams": true } }

Health check field reference

Field Type Default Description
path string /__health__ Probe URL path
intervalSecs number 10 Probe interval
timeoutMs number 2000 Probe timeout
unhealthyThreshold number 3 Consecutive failures before removal
healthyThreshold number 1 Consecutive passes before re-adding
unhealthyStatus number[] any non-2xx HTTP status codes from the health-check probe that count as failures. Default: any non-2xx response. Example: [429, 500, 502, 503, 504]
unhealthyLatencyMs number — Health-check probe responses slower than this (ms) count as failures, even if the status code is 2xx
slowStartSecs number 0 Traffic ramp-up period after recovery. Ignored for ipHash/consistentHash and sticky routes.
maxConnectionsPerUpstream number — Circuit breaker threshold
prewarmConnections number 0 Pre-establish N keepalive connections at startup (max 8). 🚫 Blocked — warms a throwaway client, not Conduit’s real upstream pool (Pingora 0.9 has no public API for it) — see note below.
includeUpstreams bool false Include upstream health in /__health__ response

Circuit Breaker

maxConnectionsPerUpstream enforces a per-upstream connection cap for every load-balance strategy, across all three config shapes (proxy: {} map, routes[] array, and groups):

Known limitations still open after the 2026-08-03 integrity audit — see the repo’s issue tracker for current status:

# YAML
proxy:
  /api:
    targets: ["http://a:4000", "http://b:4000", "http://c:4000"]
    healthCheck:
      maxConnectionsPerUpstream: 100
    backup: "http://replica:4000"

// JSON
{
  "proxy": {
    "/api": {
      "targets": ["http://a:4000", "http://b:4000", "http://c:4000"],
      "healthCheck": { "maxConnectionsPerUpstream": 100 },
      "backup": "http://replica:4000"
    }
  }
}

See examples/circuit-breaker.yaml

Slow start

healthCheck.slowStartSecs ramps traffic to an upstream that just recovered from an unhealthy state, instead of sending it 100% of its normal share immediately (the classic thundering-herd-into-a-just-recovered-backend scenario).

For the slowStartSecs seconds immediately after recovery, the upstream participates in each pick with a probability equal to how far through the ramp window it is (0% right after recovery, rising linearly to 100% once the window elapses). This applies to every load-balance strategy except ipHash/consistentHash and sticky sessions:

Recovery is recorded both when an active health-check probe flips an upstream back to healthy, and when a half-open outlier-detection probe succeeds — the latter is the only recovery signal available for upstreams configured via routes[]/groups, since active probes aren’t spawned there.

# YAML — pairs well with least-conn, since that's the strategy slow-start
# benefits the most
proxy:
  /api:
    targets: ["http://a:4000", "http://b:4000"]
    strategy: least-conn
    healthCheck:
      slowStartSecs: 30

// JSON
{
  "proxy": {
    "/api": {
      "targets": ["http://a:4000", "http://b:4000"],
      "strategy": "least-conn",
      "healthCheck": { "slowStartSecs": 30 }
    }
  }
}

Retry

# YAML
proxy:
  /api:
    targets: ["http://a:4000", "http://b:4000"]
    retry:
      attempts: 3
      conditions:
        - connection_error
        - "5xx"
        - timeout
      backoffMs: 100
      backoffJitter: true # add ±50% random spread to backoffMs
      budgetPercent: 20
    timeout:
      perTryMs: 2000

// JSON
{
  "proxy": {
    "/api": {
      "targets": ["http://a:4000", "http://b:4000"],
      "retry": {
        "attempts": 3,
        "conditions": ["connection_error", "5xx", "timeout"],
        "backoffMs": 100,
        "backoffJitter": true,
        "budgetPercent": 20
      },
      "timeout": { "perTryMs": 2000 }
    }
  }
}

Retry field reference

Field Type Default Description
attempts number 0 Number of retry attempts (0 = disabled)
conditions string[] — Triggers: "connection_error", "5xx", "timeout". Retries only happen when at least one matches.
backoffMs number 0 Fixed wait between attempts (ms). 0 = immediate retry.
backoffJitter bool false Apply ±50% random spread to backoffMs to avoid thundering herd. Effective delay: [ms/2, ms*3/2)
budgetPercent number — Soft cap: at most this fraction of in-flight requests may be retries. Prevents retry storms under mass failure.

Body buffering for retry — POST/PUT/PATCH requests are only retried when limits.maxBodyBufferBytes is set. Without it, request bodies are not buffered and connection_error retries on non-GET methods are skipped silently.

1xx interim responses

Some upstream backends (Spring Boot, CDNs, gRPC gateways) send one or more 1xx informational responses before the final response — for example 103 Early Hints for browser resource preloading, or 100 Continue after a Expect: 100-continue request header.

Conduit passes 1xx responses through to the client without running any middleware (retry logic, error masking, response transforms, etc.), then continues waiting for the real response. No configuration is required.

Exception: 101 Switching Protocols (WebSocket upgrade) is handled separately by the websocket: true route option — see the field reference table.

Outlier Detection

Passively eject upstreams that return too many 5xx responses from real traffic. Tracks and ejects for every load-balance strategy, not just LeastConn.

# YAML
outlierDetection:
  consecutive5xx: 5
  baseEjectionTimeSecs: 30
  maxEjectionTimeSecs: 300
  maxEjectionPercent: 33

// JSON
{
  "outlierDetection": {
    "consecutive5xx": 5,
    "baseEjectionTimeSecs": 30,
    "maxEjectionTimeSecs": 300,
    "maxEjectionPercent": 33
  }
}

Ejection uses exponential backoff: 30 s → 60 s → 120 s → … up to maxEjectionTimeSecs.

Half-open circuit breaker: when the ejection period expires, the first request is allowed through as a probe. If the probe succeeds (non-5xx), the upstream is fully restored and ejection_count is reset. If it fails, the upstream is re-ejected with the next backoff level. All other requests during the probe are blocked until the probe completes.

Field Type Default Description
consecutive5xx number 5 Consecutive errors before ejection
baseEjectionTimeSecs number 30 Initial ejection duration
maxEjectionTimeSecs number 300 Maximum ejection duration (cap on backoff)
maxEjectionPercent number 10 Max % of cluster that may be ejected at once

Limits

# YAML
limits:
  maxBodyBytes: 10485760 # reject request bodies over 10 MB (413)
  maxHeaderBytes: 65536 # reject headers over 64 KB
  timeoutSecs: 30 # global request timeout (seconds)
  maxInflightRequests: 1000 # return 503 when 1000 requests are in flight
  maxBodyBufferBytes: 1048576 # buffer up to 1 MB per request for retry replay
  maxConnectionsPerIp: 50 # max simultaneous connections from one IP (429)
  keepaliveRequestLimit: 1000 # recycle connections after this many requests
  priorityThreshold: 0.8 # shed low-priority routes above 80% concurrency
  minUploadRateBytesPerSec: 1024 # reject uploads slower than 1 KiB/s (408)

// JSON
{
  "limits": {
    "maxBodyBytes": 10485760,
    "maxHeaderBytes": 65536,
    "timeoutSecs": 30,
    "maxInflightRequests": 1000,
    "maxBodyBufferBytes": 1048576,
    "maxConnectionsPerIp": 50,
    "keepaliveRequestLimit": 1000,
    "priorityThreshold": 0.8,
    "minUploadRateBytesPerSec": 1024
  }
}
Field Type Default Description
maxBodyBytes number — Max request body size — returns 413 if exceeded
maxHeaderBytes number — Max request header size
timeoutSecs number — Global request timeout
maxInflightRequests number — Max concurrent requests — returns 503 if exceeded (must be ≥ 1)
maxBodyBufferBytes number — Max body buffered per request for retry replay
maxConnectionsPerIp number — Max simultaneous open connections from a single client IP — returns 429 if exceeded
maxRequestHeaders number — Max number of request headers — returns 431 Request Header Fields Too Large if exceeded
keepaliveRequestLimit number — Max requests per keepalive connection; closes and recycles after. Equivalent to nginx’s keepalive_requests.
priorityThreshold number 0.8 Fraction of maxInflightRequests at which low-priority routes are shed (0.0–1.0) — see Priority routing
minUploadRateBytesPerSec number — Minimum upload rate in bytes/s — closes slow uploads with 408 Request Timeout (slow-loris protection)

Priority Routing

Priority routing lets high-value routes continue to be served when the site is under load, while low-priority routes are shed with 503 Load Shedding.

How it works

  1. Set limits.maxInflightRequests to cap total concurrency.
  2. Set limits.priorityThreshold (default 0.8) — the fraction of the cap at which shedding begins.
  3. Mark routes with priority: 0–100 (50 = normal, omitted = normal).
  4. When inflight / maxInflightRequests ≥ priorityThreshold, any request whose effective priority is below 50 receives 503 Load Shedding.

Requests with priority ≥ 50 (normal or high) are never shed by this mechanism. The X-Priority: <0–100> request header can raise the effective priority above the configured route value (useful for trusted internal callers).

# YAML
limits:
  maxInflightRequests: 2000
  priorityThreshold: 0.8 # shed low-priority at 1600+ concurrent

routes:
  - match:
      path: /api/critical/**
    proxy:
      targets: [http://api:4000]
      priority: 90 # always served

  - match:
      path: /api/batch/**
    proxy:
      targets: [http://api:4000]
      priority: 10 # shed first when overloaded

  - match:
      path: /api/**
    proxy:
      targets: [http://api:4000]
      # no priority → defaults to 50 (normal, not shed)

{
  "limits": {
    "maxInflightRequests": 2000,
    "priorityThreshold": 0.8
  },
  "routes": [
    {
      "match": { "path": "/api/critical/**" },
      "proxy": { "targets": ["http://api:4000"], "priority": 90 }
    },
    {
      "match": { "path": "/api/batch/**" },
      "proxy": { "targets": ["http://api:4000"], "priority": 10 }
    }
  ]
}
Field Type Default Description
limits.priorityThreshold number 0.8 Load fraction at which shedding begins (0.0–1.0)
proxy.*.priority number (0–100) 50 Route priority; below 50 = sheddable

Note: Priority routing only applies when both maxInflightRequests and priorityThreshold are configured on the site.

Fault Injection

Requires cargo build --features fault-injection

For testing only — do not use in production.

# YAML
faultInjection:
  abort:
    percent: 5
    status: 503
    body: "Injected fault"
  delay:
    percent: 10
    ms: 500

// JSON
{
  "faultInjection": {
    "abort": { "percent": 5, "status": 503, "body": "Injected fault" },
    "delay": { "percent": 10, "ms": 500 }
  }
}

Proxy Cache

Requires cargo build --features cache For Redis-backed cache also add --features redis; for disk cache add --features disk-cache.

Size limit: cache.maxSizeMb bounds the store with an LRU eviction manager (least-recently-used entries are purged once the total exceeds the budget). There is no per-body cap: a single response larger than the budget is written and then evicted again, because capping bodies without a Content-Length would abort the client mid-transfer. Limits of the current implementation: the budget of a store is fixed by the first route that uses it (changing maxSizeMb needs a restart, not a reload), routes sharing a store share its budget, and for disk:/redis:// stores only entries admitted since the process started are counted, so entries left over from a previous run are not included until they are rewritten.

# YAML
proxy:
  /api:
    targets: ["http://backend:4000"]
    cache:
      store: memory
      ttlSecs: 60
      maxSizeMb: 256 # store budget (MiB), LRU eviction
      staleWhileRevalidateSecs: 300 # serve stale up to 5 min while refreshing
      staleIfErrorSecs: 600 # serve stale up to 10 min if upstream fails
      varyHeaders: [Accept-Language, Accept-Encoding]
      skipPaths: [/api/me, /api/cart] # never cache these paths
      skipIfCookie: true
      methods: [GET, HEAD]

// JSON
{
  "proxy": {
    "/api": {
      "targets": ["http://backend:4000"],
      "cache": {
        "store": "memory",
        "ttlSecs": 60,
        "maxSizeMb": 256,
        "staleWhileRevalidateSecs": 300,
        "staleIfErrorSecs": 600,
        "varyHeaders": ["Accept-Language", "Accept-Encoding"],
        "skipPaths": ["/api/me", "/api/cart"],
        "skipIfCookie": true,
        "methods": ["GET", "HEAD"]
      }
    }
  }
}

Cache field reference

Field Type Default Description
store string — "memory", "redis://..." / "rediss://..." (--features redis), "disk:/path" (--features disk-cache)
ttlSecs number — Fresh cache TTL (seconds)
maxSizeMb number — Size budget of the store in MiB (LRU eviction) (≥ 1; unset = unlimited)
staleWhileRevalidateSecs number 0 Serve stale while refreshing in background (RFC 5861)
staleIfErrorSecs number 0 Serve stale when upstream returns 5xx, including after retries are exhausted (RFC 5861)
earlyRefreshSecs number 0 Refresh cache in the background when remaining TTL < this value (see below)
varyHeaders string[] — Vary cache key by these request headers
skipPaths string[] — Paths to never cache
skipIfCookie bool false Skip caching when request has a cookie
methods string[] [GET, HEAD] Cacheable HTTP methods

Cache key — scheme + host + path + query string. Request body is never part of the key, so POST responses are not cached by default (add "POST" to methods only for idempotent endpoints). Use varyHeaders to differentiate responses by Accept-Language or Accept-Encoding.

Upgrading from a Pingora 0.8 based release: the key is now built with an explicit boundary between the host and the rest, so every key hashes differently. A persistent store (disk: or redis://) starts cold once; Redis entries expire on their own TTL, but the old disk: files are never read again and are not removed automatically — delete the cache directory to reclaim the space.

Age header (RFC 7234 §5.1): Conduit automatically injects an `Age:

` header on every cache hit, computed as `now − Date` from the stored response. Any `Age` header carried by the cached response is replaced to prevent double-counting across proxy hops. No configuration is required. **Stale-while-revalidate** (RFC 5861): the first request after TTL expiry returns the stale response immediately while a background request refreshes the cache. Zero latency penalty for users. A built-in cache lock prevents thundering herd — only one background fetch goes to the upstream at a time. **Stale-if-error** (RFC 5861): when the upstream returns a 5xx error, Conduit serves the last known good cached response instead of forwarding the error to the client. This works in all three scenarios: 1. **No retry configured** — upstream 5xx immediately falls back to stale cache. 2. **Retry configured, budget exhausted** — after all retry attempts fail, stale cache is served instead of the final 5xx error. 3. **Retry + stale together** — Conduit retries the configured number of times; if all retries fail and stale cache is available, it serves stale. Set `staleIfErrorSecs` to the maximum age (in seconds) of a stale response you are willing to serve. When no stale entry exists or the stale entry is older than `staleIfErrorSecs`, the upstream error is forwarded to the client. **Early refresh** (`earlyRefreshSecs`): when the remaining TTL of a cached entry drops below `earlyRefreshSecs`, Conduit fires a background GET request directly to the upstream while the **current** client request is still served the (still-valid) cached response with zero latency. The cache is updated before it ever expires, so clients never see stale content as long as the upstream is reachable. Comparison with `staleWhileRevalidateSecs`: | Feature | Activates | Clients see stale? | | --------------------------- | ---------------- | ------------------ | | `staleWhileRevalidateSecs` | After TTL expires | Yes, until refresh | | `earlyRefreshSecs` | Before TTL expires | No | Use `earlyRefreshSecs` when zero-stale is important (news feeds, pricing data, session-sensitive API). Use `staleWhileRevalidateSecs` when occasional stale is acceptable and you want a simpler setup. ```yaml # Never-stale cache: refresh 10 s before the 60-second TTL expires. cache: store: memory ttlSecs: 60 earlyRefreshSecs: 10 ``` Source: h2o `lib/common/cache.c` — `H2O_CACHE_FLAG_EARLY_UPDATE`. **`s-maxage` handling**: Conduit respects the upstream `Cache-Control: s-maxage=N` directive as the effective TTL when the upstream returns it. `s-maxage=0` explicitly prevents caching regardless of `ttlSecs`. When the upstream returns no `Cache-Control` directive, `ttlSecs` from the route config is used. `ttlSecs` in the config always caps the maximum TTL — upstream headers cannot extend it beyond the configured limit. | Upstream `Cache-Control` | Effect | | ------------------------ | -------------------------- | | not present | Use `ttlSecs` from config | | `s-maxage=N` | Use `min(N, ttlSecs)` | | `s-maxage=0` | Do not cache this response | | `no-store` or `private` | Do not cache this response | ### Cache store options **`"memory"`** — in-process cache, lost on restart. Best for single-instance deployments with small response bodies. **`"redis://host:port"` / `"rediss://host:port"`** — shared Redis cache. (`--features redis` required) All Conduit instances share the same cache — consistent hit rate under horizontal scaling. `rediss://` enables TLS (AWS ElastiCache, Azure Cache). ```yaml # conduit.yaml — Redis cache shared across multiple instances proxy: /api: targets: ["http://api1:4000", "http://api2:4000"] cache: store: "redis://redis:6379" ttlSecs: 300 staleWhileRevalidateSecs: 60 varyHeaders: [Accept-Language] ``` ```json // conduit.json { "proxy": { "/api": { "targets": ["http://api1:4000", "http://api2:4000"], "cache": { "store": "redis://redis:6379", "ttlSecs": 300, "staleWhileRevalidateSecs": 60 } } } } ``` If Redis is unreachable at startup or during a request, caching is silently disabled for that request — the proxy continues to work normally (fail-open). **`"disk:/path/to/dir"`** — filesystem cache, survives restarts. (`--features disk-cache` required) Useful for large response bodies or when Redis is not available. ```yaml proxy: /assets: targets: ["http://assets:4000"] cache: store: "disk:/var/cache/conduit" ttlSecs: 86400 # 1 day ``` ```json { "proxy": { "/assets": { "targets": ["http://assets:4000"], "cache": { "store": "disk:/var/cache/conduit", "ttlSecs": 86400 } } } } ``` See [`examples/stale-while-revalidate.yaml`](/conduit/examples/stale-while-revalidate.yaml) --- ## Basic Auth ```yaml # YAML basicAuth: users: alice: "$ALICE_PASSWORD" bob: "$BOB_PASSWORD" realm: "My App" challenge: true # send WWW-Authenticate header (default: true) skipPaths: [/__health__] ``` ```json // JSON { "basicAuth": { "users": { "alice": "$ALICE_PASSWORD", "bob": "$BOB_PASSWORD" }, "realm": "My App", "challenge": true, "skipPaths": ["/__health__"] } } ``` | Field | Type | Default | Description | | ----------- | -------- | ----------- | ------------------------------------------------------------------------ | | `users` | object | — | `{ username: password }` map | | `realm` | string | `"Conduit"` | Shown in browser login dialog | | `challenge` | bool | `true` | Whether to send `WWW-Authenticate` header | | `skipPaths` | string[] | — | Paths that bypass Basic Auth — see [glob syntax](#skippaths-glob-syntax) | --- ## API Key ```yaml # YAML apiKey: keys: - "$PRIMARY_API_KEY" - "$SECONDARY_API_KEY" header: X-API-Key skipPaths: [/__health__, /public/**] ``` ```json // JSON { "apiKey": { "keys": ["$PRIMARY_API_KEY", "$SECONDARY_API_KEY"], "header": "X-API-Key", "skipPaths": ["/__health__", "/public/**"] } } ``` The key may be sent in the configured `header` or as a `?api_key=` query parameter. --- ## JWT Auth > **Requires** `cargo build --features jwt` Validates `Authorization: Bearer ` on every request. ### JWKS endpoint (recommended for production) ```yaml # YAML jwtAuth: jwksUrl: "https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json" audience: ["https://api.example.com"] issuer: "https://YOUR_DOMAIN.auth0.com" jwksRefreshSecs: 3600 skipPaths: [/__health__, /public/**] ``` ```json // JSON { "jwtAuth": { "jwksUrl": "https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json", "audience": ["https://api.example.com"], "issuer": "https://YOUR_DOMAIN.auth0.com", "jwksRefreshSecs": 3600, "skipPaths": ["/__health__", "/public/**"] } } ``` JWKS keys are fetched on the first request that needs them (that request waits for the fetch; concurrent first requests share one fetch) and refreshed once they are `jwksRefreshSecs` old (minimum 60s, enforced). The refresh runs in the background: requests keep verifying against the last good keys and never wait for the network. If the JWKS endpoint is unreachable, the last good keys keep verifying tokens for up to 24 hours past the refresh interval, and a failed fetch is not retried for 30 seconds. Beyond that window the keys are no longer trusted (a key the issuer has rotated out or revoked must not verify forever) and JWT requests return 401 until a fetch succeeds. If the very first fetch fails there are no keys to fall back on, so requests return 401 until the endpoint is reachable. ### Shared secret (HS256) ```yaml jwtAuth: secret: "$JWT_SECRET" skipPaths: [/__health__] ``` ```json // JSON { "jwtAuth": { "secret": "$JWT_SECRET", "skipPaths": ["/__health__"] } } ``` ### JWT field reference | Field | Type | Default | Description | | ----------------- | -------- | ------- | ------------------------------------------------------- | | `secret` | string | — | HS256 shared secret (mutually exclusive with `jwksUrl`) | | `jwksUrl` | string | — | JWKS endpoint URL (RS256 / ES256) | | `jwksRefreshSecs` | number | `3600` | JWKS key refresh interval (minimum `60`) | | `audience` | string[] | — | Required `aud` claims | | `issuer` | string | — | Required `iss` claim | | `skipPaths` | string[] | — | Paths that bypass JWT validation | ### Injecting JWT claims as upstream headers ```yaml requestTransform: setHeaders: X-User-ID: "" X-User-Email: "" X-Tenant: "" removeHeaders: - Authorization ``` ```json // JSON { "requestTransform": { "setHeaders": { "X-User-ID": "", "X-User-Email": "" }, "removeHeaders": ["Authorization"] } } ``` Unknown claims expand to empty string. Non-string claims (numbers, booleans, arrays, objects) expand to their JSON text representation — e.g. a `roles` claim holding `["admin", "editor"]` expands `` to the literal text `["admin","editor"]`, brackets and quotes included. See [Request / Response Transform](#request--response-transform). See [`examples/jwt-auth.yaml`](/conduit/examples/jwt-auth.yaml) --- ## Forward Auth > **Requires** `cargo build --features forward-auth` Delegate authentication to an external HTTP service. ```txt Client -> Conduit -> Auth service 2xx -> copy responseHeaders, forward to upstream 4xx -> return to client, stop fail -> 401 (fail closed) ``` ```yaml # YAML forwardAuth: url: "http://auth-service:9000/verify" requestHeaders: [Authorization, Cookie] responseHeaders: [X-User-ID, X-Role] timeoutMs: 3000 skipPaths: [/__health__, /public/**] ``` ```json // JSON { "forwardAuth": { "url": "http://auth-service:9000/verify", "requestHeaders": ["Authorization", "Cookie"], "responseHeaders": ["X-User-ID", "X-Role"], "timeoutMs": 3000, "skipPaths": ["/__health__", "/public/**"] } } ``` | Field | Type | Default | Description | | ----------------- | -------- | ------- | ----------------------------------------------------- | | `url` | string | — | Auth service URL (required) | | `requestHeaders` | string[] | — | Client headers to forward to auth service | | `responseHeaders` | string[] | — | Auth response headers to inject into upstream request | | `timeoutMs` | number | `5000` | Auth service timeout | | `skipPaths` | string[] | — | Paths that bypass forward auth | The auth service receives `X-Forwarded-Method`, `X-Forwarded-Uri`, `X-Forwarded-For`, plus any `requestHeaders`. See [`examples/forward-auth.yaml`](/conduit/examples/forward-auth.yaml) --- ## Consumers > **Requires** `cargo build --features consumers` > JWT consumers (V2 / V3) additionally require `--features jwt`. Named API clients with per-consumer credentials, rate limits, and headers. After identification, the consumer's username is injected as `X-Consumer-ID`. Unidentified requests receive `401`. ```yaml # YAML — V1 (API key / Basic Auth) + V2 (per-consumer JWT) consumers: idHeader: "X-Consumer-ID" apiKeyHeader: "X-API-Key" skipPaths: [/__health__] consumers: # V1: API key - username: alice apiKey: "$ALICE_KEY" rateLimit: { windowSecs: 60, limit: 100 } headers: { X-Tier: free } # V1: Basic Auth (username from consumer.username, password from basicAuth.password) - username: billing-service basicAuth: { password: "$BILLING_PASSWORD" } headers: { X-Internal: "true" } # V2: JWT with HS256 secret — token must be signed with this secret - username: mobile-app jwt: secret: "$MOBILE_JWT_SECRET" issuer: "https://auth.internal" rateLimit: { windowSecs: 60, limit: 500 } # V2: JWT with JWKS — token validated against public keys from this endpoint - username: partner-app jwt: jwksUrl: "https://partner.example.com/.well-known/jwks.json" audience: ["my-api"] ``` ```json // JSON { "consumers": { "idHeader": "X-Consumer-ID", "skipPaths": ["/__health__"], "consumers": [ { "username": "alice", "apiKey": "$ALICE_KEY", "rateLimit": { "windowSecs": 60, "limit": 100 }, "headers": { "X-Tier": "free" } }, { "username": "billing-service", "basicAuth": { "password": "$BILLING_PASSWORD" }, "headers": { "X-Internal": "true" } }, { "username": "mobile-app", "jwt": { "secret": "$MOBILE_JWT_SECRET" }, "rateLimit": { "windowSecs": 60, "limit": 500 } }, { "username": "partner-app", "jwt": { "jwksUrl": "https://partner.example.com/.well-known/jwks.json", "audience": ["my-api"] } } ] } } ``` ### V3: Shared JWT (Auth0 / Cognito / Keycloak pattern) One JWKS endpoint for all consumers; consumers are identified by `sub` claim. ```yaml # YAML consumers: sharedJwt: jwksUrl: "https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json" audience: ["https://api.example.com"] issuer: "https://YOUR_DOMAIN.auth0.com" usernameClaim: "sub" # default consumers: - username: "auth0|alice123" rateLimit: { windowSecs: 60, limit: 100 } headers: { X-Tier: free } - username: "auth0|bob456" rateLimit: { windowSecs: 60, limit: 10000 } headers: { X-Tier: premium } ``` ```json // JSON { "consumers": { "sharedJwt": { "jwksUrl": "https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json", "audience": ["https://api.example.com"], "issuer": "https://YOUR_DOMAIN.auth0.com", "usernameClaim": "sub" }, "consumers": [ { "username": "auth0|alice123", "rateLimit": { "windowSecs": 60, "limit": 100 } }, { "username": "auth0|bob456", "rateLimit": { "windowSecs": 60, "limit": 10000 } } ] } } ``` ### `ConsumersConfig` field reference | Field | Type | Default | Description | | -------------- | -------- | --------------- | ---------------------------------------------------- | | `consumers` | object[] | — | List of named consumers | | `idHeader` | string | `x-consumer-id` | Header injected into upstream with consumer username | | `apiKeyHeader` | string | `x-api-key` | Header to read API keys from | | `skipPaths` | string[] | — | Paths that bypass consumer auth | | `sharedJwt` | object | — | Single JWKS for all consumers, identified by `sub` claim — Auth0/Cognito/Keycloak pattern (`--features jwt` required) | ### Per-consumer fields | Field | Type | Description | | ----------- | ------ | ----------------------------------------------------------- | | `username` | string | Required — unique name, injected as `X-Consumer-ID` | | `apiKey` | string | API key credential | | `basicAuth` | object | `{ password }` — username is taken from `consumer.username` | | `jwt` | object | `{ secret? jwksUrl? audience? issuer? }` — per-consumer JWT identification (`--features jwt` required) | | `rateLimit` | object | Per-consumer rate limit (global, not per-IP) | | `headers` | object | Additional headers to inject into upstream request | See [`examples/consumers.yaml`](/conduit/examples/consumers.yaml) --- ## Rate Limiting In-memory rate limiting requires no feature flag — available in every build, including the minimal `default = ["proxy", "compression", "static", "hotreload"]`. `store: "redis://..."` requires `--features redis`. ### Site-level Applied to all requests before authentication. ```yaml # YAML rateLimit: windowSecs: 60 limit: 1000 keyBy: ip store: memory # or "redis://host:port" for multi-instance skipPaths: [/__health__] ``` ```json // JSON { "rateLimit": { "windowSecs": 60, "limit": 1000, "keyBy": "ip", "store": "memory", "skipPaths": ["/__health__"] } } ``` ### Per-route Applied after routing, independently of the site-level limit. ```yaml proxy: /api/payments: targets: ["http://payments:4000"] rateLimit: windowSecs: 60 limit: 10 keyBy: "header:X-User-ID" ``` ```json // JSON { "proxy": { "/api/payments": { "targets": ["http://payments:4000"], "rateLimit": { "windowSecs": 60, "limit": 10, "keyBy": "header:X-User-ID" } } } } ``` Per-route rate limiting also applies to routes matched via the advanced `routes[]` mechanism (`site.routes[*].proxy.rateLimit`), not just the `proxy` map shown above — each `routes[]` entry gets its own bucket, keyed by its position (`routes[0]`, `routes[1]`, ...). One consequence of the positional key: reordering `site.routes[]` entries across a hot reload can hand a route a bucket previously used by whatever entry occupied that position before — the same accepted trade-off as this codebase's existing "buckets aren't preserved across a config reload" behavior elsewhere. If this matters for a specific deployment, avoid reordering `routes[]` entries in a live config (appending/removing at the end is unaffected). ### Rate limit field reference | Field | Type | Default | Description | | ------------ | -------- | ---------- | ----------------------------------------------------------------------------------------------------------- | | `windowSecs` | number | — | Sliding window duration (seconds) — **required** | | `limit` | number | — | Max requests per key per window — **required** | | `burst` | number | `0` | Extra burst capacity above `limit` (see below) | | `algorithm` | string | — | Optional; only `"token-bucket"` is supported — a typo fails validation | | `keyBy` | string | `"ip"` | `"ip"` or `"header:"` | | `store` | string | `"memory"` | `"memory"` or `"redis://host:port"` (`--features redis` required for Redis) | | `skipPaths` | string[] | — | Paths that bypass rate limiting — see [skipPaths glob syntax](#skippaths-glob-syntax) | | `dryRun` | bool | `false` | Log rate-limit violations without actually rejecting requests — useful for tuning limits before enforcement | The rate limiter uses a **token-bucket** algorithm. Tokens refill at `limit / windowSecs` per second. Without `burst`, the bucket holds `limit` tokens. **Burst capacity** (`burst: N`): the bucket starts with `limit + N` tokens, allowing short spikes above the sustained rate. The refill rate stays at `limit / windowSecs` — burst is absorbed and not refilled. ```yaml # Allow up to 80 requests in a burst, sustained at 1 req/s rateLimit: windowSecs: 60 limit: 60 burst: 20 ``` **Validation applies at every level.** `windowSecs`/`limit`/`algorithm`/`keyBy`/`store` are checked at config-load and reload time for site-level, per-route, and per-consumer `rateLimit` blocks alike — a malformed value (e.g. `keyBy: "header:bad name"`, which contains a space and isn't a valid HTTP header name) fails validation instead of silently collapsing every client into one shared bucket at runtime. **`store` (Redis) works at every level** — site, per-route, and per-consumer (issue #322). Each level uses its own Redis key scope so buckets never collide: site-level uses the site label, per-route uses `"route\0{site}\0{route}"`, and per-consumer uses the fixed scope `"consumer"` with the consumer's username as the client key (mirroring the in-memory limiter's own `\0`-separated key namespaces — see #303/#304). `keyBy` is inert at the consumer level specifically, regardless of backend (the bucket key is always the username, not derived from the request). `burst`, `skipPaths`, and `dryRun` all work at every level that accepts them — `dryRun` isn't accepted at the route level at all (the schema rejects it there; it's a site/consumer-only field). `burst` also works under a Redis `store`, not just in-memory — implemented as the fixed-window counter's admission ceiling rising from `limit` to `limit + burst` within the current window, rather than a continuously-refilling allowance like the in-memory token bucket's burst. **Only one Redis connection is ever established per process**, regardless of how many levels configure a `store` URL. At startup Conduit scans site, then route, then consumer `rateLimit.store` values and connects to the *first* `redis://`/`rediss://` URL it finds; every level that configures Redis shares that one connection. If different levels are configured with genuinely different Redis URLs, only the first-discovered one is actually used — the others silently share it rather than each getting their own connection. Point every level's `store` at the same Redis instance/URL if you use Redis at more than one level. **This is checked at config-load time (issue #357)**: configuring more than one distinct Redis URL across site/route/consumer produces an advisory warning (logged, not fatal — same non-blocking treatment as the near-expiry-certificate warning) naming which URL is actually used and which are ignored. --- ## Request / Response Transform ### Static header transforms ```yaml # YAML requestTransform: setHeaders: X-User-ID: "" X-Gateway: conduit removeHeaders: - Authorization responseTransform: setHeaders: X-Served-By: conduit removeHeaders: - Server - X-Powered-By - X-AspNet-Version ``` ```json // JSON { "requestTransform": { "setHeaders": { "X-User-ID": "", "X-Gateway": "conduit" }, "removeHeaders": ["Authorization"] }, "responseTransform": { "setHeaders": { "X-Served-By": "conduit" }, "removeHeaders": ["Server", "X-Powered-By", "X-AspNet-Version"] } } ``` ### JWT claim templates > **Requires** `cargo build --features jwt` — templates expand to `""` when JWT auth is not active. Available in `requestTransform.setHeaders` after JWT validation: | Template | Claim | Notes | | ----------------- | ------- | --------------------------------------------------- | | `` | `sub` | User identifier — always present | | `` | `email` | Email claim (if IdP includes it) | | `` | `iss` | Token issuer | | any claim | any | `` — unknown claims expand to `""` | Non-string claims (numbers, booleans, arrays, objects) expand to their JSON text representation — e.g. `` for `roles: ["admin", "editor"]` expands to the literal text `["admin","editor"]`. --- ## Traffic Mirroring Send a copy of requests to a shadow backend. The shadow response is discarded — clients only see the primary response. ```yaml proxy: /api: targets: ["http://api-v1:4000"] mirror: "http://api-v2:4000" ``` ```json // JSON { "proxy": { "/api": { "targets": ["http://api-v1:4000"], "mirror": "http://api-v2:4000" } } } ``` The mirrored request includes all original headers plus `X-Mirrored-From: `. Mirror failures do not affect clients. > **Note:** request body is not mirrored — only headers are forwarded to the shadow > backend. This is sufficient for observability and shadow testing of read workloads. --- ## Custom Response Headers Inject headers into every response site-wide. These are in addition to any headers set by `responseTransform`. ```yaml # YAML headers: X-Environment: production X-API-Version: "3" ``` ```json // JSON { "headers": { "X-Environment": "production", "X-API-Version": "3" } } ``` --- ## Logging ```yaml # YAML — shorthand logging: dev # colorized, short — for development logging: json # structured JSON — for production logging: combined # Apache Combined Log Format ``` ```json // JSON { "logging": "json" } ``` Full config: ```yaml logging: format: json file: ./logs/access.log stripQuery: true # omit query string from logged path (e.g. /search?q=... → /search) skipPaths: - /__health__ - /__metrics__ - /favicon.ico ``` ```json // JSON { "logging": { "format": "json", "file": "./logs/access.log", "stripQuery": true, "skipPaths": ["/__health__", "/__metrics__", "/favicon.ico"] } } ``` | Field | Type | Default | Description | | ------------ | -------- | ------- | ----------------------------------------------------------------------------------- | | `format` | string | `dev` | Log format — see table below | | `file` | string | — | Append access logs to this file path (in addition to stdout) | | `stripQuery` | bool | `false` | Remove query string from the logged path. Useful when queries contain PII or tokens | | `skipPaths` | string[] | — | Glob patterns — requests matching these paths are not logged | | Format | Description | | ---------- | -------------------------------------------- | | `dev` | Colorized, short — development | | `combined` | Apache Combined Log Format | | `common` | Apache Common Log Format | | `short` | Short, no timestamps | | `json` | Structured JSON — Loki, Datadog, Splunk, ELK | ### JSON log fields ```json // JSON { "time": "2026-01-15T14:23:01Z", "method": "GET", "path": "/api/users", "status": 200, "bytes": 1234, "duration_ms": 42, "upstream_ms": 38, "ip": "10.0.0.1", "request_id": "a1b2c3d4-e5f6-...", "upstream": "http://api-1:4000" } ``` | Field | Description | | ------------- | --------------------------------------------------------------------------------------------- | | `duration_ms` | Total request time from accept to response sent (ms) | | `upstream_ms` | Time spent waiting for the upstream response (ms). Absent for local handlers (health, static) | | `request_id` | Value of `X-Request-ID` — auto-generated UUID v4 if absent | | `upstream` | Selected upstream URL | --- ## Metrics ```yaml # YAML metrics: path: /__metrics__ token: "$METRICS_TOKEN" ``` ```json // JSON { "metrics": { "path": "/__metrics__", "token": "$METRICS_TOKEN" } } ``` Prometheus scrape config: ```yaml scrape_configs: - job_name: conduit static_configs: [{ targets: ["conduit-host:8080"] }] metrics_path: /__metrics__ bearer_token: "my-token" ``` ### Per-upstream metrics In addition to the site-level metrics, Conduit exposes per-upstream URL metrics: | Metric | Type | Labels | Description | | ------------------------------------- | --------- | -------------------- | ------------------------------------------------------------- | | `conduit_upstream_requests_total` | counter | `upstream`, `status` | Requests forwarded to each upstream (including retries) | | `conduit_upstream_latency_seconds` | histogram | `upstream` | Upstream response latency (request sent → response received) | | `conduit_upstream_active_connections` | gauge | `upstream` | In-flight requests currently being processed by each upstream | These complement `conduit_upstream_errors_total{route}` for diagnosing which specific backend is slow or returning errors. --- ## OpenTelemetry Tracing > **Requires** `cargo build --features otlp` ```yaml # YAML global: otlp: endpoint: "http://tempo:4317" serviceName: "my-api" sampleRate: 0.1 timeoutMs: 5000 ``` ```json // JSON { "global": { "otlp": { "endpoint": "http://tempo:4317", "serviceName": "my-api", "sampleRate": 0.1, "timeoutMs": 5000 } } } ``` Each span: `method`, `path`, `status`, `duration_ms`, `upstream_url`, `request_id`. 5xx responses set span status to `ERROR`. | Field | Type | Default | Description | | ------------- | ------ | ------- | --------------------------------------- | | `endpoint` | string | — | gRPC OTLP endpoint URL | | `serviceName` | string | — | `service.name` in all spans | | `sampleRate` | number | `1.0` | Fraction of requests to trace (0.0–1.0) | | `timeoutMs` | number | `5000` | Export timeout | See [`examples/observability.yaml`](/conduit/examples/observability.yaml) --- ## Hot Reload Watch the config file for changes and reload without restarting. ```yaml # YAML hotReload: true hotReload: extensions: [html, css, js, ts, jsx, tsx] # file types that trigger browser reload ``` ```json // JSON { "hotReload": true } ``` ```json // JSON { "hotReload": { "extensions": ["html", "css", "js"] } } ``` **Hot-reloadable** (no restart): `proxy`, `static`, `routes`, `rateLimit`, `basicAuth`, `apiKey`, `jwtAuth`, `forwardAuth`, `consumers`, `middleware`, `logging`, `cors`, `securityHeaders`, `cache`, `outlierDetection`, `limits`, `requestTransform`, `responseTransform`, `maskErrors`. **Requires cold restart:** `port`, `tls.cert/key`, `workers`, `backlog`, `global.admin.bind`. (`tls.versions`/`tls.ciphers` are not listed here because they're rejected at validate-time — see [TLS field reference] (#tls-field-reference) — not merely cold-restart-only.) --- ## Security Headers ### `securityHeaders: true` — safe defaults ```yaml securityHeaders: true ``` Sets these four headers on every response: | HTTP header | Value | | ------------------------ | --------------------------------- | | `X-Content-Type-Options` | `nosniff` | | `X-Frame-Options` | `SAMEORIGIN` | | `Referrer-Policy` | `strict-origin-when-cross-origin` | | `X-XSS-Protection` | `1; mode=block` | ### Custom security headers ```yaml securityHeaders: hstsMaxAgeSecs: 63072000 # → Strict-Transport-Security: max-age=63072000; includeSubDomains csp: "default-src 'self'; script-src 'self'" xFrameOptions: DENY referrerPolicy: "strict-origin-when-cross-origin" ``` ```json // JSON { "securityHeaders": { "hstsMaxAgeSecs": 63072000, "csp": "default-src 'self'", "xFrameOptions": "DENY", "referrerPolicy": "strict-origin-when-cross-origin" } } ``` Full example with all fields: ```yaml securityHeaders: hstsMaxAgeSecs: 63072000 hstsIncludeSubDomains: true # add includeSubDomains to HSTS header hstsPreload: true # add preload to HSTS (see hstspreload.org) csp: "default-src 'self'" xFrameOptions: DENY referrerPolicy: "no-referrer" permissionsPolicy: "geolocation=(), microphone=()" allowedHosts: # reject Host headers not in this list (→ 400) - "example.com" - "www.example.com" ``` | Field | Type | Default (object form) | Sets HTTP header / action | | ----------------------- | -------- | --------------------------------- | ------------------------------------------------------------------------------------ | | `hstsMaxAgeSecs` | number | — (not set) | `Strict-Transport-Security: max-age=` | | `hstsIncludeSubDomains` | bool | `true` when hstsMaxAgeSecs is set | Append `; includeSubDomains` to HSTS header | | `hstsPreload` | bool | `false` | Append `; preload` to HSTS header (see [hstspreload.org](https://hstspreload.org)) | | `csp` | string | — (not set) | `Content-Security-Policy` | | `xFrameOptions` | string | `SAMEORIGIN` | `X-Frame-Options` | | `referrerPolicy` | string | `strict-origin-when-cross-origin` | `Referrer-Policy` | | `permissionsPolicy` | string | — (not set) | `Permissions-Policy` — restrict browser feature access | | `allowedHosts` | string[] | falls back to the site's `host:` | Reject requests with a `Host` header not in this list with `400 Bad Request` | > **Always set:** `X-Content-Type-Options: nosniff` and `X-XSS-Protection: 1; mode=block` > are added in both `true` and object forms — they cannot be disabled. > > **HSTS and CSP** are only set when explicitly configured. > HSTS should only be used on HTTPS sites — omit it for HTTP-only configs. > > **Permissions-Policy** restricts access to browser APIs (geolocation, camera, microphone, etc.). > See the [Permissions Policy spec](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy). > > **`allowedHosts`** prevents host-header injection attacks where an attacker sends a request with > a forged `Host` header to bypass routing or cache-keying logic — the classic exploit is a > poisoned password-reset link: an app that builds absolute URLs from `Host`/`X-Forwarded-Host` > will happily email a reset link pointing at an attacker-controlled domain. > > **Secure by default even without this option:** when `allowedHosts` is not set, Conduit falls > back to validating the incoming `Host` against the site's own `host:` value (when one is > configured) and rejects anything else. Set `allowedHosts` explicitly when a site must accept > more than one hostname (e.g. `example.com` and `www.example.com`), or leave a site's `host:` > unset/`"*"` for an intentional catch-all that accepts any Host. --- ## CORS ```yaml # YAML — open CORS (development only) cors: true # Locked to specific origins (production) cors: origins: ["https://app.example.com", "https://admin.example.com"] credentials: true methods: [GET, POST, PUT, DELETE, OPTIONS] allowedHeaders: [Authorization, Content-Type, X-Request-ID] maxAgeSecs: 86400 ``` ```json // JSON { "cors": { "origins": ["https://app.example.com"], "credentials": true, "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"], "allowedHeaders": ["Authorization", "Content-Type"], "maxAgeSecs": 86400 } } ``` | Field | Type | Default | Description | | ---------------- | -------- | ------- | -------------------------------------------- | | `origins` | string[] | `["*"]` | Allowed origins | | `methods` | string[] | all | Allowed methods | | `allowedHeaders` | string[] | all | Allowed request headers | | `credentials` | bool | `false` | Allow `Authorization` / cookies cross-origin | | `maxAgeSecs` | number | — | `Access-Control-Max-Age` (preflight cache) | `cors: true` allows any origin (`*`). Always use the object form in production. `credentials: true` requires an explicit, non-wildcard `origins` list — config validation rejects `credentials: true` with `origins` unset or containing `"*"` at startup/reload. Without this, every origin's credentialed (cookie-bearing) cross-origin requests would be allowed, which defeats the purpose of the credentials gate. --- ## IP Filter Allow or deny requests by client IP or CIDR range. Evaluated **before** authentication — blocked IPs get `403` immediately. ```yaml # YAML — allowlist (deny all others) ipFilter: allow: - "10.0.0.0/8" - "172.16.0.0/12" - "203.0.113.0/24" trustProxy: true # trust X-Forwarded-For for client IP detection # Denylist ipFilter: deny: - "192.0.2.0/24" # Dry-run mode — log violations without blocking ipFilter: deny: - "192.0.2.0/24" dryRun: true # IPv6 CIDR ranges are supported alongside IPv4 ipFilter: allow: - "2001:db8::/32" - "::1" # exact match, not just CIDR - "10.0.0.0/8" # IPv4 and IPv6 rules can be mixed freely ``` ```json // JSON { "ipFilter": { "allow": ["10.0.0.0/8", "172.16.0.0/12"], "trustProxy": true } } ``` | Field | Type | Default | Description | | ------------ | -------- | ------- | ----------------------------------------------------------------------------------------- | | `allow` | string[] | — | Allowed CIDRs — deny all others | | `deny` | string[] | — | Denied CIDRs — allow all others | | `trustProxy` | bool | `false` | Trust `X-Forwarded-For` for client IP | | `dryRun` | bool | `false` | Log blocks without enforcing them — useful for auditing a new deny list before going live | When both `allow` and `deny` are set, `allow` takes precedence. > **Dynamic CIDR management:** use the Admin API to add or remove deny entries at runtime > without a configuration reload — see [Admin API — IP deny list](#admin-api). --- ## Error Masking Replace upstream `5xx` bodies with a generic JSON error. ```yaml maskErrors: true ``` ```json // JSON { "maskErrors": true } ``` Clients receive: `{ "error": "Internal Server Error", "status": 500 }` --- ## Upstream Protocol Compatibility ### allowDuplicateChunked By default, Conduit deduplicates `Transfer-Encoding: chunked` headers from upstream responses. Some misconfigured origins emit `Transfer-Encoding: chunked, chunked` or two separate `Transfer-Encoding: chunked` headers, which confuses strict HTTP clients. ```yaml allowDuplicateChunked: true # pass duplicate chunked headers through unmodified ``` Only enable this for upstreams that deliberately rely on duplicate chunked headers. --- ## Upstream TLS Verification ```yaml proxy: /api: targets: ["https://api-internal:8443"] upstreamTls: verify: true serverName: api-internal.svc.cluster.local ``` ```json // JSON { "proxy": { "/api": { "targets": ["https://api-internal:8443"], "upstreamTls": { "verify": true, "serverName": "api-internal.svc.cluster.local" } } } } ``` | Field | Type | Default | Description | | ------------ | ------ | -------- | -------------------------------------------- | | `verify` | bool | `false` | Verify upstream cert against system CA store | | `serverName` | string | from URL | Override SNI hostname | --- ## mTLS — Client Certificate Authentication Require clients to present a TLS certificate signed by a trusted CA. ```yaml tls: cert: /etc/tls/server.crt key: /etc/tls/server.key clientAuth: ca: /etc/tls/client-ca.crt optional: false # true = allow connections without cert ``` ```json // JSON { "tls": { "cert": "/etc/tls/server.crt", "key": "/etc/tls/server.key", "clientAuth": { "ca": "/etc/tls/client-ca.crt", "optional": false } } } ``` | Field | Type | Default | Description | | ---------- | ---- | ------- | ------------------------------------------------------------- | | `ca` | path | — | CA PEM file that signs authorized client certs — **required** | | `optional` | bool | `false` | `false` = reject without cert; `true` = allow without cert | See [`examples/mtls.yaml`](/conduit/examples/mtls.yaml) --- ## Rhai Script Middleware > **Requires** `cargo build --features rhai` Execute custom Rhai scripts per request. Scripts run in order; any script can reject the request or read headers to make decisions. **→ Full guide with examples: [rhai.md](/conduit/docs/rhai/)** ```yaml # YAML middleware: - type: script path: ./scripts/auth-check.rhai - type: script path: ./scripts/add-headers.rhai config: tier: premium ``` ```json // JSON { "middleware": [ { "type": "script", "path": "./scripts/auth-check.rhai" }, { "type": "script", "path": "./scripts/add-headers.rhai", "config": { "tier": "premium" } } ] } ``` > **Note:** inline scripts are not supported — use `path` to a `.rhai` file. > Optional `config` is passed to the script as a JSON value. **Available Rhai functions** (request phase — `request` is **read-only**; mutating a live request isn't supported here. A response *can* be rewritten on the way out, either via a `phase: "response"` Rhai script — see the "Rhai `on_response`" backlog entry in `CLAUDE.md` for its separate `response`/`upstream` API — or via WASM's response phase, see [WASM Middleware](#wasm-middleware) below): | Function | Description | | ----------------------------- | ---------------------------------------------------------- | | `request.header(name)` | Read a request header | | `request.path` | Get the request path | | `request.method` | Get the HTTP method | | `request.query` | Get the raw query string | | `response.status` | Get/set the short-circuit response status (default `200`) | | `response.body` | Get/set the short-circuit response body | | `response.header(name, value)` | Append a header to the short-circuit response | Return `false` from the script to abort the request with whatever `response.status`/`response.body` were set (defaults to `200`/empty if untouched); return `true` (or nothing) to continue the pipeline. --- ## WASM Middleware > **Requires** `cargo build --features wasm` **→ Full guide with ABI reference, Rust examples, and build instructions: [wasm.md](/conduit/docs/wasm/)** ```yaml # YAML middleware: - type: wasm path: ./plugins/my-plugin.wasm ``` ```json // JSON { "middleware": [{ "type": "wasm", "path": "./plugins/my-plugin.wasm" }] } ``` Plugins export `on_request() -> i32` and a `memory` export. Return `0` to continue, non-zero to reject. Conduit **fails open** on errors. **Host functions (request phase, `on_request`):** | Function | Description | | --------------------------------- | -------------------------- | | `conduit_get_header` | Read a request header | | `conduit_set_request_header` | Set a request header | | `conduit_remove_request_header` | Remove a request header | | `conduit_get_uri` | Get request URI | | `conduit_get_method` | Get HTTP method | | `conduit_get_header_names` | List all header names | | `conduit_abort_with_redirect` | Redirect the client | | `conduit_get_request_id` | Get X-Request-ID | | `conduit_log` | Write to Conduit log | An optional `on_response(status: i32) -> i32` export gets its own set of host functions (read/set/remove response headers and status, replace the response body, read plugin config). See [wasm.md](/conduit/docs/wasm/) for the complete, authoritative ABI reference (request- and response-phase) — this table only covers the request phase and isn't meant to be exhaustive. --- ## Connection Pool Configure the upstream HTTP connection pool per route. ```yaml proxy: /api: targets: ["http://backend:4000"] pool: maxIdle: 100 # max idle connections to keep open idleTimeoutSecs: 90 # close idle connections after 90 s ``` ```json // JSON { "proxy": { "/api": { "targets": ["http://backend:4000"], "pool": { "maxIdle": 100, "idleTimeoutSecs": 90 } } } } ``` | Field | Type | Default | Description | | ----------------- | ------ | ------- | ---------------------------------------------- | | `maxIdle` | number | — | Max idle connections kept alive | | `idleTimeoutSecs` | number | — | Close idle connections after this many seconds | --- ## Multi-Site Run multiple virtual hosts from one process. ```yaml # YAML global: workers: 4 backlog: 1024 shutdownTimeoutSecs: 30 admin: bind: "127.0.0.1:2019" token: "$ADMIN_TOKEN" sites: - port: 443 host: app.example.com tls: { cert: ./certs/app.crt, key: ./certs/app.key } jwtAuth: { jwksUrl: "https://auth.example.com/.well-known/jwks.json" } proxy: /api: "http://app-backend:4000" - port: 443 host: admin.example.com tls: { cert: ./certs/admin.crt, key: ./certs/admin.key } basicAuth: { users: { admin: "$ADMIN_PASS" } } proxy: /: "http://admin-ui:3000" - port: 8080 static: ./public fallback: { file: ./public/404.html, status: 404 } ``` ```json // JSON { "global": { "workers": 4, "shutdownTimeoutSecs": 30, "admin": { "bind": "127.0.0.1:2019", "token": "$ADMIN_TOKEN" } }, "sites": [ { "port": 443, "host": "app.example.com", "tls": { "cert": "./certs/app.crt", "key": "./certs/app.key" }, "proxy": { "/api": "http://app-backend:4000" } } ] } ``` ### Global field reference | Field | Type | Default | Description | | --------------------- | ------ | --------------- | ------------------------------------------------------------------------------------ | | `workers` | number | CPU count | Worker threads — cold restart to change | | `backlog` | number | `1024` | TCP accept backlog | | `shutdownTimeoutSecs` | number | — | Grace period for in-flight requests on shutdown | | `admin.bind` | string | — (not started) | Admin API address. **Required to enable the Admin API.** Omit to disable it entirely | | `admin.token` | string | — | Bearer token required for every Admin API request (strongly recommended) | | `otlp` | object | — | OpenTelemetry tracing config (`--features otlp` required — see [OpenTelemetry Tracing](#opentelemetry-tracing)) | --- ## TCP Proxy > **Requires** `cargo build --features tcp` Forward raw TCP connections without HTTP parsing. Useful for MySQL, PostgreSQL, Redis, SMTP, and any other non-HTTP protocol. ```yaml # conduit.yaml sites: - port: 3306 tcp: targets: - "mysql-primary:3306" - "mysql-replica:3306" strategy: round-robin # or "random" (default: round-robin) connectTimeoutMs: 5000 # upstream connect timeout (default: 5000) ``` ```json // conduit.json { "sites": [ { "port": 3306, "tcp": { "targets": ["mysql-primary:3306", "mysql-replica:3306"], "strategy": "round-robin", "connectTimeoutMs": 5000 } } ] } ``` | Field | Type | Default | Description | | ------------------ | -------- | ------------- | --------------------------------------------- | | `targets` | string[] | — | Upstream `host:port` addresses — **required** | | `strategy` | string | `round-robin` | `"round-robin"` or `"random"` | | `connectTimeoutMs` | number | `5000` | Upstream connect timeout (ms) | > **Note:** `tcp` cannot be combined with `proxy`, `static`, or other HTTP > features on the same site. Use a separate port/site for HTTP traffic. --- ## Upload > **Requires** `cargo build --features upload` Enable multipart file upload. The upload handler is only started when this section is present in the config. ```yaml # YAML upload: path: /upload # URL path for the upload endpoint (required) dir: ./uploads # directory where files are saved (required) maxFileSizeBytes: 52428800 # 50 MB per file maxTotalSizeBytes: 209715200 # 200 MB total per request maxFiles: 10 allowedMimeTypes: ["image/jpeg", "image/png", "application/pdf"] fieldName: file # multipart field name (default: "file") ``` ```json // JSON { "upload": { "path": "/upload", "dir": "./uploads", "maxFileSizeBytes": 52428800, "maxTotalSizeBytes": 209715200, "maxFiles": 10, "allowedMimeTypes": ["image/jpeg", "image/png", "application/pdf"], "fieldName": "file" } } ``` | Field | Type | Default | Description | | ------------------- | -------- | -------- | ----------------------------------------------- | | `path` | string | — | URL path for upload endpoint — **required** | | `dir` | string | — | Directory to save uploaded files — **required** | | `maxFileSizeBytes` | number | — | Max size per individual file | | `maxTotalSizeBytes` | number | — | Max total size of all files in one request | | `maxFiles` | number | — | Max number of files per request | | `allowedMimeTypes` | string[] | all | Allowed MIME types (e.g. `"image/jpeg"`) | | `fieldName` | string | `"file"` | Multipart field name to read | --- ## Admin API Configure with [`global.admin`](#multi-site): ```yaml global: admin: bind: "127.0.0.1:2019" # loopback only token: "$ADMIN_TOKEN" # optional Bearer token ``` The Admin API provides 12 endpoints: hot-reload, status, upstream management, cache purge, rate-limit stats, and runtime IP deny-list. **→ Full reference with request/response examples: [docs/admin.md](/conduit/docs/admin/)** --- ## Prometheus Metrics Reference All metrics are at the [`metrics.path`](#metrics) endpoint. | Metric | Type | Labels | Description | | ------------------------------------- | --------- | -------------------- | ---------------------------------------------------------------- | | `conduit_requests_total` | counter | `method`, `status` | Total HTTP requests handled | | `conduit_request_duration_seconds` | histogram | `method`, `status` | Full request latency (accept → response sent) | | `conduit_active_connections` | gauge | — | Requests currently in-flight (site-wide) | | `conduit_upstream_errors_total` | counter | `route`, `status` | Upstream 5xx responses per route | | `conduit_upstream_requests_total` | counter | `upstream`, `status` | Requests forwarded to each upstream URL | | `conduit_upstream_latency_seconds` | histogram | `upstream` | Upstream response latency per URL | | `conduit_upstream_active_connections` | gauge | `upstream` | In-flight requests per upstream URL | | `conduit_retry_attempts_total` | counter | `route`, `condition` | Retry attempts by trigger (`5xx`, `connection_error`, `timeout`) | | `conduit_rate_limit_rejected_total` | counter | `site` | Rate-limited (429) requests per site | | `conduit_cache_hits_total` | counter | `route` | Proxy cache hits | | `conduit_cache_misses_total` | counter | `route` | Proxy cache misses | | `conduit_eventloop_lag_ms` | gauge | — | Mean scheduling delay (ms) of the admin runtime (**`--features tokio-metrics`**) | **Example Grafana queries:** ```promql # Request rate rate(conduit_requests_total[5m]) # p99 latency histogram_quantile(0.99, rate(conduit_request_duration_seconds_bucket[5m])) # Error rate rate(conduit_upstream_errors_total[5m]) # Cache hit ratio rate(conduit_cache_hits_total[5m]) / (rate(conduit_cache_hits_total[5m]) + rate(conduit_cache_misses_total[5m])) ```