Reference on bouine

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.

Admin API

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:

Response headers

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

X-Cache

Indicates how the response was served.

Value	Description
`HIT`	Served from cache (fresh)
`MISS`	Fetched from origin and cached
`STALE`	Served from cache (stale, within stale-while-revalidate or stale-if-error window)
`BYPASS`	Cache bypassed (no-store, no-cache, or cache disabled for route)
`REVALIDATED`	Conditional request to origin returned 304, served from cache with updated freshness

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

Age

The age of the cached object in seconds, calculated as the time since the Date header of the original response plus any time spent in upstream forward proxies. Updated on every 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.

Example Reference

Thu, 07 Sep 2023 16:13:18 +0200

Reference pages are ideal for outlining how things work in terse and clear terms. Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what your documenting.