Cache control

The edge honours standard response directives. Where an origin sends none, a conservative default of five minutes applies to 200, 301 and 404 responses.

Directive	Effect at the edge
s-maxage	Takes precedence over max-age for shared caches
stale-while-revalidate	Serves the stale object while a background fetch runs
stale-if-error	Serves the stale object when the origin returns 5xx or times out
private, no-store	Bypasses the edge cache entirely
Vary	Honoured; a high-cardinality header will fragment the cache

Response headers

Every response carries the PoP that served it and the cache disposition, which makes a miss easy to attribute.

HTTP/2 200
cache-control: public, s-maxage=600, stale-while-revalidate=86400
x-halcyon-pop: sg01
x-halcyon-cache: HIT
x-halcyon-shield: ap-shield-1
age: 143

Values for x-halcyon-cache are HIT, MISS, REVALIDATED, BYPASS and EXPIRED.

Purge API

Invalidation is asynchronous and idempotent. A purge is accepted with 202 and propagates to every PoP; repeating the same call is harmless.

curl -X POST https://api.halcyon-edge.example/v1/zones/$ZONE/purge \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"tags":["catalog","pricing"]}'

Prefix purges are also accepted, and are the right tool after a deploy that rewrote a whole directory:

{"prefixes": ["/static/build/", "/img/hero/"]}

Health checks

Each node answers a plain-text probe. Use it for synthetic monitoring rather than fetching the landing page.

$ curl -s https://sg01tls.bulsan.site/healthz
ok sg01