QSCSCore HTTP API, HTTP Gateway & Modes
On this page 1 sections
HTTP Gateway & Modes
Any request whose Host header matches a configured origin is treated as site traffic. QSCS either serves it from cache, proxies it to the upstream backend and caches the response, or, during an outage, serves the last known good copy in HEADLESS mode.
Decision flow
- OPTIONS → returned immediately with permissive CORS headers.
- Host not in
[Origins]→ 404 (unless a static page or health-check matches; see Static Pages). - Origin requires identity (
Auth=identity) and no authenticated identity → 401{"error":"not authenticated"}. Root page and static asset extensions pass through so the SPA can render its login UI. - POST or cookie-bearing GET → forwarded live to the upstream every time (uncacheable).
- Plain GET → checked against the response cache, then forwarded to the upstream; the result is cached.
- Upstream unreachable → HEADLESS fallback.
Modes (X-QSCS-Mode)
| Mode | Trigger | Body |
|---|---|---|
full | First fetch for this URL, or upstream returned a body different from the cached one. | Full upstream body, cached. |
nochange | Upstream body identical to the cached version. | Cached body returned, cache untouched. |
incremental | Upstream body differs from cache; delta is computed for telemetry. | Full upstream body returned to client; cache updated with new version. |
headless | Upstream unreachable or origin marked degraded. | Last-cached body served. See HEADLESS Behaviour. |
Caching rules
- Cache key:
<origin-host>|<uri>. - Cookie-bearing GETs are never cached (per-user variability).
- POST / PUT / DELETE / PATCH are never cached.
- 3xx redirects are forwarded verbatim with their
Locationheader and are not stored. - Only
200responses with non-empty bodies are markedvalidfor HEADLESS replay.
Methods
GET,POST,HEAD,OPTIONS, supported.HEADis treated asGETand the body is stripped before sending.- Any other method →
400 Bad Request.
Example
$ curl -i -H 'Host: example.com' http://node-eu1:8080/
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
X-QSCS-Mode: nochange
X-QSCS-Wire-Bytes: 67098
X-QSCS-Payload-Bytes: 67098
Content-Length: 67098
...