Stellate Headers

📘

Header names were not updated (yet) when we renamed the company and product to Stellate. We will introduce a new set of headers prepended with stellate at a later time.

Whenever a request and subsequent response passes through Stellate, we add specific headers to the response providing additional information about the request and the cache. Some of them are included on all requests; many are available by passing in a special debugging header on the request itself.

The following headers are included with each response from Stellate.

• age, the amount of time a document has been cached in seconds.
• cache-control, affects the operation of caches and indicates how long they should consider a document to be fresh
• gcdn-cache, indicates whether the request was a cache hit, miss, or pass
• vary, indicates additional request headers that are used for scopes and bypass headers

Debug Headers

If you want to debug a specific request and are looking for additional hints, include a gcdn-debug header with any value on your request to Stellate. Including this header will enable additional debug headers on the response.

• gcdn-app-id, the internal three-letter ID of the service handling the request
• gcdn-cache-control, the cache control headers applied by Stellate
• gcdn-cached-introspection, whether the response to an introspection query was served from the cache or not
• gcdn-field-strings, types and fields asked for in the GraphQL query
• gcdn-fields, internal identifiers for those types and fields
• gcdn-graphql-error, whether or not there are GraphQL errors present on the response
• gcdn-graphql-operation, mutation, query or subscription
• gcdn-missing-id-paths, entities included in the response that are missing a way to identify them uniquely, eg because the query doesn't ask for id or another configured key field
• gcdn-operation-name, the operation name passed into the query
• gcdn-original-elapsed, the time taken by the origin server to handle the query
• gcdn-scope-value-missing, scopes applied by the configured rules, which are not present on the request
• gcdn-scopes, scopes applied to this specific request
• gcdn-surrogate-key, surrogate keys applied to the cached document
• gcdn-surrogate-skipped-keys, surrogate keys applied to the cached document which did not fit within the gcdn-surrogate-key header (because of header length restrictions)
• gcdn-type-strings, types found in the response as strings
• gcdn-types, types found in the response in a Stellate internal hash
• gcdn-var-enforcement-needed, whether variables had to be obfuscated
• gcdn-worker-elapsed, the time taken by the Stellate edge worker handling the request

GCDN Force

If your requests to Stellate include a gcdn-force header (with any non-emtpy value, e.g. 1 or true), you trigger special behavior on our end. For any request with that header present, Stellate will

1. ignore the Cache-Control header sent by the backend service and only set Cache-Control headers based on your cache rules
2. remove any Set-Cookie headers present on the response

While this allows you to cache responses if your server includes a Set-Cookie header with each response, be very careful about employing it. Any cookies that your backend service would have set will be removed and won't be set on your clients via the GraphQL requests. Therefore, you need to be sure that those cookies are set some other way before adding this header.