Edge Cache documentation

Edge Cache is a small HTTP caching layer that sits in front of an origin server and answers repeat requests from a node close to the visitor. This page is the operator reference: cache keys, freshness rules, the purge endpoint and the response headers you can expect to see.

How a request is served

A request arriving at a node is normalised into a cache key. If a fresh object exists for that key it is returned immediately. If the object exists but has expired, the node revalidates it against the origin with a conditional request. If nothing is stored, the node fetches the object, stores it when it is cacheable and returns it to the visitor.

Cache key

The default key is the scheme, host, path and the sorted query string. The fragment is never part of the key, and cookies are ignored unless the origin marks a response as varying on them.

https://example.com/assets/app.css?v=8
  -> https|example.com|/assets/app.css|v=8

Freshness

Origin directives win. A node only applies its own default TTL when the origin sends no explicit freshness information at all.

Origin sends	Node behaviour
`Cache-Control: max-age=N`	Stored for N seconds.
`Cache-Control: no-store`	Never stored.
`Cache-Control: private`	Never stored on a shared node.
`Expires` only	Used when no `max-age` is present.
nothing	Default TTL of 600 s for `200`, 30 s for `404`.

Response headers

Every response carries a status header describing what the node did:

`X-Cache`	Meaning
`HIT`	Served from the node, still fresh.
`MISS`	Not stored; fetched from the origin.
`REVALIDATED`	Stored but stale; origin confirmed it with `304`.
`BYPASS`	Request or response was not cacheable.

Age reports how many seconds the stored copy has been held. Range requests, ETag and Last-Modified pass through unchanged.

Purging

A purge removes one object from every node. Purges are asynchronous; the call returns as soon as the request is accepted, and propagation normally completes within a few seconds.

curl -X POST https://docs.cdn-edge.space/api/purge \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/assets/app.css?v=8"}'

Prefix purges use {"prefix":"https://example.com/assets/"} instead of url. A prefix purge is rate limited to one call per minute per zone, because it invalidates every matching object on every node.

Compression

Nodes store one copy per encoding actually negotiated. If the origin sends an uncompressed body and the visitor accepts gzip, the node compresses once and reuses the result. Origins that already compress are passed through untouched — double compression is never applied.

Limits

Maximum object size	512 MB
Maximum TTL	31 days
Origin connect timeout	5 s
Origin read timeout	60 s

Troubleshooting

Everything is a MISS

Check the origin's Cache-Control. A single private or no-store directive disables storage entirely, and many application frameworks add one by default to every response that touches a session.

Stale content after a deploy

Version your asset URLs rather than relying on purges. A changed query string is a different cache key and takes effect immediately everywhere.

A purge did not take effect

Purges match the full normalised key. ?v=8 and ?v=9 are two different objects, and purging one leaves the other in place.