Configuration

bouine is configured via a YAML file passed with --config. Environment variable interpolation is supported: ${VAR} is replaced with the value of VAR, and ${VAR:-default} provides a fallback. $$ escapes to a literal $.

Pages in this section

• Cache policy — TTL selection, stale serving, negative caching, jitter, refresh-before-expiry, and cache keys.
• Streaming and live responses — SSE, streaming misses, fetch-slot shedding, and memory caps.
• Static file serving — serve files from a local directory instead of an upstream pool.
• Storage tiers — hot and warm tiers, eviction, sizing guidelines.
• TLS — certificates, SNI, and automatic reload.
• Clustering — consistency modes, gossip, peer fetch, mTLS, invalidation.
• Experimental features — opt-in features like the H1 fast path.
• Helm chart reference — all values.yaml keys with defaults.

Minimal working config

listen:
  http: ":8080"
  admin: ":9000"

storage:
  hot_max_bytes: 256MiB

upstream_pools:
  - name: app
    targets: ["app.default.svc:8080"]

routes:
  - match: { path_prefix: / }
    pool: app
    cache:
      ttl_default: 60s

Full example

listen:
  http: ":80"
  https: ":443"
  admin: ":9000"
  cluster: ":8443"

tls:
  certs:
    - cert_file: /etc/bouine/tls/cert.pem
      key_file: /etc/bouine/tls/key.pem
      sni: ["example.com", "*.example.com"]
  min_version: "1.2"

storage:
  hot_max_bytes: 2GiB
  warm_dir: /var/lib/bouine
  warm_max_bytes: 50GiB

cluster:
  join:
    - "bouine-0.bouine-headless.ns.svc.cluster.local:8443"
    - "bouine-1.bouine-headless.ns.svc.cluster.local:8443"
    - "bouine-2.bouine-headless.ns.svc.cluster.local:8443"
  hop_limit: 2

upstream_pools:
  - name: api
    targets: [api.default.svc:8080]
    tls:
      enabled: false
    health:
      active:
        path: /healthz
        interval: 5s
        timeout: 1s
        unhealthy_threshold: 3
      passive:
        consecutive_5xx: 5
    connect:
      timeout: 10s
      keep_alive: 15s

routes:
  - match: { host: "api.example.com", path_prefix: /v1/ }
    pool: api
    cache:
      ttl_default: 60s
      stale_while_revalidate: 30s
      stale_if_error: 300s
      negative_ttl: 5s
      jitter_percent: 10
      refresh_before_expiry: true
      refresh_margin_percent: 20
      refresh_timeout: 5s
      refresh_concurrency: 16
      refresh_min_hits: 3
      refresh_persist_cycles: 2
      refresh_min_score: 1048576
      refresh_max_rps: 100
      refresh_reactive_first: true
      key:
        include_headers:
          - Accept-Language
        exclude_headers:
          - x-request-id
          - x-trace-id
          - x-forwarded-for

Field reference

listen

storage

cluster

routes[]

Route matching uses host (exact or a leading-*. wildcard since v0.5.27), path_prefix or path (an anchored RE2 regex, since v0.5.27), and optionally methods. Routes are matched in declaration order; the first match wins. A later route fully covered by an earlier one (host, path, and methods all covered) is dead config and is reported at Error level at boot while boot proceeds. Ban predicates still use their own path_regex — see ban predicates.

A route must specify exactly one of pool or static.root. The former proxies to an upstream pool; the latter serves files from a local directory. See Static file serving.

routes[].request

routes[].cache

routes[].cache.key

canonicalize_path was removed in v0.5.19. The knob was parsed and documented but its listener-level wiring never landed, so it had no effect; configs setting it now fail at load time with the strict loader. Remove the key from your config when upgrading.

route_defaults

Declare per-route blocks once instead of repeating them on every route (since v0.5.27). Values are merged into every route before validation; only the two blocks with defined merge semantics are accepted — any other route field under route_defaults is rejected at decode time.

route_defaults:
  request:
    forwarded: standard        # inherited by every route that does not opt out
  cache:
    bypass_on_user_agent: ["*ShoppingFeedBot*"]

upstream_pools[].connect

All fields are optional; a zero/empty value applies the built-in default, so existing configs keep their current behaviour.

Health checks

Active health probes the upstream periodically. Passive ejects after consecutive failures.

health:
  active:
    path: /healthz
    method: GET          # default
    interval: 5s
    timeout: 1s
    healthy_threshold: 1
    unhealthy_threshold: 3
    expected_status_codes: [200]
  passive:
    consecutive_5xx: 5
    eject_for: 30s

passive.eject_for restores passively ejected targets once the window elapses and re-ejects them automatically if they are still broken (enforced since v0.5.19; restores are counted in the origin_restores_total metric with a source label).

metrics

metrics:
  traffic_classes:
    - name: checkout
      hosts: ["checkout.example.com"]
    - name: marketing
      hosts: ["*.example.com"]   # suffix match on the label boundary

Every invalid field is reported at once, each anchored to its own metrics.traffic_classes[i].name / .hosts[j] path. See Monitoring → traffic classes for the label semantics and the series-cardinality note.

admin

tracing

Configure OpenTelemetry span export. Leave endpoint empty (default) to disable tracing.

cloudflare

Optional Cloudflare Cache API propagation. See Cloudflare CDN propagation for full details and Kubernetes secret wiring.

experimental

Opt-in features that are not yet stable. All fields default to off. See Experimental features.

Top-level fields

Hedged fetch

Set upstream_pools[].connect.hedge_timeout to hedge slow origins (wired into the fetch path since v0.5.19). When the primary request does not get a response within hedge_timeout, bouine fires a duplicate request to the same pool and returns whichever response arrives first. Only idempotent methods (GET, HEAD, OPTIONS) are hedged — SSE and non-idempotent requests never duplicate. Zero (the default) disables hedging.

upstream_pools:
  - name: api
    targets: [api.default.svc:8080]
    connect:
      hedge_timeout: 250ms

Forwarded headers

routes[].request.forwarded (since v0.5.27) injects client-identity headers onto origin-bound requests only — miss, invalidating proxy (POST/PUT/DELETE), bypass, revalidate, streaming/SSE, and the background fetchers. The cache-hit path is untouched, and the headers never join the cache key or the stored request headers.

Four YAML shapes:

request:
  forwarded: standard           # all four headers, one line
  forwarded: [client_ip, proto]  # exactly these headers, no implicit extras
  forwarded: false              # explicit opt-out (kills a route_default)
  forwarded:                    # full mapping, field-by-field
    client_ip: true
    proto: true
    max_append: 10              # chain cap, default 5 (range 1–64)

The XFF and Via chains are capped at max_append entries (the rightmost — nearest — entries are kept) and the 8 KiB per-header budget. Background fetches (SWR revalidation, refresh-before-expiry, shed refill) inject proto/host/Via from the captured request but deliberately never append X-Forwarded-For — there is no live peer, and replaying the original requester’s address would attribute one user’s identity to an anonymous refresh. forwarded requires a pool (rejected on static routes) and is mutually exclusive with header_set entries targeting the same header.

TCP Fast Open

bouine supports TCP Fast Open on three surfaces, all disabled by default since v0.5.29 (previously an unset listen.tcp_fast_open meant “enabled on Linux”):

With a kernel-cached TFO cookie, the first request bytes ride in the SYN packet — one full RTT saved on every fresh connection. The option is advisory: peers or origins without server-side TFO never issue a cookie and the dial silently falls back to the regular handshake, so there is no penalty for enabling it. Linux only (4.11+ for the client side; no-op elsewhere); the kernel is probed once at startup and an unsupported option is left unwired with a single warn line. bouine↔bouine peer dials use TFO end-to-end when both sides opt in — cluster.peer_tcp_fast_open on the dialing side, listen.tcp_fast_open on the answering side — and peers’ kernels need net.ipv4.tcp_fastopen to include the server bit. Per-socket failures are best-effort and never fail a dial.

Upgrade note (v0.5.29): deployments relying on the old listener-side default must set listen.tcp_fast_open: true explicitly after upgrading.

Size units

All byte-size fields (hot_max_bytes, warm_max_bytes) accept any of these suffixes (case-insensitive):

Recommendation: Use IEC binary units (MiB, GiB) for clarity. The Helm chart defaults use GiB.

Config updates

bouine does not support live config reload. All config changes require a process restart. On Kubernetes, use a rolling restart:

kubectl rollout restart statefulset/bouine

For TLS certificate rotation, restart the process or use Kubernetes rolling restarts with cert-manager.