Configuration

bouine est configuré via un fichier YAML passé avec --config. Les variables d’environnement sont développées (${VAR}, ${VAR:-default}) avant le décodage.

listen:
  http: ":8080"
  https: ":443"
  admin: ":9000"

storage:
  hot_max_bytes: 1GiB

upstream_pools:
  - name: app
    targets: ["app.default.svc:8080"]
    health:
      active:
        path: /healthz
        interval: 10s

routes:
  - match: { path_prefix: /api/ }
    pool: app
    cache:
      ttl_default: 60s
      stale_while_revalidate: 10s
      stale_if_error: 300s

Pages dans cette section

• Politique de cache — sélection TTL, override, stale-while-revalidate, mise en cache négative, jitter, clés de cache.
• Streaming et réponses live — SSE, misses en streaming, shedding de fetch slots et limites mémoire.
• Modes de cluster — strong, eventual ; Service headless ; gossip.
• Chart Helm — valeurs configurables du chart Helm.
• Servir des fichiers statiques — servir des fichiers depuis le disque sans serveur d’origine.
• Stockage — niveaux hot (RAM) et warm (mmap), éviction SIEVE.
• TLS — terminaison TLS, mTLS entre pairs, certificats.
• Fonctionnalités expérimentales — fonctionnalités opt-in susceptibles de changer.

Nouveautés v0.6

• listen.max_connections — plafond par défaut relevé de 4096 à 65536 (v0.6.0) ; les refus à l’accept sont comptés par bouine_conn_rejections_total.
• Chemin rapide H1 toujours actif (v0.6.0, ADR-0069) : experimental.h1_fast_path et h1_fast_peer_path sont retirés (clés ignorées, avis au démarrage), experimental.h1_reactor est supprimé (erreur de parsing stricte — retirez la clé).
• routes[].cache.max_fetch_concurrency — défaut intégré relevé de 32 à 256 (v0.6.0).
• cluster.peer_fetch_concurrency — défaut relevé de 16 à 64 (v0.6.0).
• health.passive — eject_for non défini = fenêtre de restauration intégrée de 30 s (v0.6.1) ; les 5xx ne comptent vers l’éjection qu’après une fenêtre de succès de 5 s (v0.6.0) ; consecutive_5xx et eject_for modifiables à chaud par pool (v0.6.0).
• Configuration à chaud (v0.6.0) : bouine config get/set/diff, bouine config reload (expérimental, experimental.config_reload), GET|POST /v1/config/hot, POST /v1/config/reload — voir Configuration à chaud.
• Nouvelles commandes CLI / API (v0.6.0) : bouine status, bouine explain, bouine keys find/top/recent, GET /v1/status, GET /v1/explain, GET /v1/keys/* — voir CLI et API.
• Set-Login rejoint Set-Cookie dans toutes les portes de stockage et le strip (v0.6.0) ; les réponses à état client ne sont plus servies à un second client via le collapse (ADR-0067).
• Collapse des miss froid sans include_headers onto one fill flight, served from the store (ADR-0066, v0.6.0).
• Plafond de bans relevé de 1024 à 4096, registration O(1) et bans surrogate appliqués via un ensemble lock-free (v0.6.0).

Référence des champs

listen

storage

upstream_pools[]

routes[]

route_defaults

Déclare une fois des blocs par route au lieu de les répéter sur chaque route (depuis v0.5.27). Fusionnés dans chaque route avant validation ; seuls les deux blocs ayant des sémantiques de fusion définies sont acceptés — tout autre champ est rejeté au décodage.

route_defaults:
  request:
    forwarded: standard        # hérité par toute route qui n'opte pas out
  cache:
    bypass_on_user_agent: ["*ShoppingFeedBot*"]

• request.forwarded : une route sans bloc forwarded hérite du défaut en entier ; un preset ou une liste de tokens remplace les drapeaux du défaut (seul max_append retombe dessus) ; la forme mapping fait un OU champ par champ ; false/none désactive pour la route. Les routes statiques ignorent le défaut hérité.
• cache.bypass_on_user_agent : chaque route sans liste propre hérite du défaut en entier ; la liste propre d’une route la remplace (jamais une union) ; une liste vide explicite ([]) désactive pour la route ; les routes statiques n’héritent de rien.

cluster

tls

cloudflare

tracing

metrics

metrics:
  traffic_classes:
    - name: checkout
      hosts: ["checkout.example.com"]
    - name: marketing
      hosts: ["*.example.com"]   # correspondance par suffixe sur la frontière de label

admin

En-têtes forwarded

routes[].request.forwarded (depuis v0.5.27) injecte des en-têtes d’identité client sur les requêtes vers l’origine uniquement — miss, proxy invalidant (POST/PUT/DELETE), bypass, revalidation, streaming/SSE et fetchs en arrière-plan. Le chemin de hit n’est pas touché, et ces en-têtes n’entrent jamais dans la clé de cache ni dans les en-têtes de requête stockés.

Quatre formes YAML :

request:
  forwarded: standard           # les quatre en-têtes, une ligne
  forwarded: [client_ip, proto]  # exactement ces en-têtes
  forwarded: false              # opt-out explicite (tue un route_default)
  forwarded:                    # mapping complet, champ par champ
    client_ip: true
    proto: true
    max_append: 10              # plafond de chaîne, défaut 5 (plage 1–64)

Les chaînes XFF et Via sont plafonnées à max_append entrées (les plus récentes — les plus à droite — sont conservées) et au budget de 8 KiB par en-tête. Les fetchs en arrière-plan (revalidation SWR, refresh-before-expiry, recharge après shed) injectent proto/host/Via mais n’ajoutent jamais X-Forwarded-For — il n’y a pas de peer vivant, et rejouer l’adresse du demandeur original attribuerait l’identité d’un utilisateur à un refresh anonyme. forwarded exige un pool (rejeté sur les routes statiques).

TCP Fast Open

bouine prend en charge TCP Fast Open sur trois surfaces, toutes désactivées par défaut depuis v0.5.29 (précédemment, un listen.tcp_fast_open non défini signifiait « activé sur Linux ») :

Avec un cookie TFO mis en cache par le noyau, les premiers octets de requête partent dans le paquet SYN — un RTT complet économisé sur chaque nouvelle connexion. L’option est advisory : des peers ou origines sans TFO côté serveur n’émettent jamais de cookie et le dial retombe silencieusement sur le handshake habituel, donc il n’y a aucun coût à l’activer. Linux uniquement (4.11+ côté client ; no-op ailleurs) ; le noyau est sondé une fois au démarrage. Les dials bouine↔bouine utilisent TFO de bout en bout quand les deux côtés l’activent — cluster.peer_tcp_fast_open côté appelant, listen.tcp_fast_open côté répondant — et les noyaux des peers doivent avoir net.ipv4.tcp_fastopen avec le bit serveur.

Note de mise à jour (v0.5.29) : les déploiements qui comptaient sur l’ancien défaut côté listener doivent définir listen.tcp_fast_open: true explicitement après la mise à niveau.

Configuration à chaud

Depuis v0.6.0, deux surfaces d’exécution existent en complément du redémarrage :

• Boutons de configuration à chaud (bouine config get/set/diff, GET|POST /v1/config/hot) : modifient des champs réellement appliquables à chaud sur un démon en cours d’exécution. Boutons actuels : cluster.ban_ttl, url_ring_sample_rate, et par pool pool:<name>.health.passive.consecutive_5xx / pool:<name>.health.passive.eject_for. Les overrides runtime sont éphémères (perdus au redémarrage, dérive visible via bouine config diff) et bouine config set se propage à tous les peers vivants en mode strong (POST /v1/peer/config/hot).
• bouine config reload / POST /v1/config/reload (expérimental, derrière experimental.config_reload) : ré-applique un fichier de config à un démon en cours, applique le sous-ensemble à chaud, et rapporte applied / unchanged / NEEDS RESTART.

bouine config get
bouine config set cluster.ban_ttl 45m
bouine config set cluster.ban_ttl 45m --dry-run
bouine config diff
bouine config reload --file /etc/bouine/config.yaml