HEADLESS Mode
On this page 4 sections
HEADLESS mode is what QSCS does when it cannot reach the thing it normally proxies to. Instead of returning errors, it serves the most recent cached response. The site keeps working, slightly stale, but reachable.
What triggers it
Each node tracks the success and failure of every outbound request to its upstream (the origin if you are the master, the master if you are a thin client). After two consecutive failures for the same upstream, the node marks that upstream as degraded and enters HEADLESS mode for it.
While degraded, QSCS sends a quiet background probe roughly every 30 seconds. After two consecutive successful probes the upstream is considered recovered and normal mode resumes.
What a client sees during HEADLESS
A successful HEADLESS response looks like a normal 200 OK with extra headers:
HTTP/1.1 200 OK
X-QSCS-Mode: headless
X-QSCS-Headless-Reason: served
X-QSCS-Headless-Age: 42
Content-Length: 1234| Header | Meaning |
|---|---|
X-QSCS-Mode: headless | This response came from cache, not from the upstream. |
X-QSCS-Headless-Reason | Why HEADLESS engaged. served = origin down. post_soft_fail = POST during outage. |
X-QSCS-Headless-Age | Seconds since this entry was last refreshed from origin. |
What if there is nothing in cache?
HEADLESS can only serve a URL it has seen before. A request for a URL with no cached entry, while in degraded mode, returns:
HTTP/1.1 503 Error
X-QSCS-Mode: fullThis is rare in practice, by the time an origin is down, most of your trafficked URLs are already in cache.
What about POSTs?
POSTs (and other state-changing methods) are never served from cache; that would be unsafe. While degraded, they short-circuit immediately to a soft-fail response, see POST During Outage.
X-QSCS-Mode: headless, a working site whose backend isn't even running. Try curl -I https://wp.spook.systems/ and inspect the X-QSCS-* headers.