schema variants/ graph feature flags

[n1ru4l]

Problem Statement

Developers create pull requests with service and schema changes and deploy these services ad-hoc to their environment for internal testing/staging purposes. These are never exposed to actual customers/users of their product.

They want their Federation Gateway being able to serve a variant of the default supergraph that is composed with the service(s) schema(s) from one or multiple PR(s) instead of the production service schema(s).

Today, we offer no such feature that allows ad-hoc composition and serving this ad-hoc supergraph to the router for resolution.

The client that wants to use the ad-hoc version of the supergraph will usually indicate so via a header or cookie within the request to the gateway (e.g. Cookie: feature_flag=pr-69).

As a workaround customers build their own layer into the gateway for ad-hoc pulling graphql schemas from the hive schema registry and composition in memory on the gateway for serving the schema based on such a header.

Proposed Solution

Hive Console: Workflow for using CLI/API for creating Ad-Hoc Deployments

The user publishes a variant subgraph to the schema registry. This variant subgraph publish is a write that does not mark the subgraph as the latest subgraph version; and it does not trigger a supergraph composition and a resulting new schema version.

This can be done via a CLI command:

hive schema:publish-service \
  --target the-guild/hive/production \
  --service.name "<service_name>" \
  --service.tag "<service_tag>" \ # unique identifier for the service "version"
  --service.url "<service_url>" \
  --service.schema "./schema.graphqls" \

Then the user defines a feature flag where he overrides some overriden services based on the previously published variant subgraphs.

hive feature-flag:create \
  --target the-guild/hive/production \
  # the services are referenced by the previous publish command
  --service "<service_name>@<service_tag>" \
  --service "<service_name>@<service_tag>" \
  "<flag_name>"

After the feature flag was defined, this results in a schema composition that updates the CDN with the information:

• After the feature flag was created, we start composing a new supergraph variant.

  The input for these composition is:

  • The main registry state (all services)
  • feature flag service overrides

• Each publish to the main schema registry, will result in also attempting a composition of the feature flag supergraph

• Similar to the main supergraph, we publish the (successful) composition result to the CDN at the following key:

  • https://cdn.graphql-hive.com/artifacts/v1/<target_id>/feature-flags/<flag_name>/supergraph (and other artifacts sdl; services etc.)

• Upon the first successful composition the feature flag is also added to the list of active feature flags on the CDN:

  • https://cdn.graphql-hive.com/artifacts/v1/<target_id>/feature-flags
  • This list is polled by the gateway in order to identify which supergraphs need to be serve-able in addition to the main supergraph

Subsequent publishes of the variant subgraphs and main schema registry subgraphs, will queue a new composition for the feature flag, that updates the artifacts on the CDN:

• Main Graph
  • Supergraph
  • Schema Contract Supergraphs
• Feature Flag Graph(s)
  • Supergraph
  • Schema Contracts (NOTE: This is an optional goal; since the interviewed customer doe not use schema contracts in combination with feature flags)

When a schema check is performed, the composability of the feature-flag is checked in addition to the other checks (NOTE: This is an optional goal, as the interviewed customers only use feature flags for their internal pre-production testing. This requirement can change if feature flags are rolled out to customer traffic.)

Hive Router / Gateway: Support for serving alternative Supergraph based on Request Header/Cookie

Ability to poll a list of enabled feature flags from the CDN.

Ability to initializing multiple supergraphs:

• Main Graph
• Feature Flag Graph(s)

Ability to forward requests to a feature flag supergraph

• Ability to poll a list of enabled feature flags from the CDN

  • The feature to poll for feature-flags should be opt-in

  • Endpoint: https://cdn.graphql-hive.com/artifacts/v1/<target_id>/feature-flags

  • poll this endpoint and initialise/shutdown ad-hoc supergraphs based on the response

    [
      "feature-flag-1",
      "feature-flag-69",
      "feature-flag-420"
    ]

• Ability to initialising multiple supergraphs:

  • Main Graph (as we do today)
  • Feature Flag Graph
    • as specified by the /feature-flags endpoint result
    • https://cdn.graphql-hive.com/artifacts/v1/<target_id>/feature-flags/<flag_name>/supergraph
    • poll each feature flag endpoint similar to how the main graph is polled

• Ability to forward requests to a feature flag supergraph

  • based on a cookie or header
  • e.g. Cookie: feature_flag=pr-69

Hive Console: Other Requirements

Viewing active feature flags in the Dashboard

• It should be possible to see active feature flags and the latest status
  • is the latest version composable (or is it lacking behind?)
    • because the schema is not composable with latest services and service overrides
  • how does the feature flag schema differ from the main schema?
  • what are the changes between different “versions” of the feature flag?

Can be roughly inspired by our current schema version view

Since the feature flag graphs is variant, we could allow seeing the history of such feature flags similar to the following:

Another option would be a dropdown for selecting the feature-flag history.

Schema Contract Integration (@tag directive)

We can support schema contracts with feature flags together, but it will result in a massive growing amount of additional compositions required per feature-flag/contract

• 2 feature flags + 3 contracts equals:

  (1 base composition + 3 feature flag compositions)
  * (1 main graph composition + 3 contract composition)
  = 16 compositions per schema publish

• 5 feature flags + 5 contracts equals

  (1 base composition + 5 feature flag compositions)
  * (1 main graph composition + 5 contract composition)
  = 36 compositions per schema publish

• you get the math and formular, it could escalate really quick.

From the interview with customers, they are not using contracts in combination with experiments. So we can safely ignore composing schema contracts.

Integration with Schema Proposals

Deploying experiments happens when the services already have schema adjustments and are deployed. But maybe it is possible to model this as a late stage as part of a schema proposal if really necessary. There is no need for tying this flow to schema proposals.

Hive Gateway / Hive Router

Usage reporting

Since the experiments are only used for internal experiments, it is safe to drop usage reporting for requests handled by a feature flag supergraph