Stellate Headers

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.

Request Headers

The following headers are included with the request to your origin. By default, we pass any headers you configure on your request through to your origin. However there are some with special behavior

gcdn-request-id

An unique ID identifying a specific request. This ID is shown on the Metrics dashboard and helps trace requests as they pass through Stellate and your backend service.

x-forwarded-for

The IP address of the client making the request to Stellate is appended to the existing value if present, if not the header is set to that IP address

forwarded

Same behavior as the x-forwarded-for header mentioned above

Response Headers

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 a value of 1 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, e.g. 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 a value of 1, 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.

If you want to make sure gcdn-force is set on every single request sent to Stellate, you can configure your service to automatically inject the header. See the following snippet for the required configuration.

import { Config } from 'stellate'
 
const config: Config = {
  config: {
    // ... other configuration ...
 
    // The following 2 directives are required to make sure the `gcdn-force` header
    // is included with each request.
    injectHeaders: true,
    headers: {
      'gcdn-force': '1',
    },
  },
}
export default config