QSCSCore HTTP API, HEADLESS Behaviour

HEADLESS Behaviour

HEADLESS is the mode QSCS enters when it cannot reach an upstream. The daemon emits a deterministic response shape so client code can react without parsing HTML or guessing.

Trigger conditions

• The configured upstream for an origin fails twice in a row (connection refused, timeout, write/read failure). The origin is marked degraded.
• While degraded, plain GETs without cookies are short-circuited from cache (bypassDegraded) without even attempting the upstream.
• Cookie-bearing GETs and POSTs still attempt the upstream on each request, they cannot be safely served from cache, but get a deterministic soft-fail if it is still unreachable.
• Two consecutive successful probes clear the degraded state. Probes are sent at roughly 30 second intervals.

Cached body available, GET

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
X-QSCS-Mode: headless
X-QSCS-Headless-Age: 42
X-QSCS-Headless-Reason: served
X-QSCS-Headless-Session: degraded
Content-Length: ...

<cached body>

No cached body, GET

HTTP/1.1 503 Service Unavailable
X-QSCS-Mode: headless
X-QSCS-Headless-Reason: no_cache
X-QSCS-Headless-Session: degraded
Content-Length: ...

POST during outage, soft-fail JSON

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
X-QSCS-Mode: headless
X-QSCS-Headless-Reason: post_soft_fail
Content-Length: ...

{
  "error":  "upstream_unavailable",
  "retry":  true,
  "reason": "origin_unreachable",  // or "origin_degraded"
  "host":   "example.com",
  "uri":    "/api/checkout"
}

The JSON body is byte-stable: clients can rely on the field set, the field names, and the type of each field. retry: true means a future identical request will likely succeed once the upstream recovers, well-behaved clients should requeue with exponential backoff rather than alert the user.

Client patterns