[1.5.0] - 2022-12-06

❗ BREAKING ❗

Router debug Docker images now run under the control of heaptrack (Issue #2135)

From 1.5.0, our debug Docker image will invoke the router under the control of heaptrack. We are making this change to make it simple for users to investigate potential memory issues with the Router.

Do not run debug images in performance sensitive contexts. The tracking of memory allocations will significantly impact performance. In general, the debug image should only be used in consultation with Apollo engineering and support.

Look at our documentation for examples of how to use the image in either Docker or Kubernetes.

By @garypen in #2142

Fix naming inconsistency of telemetry.metrics.common.attributes.router (Issue #2076)

Mirroring the rest of the config router should be supergraph

telemetry:
  metrics:
    common:
      attributes:
        router: # old

becomes

telemetry:
  metrics:
    common:
      attributes:
        supergraph: # new

By @bryncooke in #2116

CLI structure changes (Issue #2123)

There is now a separate subcommand for config related operations:

• config
  • schema - Output the configuration schema
  • upgrade - Upgrade the configuration with optional diff support.

router --schema has been deprecated and users should move to router config schema.

By @bryncooke in #2116

🚀 Features

Add configuration for trace ID (Issue #2080)

Trace ids can be propagated directly from a request header:

telemetry:
  tracing:
    propagation:
      # If you have your own way to generate a trace id and you want to pass it via a custom request header
      request:
        header_name: my-trace-id

In addition, trace id can be exposed via a response header:

telemetry:
  tracing:
    experimental_response_trace_id:
      enabled: true # default: false
      header_name: "my-trace-id" # default: "apollo-trace-id"

Using this configuration you will have a response header called my-trace-id containing the trace ID. It could help you to debug a specific query if you want to grep your log with this trace id to have more context.

By @bnjjj in #2131

Add configuration for logging and add more logs (Issue #1998)

By default, logs do not contain request body, response body or headers.
It is now possible to conditionally add this information for debugging and audit purposes.
Here is an example how you can configure it:

telemetry:
  experimental_logging:
    format: json # By default it's "pretty" if you are in an interactive shell session
    display_filename: true # Display filename where the log is coming from. Default: true
    display_line_number: false # Display line number in the file where the log is coming from. Default: true
    # If one of these headers matches we will log supergraph and subgraphs requests/responses
    when_header:
      - name: apollo-router-log-request
        value: my_client
        headers: true # default: false
        body: true # default: false
      # log request for all requests/responses headers coming from Iphones
      - name: user-agent
        match: ^Mozilla/5.0 (iPhone*
        headers: true

By @bnjjj in #2040

Provide multi-arch (amd64/arm64) Docker images for the Router (Issue #1932)

From 1.5.0 our Docker images will be multi-arch.

By @garypen in #2138

Add a supergraph configmap option to the helm chart (PR #2119)

Adds the capability to create a configmap containing your supergraph schema. Here's an example of how you could make use of this from your values.yaml and with the helm install command.

extraEnvVars:
  - name: APOLLO_ROUTER_SUPERGRAPH_PATH
    value: /data/supergraph-schema.graphql

extraVolumeMounts:
  - name: supergraph-schema
    mountPath: /data
    readOnly: true

extraVolumes:
  - name: supergraph-schema
    configMap:
      name: "{{ .Release.Name }}-supergraph"
      items:
        - key: supergraph-schema.graphql
          path: supergraph-schema.graphql

With that values.yaml content, and with your supergraph schema in a file name supergraph-schema.graphql, you can execute:

helm upgrade --install --create-namespace --namespace router-test --set-file supergraphFile=supergraph-schema.graphql router-test oci://ghcr.io/apollographql/helm-charts/router --version 1.0.0-rc.9 --values values.yaml

By @garypen in #2119

Configuration upgrades (Issue #2123)

Occasionally we will make changes to the Router yaml configuration format.
When starting the Router, if the configuration can be upgraded, it will do so automatically and display a warning:

2022-11-22T14:01:46.884897Z  WARN router configuration contains deprecated options: 

  1. telemetry.tracing.trace_config.attributes.router has been renamed to 'supergraph' for consistency

These will become errors in the future. Run `router config upgrade <path_to_router.yaml>` to see a suggested upgraded configuration.

Note: If a configuration has errors after upgrading then the configuration will not be upgraded automatically.

From the CLI users can run:

• router config upgrade <path_to_router.yaml> to output configuration that has been upgraded to match the latest config format.
• router config upgrade --diff <path_to_router.yaml> to output a diff e.g.

 telemetry:
   apollo:
     client_name_header: apollographql-client-name
   metrics:
     common:
       attributes:
-        router:
+        supergraph:
           request:
             header:
             - named: "1" # foo

There are situations where comments and whitespace are not preserved.

By @bryncooke in #2116, #2162

Experimental 🥼 subgraph request retry (Issue #338, Issue #1956)

Implements subgraph request retries, using Finagle's retry buckets algorithm:

• it defines a minimal number of retries per second (min_per_sec, default is 10 retries per second), to
  bootstrap the system or for low traffic deployments
• for each successful request, we add a "token" to the bucket, those tokens expire after ttl (default: 10 seconds)
• the number of available additional retries is a part of the number of tokens, defined by retry_percent (default is 0.2)

Request retries are disabled by default on mutations.

This is activated in the traffic_shaping plugin, either globally or per subgraph:

traffic_shaping:
  all:
    experimental_retry:
      min_per_sec: 10
      ttl: 10s
      retry_percent: 0.2
      retry_mutations: false
  subgraphs:
    accounts:
      experimental_retry:
        min_per_sec: 20

By @Geal in #2006 and #2160

Experimental 🥼 Caching configuration (Issue #2075)

Split Redis cache configuration for APQ and query planning:

supergraph:
  apq:
    experimental_cache:
      in_memory:
        limit: 512
      redis:
        urls: ["redis://..."]
  query_planning:
    experimental_cache:
      in_memory:
        limit: 512
      redis:
        urls: ["redis://..."]

By @Geal in #2155

@defer Apollo tracing support (Issue #1600)

Added Apollo tracing support for queries that use @defer. You can now view traces in Apollo Studio as normal.

By @bryncooke in #2190

🐛 Fixes

Fix panic when dev mode enabled with empty config file (Issue #2182)

If you're running the Router with dev mode with an empty config file, it will no longer panic

By @bnjjj in #2195

Fix missing apollo tracing variables (Issue #2186)

Send variable values had no effect. This is now fixed.

telemetry:
  apollo:
    send_variable_values: all

By @bryncooke in #2190

fix build_docker_image.sh script when using default repo (PR #2163)

Adding the -r flag recently broke the existing functionality to build from the default repo using -b. This fixes that.

By @garypen in #2163

Improve errors when subgraph returns non-GraphQL response with a non-2xx status code (Issue #2117)

The error response will now contain the status code and status name. Example: HTTP fetch failed from 'my-service': 401 Unauthorized

By @col in #2118

handle mutations containing @defer (Issue #2099)

The Router generates partial query shapes corresponding to the primary and deferred responses,
to validate the data sent back to the client. Those query shapes were invalid for mutations.

By @Geal in #2102

Experimental 🥼 APQ and query planner Redis caching fixes (PR #2176)

• use a null byte as separator in Redis keys
• handle Redis connection errors
• mark APQ and query plan caching as license key functionality

By @Geal in #2176

🛠 Maintenance

Verify that deferred fragment acts as a boundary for nullability rules (Issue #2169)

Add a test to ensure that deferred fragments act as a boundary for nullability rules.

By @garypen in #2183

Refactor APQ (PR #2129)

Remove duplicated code.

By @Geal in #2129

Update apollo-rs (PR #2177)

Updates to new apollo-rs APIs, and fixes some potential panics on unexpected user input.

By @goto-bus-stop in #2177

Semi-automate the release (PR #2202)

Developers can now run:
cargo xtask release prepare minor

To raise a release PR.

By @bryncooke in #2202

Fix webpki license check (PR #2202)

Fixed webpki license check.
Add missing Google Chromimum license.
By @o0Ignition0o @bryncooke in #2202

📚 Documentation

Docs: Update cors match regex example (Issue #2151)

The docs CORS regex example now displays a working and safe way to allow HTTPS subdomains of api.example.com.

By @o0Ignition0o in #2152

update documentation to reflect new examples structure (Issue #2095)

Updated the examples directory structure. This fixes the documentation links to the examples. It also makes clear that rhai subgraph fields are read-only, since they are shared resources.

By @garypen in #2133

Docs: Add a disclaimer for users who set up health-checks and prometheus endpoints in a containers environment (Issue #2079)

The health check and the prometheus endpoint listen to 127.0.0.1 by default.
While this is a safe default, it prevents other pods from performing healthchecks and scraping prometheus data.
This behavior and customization is now documented in the health-checks and the prometheus sections.

By @o0Ignition0o in #2194