Architecture

Layered design

bouine is structured in 8 layers, each testable in isolation.

HTTP stacks

One HTTP implementation only:

• fasthttp — HTTP/1.1 only (data plane + admin)

The admin API uses a manual method+path router on fasthttp.Server.

HTTP/2 is not currently available. bouine previously supported HTTP/2 (h2 over TLS, h2c over plaintext) via Go’s net/http. The migration to fasthttp as the sole HTTP stack (ADR-0034) dropped HTTP/2 support to achieve a zero-allocation hit path. HTTP/2 reintroduction is in progress, planned as a fasthttp-native implementation rather than re-adopting net/http.

Cache engine

The RFC 9111 state machine is deterministic: inputs are *http.Request, stored *Object, and now. Outputs are HIT, MISS, REVALIDATE, STALE_HIT, or BYPASS.

Cache key

Primary key: 128-bit XXH128(scheme | host | path | sorted_query | method). The full 16-byte hash is used as a map key, providing 128-bit collision resistance without a separate lookup step. Zero allocations via one-shot Sum128.

Secondary key (Vary): derived from the request headers listed in the response’s Vary header, or from cache.key.include_headers.

Eviction

• SIEVE — simple, near-LRU-K performance, O(1) per operation
• mmap slab (optional, Linux) — hot body bytes are allocated via mmap to avoid Go heap GC pressure (storage.hot_mmap_slab: true)

CDN-Cache-Control (RFC 9211)

When the origin sends a CDN-Cache-Control header, it takes precedence over Cache-Control for all shared-cache decisions. This allows origins to set different TTLs for CDN caches vs browser caches:

Cache-Control: no-store              # browsers don't cache
CDN-Cache-Control: max-age=3600      # bouine caches for 1h

Surrogate keys

Origins can tag responses with opaque surrogate keys for grouped invalidation:

Surrogate-Key: product-456 category-shoes
Cache-Tag: product-456, category-shoes

bouine reads Surrogate-Key, Cache-Tag, and X-Cache-Tags at store time and makes them available for POST /v1/ban{surrogate_key:"..."} invalidation.

Negative caching

404, 405, 410, 501 responses can be cached for a configurable duration (negative_ttl).

Jittered TTLs

Random ±N% applied to every TTL to prevent synchronized expiry stampedes across cached entries.

Clustering

bouine supports two consistency modes (see Clustering):

Strong mode (default)

Sharding: Consistent hash with 256 virtual nodes per real node. On a miss, the requesting node checks the owner node before going to origin.

Eventual mode

Every node is independent — no sharding, no peer-fetch. Invalidations propagate via gossip only. Each node caches whatever it receives from origin.

Membership (all modes)

hashicorp/memberlist for gossip. Nodes bootstrap via StatefulSet DNS.

Peer fetch flow (strong mode only)

Added latency for a peer hit: ~0.3ms (one in-cluster HTTP/1.1 hop).

Stale-while-revalidate (SWR)

When an object enters its stale-while-revalidate window, bouine:

1. Serves the stale object immediately (no client wait).
2. Fires a background goroutine (bgRevalSem bounds concurrency to 256) that conditionally revalidates with the origin.
3. The origin reply (200 or 304) updates the hot store; the next request gets a fresh HIT.

This is what eliminates the 93% effective hit rate gap vs Varnish in mixed workloads — both caches serve stale immediately and refresh asynchronously.

Invalidation propagation

In strong mode, the HTTP fan-out ensures sub-second invalidation propagation. The gossip broadcast queue provides a redundant delivery path.

Join protocol

Pods retry joining every 2 seconds for up to 60 seconds. Success requires Members() > 1 (at least one real peer, not self-join). The headless Service must have publishNotReadyAddresses: true.

Performance

Load-test results (Docker, 3k RPS, single node vs Varnish + nginx):

†nginx’s high mixed average is due to blocking revalidation; bouine and Varnish both use background SWR refresh.

All gates enforced in CI — regressions block merge.