CDN
CDN control-plane. Multi-provider (cloudflare | cloudfront | fastly | direct | stub).
TRUTHFULNESS INVARIANT (changed in 0.2.0 — read before generating a client): purged: true means an upstream purge ACTUALLY happened and succeeded, and nothing else. Every configuration with no working upstream — provider direct, provider stub, the declared-but-unimplemented cloudfront/fastly, and cloudflare without CLOUDFLARE_ZONE_ID + CLOUDFLARE_API_TOKEN — answers 503 with purged: false and a reason. In 0.1.0 direct answered 200 purged: true after making no upstream call at all, so a caller reported a cleared cache that was never cleared; indexofnews.com is served THROUGH the Cloudflare edge, so that was a false claim about a real cache. A non-2xx (rather than 200 + purged:false) is what makes the platform cutover deploy-order-independent: the platform's shipped client treats any status >= 300 as a failed delegation and fails CLOSED, so setting CDN_CORE_URL before the platform image carries a matching client still yields the honest answer instead of a silent success.
AUTH (added in 0.2.0): the two state-changing routes require a bearer (SERVICE_TOKEN, or an identity JWT when IDENTITY_JWKS_URL is armed) and resolve a tenant via the shared TenancyResolver. With neither configured they answer 503 — "not configured" is never "open". They were previously reachable unauthenticated by anything on the shared docker network, which made purge_all a one-request cache-nuke once creds are armed. Read-only routes stay open.
Cloudflare purge is capped at 30 URLs/call. cache_key = sha256 first-32 hex of the url joined with vary headers SORTED BY HEADER NAME (url|k1=v1|k2=v2) — sorting the formatted k=v strings instead diverges from the platform for prefix pairs such as Accept / Accept-Encoding.
- Group: Content & media
- Contract:
contracts/cdn/v1/openapi.yaml - Console: internal — operated by Vagary Labs; no customer console page for this capability.
- Runbook: operational checklist for
cdn— internal (Vagary Labs ops; not part of this public site):docs/runbooks/capability-operations.md#cdn - Public access: none — internal-only capability. It is NOT exposed on the public API gateway (
https://api.vagarylabs.com); it is reachable only inside the fleet (container/tailnet) by first-party callers. There is no customer-facing endpoint to call.
Endpoints
| Method | Path | Summary |
|---|---|---|
GET | /health | liveness + provider + purge_mode (open) |
GET | /metrics | Prometheus text (open) |
POST | /v1/cdn/purge | purge CDN cache (by paths, capped 30/CF-call, or purge_all) |
POST | /v1/cdn/configure | set provider + base_url (cloudflare without creds is downgraded to direct, and says so) |
GET | /v1/cdn/stats | provider + purge_mode + recent purge stats (open, read-only) |
GET | /v1/cdn/url-rewrite | the CDN URL for an asset path (open, pure) |
GET | /v1/cdn/cache-key | sha256[:32] cache key for a url + vary headers sorted by header NAME |
Schemas
PurgeResult
| Field | Type | Description |
|---|---|---|
purged | boolean | TRUE only when an upstream purge was performed AND succeeded. |
upstream_purged | boolean | whether a call was actually made to a CDN provider. Never true when mode != cloudflare. |
mode | string | what the current provider config can do to an upstream cache. none = provider 'direct' (nothing in front to purge); unconfigured = cloudflare selected but creds absent; unimplemented = provider has no purge backend here; stub = test double. |
reason | string | present when mode != cloudflare — why no purge happened |
provider | string | |
paths_count | integer | |
purge_all | boolean | |
ts | string | |
error | string | present when an attempted upstream purge failed |
Generated by scripts/gen-capability-docs.py from contracts/cdn/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page. The Edge route table section is synced from the live edge catalog snapshot (v1) — re-sync with python3 scripts/sync-edge-catalog.py.