bouine

Cycle de vie

Mon, 01 Jan 0001 00:00:00 +0000

Starting bouine

bouine serve --config /etc/bouine/config.yaml --log-format json

On Kubernetes the StatefulSet container runs this command via the Helm chart (see deploy/helm/bouine/templates/statefulset.yaml). The --log-format json flag ensures structured logging for aggregation.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Docker

Le moyen le plus rapide d’exécuter bouine est l’image Docker :

docker pull bouinecache/bouine:latest
docker run --rm -p 8080:80 -p 9000:9000 bouinecache/bouine:latest

L’image par défaut inclut une configuration minimale dans /etc/bouine/config.yaml afin que le conteneur démarre sans montage de volume.

Migration depuis NGINX

Mon, 01 Jan 0001 00:00:00 +0000

Directive mapping

NGINX directive	bouine config	Notes
`proxy_cache_path ... max_size=1g`	`storage.hot_max_bytes: 1GiB`	bouine uses in-RAM storage, no filesystem levels
`proxy_cache_path ... keys_zone=api:10m`	Not needed	bouine manages shard count automatically (`N=NumCPU`)
`proxy_cache_valid 200 60s`	`routes[].cache.ttl_default: 60s`	Per-route, respects `Cache-Control` by default
`proxy_cache_valid 404 10s`	`routes[].cache.negative_ttl: 10s`	Negative caching for error responses
`proxy_cache_use_stale error http_500 http_502 http_503 http_504`	`routes[].cache.stale_if_error: 30s`	Serves stale on origin 5xx or timeout
`proxy_cache_background_update on`	`routes[].cache.stale_while_revalidate: 10s`	Background revalidation while serving stale
`proxy_cache_revalidate on`	Built-in	Conditional requests (`If-None-Match`, `If-Modified-Since`)
`proxy_cache_key $scheme$host$request_uri`	Automatic	xxhash128 of scheme+host+path+sorted query
`proxy_cache_key $scheme$host$request_uri$http_accept`	`cache.key.include_headers: [Accept]`	Explicit header keying
`proxy_ignore_headers Vary`	`cache.key.include_headers: [...]`	Explicit header keying instead of Vary
`proxy_no_cache $variable`	`routes[].cache.enabled: false`	Per-route disable
`proxy_cache_bypass $variable`	Not needed	Use route matching to separate cached/uncached
`proxy_cache_lock on`	Built-in (request collapsing)	Single-flight per cache key
`proxy_cache_lock_timeout 5s`	Built-in	Subscribers wait for leader fetch
`proxy_cache_min_uses 3`	Not needed	bouine caches on first response (RFC 9111)
`add_header X-Cache-Status $upstream_cache_status`	Built-in	`X-Cache` header (HIT, MISS, STALE, BYPASS, REVALIDATED)
`proxy_next_upstream error timeout`	`upstream_pools[].health.passive`	Passive health checks with outlier ejection
`upstream backend { keepalive 32; }`	`upstream_pools[].connect.max_idle_conn_duration: 60s`	Durée de vie des connexions inactives vers l’origine. Gardez la valeur de bouine en dessous de tout timeout inactif de LB entre bouine et l’origine (ex. AWS NLB 350s) pour que bouine ferme les connexions inactives en premier.
`keepalive_timeout 65s`	`listen.idle_timeout: 65s`	Timeout keep-alive inactif des connexions côté client. Gardez la valeur du frontal en dessous de celle de bouine pour que le frontal ferme les connexions inactives en premier ; sinon bouine peut fermer une connexion en cours de réutilisation et l’upstream journalise `upstream prematurely closed connection`.

Key differences

No zone configuration — bouine manages memory automatically with SIEVE eviction
No filesystem cache — bouine uses in-RAM hot tier + mmap warm tier (no proxy_cache_path on disk)
Clustering built-in — NGINX requires third-party modules for cache sharing; bouine has gossip + peer fetch
RFC 9111 native — bouine implements the spec directly, not via directives
Observability built-in — Prometheus /metrics, structured JSON access logs with cache_status
No proxy_pass needed — upstream pools are declared separately and referenced by name in routes
Declarative config — no if blocks, no map directives, no embedded Lua

Example: API gateway

NGINX:

Authentification

Mon, 01 Jan 0001 00:00:00 +0000

All write endpoints require Authorization: Bearer <token>. The token is resolved in priority order:

BOUINE_ADMIN_TOKEN environment variable (recommended for Kubernetes / Vault injection)
admin.token in the config file
Auto-generated random token (logged as WARN at startup)

Environment variable

Set BOUINE_ADMIN_TOKEN to inject the token without baking it into the config ConfigMap:

Démarrage rapide

Mon, 01 Jan 0001 00:00:00 +0000

Démarrez un petit serveur d’origine :

mkdir -p /tmp/bouine-origin
printf 'hello from origin\n' > /tmp/bouine-origin/index.html
python3 -m http.server 3000 --directory /tmp/bouine-origin

Créez config.yaml :

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

storage:
 hot_max_bytes: 256Mo

upstream_pools:
 - name: origin
 targets: ["127.0.0.1:3000"]

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

Exécutez bouine :

Exemples de reverse proxy

Mon, 01 Jan 0001 00:00:00 +0000

bouine in front of Caddy

Caddy typically serves static files or acts as a reverse proxy itself. Deploy bouine in front of Caddy to add caching without modifying Caddy’s config.

Guide du code

Mon, 01 Jan 0001 00:00:00 +0000

Carte des packages

Package	Couche	Rôle
`internal/server`	L1	HTTP/1.1 (`fasthttp`), TLS, correspondance de routes
`internal/storage`	L2	Hot store, niveau tiède, WAL, SIEVE
`internal/cache`	L3	Machine à états RFC 9111 et handler
`internal/origin`	L4	Pools amont, health checks, clients origin
`internal/cluster`	L5	gossip memberlist, anneau de hachage, peer fetch
`internal/admin`	L6	API HTTP d’administration
`internal/observability`	L7	Métriques, journaux, journal d’accès

Migration depuis Varnish

Mon, 01 Jan 0001 00:00:00 +0000

Status: Stable for production use. Assumes familiarity with VCL and bouine’s YAML configuration model.

Quick reference

Varnish concept	bouine equivalent	Notes
VCL subroutines	declarative YAML config	bouine uses config, not code
`vcl_recv`	`routes[].match`	routing and request matching
`vcl_hash`	automatic cache key (`xxhash64`)	scheme + host + path + query + method
`vcl_backend_fetch`	`upstream_pools[]`	backend pool config
`vcl_backend_response`	origin `Cache-Control`	bouine honors RFC 9111 strictly
`beresp.ttl`	`cache.ttl_default`	overridden by origin headers
`beresp.grace`	`cache.stale_while_revalidate`	SWR semantics
`ban()`	admin API `POST /v1/ban`	HTTP-based invalidation API
`purge`	admin API `POST /v1/purge`	exact-match invalidation
Varnish log (`-g request`)	structured JSON logs (stdout)	pipe to any log aggregator
`varnishstat`	`/metrics` (Prometheus)	Prometheus-compatible metrics
VSM/shared memory	in-process memory	no mmap, no VSM files

1. Conceptual mapping

The big picture

Varnish is a programmable cache — you write VCL to define cache behavior. bouine is a declarative cache — you write YAML to describe routes, backends, and cache policies, and bouine implements RFC 9111 rigorously.

Politique de cache

Mon, 01 Jan 0001 00:00:00 +0000

TTL selection

bouine picks freshness in this order:

CDN-Cache-Control (RFC 9211 targeted header — overrides Cache-Control for shared caches)
s-maxage
max-age
Expires (valid dates only; syntactically invalid Expires values are ignored)
Route ttl_default (operator fallback when origin sends no freshness)
Heuristic freshness from Last-Modified (10% of Date − Last-Modified, where allowed by status code)

If the route has ttl_override set, its value replaces the result of this waterfall entirely. See TTL override below.

Streaming et réponses live

Mon, 01 Jan 0001 00:00:00 +0000

bouine ne bufferise jamais un corps de réponse quand ce n’est pas nécessaire. Cette page documente les trois comportements de streaming et les deux protections de surcharge qui y interagissent.

Docker

Mon, 01 Jan 0001 00:00:00 +0000

Exécuter l’image officielle

docker run --rm \
 -p 8080:80 \
 -p 9000:9000 \
 bouinecache/bouine:latest

Monter un fichier de configuration

docker run --rm \
 -p 8080:80 \
 -p 9000:9000 \
 -v "$PWD/config.yaml:/etc/bouine/config.yaml:ro" \
 bouinecache/bouine:latest

Construire localement

Sur Apple Silicon ciblant un cluster Linux amd64 :

Invalidation du cache

Mon, 01 Jan 0001 00:00:00 +0000

Purge (exact URL)

# CLI
bouine purge https://example.com/products/123 --token <token>

# API
curl -X POST http://127.0.0.1:9000/v1/purge \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{"url":"https://example.com/products/123"}'

In a cluster, the purge is forwarded to all live peers via HTTP fan-out (in strong mode) or gossiped via the memberlist broadcast queue (in eventual mode). Since v0.5.14, fan-out is batched: purge and refresh events coalesce into batch frames flushed on 256 events, a 10 ms interval, or shutdown — a 1000-key purge burst in a 3-peer cluster produces a handful of batched POSTs instead of 3000 — and receivers deduplicate by per-issuer sequence number. Events arriving on an idle queue still flush synchronously, preserving the purge API’s fan-out-before-return guarantee. Ban events stay unbatched (rare; immediacy dominates).

Modes de cohérence du cluster

Mon, 01 Jan 0001 00:00:00 +0000

Verify your mode

# Prometheus metric: always 1 with the mode label.
curl -s http://127.0.0.1:9000/metrics | grep bouine_cluster_mode_info

# Admin API: /v1/cluster/peers returns all members in every mode.
curl -s http://127.0.0.1:9000/v1/cluster/peers \
 -H "Authorization: Bearer ${BOUINE_ADMIN_TOKEN}"

# CLI
bouine cluster peers --server 127.0.0.1:9000 --token "${BOUINE_ADMIN_TOKEN}"

Expected: every node reports the same mode label. If they disagree, the cluster has a configuration drift — every pod must use the same mode.

Sécurité

Mon, 01 Jan 0001 00:00:00 +0000

Signalez les problèmes de sécurité via le Signalement privé de vulnérabilités de GitHub — cela crée un avis suivi et embargoé. Aucun alias e-mail de sécurité n’est publié.

Périmètre

Binaire bouine
Chart Helm
Image conteneur
SDK Go

Exemples de problèmes à fort impact

Cache poisoning qui fuit la réponse d’un utilisateur vers un autre
HTTP request smuggling à travers le data plane
Contournement de l’authentification de l’API d’administration
Peer impersonation en mode cluster
Path traversal dans le stockage de warm tier

Checklist de durcissement

Gardez le port d’administration privé ; exposez-le uniquement via le réseau interne ou mTLS.
Utilisez la vérification TLS pour les upstreams.
Exécutez les conteneurs en tant que non-root.
Utilisez des NetworkPolicy pour les ports de cluster et d’administration.
Surveillez les taux de purge/ban pour détecter les abus.
Ne journalisez pas les corps de requête/réponse ni les identifiants.

Servir des fichiers statiques

Mon, 01 Jan 0001 00:00:00 +0000

Overview

A route can serve files from a local directory instead of proxying to an upstream pool. This eliminates the need for a separate origin server (nginx, Caddy) when the content is already on the same machine as bouine — useful for single-node CDN edges, sidecar deployments, and static asset routes.

Storage tiers

Mon, 01 Jan 0001 00:00:00 +0000

bouine uses a two-tier storage architecture: a fast in-memory hot tier and an optional disk-backed warm tier.

Hot tier (RAM)

The primary cache store. Every cache hit is served from here.

Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Ajouter le dépôt de charts

bouine publie un dépôt de charts Helm à l’adresse https://charts.bouine.org, indexé sur Artifact Hub. Le chart récupère l’image bouinecache/bouine depuis Docker Hub par défaut.

helm repo add bouine https://charts.bouine.org
helm repo update
helm search repo bouine

NAME CHART VERSION APP VERSION DESCRIPTION
bouine/bouine 0.5.8 0.5.8 Cloud-native HTTP cache in Go ...

Démarrage rapide Helm

helm install bouine bouine/bouine \
 --namespace bouine --create-namespace \
 --set "config.upstream_pools[0].name=app" \
 --set "config.upstream_pools[0].targets[0]=app.default.svc:8080" \
 --set "config.routes[0].pool=app"

Cela déploie un StatefulSet avec clustering par gossip, un Service headless pour la découverte des pairs et un PodDisruptionBudget.

Planification de capacité

Mon, 01 Jan 0001 00:00:00 +0000

Step 1: Estimate your working set

The working set is the total size of responses that need to stay cached for acceptable hit rates.

working_set ≈ unique_cacheable_urls × avg_response_size

Workload	Typical working set
REST API (100k endpoints, 2 KiB avg)	~200 MiB
E-commerce catalog (1M products, 5 KiB avg)	~5 GiB
Static site / CDN (50k assets, 50 KiB avg)	~2.5 GiB
Media-heavy site (10k pages, 200 KiB avg)	~2 GiB

If you cannot estimate, start with 2 GiB and monitor bouine_hot_store_bytes / bouine_hot_store_max_bytes. If it stays above 0.9 consistently, double hot_max_bytes.

Supervision

Mon, 01 Jan 0001 00:00:00 +0000

Prometheus metrics

All metrics are exposed at GET /metrics on the admin port (default :9000) in Prometheus text format. No authentication is required to scrape this endpoint.

Traffic (RED)

Metric	Labels	Description
`bouine_requests_total`	`status`, `cache_result`, `source`, `upstream_pool`	Total requests processed, carrying the exact status code. This is the primary RED counter.
`bouine_request_duration_seconds`	`status` (response class), `cache_result`, `upstream_pool`	Request latency histogram. The status label carries the response class (`1xx`–`5xx`), not the exact code; exact codes stay on `bouine_requests_total`. Also exposed as a native histogram for high-resolution percentiles — see below.
`bouine_response_bytes_total`	`cache_result`, `source`, `upstream_pool`	Total bytes written in responses.
`bouine_fetch_shed_total`	—	Foreground origin fetches shed after waiting `fetch_wait_timeout` for a fetch-semaphore slot. Non-zero rate means miss demand exceeds `max_fetch_concurrency`. See Streaming and live responses.

cache_result values: HIT, MISS, STALE, REVALIDATED, BYPASS.

TLS

Mon, 01 Jan 0001 00:00:00 +0000

bouine terminates TLS natively for HTTP/1.1. No external TLS proxy is needed.

Minimal TLS config

listen:
 https: ":443"
 admin: ":9000"

tls:
 certs:
 - cert_file: /etc/bouine/tls/cert.pem
 key_file: /etc/bouine/tls/key.pem

Multiple certificates (SNI)

Serve different certificates per hostname:

Clustering

Mon, 01 Jan 0001 00:00:00 +0000

Cluster mode lets multiple bouine pods share cache reads, broadcast invalidations, and reduce origin load.

Choosing a mode

listen:
 cluster: ":8443"

cluster:
 mode: strong # "strong" (default) | "eventual"

Use this decision guide:

Example configurations

Mon, 01 Jan 0001 00:00:00 +0000

Static site / blog

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

storage:
 hot_max_bytes: 64Mo

upstream_pools:
 - name: site
 targets: ["site.default.svc.cluster.local:80"]

routes:
 - match: { path_prefix: /assets/ }
 pool: site
 cache:
 ttl_default: 86400s
 stale_if_error: 604800s
 jitter_percent: 10

 - match: { path_prefix: / }
 pool: site
 cache:
 ttl_default: 300s
 stale_while_revalidate: 60s
 stale_if_error: 86400s
 jitter_percent: 15

Self-served static site (no origin server)

bouine can serve files directly from disk — no separate nginx or Caddy needed. See Static file serving for the full reference.

Guide d'observabilité

Mon, 01 Jan 0001 00:00:00 +0000

This guide walks you through deploying a complete observability stack for bouine using the Grafana LGTM components (Loki, Grafana, Tempo, Mimir/Prometheus) and Grafana Alloy as the unified collection agent.

Architecture

 monitoring namespace
 ┌──────────────────────────────────────────────────┐
 │ Grafana ──queries──▶ Prometheus (metrics) │
 │ Loki (logs) │
 │ Tempo (traces) │
 │ ▲ ▲ ▲ │
 │ Grafana Alloy (single agent) │
 └─────────────────────│────│────│──────────────────┘
 scrape :9000│ │OTLP :4318
 tail pod logs (k8s API) │
 │
 bouine pods

Grafana Alloy replaces three separate agents:

Opérations Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Scaling

kubectl scale statefulset/bouine -n <namespace> --replicas=3

Gossip auto-discovers peers via the headless Service DNS. New pods join the cluster within 60s.

Rolling update (zero 5xx)

kubectl rollout restart statefulset/bouine -n <namespace>
kubectl rollout status statefulset/bouine -n <namespace> --timeout=180s

StatefulSet rolls one pod at a time (reverse ordinal). Each pod must pass the readiness probe (GET /readyz) before the next is replaced.

Tableau de bord

Mon, 01 Jan 0001 00:00:00 +0000

The operator dashboard is embedded directly in the admin server — no extra process, no Node toolchain. Open it at:

http://<admin-addr>/dashboard/

Default on localhost: http://localhost:9000/dashboard/

Logging in

The dashboard uses a session cookie derived from the admin bearer token.

Benchmarks

Mon, 01 Jan 0001 00:00:00 +0000

Disclaimer

Benchmarks are synthetic. They measure isolated behavior in artificial conditions. Production workloads have different allocation patterns, concurrency levels, GC pressure, network conditions, and hardware. The Varnish and NGINX configurations used in these tests could likely be improved — a differently tuned Varnish or NGINX may produce different results. Benchmarking is genuinely hard, and these numbers should be treated as directional indicators, not as definitive performance claims.

Helm chart reference

Mon, 01 Jan 0001 00:00:00 +0000

The Helm chart deploys bouine as a StatefulSet with headless Service for gossip peer discovery. Source: deploy/helm/bouine/.

Install

helm repo add bouine https://charts.bouine.org
helm repo update

helm install bouine bouine/bouine \
 --namespace bouine --create-namespace \
 --set "config.upstream_pools[0].name=app" \
 --set "config.upstream_pools[0].targets[0]=app.default.svc:8080" \
 --set "config.routes[0].pool=app"

To install from a local checkout, replace bouine/bouine with the chart directory deploy/helm/bouine.

Fonctionnalités expérimentales

Mon, 01 Jan 0001 00:00:00 +0000

Experimental features are opt-in capabilities that bypass some of bouine’s standard processing paths for improved performance. They are gated behind the experimental config section and default to off.

Warning: Experimental features may change or be removed between releases. Test thoroughly before enabling in production.

Production readiness checklist

Mon, 01 Jan 0001 00:00:00 +0000

Before deploying bouine to production, verify each item below. Items are grouped by area. Skip items that don’t apply to your deployment.

TLS and network security

Data-plane TLS configured (if terminating HTTPS at bouine)
Cluster mTLS enabled (cert + key + CA bundle for peer-to-peer)
Admin port not exposed externally (NetworkPolicy or firewall)
Admin token set via Secret or environment variable (not auto-generated)
insecure_skip_verify is not set in any upstream pool TLS config
Hop-by-hop headers stripped (handled automatically by bouine)

Resource sizing

resources.limits.memory set and GOMEMLIMIT auto-computed (Helm chart does this)
hot_max_bytes sized to fit in RAM without GC pressure (default: 75% of GOMEMLIMIT)
Warm tier PVC sized for working set (warmVolume.size)
warm_max_bytes set below PVC capacity to leave headroom
max_object_size configured per route to reject oversized responses
max_response_bytes configured to prevent memory exhaustion from large bodies

Cluster and high availability

replicaCount >= 3 for quorum
podDisruptionBudget.enabled: true with minAvailable >= 2
Topology spread constraints set across zones
hop_limit configured (default 2 is fine for most deployments)
terminationGracePeriodSeconds >= 40 to allow graceful drain
minReadySeconds >= 30 to let the ring converge before traffic

Caching policy

Every route has ttl_default set explicitly
stale_while_revalidate configured for routes that can serve stale
stale_if_error configured for origin-outage resilience
negative_ttl set for routes that return errors (prevents error storms)
jitter_percent > 0 to prevent synchronized revalidation bursts
allow_set_cookie is off unless you explicitly need Set-Cookie caching
Cache key configuration reviewed (query param stripping, header includes)

Upstream and origin

Active health checks enabled per pool
Passive health checks enabled (consecutive_5xx, eject_for)
Upstream connection timeout and response header timeout configured
max_connections set per pool to prevent FD exhaustion
listen.max_connections set to bound total data-plane connections (default 4096)
listen.idle_timeout tuned against front-end/LB idle timeouts (front-end must close idle connections first)
connect.max_idle_conn_duration kept below any LB idle timeout between bouine and the origin (AWS NLB: 350s)
response_header_timeout configured to prevent slow-origin connection churn
cluster.peer_max_idle_conn_duration kept below admin.idle_timeout (default 300s)
cluster.peer_fetch_concurrency sized for strong-mode peer-hit load (default 4, range 1–128)
Alerting on bouine_fetch_shed_total (slow-origin shedding — see Streaming)
Alerting on bouine_peer_fetch_shed_total and bouine_peer_fetch_queue_wait_seconds in strong-mode clusters (peer-fetch saturation — see Monitoring)

Observability

Prometheus scraping enabled (ServiceMonitor scraping the admin Service)
Grafana dashboards imported (RED, storage, cluster, ops)
Alerting rules deployed (hit rate, error rate, peer fetch, warm tier)
OpenTelemetry tracing endpoint configured (or disabled explicitly)
Access log sampling rate appropriate (default 1:100 for 200s)
pprof_enabled is off in production (default)
Native-histogram metric_relabel_configs considered for bouine_request_duration_seconds (see Monitoring)

Kubernetes deployment

Helm chart deployed with production values (values-production.yaml as base)
NetworkPolicy.enabled: true to isolate admin and cluster ports
Data plane exposed via service.type: LoadBalancer — the admin plane stays on the separate admin Service
With autoscaling.enabled: ArgoCD ignoreDifferences for /spec/replicas on the StatefulSet
serviceAccount.automount: false (bouine doesn’t need K8s API access)
Probes configured: startup (30 min budget), readiness (/readyz), liveness (/healthz)
Rolling update strategy: maxUnavailable: 1 for sequential pod restarts
Config changes deployed via rolling update (no live config reload)

Operations

Purge and ban workflows documented for on-call
Runbook accessible (see operations docs)
Backup strategy for warm tier (PVC snapshots or rebuild from origin)
Drain procedure tested (/drain endpoint + preStop hook)
Config file stored in version control

Compatibilité avec les service mesh

Mon, 01 Jan 0001 00:00:00 +0000

bouine works with any service mesh that operates at L4/L7. The main consideration is the double-TLS problem: if the mesh enforces mTLS between sidecars, bouine must either terminate TLS itself or let the sidecar handle it.

Propagation Cloudflare CDN

Mon, 01 Jan 0001 00:00:00 +0000

Overview

When bouine sits behind Cloudflare (or any scenario where Cloudflare caches responses delivered through bouine), invalidating a URL in bouine is not enough — the entry may also be cached at the Cloudflare edge.

CLI

Mon, 01 Jan 0001 00:00:00 +0000

Commands

bouine serve --config /etc/bouine/config.yaml
bouine config validate <file>
bouine config schema
bouine completion bash|zsh|fish
bouine purge <url> --token <token>
bouine ban host_regex=example.com path_regex=^/api --token <token>
bouine refresh <url> --token <token>
bouine cluster peers
bouine version

--server defaults to 127.0.0.1:9000. All commands default to port 9000 so --server is optional when running locally.

API d'administration

Mon, 01 Jan 0001 00:00:00 +0000

Authentication

All write endpoints require a bearer token. See Authentication for full details on token resolution, environment variables, and config file setup.

Pass the token in requests:

curl -X POST http://127.0.0.1:9000/v1/purge \
 -H "Authorization: Bearer your-secret-token" \
 -H "Content-Type: application/json" \
 -d '{"url":"https://example.com/page"}'

Exempt endpoints (no token required)

These are always accessible without authentication — required for K8s probes and Prometheus scraping:

En-têtes de réponse

Mon, 01 Jan 0001 00:00:00 +0000

X-Cache

Indique comment la réponse a été servie.

Valeur	Description
`HIT`	Servi depuis le cache (frais)
`MISS`	Récupéré depuis l’origine et mis en cache
`STALE`	Servi depuis le cache (stale, dans la fenêtre stale-while-revalidate ou stale-if-error)
`BYPASS`	Cache contourné (no-store, no-cache, cache désactivé pour la route, ou requête SSE)
`REVALIDATED`	Requête conditionnelle à l’origine a renvoyé 304, servi depuis le cache avec une fraîcheur mise à jour

curl -sI http://localhost:8080/get | grep x-cache
# X-Cache: HIT

Age

L’âge de l’objet en cache en secondes, calculé comme le temps écoulé depuis l’en-tête Date de la réponse originale plus tout le temps passé dans les forward proxies upstream. Mis à jour à chaque cache hit.

Go SDK

Mon, 01 Jan 0001 00:00:00 +0000

The bouine Go SDK (pkg/bouineapi) provides typed methods for every admin API endpoint. It shares wire types with the Cobra CLI and the admin server, so there is no drift between the SDK and the API.

Dépannage

Mon, 01 Jan 0001 00:00:00 +0000

Quick reference

Symptom	Severity	Jump to
Pods don’t discover each other	Critical	Cluster discovery
Rolling restart produces 503/502	High	Rolling restart
Purge doesn’t propagate	High	Purge propagation
HIT p99 spikes to 50–100 ms under load	High	GC stop-the-world pauses
Status 0 responses / FD exhaustion	High	FD exhaustion
`X-Cache` always MISS	Medium	Cache misses
Stale reads on one node	Medium	Stale reads
Low hit rate in eventual mode	Low	Low hit rate
Docker build slow on Apple Silicon	Low	Docker build

Cluster discovery

Pods do not discover each other

Check the headless Service:

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

General

How is bouine different from Varnish?

bouine is designed for Kubernetes from day one: gossip clustering, Helm chart, Prometheus metrics, and OpenTelemetry tracing are built-in. Varnish requires commercial Varnish Plus or external orchestration for clustering, and uses VCL (an imperative DSL) instead of declarative YAML. See the migration guide for a side-by-side comparison.

404

Mon, 01 Jan 0001 00:00:00 +0000

Politique de confidentialité

Mon, 01 Jan 0001 00:00:00 +0000