Apollo Router

Apollo Router is the Rust implementation of the Apollo Federation runtime.

Hive ships a custom build of Apollo Router, because that’s how native extensions works.

With the custom build, Apollo Router will poll the supergraph from the high availability CDN to ensure production deployments without interruptions.

Installation

Make sure you have published all your subgraph schemas to your Federation target on the Hive registry. Once you have all subgraph schemas published and the subgraphs can be composed, the latest valid supergraph is always available via the CDN.

You also need to create a CDN Access Token, that will be used for authenticating the supergraph polling from the CDN.

curl -fsSL https://graphql-hive.com/apollo-router-download.sh | bash

curl -fsSL https://graphql-hive.com/apollo-router-download.sh | bash -s -- --version router1.57.1-plugin1.0.0

HIVE_CDN_ENDPOINT="..." \ # The endpoint of your CDN access token
HIVE_CDN_KEY="..." \ # The CDN access token
  ./router

docker run -p 4000:4000 \
  --env HIVE_CDN_ENDPOINT="..." \ # The endpoint of your CDN access token
  --env HIVE_CDN_KEY="..." \ # The CDN access token
  --rm \
  ghcr.io/graphql-hive/apollo-router:IMAGE_TAG_HERE

docker run -p 4000:4000 \
  --env HIVE_CDN_ENDPOINT="..." \ # The endpoint of your CDN access token
  --env HIVE_CDN_KEY="..." \ # The CDN access token
  --rm \
  ghcr.io/graphql-hive/apollo-router:IMAGE_TAG_HERE --log debug

[dependencies]
# You can find the version additional information in Crates.io:
# https://crates.io/crates/hive-apollo-router-plugin
hive_apollo_router_plugin = "..."

[dependencies]
# You can use a "branch", or commit id with "rev" key
hive_apollo_router_plugin = { git = "https://github.com/graphql-hive/console", branch = "main" }

  mod plugins;

  use anyhow::Result;
+ use hive_apollo_router_plugin::registry;

  fn main() -> Result<()> {
-   apollo_router::main()
+   match registry::HiveRegistry::new(None).and(apollo_router::main()) {
+     Ok(_) => {}
+     Err(e) => {
+         eprintln!("{}", e);
+         std::process::exit(1);
+     }
+   }
  }

Version Structure

The Docker image’s and the binary artifact’s versioning follows the pattern routerX.Y.Z-pluginX.Y.Z, combining both the core Apollo Router and Hive plugin versions.

For example: router1.57.1-plugin1.0.0.

You can find the list of releases in the releases registry page.

Configuration

• HIVE_CDN_ENDPOINT - the endpoint Hive generated for you in the previous step
• HIVE_CDN_KEY - the access key
• HIVE_CDN_POLL_INTERVAL - polling interval (default is 10 seconds)
• HIVE_CDN_ACCEPT_INVALID_CERTS - accepts invalid SSL certificates (default is false)
• HIVE_REGISTRY_LOG - defines the log level for the registry (default is INFO)
• HIVE_CDN_SCHEMA_FILE_PATH - where to download the supergraph schema (default is /<tmp-dir>/supergraph-schema.graphql)

Usage Reporting

You can send usage reporting to Hive registry by enabling hive.usage plugin in the config file (router.yaml).

Configuration

• HIVE_TOKEN (required) - Your Registry Access Token with write permission.
• HIVE_ENDPOINT (optional) - For self-hosting, you can override /usage endpoint (defaults to https://app.graphql-hive.com/usage)
• HIVE_TARGET_ID - A target ID, this can either be a slug following the format “$organizationSlug/$projectSlug/$targetSlug” (e.g “the-guild/graphql-hive/staging”) or an UUID (e.g. “a0f4c605-6541-4350-8cfe-b31f21a4bf80”). To be used when HIVE_TOKEN is configured with an organization access token.

HIVE_TOKEN="..." \
HIVE_TARGET_ID= "..." \
HIVE_CDN_ENDPOINT="..." \
HIVE_CDN_KEY="..." \
  ./router --config router.yaml

docker run -p 4000:4000 \
  --env HIVE_TOKEN="..." \
  --env HIVE_TARGET_ID="..." \
  --env HIVE_CDN_ENDPOINT="..." \
  --env HIVE_CDN_KEY="..." \
  --mount "type=bind,source=/home/usr/src/hive/router.yaml,target=/dist/config/router.yaml" \
  --rm \
  ghcr.io/graphql-hive/apollo-router:IMAGE_TAG_HERE

[dependencies]
# You can find the version additional information in Crates.io:
# https://crates.io/crates/hive-apollo-router-plugin
hive_apollo_router_plugin = "..."

[dependencies]
# You can use a "branch", or commit id with "rev" key
hive_apollo_router_plugin = { git = "https://github.com/graphql-hive/console", branch = "main" }

  mod plugins;

  use anyhow::Result;
+ use apollo_router::register_plugin;
+ use hive_apollo_router_plugin::registry;
+ use hive_apollo_router_plugin::usage::UsagePlugin;

  fn main() -> Result<()> {
-   apollo_router::main()

+ // Register the Hive usage_reporting plugin
+ register_plugin!("hive", "usage", UsagePlugin);

+   match registry::HiveRegistry::new(None).and(apollo_router::main()) {
+     Ok(_) => {}
+     Err(e) => {
+         eprintln!("{}", e);
+         std::process::exit(1);
+     }
+   }
  }

supergraph:
  listen: 0.0.0.0:4000
plugins:
  hive.usage: {}
    #  Default: true
    # enabled: true
    #
    #  Registry token to use instead of HIVE_TOKEN for usage reporting.
    # registry_token: "hvo1/xxxxxxx"
    #
    #  Endpoint for the usage reporting.
    # registry_usage_endpoint: "https://app.graphql-hive.com/usage"
    #
    #  The target for which usage should be reported.
    # target: "the-guild/graphql-hive/production"
    #
    #  Sample rate to determine sampling.
    #  0.0 = 0% chance of being sent
    #  1.0 = 100% chance of being sent.
    #  Default: 1.0
    # sample_rate: 0.5
    #
    #  Report the first operation seen for each unique key, regardless of `sample_rate`.
    #  Later operations with the same key follow `sample_rate`.
    # at_least_once:
    #   key: [operation_name, operation_body]
    #   max_distinct_keys: 100000
    #
    #  A list of operations (by name) to be ignored by Hive.
    # exclude: ["IntrospectionQuery", "MeQuery"],
    #
    #  Or use a dynamic expression to exclude requests based on runtime context.
    # exclude:
    #   expression: '.request.operation.name == "IntrospectionQuery"'
    #
    #  Uses graphql-client-name by default
    # client_name_header: "x-client-name",
    #  Uses graphql-client-version by default
    # client_version_header: "x-client-version",
    #
    #  A maximum number of operations to hold in a buffer before sending to Hive Console
    #  Default: 1000
    # buffer_size: 1000
    #
    #  A timeout for the entire request to the usage reporting endpoint in seconds
    #  Default: 15
    # connect_timeout: 15
    #
    #  Accepts invalid SSL certificates
    #  Default: false
    # accept_invalid_certs: true
    #
    #  Frequency of flushing the buffer to the server in seconds
    #  Default: 5
    # flush_interval: 5

The exclude option supports both the legacy array format and the dynamic expression object format. For example, you can skip internal traffic based on a request header:

plugins:
  hive.usage:
    exclude:
      expression: '.request.headers."graphql-client-name" == "my-internal-tool"'

Expressions can also read the operation type from .request.operation.type ("query", "mutation" or "subscription"):

plugins:
  hive.usage:
    exclude:
      expression: '.request.operation.type == "subscription"'

For more details about the Hive Router expression syntax and available request fields used by this configuration, see Expressions.

Sampling

By default, every operation is reported. To reduce the volume of usage reports, set sample_rate to a value between 0.0 (nothing is reported) and 1.0 (everything is reported).

plugins:
  hive.usage:
    sample_rate: 0.1 # report 10% of operations

Sampling is decided for each report, so with @defer or subscriptions every response chunk is sampled on its own, rather than the request as a whole.

At-least-once sampling

A low sample_rate reduces volume, but it can completely miss operations that are rarely executed. With at_least_once, the first operation for each unique key is always reported, and later operations with the same key follow sample_rate. This keeps your report volume low while making sure every distinct operation is visible in Hive Console at least once.

plugins:
  hive.usage:
    sample_rate: 0.1 # report 10% of operations
    at_least_once:
      key: # the combination of operation name and body makes an operation unique
        - operation_name
        - operation_body
      max_distinct_keys: 12000 # how many keys to track in memory

The key defines what makes an operation unique. It accepts one value or a list of:

• operation_name - the name of the GraphQL operation
• operation_type - the operation type (query, mutation, subscription)
• operation_body - the operation body

When you provide multiple values, they are combined into a single key.

Keys are tracked in memory (~16 bytes per key), up to max_distinct_keys (default 100000). When the limit is reached, older keys are evicted, so a previously seen operation may be reported as “first seen” again.

Persisted Documents (App Deployments)

To activate App Deployments in your Apollo Router, you need to enable the hive.persisted_documents plugin. The plugin uses the HIVE_CDN_ENDPOINT and HIVE_CDN_KEY environment variables to resolve the persisted documents IDs.

# ... the rest of your configuration
plugins:
  hive.usage: {}
  hive.persisted_documents:
    enabled: true

Once enabled, follow the App Deployments guide to send persisted document requests from your app, using the Hive CDN for resolving the document IDs.

Configuration

The following environment variables are required:

• HIVE_CDN_ENDPOINT - the endpoint Hive generated for you in the previous step (for example: https://cdn.graphql-hive.com/artifacts/v1/TARGET_ID/supergraph)
• HIVE_CDN_KEY - the access key to Hive CDN

You may configure the plugin with the following options:

# ... the rest of your configuration
plugins:
  hive.usage: {}
  hive.persisted_documents:
    # Enables/disables the plugin
    # Default: true
    enabled: true
    # The endpoint of the Hive CDN. You can either specify it here, or use the existing HIVE_CDN_ENDPOINT environment variable.
    # Required
    endpoint: "https://cdn.graphql-hive.com/artifacts/v1/TARGET_ID/supergraph"
    # The access key to the Hive CDN. You can either specify it here, or use the existing HIVE_CDN_KEY environment variable.
    # Required
    key: "..."
    # Enables/disables the option to allow arbitrary documents to be executed.
    # Optional
    # Default: false
    allow_arbitrary_documents: false
    # HTTP connect timeout in seconds for the Hive CDN requests.
    # Optional
    # Default: 5
    connect_timeout: 5
    # HTTP request timeout in seconds for the Hive CDN requests.
    # Optional
    # Default: 15
    request_timeout: 15
    # Accepts invalid SSL certificates for the Hive CDN requests.
    # Optional
    # Default: false
    accept_invalid_certs: false
    # The maximum number of documents to hold in a LRU cache.
    # Optional
    # Default: 1000
    cache_size: 1000

Use as library

You may also add the persisted-documents plugin:

[dependencies]
# You can use a "branch", or commit id with "rev" key
hive_apollo_router_plugin = { git = "https://github.com/graphql-hive/console", branch = "main" }

Next, update src/main.rs file with the following content to integrate with Hive Console:

  mod plugins;

  use anyhow::Result;
+ use apollo_router::register_plugin;
+ use hive_apollo_router_plugin::registry;
+ use hive_apollo_router_plugin::persisted_documents::PersistedDocumentsPlugin;

  fn main() -> Result<()> {
-   apollo_router::main()

+ // Register the persisted documents plugin, if needed
+ register_plugin!("hive", "persisted_documents", PersistedDocumentsPlugin);

+   match registry::HiveRegistry::new(None).and(apollo_router::main()) {
+     Ok(_) => {}
+     Err(e) => {
+         eprintln!("{}", e);
+         std::process::exit(1);
+     }
+   }
  }

If you are using both plugins (usage and persisted operations), you’ll need to have a register_plugin! call to both plugins.

Additional Resources

• Get started with Apollo Federation and Hive guide
• Apollo Router documentation
• Hive Plugin for Apollo-Router @ Crates.io