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.

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, a 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, 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 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.

stellate.ts →

import { Config } from 'stellate'

const config: Config = {
  config: {
    // THIS IS NOT A FULL STELLATE CONFIGURATION FILE
    // ...
    // 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