QSCSCore HTTP API, X-QSCS-* Headers
On this page 1 sections
X-QSCS-* Response Headers
Every response the daemon emits carries one or more X-QSCS-* headers that describe what happened. They are the wire contract between the daemon and any client tooling that wants to observe cache behaviour, outage status, or per-request payload economics.
Header reference
| Header | Type | Emitted on | Meaning |
|---|---|---|---|
X-QSCS-Mode | enum | every proxied response | One of full | nochange | incremental | headless. See HTTP Gateway & Modes. |
X-QSCS-Wire-Bytes | integer | every proxied response | Bytes actually flowing on the wire to the client for this response's payload. Equals X-QSCS-Payload-Bytes on full and nochange; smaller on incremental. |
X-QSCS-Payload-Bytes | integer | every proxied response | Logical size of the payload as a client sees it (full body bytes). |
X-QSCS-Headless-Reason | enum | HEADLESS responses | served · no_cache · post_soft_fail · origin_degraded · origin_unreachable. |
X-QSCS-Headless-Age | integer (seconds) | HEADLESS responses that served a cached body | Seconds since this cache entry was last refreshed from the origin. |
X-QSCS-Headless-Session | string | HEADLESS responses | Currently always degraded. Reserved for future use to correlate a sequence of HEADLESS responses with a single outage window. |
Inspection from the shell
# Mode + wire vs payload bytes
curl -s -o /dev/null \
-w 'mode=%header{X-QSCS-Mode} wire=%header{X-QSCS-Wire-Bytes} payload=%header{X-QSCS-Payload-Bytes}\n' \
-H 'Host: example.com' http://node-eu1:8080/
# HEADLESS reason + age (only useful during an outage)
curl -s -o /dev/null \
-w 'mode=%header{X-QSCS-Mode} reason=%header{X-QSCS-Headless-Reason} age=%header{X-QSCS-Headless-Age}\n' \
-H 'Host: example.com' http://node-eu1:8080/curl < 7.84 caveat. The
%header{} format string was added in curl 7.84. Older curl prints the placeholder verbatim. Use curl -I or curl -D- in that case.