🚀 Features

Newly scaffolded projects now include a Dockerfile (Issue #2295)

Custom Router binary projects created using our scaffolding tooling will now have a Dockerfile emitted to facilitate building custom Docker containers.

By @o0Ignition0o in https://github.com/apollographql/router/pull/2307

Apollo Uplink communication timeout is configurable (PR #2271)

The amount of time which can elapse before timing out when communicating with Apollo Uplink is now configurable via the APOLLO_UPLINK_TIMEOUT environment variable and the --apollo-uplink-timeout CLI flag, in a similar fashion to how the interval can be configured. It still defaults to 30 seconds.

By @o0Ignition0o in https://github.com/apollographql/router/pull/2271

Query plan cache is pre-warmed using existing operations when the supergraph changes (Issue #2302, Issue #2308)

A new warmed_up_queries configuration option has been introduced to pre-warm the query plan cache when the supergraph changes.

Under normal operation, query plans are cached to avoid the recomputation cost. However, when the supergraph changes, previously-planned queries must be re-planned to account for implementation changes in the supergraph, even though the query itself may not have changed. Under load, this re-planning can cause performance variations due to the extra computation work. To reduce the impact, it is now possible to pre-warm the query plan cache for the incoming supergraph, prior to changing over to the new supergraph. Pre-warming slightly delays the roll-over to the incoming supergraph, but allows the most-requested operations to not be impacted by the additional computation work.

To enable pre-warming, the following configuration can be introduced which sets warmed_up_queries:

supergraph:
  query_planning:
    # Pre-plan the 100 most used operations when the supergraph changes.  (Default is "0", disabled.)
    warmed_up_queries: 100
    experimental_cache:
      in_memory:
        # Sets the limit of entries in the query plan cache
        limit: 512

Query planning was also updated to finish executing and setting up the cache, even if the response couldn't be returned to the client which is important to avoid throwing away computationally-expensive work.

By @Geal in https://github.com/apollographql/router/pull/2309

🐛 Fixes

Propagate errors across inline fragments (PR #2304)

GraphQL errors are now correctly propagated across inline fragments.

By @o0Ignition0o in https://github.com/apollographql/router/pull/2304

Only rebuild protos if reports.proto source changes

Apollo Studio accepts traces and metrics from Apollo Router via the Protobuf specification which lives in the reports.proto file in the repository. With this contribution, we only re-build from the reports.proto file when the file has actually changed, as opposed to doing it on every build which was occurring previously. This change saves build time for developers.

By @scottdouglas1989 in https://github.com/apollographql/router/pull/2283

Return an error on duplicate keys in configuration (Issue #1428)

Repeat usage of the same keys in Router YAML can be hard to notice but indicate a misconfiguration which can cause unexpected behavior since only one of the values can be in effect. With this improvement, the following YAML configuration will raise an error at Router startup to alert the user of the misconfiguration:

telemetry:
  tracing:
    propagation:
      jaeger: true
  tracing:
    propagation:
      jaeger: false

In this particular example, the error produced would be:

ERROR duplicated keys detected in your yaml configuration: 'telemetry.tracing'

By @bnjjj in https://github.com/apollographql/router/pull/2270

Return requested __typename in initial chunk of a deferred response (Issue #1922)

The special-case __typename field is no longer being treated incorrectly when requested at the root level on an operation which used @defer. For example, the following query:

{
  __typename
  ...deferedFragment @defer
}

fragment deferedFragment on Query {
  slow
}

The Router now exhibits the correct behavior for this query with __typename being returned as soon as possible in the initial chunk, as follows:

{"data":{"__typename": "Query"},"hasNext":true}

By @bnjjj in https://github.com/apollographql/router/pull/2274

Log retriable Apollo Uplink failures at the debug level (Issue #2004)

The log levels for messages pertaining to Apollo Uplink schema fetch failures are now emitted at debug level to reduce noise since such failures do not indicate an actual error since they can be and are retried immediately.

By @bnjjj in https://github.com/apollographql/router/pull/2215

Traces won't cause missing field-stats (Issue #2267)

Metrics are now correctly measured comprehensively and traces will obey the trace sampling configuration. Previously, if a request was sampled out of tracing it would not always contribute to metrics correctly. This was particularly problematic for users which had configured high sampling rates for their traces.

By @bryncooke in https://github.com/apollographql/router/pull/2277 and https://github.com/apollographql/router/pull/2286

Replace default notify watcher mechanism with PollWatcher (Issue #2245)

We have replaced the default mechanism used by our underlying file-system notification library, notify, to use PollWatcher. This more aggressive change has been taken on account of continued reports of failed hot-reloading and follows up our previous replacement of hotwatch. We don't have very demanding file watching requirements, so while PollWatcher offers less sophisticated functionality and slightly slower reactivity, it is at least consistent on all platforms and should provide the best developer experience.

By @garypen in https://github.com/apollographql/router/pull/2276

Preserve subgraph error's path property when redacting subgraph errors (Issue #1818)

The path property in errors is now preserved. Previously, error redaction was removing the error's path property, which made debugging difficult but also made it impossible to correctly match errors from deferred responses to the appropriate fields in the requested operation. Since the response shape for the primary and deferred responses are defined from the client-facing "API schema", rather than the supergraph, this change will not result in leaking internal supergraph implementation details to clients and the result will be consistent, even if the subgraph which provides a particular field changes over time.

By @Geal in https://github.com/apollographql/router/pull/2273

Use correct URL decoding for variables in HTTP GET requests (Issue #2248)

The correct URL decoding will now be applied when making a GET request that passes in the variables query string parameter. Previously, all '+' characters were being replaced with spaces which broke cases where the + symbol was not merely an encoding symbol (e.g., ISO8601 date time values with timezone information).

By @neominik in https://github.com/apollographql/router/pull/2249

🛠 Maintenance

Return additional details to client for invalid GraphQL requests (Issue #2301)

Additional context will be returned to clients in the error indicating the source of the error when an invalid GraphQL request is made. For example, passing a string instead of an object for the variables property will now inform the client of the mistake, providing a better developer experience:

{
  "errors": [
    {
      "message": "Invalid GraphQL request",
      "extensions": {
        "details": "failed to deserialize the request body into JSON: invalid type: string \"null\", expected a map at line 1 column 100",
        "code": "INVALID_GRAPHQL_REQUEST"
      }
    }
  ]
}

By @bnjjj in https://github.com/apollographql/router/pull/2306

OpenTelemetry spans to subgraphs now include the request URL (Issue #2280)

A new http.url attribute has been attached to subgraph_request OpenTelemetry trace spans which specifies the URL which the particular request was made to.

By @bnjjj in https://github.com/apollographql/router/pull/2292

Errors returned to clients are now more consistently formed (Issue #2101)

We now return errors in a more consistent shape to those which were returned by Apollo Gateway and Apollo Server, and seen in the documentation. In particular, when available, a stable code field will be included in the error's extensions.

By @bnjjj in https://github.com/apollographql/router/pull/2178

🧪 Experimental

Note

These features are subject to change slightly (usually, in terms of naming or interfaces) before graduating to general availability.

Read more about how we treat experimental features.

Introduce a router_service layer (Issue #1496)

A router_service layer is now part of our service stack and allows plugin developers to process raw HTTP requests and responses from clients prior to those requests reaching the GraphQL processing within the supergraph_service layer. This will become a stable part of our API as we receive feedback from its early adopters. Please open a discussion with any feedback you might have!

By @o0Ignition0o in https://github.com/apollographql/router/pull/2170

Request pipeline customization via HTTP (Issue #1916)

We now offer the ability to configure some aspects of the Router via the response to an HTTP POST request to an external endpoint. Initially, we are only offering this option to customize the newly introduced router_service (above, in these release notes), but our intention is to introduce customization of existing service layers as well (e.g., supergraph_service,subgraph_service`, etc.). Conceptually, this addition allows similar customizations that are possible with Rhai or Rust plugin by sending the operation's context as of a particular phase of the request pipeline "over the wire" as of a particular to an external HTTP service which has the ability to process its properties and return a (potentially) modified response to the Router. This will become a stable part of our API as we receive feedback from its early adopters. Please open a discussion with any feedback you might have!

When this experimental option is enabled, contextual data will be transmitted as a JSON payload to an HTTP endpoint as a POST request. The response to such a request will be processed by the Router and any changes made by the external service will effect the remaining layers in the request pipeline. This allows external services to customize the Router behavior, but requires intentionally blocking Router's normal request pipeline. Therefore, any latency of a configured external service will have a direct impact on the performance of the Router and external services should be as performant as possible.

To experiment with this behavior, consider adopting a configuration similar to the following which communicates with a service running on http://127.0.0.1:8081 for the router service layer:

plugins:
  experimental.external:
    # A URL which will be called for each request for any configured stage.
    url: http://127.0.0.1:8081

    # A human-readable interval specifying the maximum allowed time. (Defaults to "1s", or one second)
    timeout: 2s

    # A "stage" represents a phase of the request pipeline in which the external service will be invoked.
    # They sit request pipeline as our Service Layers for Rust/Rhai, seen in our docs:
    #   https://www.apollographql.com/docs/router/customizations/overview/#how-customizations-work
    stages:

      # Currently, the only supported value is "router".
      router:

        # Define which properties of the request should be transmitted in the payload.
        # Choosing the least amount of data will reduce the size of the payload.
        # By default, all values are false and, when false, their presence in this map is optional.
        request:
          headers: true
          context: true
          body: true
          sdl: true

        # Similar to "request", but which properties of the response should be sent.
        # Again, all values are false by default and only must be specified if they are enabled.
        response:
          headers: true
          context: true

By @garypen in https://github.com/apollographql/router/pull/2229

❗ BREAKING ❗

Protoc now required to build (Issue #1970)

Protoc is now required to build Apollo Router. Upgrading to Open Telemetry 0.18 has enabled us to upgrade tonic which in turn no longer bundles protoc. Users must install it themselves https://grpc.io/docs/protoc-installation/.

By @bryncooke in https://github.com/apollographql/router/pull/1970

Jaeger scheduled_delay moved to batch_processor->scheduled_delay (Issue #2232)

Jager config previously allowed configuration of scheduled_delay for batch span processor. To bring it in line with all other exporters this is now set using a batch_processor section.

Before:

telemetry:
  tracing:
    jaeger:
      scheduled_delay: 100ms

After:

telemetry:
  tracing:
    jaeger:
      batch_processor:
        scheduled_delay: 100ms

By @bryncooke in https://github.com/apollographql/router/pull/1970

🚀 Features

Add support for experimental tooling (Issue #2136)

Display a message at startup listing used experimental_ configurations with related GitHub discussions. It also adds a new cli command router config experimental to display all available experimental configurations.

By @bnjjj in https://github.com/apollographql/router/pull/2242

Re-deploy router pods if the SuperGraph configmap changes (PR #2223)

When setting the supergraph with the supergraphFile variable a sha256 checksum is calculated and set as an annotation for the router pods. This will spin up new pods when the supergraph is mounted via config map and the schema has changed.

Note: It is preferable to not have --hot-reload enabled with this feature since re-configuring the router during a pod restart is duplicating the work and may cause confusion in log messaging.

By @toneill818 in https://github.com/apollographql/router/pull/2223

Tracing batch span processor is now configurable (Issue #2232)

Exporting traces often requires performance tuning based on the throughput of the router, sampling settings and ingestion capability of tracing ingress.

All exporters now support configuring the batch span processor in the router yaml.

telemetry:
  apollo:
    batch_processor:
      scheduled_delay: 100ms
      max_concurrent_exports: 1000
      max_export_batch_size: 10000
      max_export_timeout: 100s
      max_queue_size: 10000
  tracing:
    jaeger|zipkin|otlp|datadog:
      batch_processor:
        scheduled_delay: 100ms
        max_concurrent_exports: 1000
        max_export_batch_size: 10000
        max_export_timeout: 100s
        max_queue_size: 10000

See the Open Telemetry docs for more information.

By @bryncooke in https://github.com/apollographql/router/pull/1970

Add hot-reload support for Rhai scripts (Issue #1071)

The router will "watch" your "rhai.scripts" directory for changes and prompt an interpreter re-load if changes are detected. Changes are defined as:

• creating a new file with a ".rhai" suffix
• modifying or removing an existing file with a ".rhai" suffix

The watch is recursive, so files in sub-directories of the "rhai.scripts" directory are also watched.

The Router attempts to identify errors in scripts before applying the changes. If errors are detected, these will be logged and the changes will not be applied to the runtime. Not all classes of error can be reliably detected, so check the log output of your router to make sure that changes have been applied.

By @garypen in https://github.com/apollographql/router/pull/2198

Add support for working with multi-value header keys to Rhai (Issue #2211, Issue #2255)

Adds support for setting a header map key with an array. This causes the HeaderMap key/values to be appended() to the map, rather than inserted().

Adds support for a new values() fn which retrieves multiple values for a HeaderMap key as an array.

Example use from Rhai as:

  response.headers["set-cookie"] = [
    "foo=bar; Domain=localhost; Path=/; Expires=Wed, 04 Jan 2023 17:25:27 GMT; HttpOnly; Secure; SameSite=None",
    "foo2=bar2; Domain=localhost; Path=/; Expires=Wed, 04 Jan 2023 17:25:27 GMT; HttpOnly; Secure; SameSite=None",
  ];
  response.headers.values("set-cookie"); // Returns the array of values

By @garypen in https://github.com/apollographql/router/pull/2219, https://github.com/apollographql/router/pull/2258

🐛 Fixes

Filter nullified deferred responses (Issue #2213)

@defer spec updates mandates that a deferred response should not be sent if its path points to an element of the response that was nullified in a previous payload.

By @Geal in https://github.com/apollographql/router/pull/2184

Return root __typename when parts of a query with deferred fragment (Issue #1677)

With this query:

{
  __typename
  fast
  ...deferedFragment @defer
}

fragment deferedFragment on Query {
  slow
}

You will receive the first response chunk:

{"data":{"__typename": "Query", "fast":0},"hasNext":true}

By @bnjjj in https://github.com/apollographql/router/pull/2188

Wait for opentelemetry tracer provider to shutdown (PR #2191)

When we drop Telemetry we spawn a thread to perform the global opentelemetry trace provider shutdown. The documentation of this function indicates that "This will invoke the shutdown method on all span processors. span processors should export remaining spans before return". We should give that process some time to complete (5 seconds currently) before returning from the drop. This will provide more opportunity for spans to be exported.

By @garypen in https://github.com/apollographql/router/pull/2191

Dispatch errors from the primary response to deferred responses (Issue #1818, Issue #2185)

When errors are generated during the primary execution, some may also be assigned to deferred responses.

By @Geal in https://github.com/apollographql/router/pull/2192

Reconstruct deferred queries with knowledge about fragments (Issue #2105)

When we are using @defer, response formatting must apply on a subset of the query (primary or deferred), that is reconstructed from information provided by the query planner: a path into the response and a subselection. Previously, that path did not include information on fragment application, which resulted in query reconstruction issues if @defer was used under a fragment application on an interface.

By @Geal in https://github.com/apollographql/router/pull/2109

🛠 Maintenance

Improve plugin registration predictability (PR #2181)

This replaces ctor with linkme. ctor enables rust code to execute before main. This can be a source of undefined behaviour and we don't need our code to execute before main. linkme provides a registration mechanism that is perfect for this use case, so switching to use it makes the router more predictable, simpler to reason about and with a sound basis for future plugin enhancements.

By @garypen in https://github.com/apollographql/router/pull/2181

it_rate_limit_subgraph_requests fixed (Issue #2213)

This test was failing frequently due to it being a timing test being run in a single threaded tokio runtime.

By @bryncooke in https://github.com/apollographql/router/pull/2218

Update reports.proto protobuf definition (PR #2247)

Update the reports.proto file, and change the prompt to update the file with the correct new location.

By @o0Ignition0o in https://github.com/apollographql/router/pull/2247

Upgrade OpenTelemetry to 0.18 (Issue #1970)

Update to OpenTelemetry 0.18.

By @bryncooke and @bnjjj in https://github.com/apollographql/router/pull/1970 and https://github.com/apollographql/router/pull/2236

Remove spaceport (Issue #2233)

Removal significantly simplifies telemetry code and likely to increase performance and reliability.

By @bryncooke in https://github.com/apollographql/router/pull/1970

Update to Rust 1.65 (Issue #2220)

Rust MSRV incremented to 1.65.

By @bryncooke in https://github.com/apollographql/router/pull/2221 and https://github.com/apollographql/router/pull/2240

Improve automated release (Pull #2220)

Improved the automated release to:

• Update the scaffold files
• Improve the names of prepare release steps in circle.

By @bryncooke in https://github.com/apollographql/router/pull/2256

Use Elastic-2.0 license spdx (PR #2055)

Now that the Elastic-2.0 spdx is a valid identifier in the rust ecosystem, we can update the router references.

By @o0Ignition0o in https://github.com/apollographql/router/pull/2054

📚 Documentation

Create yaml config design guidance (Issue #2158)

Added some yaml design guidance to help us create consistent yaml config for new and existing features.

By @bryncooke in https://github.com/apollographql/router/pull/2159

❗ 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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/2116, https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/2006 and https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/2183

Refactor APQ (PR #2129)

Remove duplicated code.

By @Geal in https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/2177

Semi-automate the release (PR #2202)

Developers can now run: cargo xtask release prepare minor

To raise a release PR.

By @bryncooke in https://github.com/apollographql/router/pull/2202

Fix webpki license check (PR #2202)

Fixed webpki license check. Add missing Google Chromimum license. By @o0Ignition0o @bryncooke in https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/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 https://github.com/apollographql/router/pull/2194

🚀 Features

Add support for returning different HTTP status codes in Rhai (Issue #2023)

It is now possible to return different HTTP status codes when raising an exception in Rhai. You do this by providing an object map with two keys: status and message, rather than merely a string as was the case previously.

throw #{
    status: 403,
    message: "I have raised a 403"
};

This example will short-circuit request/response processing and return with an HTTP status code of 403 to the client and also set the error message accordingly.

It is still possible to return errors using the current pattern, which will continue to return HTTP status code 500 as previously:

throw "I have raised an error";

It is not currently possible to return a 200 status code using this pattern. If you try, it will be implicitly converted into a 500 error.

By @garypen in https://github.com/apollographql/router/pull/2097

Add support for urlencode() / decode() in Rhai (Issue #2052)

Two new functions, urlencode() and urldecode() may now be used to URL-encode or URL-decode strings, respectively.

By @garypen in https://github.com/apollographql/router/pull/2053

Experimental 🥼 External cache storage in Redis (PR #2024)

We are experimenting with introducing external storage for caches in the Router, which will provide a foundation for caching things like automated persisted queries (APQ) amongst other future-looking ideas. Our initial implementation supports a multi-level cache hierarchy, first attempting an in-memory LRU-cache, proceeded by a Redis Cluster backend.

As this is still experimental, it is only available as an opt-in through a Cargo feature-flag.

By @garypen and @Geal in https://github.com/apollographql/router/pull/2024

Expose query_plan to ExecutionRequest in Rhai (PR #2081)

You can now read the query-plan from an execution request by accessing request.query_plan. Additionally, request.context also now supports the Rhai in keyword.

By @garypen in https://github.com/apollographql/router/pull/2081

🐛 Fixes

Move error messages about nullifying into extensions (Issue #2071)

The Router was previously creating and returning error messages in errors when nullability rules had been triggered (e.g., when a non-nullable field was null, it nullifies the parent object). These are now emitted into a valueCompletion portion of the extensions response.

Adding those messages in the list of errors was potentially redundant and resulted in failures by clients (such as the Apollo Client error policy, by default) which would otherwise have expected nullified fields as part of normal operation execution. Additionally, the subgraph could already add such an error message indicating why a field was null which would cause the error to be doubled.

By @Geal in https://github.com/apollographql/router/pull/2077

Fix Float input-type coercion for default values with values larger than 32-bit (Issue #2087)

A regression has been fixed which caused the Router to reject integers larger than 32-bits used as the default values on Float fields in input types.

In other words, the following will once again work as expected:

input MyInputType {
    a_float_input: Float = 9876543210
}

By @o0Ignition0o in https://github.com/apollographql/router/pull/2090

Assume Accept: application/json when no Accept header is present Issue #1990)

The Accept header means */* when it is absent, and despite efforts to fix this previously, we still were not always doing the correct thing.

By @bnjjj in https://github.com/apollographql/router/pull/2078

@skip and @include implementation for root-level fragment use (Issue #2072)

The @skip and @include directives are now implemented for both inline fragments and fragment spreads at the top-level of operations.

By @Geal in https://github.com/apollographql/router/pull/2096

🛠 Maintenance

Use debian:bullseye-slim as our base Docker image (PR #2085)

A while ago, when we added compression support to the router, we discovered that the Distroless base-images we were using didn't ship with a copy of libz.so.1. We addressed that problem by copying in a version of the library from the Distroless image (Java) which does ship it. While that worked, we found challenges in adding support for both aarch64 and amd64 Docker images that would make it less than ideal to continue using those Distroless images.

Rather than persist with this complexity, we've concluded that it would be better to just use a base image which ships with libz.so.1, hence the change to debian:bullseye-slim. Those images are still quite minimal and the resulting images are similar in size.

By @garypen in https://github.com/apollographql/router/pull/2085

Update apollo-parser to v0.3.2 (PR #2103)

This updates our dependency on our apollo-parser package which brings a few improvements, including more defensive parsing of some operations. See its CHANGELOG in the apollo-rs repository for more details.

By @abernix in https://github.com/apollographql/router/pull/2103

📚 Documentation

Fix example helm show values command (PR #2088)

The helm show vaues command needs to use the correct Helm chart reference oci://ghcr.io/apollographql/helm-charts/router.

By @col in https://github.com/apollographql/router/pull/2088

🚀 Features

Add support for DHAT-based heap profiling (PR #1829)

The dhat-rs crate provides DHAT-style heap profiling. We have added two compile-time features, dhat-heap and dhat-ad-hoc, which leverage this ability.

By @garypen in https://github.com/apollographql/router/pull/1829

Add trace_id in logs to correlate entries from the same request (Issue #1981)

A trace_id is now added to each log line to help correlate log entries to specific requests. The value for this property will be automatically inherited from any enabled distributed tracing headers, such as those listed in our Tracing propagation header documentation (e.g., Jaeger, Zipkin, Datadog, etc.).

In the event that a trace_id was not inherited from a propagated header, the Router will originate a trace_id and also propagate that value to subgraphs to enable tracing in subgraphs.

Here is an example of the trace_id appearing in plain-text log output:

2022-10-21T15:17:45.562553Z ERROR [trace_id=5e6a6bda8d0dca26e5aec14dafa6d96f] apollo_router::services::subgraph_service: fetch_error="hyper::Error(Connect, ConnectError(\"tcp connect error\", Os { code: 111, kind: ConnectionRefused, message: \"Connection refused\" }))"
2022-10-21T15:17:45.565768Z ERROR [trace_id=5e6a6bda8d0dca26e5aec14dafa6d96f] apollo_router::query_planner::execution: Fetch error: HTTP fetch failed from 'accounts': HTTP fetch failed from 'accounts': error trying to connect: tcp connect error: Connection refused (os error 111)

And an exmaple of the trace_id appearing in JSON-formatted log output in a similar scenario:

{"timestamp":"2022-10-26T15:39:01.078260Z","level":"ERROR","fetch_error":"hyper::Error(Connect, ConnectError(\"tcp connect error\", Os { code: 111, kind: ConnectionRefused, message: \"Connection refused\" }))","target":"apollo_router::services::subgraph_service","filename":"apollo-router/src/services/subgraph_service.rs","line_number":182,"span":{"name":"subgraph"},"spans":[{"trace_id":"5e6a6bda8d0dca26e5aec14dafa6d96f","name":"request"},{"name":"supergraph"},{"name":"execution"},{"name":"parallel"},{"name":"fetch"},{"name":"subgraph"}]}
{"timestamp":"2022-10-26T15:39:01.080259Z","level":"ERROR","message":"Fetch error: HTTP fetch failed from 'accounts': HTTP fetch failed from 'accounts': error trying to connect: tcp connect error: Connection refused (os error 111)","target":"apollo_router::query_planner::execution","filename":"apollo-router/src/query_planner/execution.rs","line_number":188,"span":{"name":"parallel"},"spans":[{"trace_id":"5e6a6bda8d0dca26e5aec14dafa6d96f","name":"request"},{"name":"supergraph"},{"name":"execution"},{"name":"parallel"}]}

By @bnjjj in https://github.com/apollographql/router/pull/1982

Reload configuration when receiving the SIGHUP signal (Issue #35)

The Router will now reload its configuration when receiving the SIGHUP signal. This signal is only supported on *nix platforms, and only when a configuration file was passed to the Router initially at startup.

By @Geal in https://github.com/apollographql/router/pull/2015

🐛 Fixes

Fix the deduplication logic in deduplication caching (Issue #1984)

Under load, we found it was possible to break the router de-duplication logic and leave orphaned entries in the waiter map. This fixes the de-duplication logic to prevent this from occurring.

By @garypen in https://github.com/apollographql/router/pull/2014

Follow back-off instructions from Studio Uplink (Issue #1494 Issue #1539)

When operating in a Managed Federation configuration and fetching the supergraph from Apollo Uplink, the Router will now react differently depending on the response from Apollo Uplink, rather than retrying incessantly:

• Not attempt to retry when met with unrecoverable conditions (e.g., a Graph that does not exist).
• Back-off on retries when the infrastructure asks for a longer retry interval.

By @Geal in https://github.com/apollographql/router/pull/2001

Fix the rhai SDL print function (Issue #2005)

Fixes the print function exposed to rhai which was broken due to a recent change that was made in the way we pass SDL (schema definition language) to plugins.

By @fernando-apollo in https://github.com/apollographql/router/pull/2007

Export router_factory::Endpoint (PR #2007)

We now export the router_factory::Endpoint struct that was inadvertently unexposed. Without access to this struct, it was not possible to implement the web_endpoints trait in plugins.

By @scottdouglas1989 in https://github.com/apollographql/router/pull/2007

Validate default values for input object fields (Issue #1979)

When validating variables, the Router now uses graph-specified default values for object fields, if applicable.

By @Geal in https://github.com/apollographql/router/pull/2003

Address regression when sending gRPC to localhost (Issue #2036)

We again support sending unencrypted gRPC tracing and metrics data to localhost. This follows-up on a regression which occurred in the previous release which addressed a limitation which prevented sending gRPC to TLS-secured endpoints.

Applying a proper fix was complicated by an upstream issue (opentelemetry-rust#908) which incorrectly assumes https in the absence of a more-specific protocol/schema, contrary to the OpenTelmetry specification which indicates otherwise.

The Router will now detect and work-around this upstream issue by explicitly setting the full, correct endpoint URLs when not specified in config.

In addition:

• Basic TLS-encyrption will be enabled when the endpoint scheme is explicitly https.
• A warning will be emitted if the endpoint port is 443 but no TLS config is specified since most traffic on port 443 is expected to be encrypted.

By @bryncooke in https://github.com/apollographql/router/pull/#2048

🛠 Maintenance

Apply Tower best-practice to "inner" Service cloning (PR #2030)

We found our Service readiness checks could be improved by following the Tower project's recommendations for cloning inner Services.

By @garypen in https://github.com/apollographql/router/pull/2030

Split the configuration file implementation into modules (Issue #1790)

The internals of the implementation for the configuration have been modularized to facilitate on-going development. There should be no impact to end-users who are only using YAML to configure their Router.

By @Geal in https://github.com/apollographql/router/pull/1996

Apply traffic-shaping directly to supergraph and subgraph (PR #2034)

The plugin infrastructure works on BoxService instances and makes no guarantee on plugin ordering. The traffic shaping plugin needs a clonable inner service, and should run right before calling the underlying service. We'e changed the traffic plugin application so it can work directly on the underlying service. The configuration remains the same since this is still implemented as a plugin.

By @Geal in https://github.com/apollographql/router/pull/2034

📚 Documentation

Remove references to Git submodules from DEVELOPMENT.md (Issue #2012)

We've removed the instructions from our development documentation which guide users to familiarize themselves with and clone Git submodules when working on the Router source itself. This follows-up on the removal of the modules themselves in PR #1856.

By @garypen in https://github.com/apollographql/router/pull/2045

🐛 Fixes

Update to Federation v2.1.4 (PR #1994)

In addition to general Federation bug-fixes, this update should resolve a case (seen in Issue #1962) where a @defer directives which had been previously present in a Supergraph were causing a startup failure in the Router when we were trying to generate an API schema in the Router with @defer.

By @abernix in https://github.com/apollographql/router/pull/1994

Assume Accept: application/json when no Accept header is present (Issue #1995)

the Accept header means */* when it is absent.

By @Geal in https://github.com/apollographql/router/pull/1995

Fix OpenTelemetry OTLP gRPC (Issue #1976)

OpenTelemetry (OTLP) gRPC failures involving TLS errors have been resolved against external APMs: including Datadog, NewRelic and Honeycomb.io.

By @bryncooke in https://github.com/apollographql/router/pull/#1977

Prefix the Prometheus metrics with apollo_router_ (Issue #1915)

Correctly prefix Prometheus metrics with the apollo_router prefix, per convention.

- http_requests_error_total{message="cannot contact the subgraph",service_name="apollo-router",subgraph="my_subgraph_name_error",subgraph_error_extended_type="SubrequestHttpError"} 1
+ apollo_router_http_requests_error_total{message="cannot contact the subgraph",service_name="apollo-router",subgraph="my_subgraph_name_error",subgraph_error_extended_type="SubrequestHttpError"} 1

By @bnjjj in https://github.com/apollographql/router/pull/1971 & https://github.com/apollographql/router/pull/1987

Fix --hot-reload in Kubernetes and Docker (Issue #1476)

The --hot-reload flag now chooses a file event notification mechanism at runtime. The exact mechanism is determined by the notify crate.

By @garypen in https://github.com/apollographql/router/pull/1964

Fix a coercion rule that failed to validate 64-bit integers (PR #1951)

Queries that passed 64-bit integers for Float input variables would were failing to validate despite being valid.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1951

Prometheus: make sure apollo_router_http_requests_error_total and apollo_router_http_requests_total are incremented. (PR #1953)

This affected two different metrics differently:

• The apollo_router_http_requests_error_total metric only incremented for requests that would be an INTERNAL_SERVER_ERROR in the Router (the service stack returning a BoxError). This meant that GraphQL validation errors were not increment this counter.

• The apollo_router_http_requests_total metric would only increment for successful requests despite the fact that the Prometheus documentation suggests this should be incremented regardless of whether the request succeeded or not.

This PR makes sure we always increment apollo_router_http_requests_total and we increment apollo_router_http_requests_error_total when the status code is 4xx or 5xx.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1953

Set no_delay and keepalive on subgraph requests Issue #1905)

This re-introduces these parameters which were incorrectly removed in a previous pull request.

By @Geal in https://github.com/apollographql/router/pull/1910

🛠 Maintenance

Improve the stability of some flaky tests (PR #1972)

The trace and rate limiting tests have been sporadically failing in our CI environment. The root cause was a race-condition in the tests so the tests have been made more resilient to reduce the number of failures.

By @garypen in https://github.com/apollographql/router/pull/1972 and https://github.com/apollographql/router/pull/1974

Update docker-compose and Dockerfiles now that the submodules have been removed (PR #1950)

We recently removed Git submodules from this repository but we didn't update various docker-compose.yml files.

This PR adds new Dockerfiles and updates existing docker-compose.yml files so we can run integration tests (and the fuzzer) without needing to git clone and set up the Federation and federation-demo repositories.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1950

Fix logic around Accept headers and multipart responses (PR #1923)

If the Accept header contained multipart/mixed, even with other alternatives like application/json, a query with a single response was still sent as multipart, which made Apollo Studio Explorer fail on the initial introspection query.

This changes the logic so that:

• If the client has indicated an accept of application/json or */* and there is a single response, it will be delivered as content-type: application/json.
• If there are multiple responses or the client only accepts multipart/mixed, we will send content-type: multipart/mixed response. This will occur even if there is only one response.
• Otherwise, we will return an HTTP status code of 406 Not Acceptable.

By @Geal in https://github.com/apollographql/router/pull/1923

@defer: duplicated errors across incremental items (Issue #1834, Issue #1818)

If a deferred response contains incremental responses, the errors should be dispatched in each increment according to the error's path.

By @Geal in https://github.com/apollographql/router/pull/1892

Our Docker images are now linked to our GitHub repository per OCI-standards (PR #1958)

The org.opencontainers.image.source annotation has been added to our Dockerfiles and published Docker image in order to map the published image to our GitHub repository.

By @ndthanhdev in https://github.com/apollographql/router/pull/1958

❗ BREAKING ❗

Note the breaking change is not for the Router itself, but for the Router helm chart which is still 1.0.0-rc.5

Remove support for rhai.input_file from the helm chart (Issue #1826)

The existing rhai.input_file mechanism doesn't really work for most helm use cases. This PR removes this mechanism and and encourages the use of the extraVolumes/extraVolumeMounts mechanism with rhai.

Example: Create a configmap which contains your rhai scripts.

apiVersion: v1
kind: ConfigMap
metadata:
  name: rhai-config
  labels:
    app.kubernetes.io/name: rhai-config
    app.kubernetes.io/instance: rhai-config
data:
  main.rhai: |
    // Call map_request with our service and pass in a string with the name
    // of the function to callback
    fn subgraph_service(service, subgraph) {
        print(`registering request callback for ${subgraph}`);
        const request_callback = Fn("process_request");
        service.map_request(request_callback);
    }
  
    // This will convert all cookie pairs into headers.
    // If you only wish to convert certain cookies, you
    // can add logic to modify the processing.
    fn process_request(request) {
  
        // Find our cookies
        if "cookie" in request.headers {
            print("adding cookies as headers");
            let cookies = request.headers["cookie"].split(';');
            for cookie in cookies {
                // Split our cookies into name and value
                let k_v = cookie.split('=', 2);
                if k_v.len() == 2 {
                    // trim off any whitespace
                    k_v[0].trim();
                    k_v[1].trim();
                    // update our headers
                    // Note: we must update subgraph.headers, since we are
                    // setting a header in our sub graph request
                    request.subgraph.headers[k_v[0]] = k_v[1];
                }
            }
        } else {
            print("no cookies in request");
        }
    }
  my-module.rhai: |
    fn process_request(request) {
        print("processing a request");
    }

Note how the data represents multiple rhai source files. The module code isn't used, it's just there to illustrate multiple files in a single configmap.

With that configmap in place, the helm chart can be used with a values file that contains:

router:
  configuration:
    rhai:
      scripts: /dist/rhai
      main: main.rhai
extraVolumeMounts:
  - name: rhai-volume
    mountPath: /dist/rhai
    readonly: true
extraVolumes:
  - name: rhai-volume
    configMap:
      name: rhai-config

The configuration tells the router to load the rhai script main.rhai from the directory /dist/rhai (and load any imported modules from /dist/rhai)

This will mount the confimap created above in the /dist/rhai directory with two files:

• main.rhai
• my-module.rhai

By @garypen in https://github.com/apollographql/router/pull/1917

🚀 Features

Expose the TraceId functionality to rhai (Issue #1935)

A new function, traceid(), is exposed to rhai scripts which may be used to retrieve a unique trace id for a request. The trace id is an opentelemetry span id.

fn supergraph_service(service) {
    try {
        let id = traceid();
        print(`id: ${id}`);
    }
    catch(err)
    {
        // log any errors
        log_error(`span id error: ${err}`);
    }
}

By @garypen in https://github.com/apollographql/router/pull/1937

🐛 Fixes

Fix studio reporting failures (Issue #1903)

The root cause of the issue was letting the server component of spaceport close silently during a re-configuration or schema reload. This fixes the issue by keeping the server component alive as long as the client remains connected.

Additionally, recycled spaceport connections are now re-connected to spaceport to further ensure connection validity.

Also make deadpool sizing constant across environments (#1893)

By @garypen in https://github.com/apollographql/router/pull/1928

Update apollo-parser to v0.2.12 (PR #1921)

Correctly lexes and creates an error token for unterminated GraphQL StringValues with unicode and line terminator characters.

By @lrlna in https://github.com/apollographql/router/pull/1921

traffic_shaping.all.deduplicate_query was not correctly set (PR #1901)

Due to a change in our traffic_shaping configuration the deduplicate_query field for all subgraph wasn't set correctly.

By @bnjjj in https://github.com/apollographql/router/pull/1901

🛠 Maintenance

Fix hpa yaml for appropriate kubernetes versions (#1908)

Correct schema for autoscaling/v2beta2 and autoscaling/v2 api versions of the HorizontalPodAutoscaler within the helm chart

By @damienpontifex in https://github.com/apollographql/router/issues/1914

🚀 Features

Build, test and publish binaries for aarch64-unknown-linux-gnu architecture (Issue #1192)

We're now testing and building aarch64-unknown-linux-gnu binaries in our release pipeline and publishing those build artifacts as releases. These will be installable in the same way as our existing installation instructions.

By @EverlastingBugstopper in https://github.com/apollographql/router/pull/1907

Add ability to specify repository location in "DIY" Docker builds (PR #1904)

The new -r flag allows a developer to specify the location of a repository when building a diy docker image. Handy for developers with local repositories.

By @garypen in https://github.com/apollographql/router/pull/1904

Support serviceMonitor in Helm chart

kube-prometheus-stack ignores scrape annotations, so a serviceMonitor Custom Resource Definition (CRD) is required to scrape a given target to avoid scrape_configs.

By @hobbsh in https://github.com/apollographql/router/pull/1853

Add support for dynamic header injection (Issue #1755)

The following are now possible in our YAML configuration for headers:

• Insert static header

  headers:
    all: # Header rules for all subgraphs
      request:
      - insert:
          name: "sent-from-our-apollo-router"
          value: "indeed"
  

• Insert header from context

  headers:
    all: # Header rules for all subgraphs
      request:
      - insert:
          name: "sent-from-our-apollo-router-context"
          from_context: "my_key_in_context"
  

• Insert header from request body

  headers:
    all: # Header rules for all subgraphs
      request:
      - insert:
          name: "sent-from-our-apollo-router-request-body"
          path: ".operationName" # It's a JSON path query to fetch the operation name from request body
          default: "UNKNOWN" # If no operationName has been specified
  

By @bnjjj in https://github.com/apollographql/router/pull/1833

🐛 Fixes

Fix external secret support in our Helm chart (Issue #1750)

If an external secret is specified, e.g.:

helm install --set router.managedFederation.existingSecret="my-secret-name" <etc...>

...then the router should be deployed and configured to use the existing secret.

By @garypen in https://github.com/apollographql/router/pull/1878

Do not erase errors when missing _entities (Issue #1863)

In a federated query, if the subgraph returned a response with errors and a null or absent data field, the Router was ignoring the subgraph error and instead returning an error complaining about the missing_entities field.

The Router will now aggregate the subgraph error and the missing _entities error.

By @Geal in https://github.com/apollographql/router/pull/1870

Fix Prometheus annotation and healthcheck default

The Prometheus annotation is breaking on a helm upgrade so this fixes the template and also sets defaults. Additionally, defaults are now set for health-check's listen to be 0.0.0.0:8088 within the Helm chart.

By @hobbsh in https://github.com/apollographql/router/pull/1883

Move response formatting to the execution service (PR #1771)

The response formatting process (in which response data is filtered according to deferred responses subselections and the API schema) was being executed in the supergraph service. This was a bit late since it resulted in the execution service returning a stream of invalid responses leading to the execution plugins operating on invalid data.

By @Geal in https://github.com/apollographql/router/pull/1771

Hide footer from "homepage" landing page (PR #1900)

Hides some incorrect language about customization on the landing page. Currently to customize the landing page it requires additional support.

By @glasser in https://github.com/apollographql/router/pull/1900

🛠 Maintenance

Update to Federation 2.1.3 (Issue #1880)

This brings in Federation 2.1.3 to bring in updates to @apollo/federation via the relevant bump in router-bridge.

By @abernix in https://github.com/apollographql/router/pull/1806

Update reqwest dependency to resolve DNS resolution failures (Issue #1899)

This should resolve intermittent failures to resolve DNS in Uplink which were occurring due to an upstream bug in the reqwest library.

By @abernix in https://github.com/apollographql/router/pull/1806

Remove span details from log records (PR #1896)

Prior to this change, span details were written to log files. This was unwieldy and contributed to log bloat. Spans and logs are still linked in trace aggregators, such as jaeger, and this change simply affects the content of the written to the console output.

By @garypen in https://github.com/apollographql/router/pull/1896

Change span attribute names in OpenTelemetry to be more consistent (PR #1876)

The span attributes in our OpenTelemetry tracing spans are corrected to be consistently namespaced with attributes that are compliant with the OpenTelemetry specification.

By @bnjjj in https://github.com/apollographql/router/pull/1876

Have CI use rust-toolchain.toml and not install another redudant toolchain (Issue #1313)

Avoids redundant work in CI and makes the YAML configuration less mis-leading.

By @garypen in https://github.com/apollographql/router/pull/1877

Query plan execution refactoring (PR #1843)

This splits the query plan execution in multiple modules to make the code more manageable.

By @Geal in https://github.com/apollographql/router/pull/1843

Remove Buffer from APQ (PR #1641)

This removes tower::Buffer usage from the Automated Persisted Queries (APQ) implementation to improve reliability.

By @Geal in https://github.com/apollographql/router/pull/1641

Remove Buffer from query deduplication (PR #1889)

This removes tower::Buffer usage from the query deduplication implementation to improve reliability.

By @Geal in https://github.com/apollographql/router/pull/1889

Set MSRV to 1.63.0 (PR #1886)

We compile and test with 1.63.0 on CI at the moment, so it is our de-facto Minimum Supported Rust Version (MSRV).

Setting rust-version in Cargo.toml provides a more helpful error message when using an older version rather than unexpected compilation errors.

By @SimonSapin in https://github.com/apollographql/router/issues/1886

Note

🤸 We've reached our initial v1.0.0 release. This project adheres to Semantic Versioning v2.0.0 and our version numbers follow the practices outlined in that specification. If you're updating from 1.0.0-rc.2 there is one breaking change to the API that is unlikely to affect you.

The migration steps from each pre-1.0 version will vary depending on which release you're coming from. To update from previous versions, you can consult the Release Notes for whichever version you are running and work your way to v1.0.0.

Our documentation has been updated to match our current v1.x state. In general, if you run the Router with your existing configuration, you should receive output indicating any values which are no longer valid and find their v1.0.0 equivalent in the updated documentation, or by searching the CHANGELOG.md for the prior configuration option to find when it changed.

Lastly, thank you for all of your positive and constructive feedback in our pre-1.0 stages. If you encounter any questions or feedback while updating to v1.0.0, please search for or open a GitHub Discussion or file a GitHub Issue if you find something working differently than it's documented.

We're excited about the path ahead! 👐

❗ BREAKING ❗

Removed Request::from_bytes() from public API (Issue #1855)

We've removed Request::from_bytes() from the public API. We were no longer using it internally and we hardly expect anyone external to have been relying on it so it was worth the remaining breaking change prior to v1.0.0.

We discovered this function during an exercise of documenting our entire public API. While we considered keeping it, it didn't necessarily meet our requirements for shipping it in the public API. It's internal usage was removed in [d147f97d](https://github.com/apollographql/router/commit/d147f97d as part of PR #429.

We're happy to consider re-introducing this in the future (it even has a matching Response::from_bytes() which it composes against nicely!), but we thought it was best to remove it for the time-being.

By @abernix in https://github.com/apollographql/router/pull/1858

🚀 Features

Reintroduce health check (Issue #1861)

We have re-introduced a health check at the /health endpoint on a dedicated port that is not exposed on the default GraphQL execution port (4000) but instead on port 8088. We recommend updating from the previous health-point suggestion by consulting our health check configuration documentation. This health check endpoint will act as an "overall" health check for the Router and we intend to add separate "liveliness" and "readiness" checks on their own dedicated endpoints (e.g., /health/live and /health/ready) in the future. At that time, this root /health check will aggregate all other health checks to provide an overall health status however, today, it is simply a "liveliness" check and we have not defined "readiness". We also intend to use port 8088 for other ("internal") functionality in the future, keeping the GraphQL execution endpoint dedicated to serving external client requests.

As for some additional context as to why we've brought it back so quickly: We had previously removed the health check we had been offering in PR #1766 because we wanted to do some additional configurationd design and lean into a new "admin port" (8088). As a temporary solution, we offered the instruction to send a GET query to the Router with a GraphQL query. After some new learnings and feedback, we've had to re-visit that conversation earlier than we expected!

Due to default CSRF protections enabled in the Router, GET requests need to be accompanied by certain HTTP headers in order to disqualify them as being CORS-preflightable requests. While sending the additional header was reasonable straightforward in Kubernetes, other environments (including Google Kubernetes Engine's managed load balancers) didn't offer the ability to send those necessary HTTP headers along with their GET queries. So, the /health endpoint is back.

The health check endpoint is now exposed on 127.0.0.1:8088/health by default, and its listen socket address can be changed in the YAML configuration:

health-check:
  listen: 127.0.0.1:8088 # default
  enabled: true # default

The previous health-check suggestion (i.e., GET /?query={__typename}) will still work, so long as your infrastructure supports sending custom HTTP headers with HTTP requests. Again though, we recommend updating to the new health check.

By @o0Ignition0o and @BrynCooke in https://github.com/apollographql/router/pull/1859

🐛 Fixes

Remove apollo_private and OpenTelemetry entries from logs (Issue #1862)

This change removes some apollo_private and OpenTelemetry (e.g., otel.kind) fields from the logs.

By @garypen and @bnjjj in https://github.com/apollographql/router/pull/1868

Update and validate Dockerfile files (Issue #1854)

Several of the Dockerfiles in the repository were out-of-date with respect to recent configuration changes. We've updated the configuration files and extended our tests to catch this automatically in the future.

By @garypen in https://github.com/apollographql/router/pull/1857

🛠 Maintenance

Disable Deno snapshotting when building inside docs.rs

This works around V8 linking errors and caters to specific build-environment constraints and requirements that exist on the Rust documentation site docs.rs.

By @SimonSapin in https://github.com/apollographql/router/pull/1847

Add the Studio Uplink schema to the repository, with a test checking that it is up to date.

Previously we were downloading the Apollo Studio Uplink schema (which is used for fetching Managed Federation schema updates) at compile-time, which would fail in build environments without Internet access, like docs.rs' build system.

If an update is needed, the test failure will print a message with the command to run.

By @SimonSapin in https://github.com/apollographql/router/pull/1847

Note There are no breaking changes in this release! Thank you for the constructive and positive feedback and validation as well as the contributions from our external contributors. We look forward to seeing you at v1.0.0 soon!

🐛 Fixes

Update apollo-parser to v0.2.11 (PR #1841)

Fixes error creation for missing selection sets in named operation definitions by updating to apollo-rs's apollo-parser v0.2.11.

By @lrlna in https://github.com/apollographql/router/pull/1841

Fix router scaffold version (Issue #1836)

Add v prefix to the package version emitted in our scaffold tooling when a published version of the crate is available. This results in packages depending (appropriately, we would claim!) on our published Cargo crates, rather than Git references to the repository.

By @bnjjj in https://github.com/apollographql/router/pull/1838

Fixed extraVolumeMounts in Helm charts (Issue #1824)

Correct a case in our Helm charts where extraVolumeMounts was not be being filled into the deployment template correctly.

By @LockedThread in https://github.com/apollographql/router/pull/1831

Do not fill in a skeleton object when canceling a subgraph request (Issue #1819)

Given a supergraph with multiple subgraphs USER and ORGA, like this example supergraph, if a query spans multiple subgraphs, like this:

query {
  currentUser { # USER subgraph
    activeOrganization { # ORGA subgraph
      id
      creatorUser {
        name
      }
    }
  }
}

...when the USER subgraph returns {"currentUser": { "activeOrganization": null }}, then the request to the ORGA subgraph should be cancelled and no data should be generated. This was not occurring since the query planner was incorrectly creating an object at the target path. This is now corrected.

This fix also improves the internal usage of mocked subgraphs with TestHarness.

By @Geal in https://github.com/apollographql/router/pull/1819

Default conditional @defer condition to true (Issue #1820)

According to recent updates in the @defer specification, defer conditions must default to true. This corrects a bug where that default value wasn't being initialized properly.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1832

Support query plans with empty primary subselections (Issue #1778)

When a query with @defer would result in an empty primary response, the router was returning an error in interpreting the query plan. It is now using the query plan properly, and detects more precisely queries containing @defer.

By @Geal in https://github.com/apollographql/router/pull/1778

🛠 Maintenance

Add more compilation gates to hide noisy warnings (PR #1830)

Add more gates (for the console feature introduced in PR #1632) to not emit compiler warnings when using the --all-features flag. (See original PR for more details on the flag usage.)

By @bnjjj in https://github.com/apollographql/router/pull/1830

Deny panic, unwrap and expect in the spec module (Issue #1844)

We are generally working to eliminate unwrap() and expect() statements from critical paths in the codebase and have done so on the spec module. The spec module, in particular, is reached after parsing has occurred so any invariants expressed by these expects would have already been enforced or validated. Still, we've decided to tighten things even further, by raising errors instead to provide end-users with even more stability.

To further defend against re-introduction, the spec module now has linting annotations that prevent its content from using any code that explicitly panics.

#![deny(clippy::unwrap_used)]
#![deny(clippy::expect_used)]
#![deny(clippy::panic)]

By @o0Ignition0o in https://github.com/apollographql/router/pull/1844

Remove potential panics from query plan execution (PR #1842)

Some remaining parts of the query plan execution code were using expect(), unwrap() and panic() to guard against assumptions about data. These conditions have been replaced with errors which will returned in the response preventing the possibility of panics in these code paths.

By @Geal in https://github.com/apollographql/router/pull/1842

Note We're almost to 1.0! We've got a couple relatively small breaking changes to the configuration for this release (none to the API) that should be relatively easy to adapt to and a number of bug fixes and usability improvements.

❗ BREAKING ❗

Change headers propagation configuration (PR #1795)

While it wasn't necessary today, we want to avoid a necessary breaking change in the future by proactively making room for up-and-coming work. We've therefore introduced another level into the headers configuration with a request object, to allow for a response (see Issue #1284) to be an additive feature after 1.0.

A rough look at this should just be a matter of adding in request and indenting everything that was inside it:

headers:
    all:
+     request:
          - remove:
              named: "test"

The good news is that we'll have response in the future! For a full set of examples, please see the header propagation documentation.

By @bnjjj in https://github.com/apollographql/router/pull/1795

Bind the Sandbox on the same endpoint as the Supergraph, again (Issue #1785)

We have rolled back an addition that we released in this week's v1.0.0-rc.0 which allowed Sandbox (an HTML page that makes requests to the supergraph endpoint) to be on a custom socket. In retrospect, we believe it was premature to make this change without considering the broader impact of this change which ultimately touches on CORS and some developer experiences bits. Practically speaking, we may not want to introduce this because it complicates the model in a number of ways.

For the foreseeable future, Sandbox will continue to be on the same listener address as the supergraph listener.

It's unlikely anyone has really leaned into this much already, but if you've already re-configured sandbox or homepage to be on a custom listen-er and/or path in 1.0.0-rc.0, here is a diff of what you should remove:

sandbox:
-  listen: 127.0.0.1:4000
-  path: /
  enabled: false
homepage:
-  listen: 127.0.0.1:4000
-  path: /
  enabled: true

Note this means you can either enable the homepage, or the sandbox, but not both.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1796

🚀 Features

Automatically check "Return Query Plans from Router" checkbox in Sandbox (Issue #1803)

When loading Sandbox, we now automatically configure it to toggle the "Request query plans from Router" checkbox to the enabled position which requests query plans from the Apollo Router when executing operations. These query plans are displayed in the Sandbox interface and can be seen by selecting "Query Plan Preview" from the drop-down above the panel on the right side of the interface.

By @abernix in https://github.com/apollographql/router/pull/1804

🐛 Fixes

Fix --dev mode when no configuration file is specified (Issue #1801) (Issue #1802)

We've reconciled an issue where the --dev mode flag was being ignored when running the router without a configuration file. (While many use cases do require a configuration file, the Router actually doesn't need a confguration in many cases!)

By @bnjjj in https://github.com/apollographql/router/pull/1808

Respect supergraph's path for Kubernetes deployment probes (Issue #1787)

If you've configured the supergraph's path property using the Helm chart, the liveness and readiness probes now utilize these correctly. This fixes a bug where they continued to use the default path of / and resulted in a startup failure.

By @damienpontifex in https://github.com/apollographql/router/pull/1788

Get variable default values from the query for query plan condition nodes (PR #1640)

The query plan condition nodes, generated by the if argument of the @defer directive, were not using the default value of the variable passed in as an argument.

This also fixes default value validations for non-@defer'd queries.

By @Geal in https://github.com/apollographql/router/pull/1640

Correctly hot-reload when changing the supergraph's listen socket (Issue #1814)

If you change the supergraph's listen socket while in --hot-reload mode, the Router will now correctly pickup the change and bind to the new socket.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1815

🛠 Maintenance

Improve error message when querying non existent field Issue #1816

When querying a non-existent field you will get a better error message:

{
  "errors": [
    {
-       "message": "invalid type error, expected another type than 'Named type Computer'"
+       "message": "Cannot query field \"xxx\" on type \"Computer\""
    }
  ]
}

By @bnjjj in https://github.com/apollographql/router/pull/1817

Update apollo-router-scaffold to use the published apollo-router crate PR #1782

Now that apollo-router is released on crates.io, we have updated the project scaffold to rely on the published crate instead of Git tags.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1782

Refactor Configuration validation Issue #1791

Instantiating Configurations is now fallible, because it will run consistency checks on top of the already run structure checks.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1794

Refactor response-formatting tests #1798

Rewrite the response-formatting tests to use a builder pattern instead of macros and move the tests to a separate file.

By @Geal in https://github.com/apollographql/router/pull/1798

📚 Documentation

Add rustdoc documentation to various modules (Issue #799)

Adds documentation for:

• apollo-router/src/layers/instrument.rs
• apollo-router/src/layers/map_first_graphql_response.rs
• apollo-router/src/layers/map_future_with_request_data.rs
• apollo-router/src/layers/sync_checkpoint.rs
• apollo-router/src/plugin/serde.rs
• apollo-router/src/tracer.rs

By @garypen in https://github.com/apollographql/router/pull/1792

Fixed docs.rs publishing error from our last release

During our last release we discovered for the first time that our documentation wasn't able to compile on the docs.rs website, leaving our documentation in a failed state.

While we've reconciled that particular problem, we're now being affected by this internal compiler errors (ICE) that is affecting anyone using 1.65.0-nightly builds circa today. Since docs.rs uses nightly for all builds, this means it'll be a few more days before we're published there.

With thanks to @SimonSapin in https://github.com/apollographql/federation-rs/pull/185

Note

👋 We're at our release candidate stage but we still have a round of breaking changes and features in this release. Not much more after this! Those using the apollo-router as a library should be minimally impacted by Rust API changes in this 1.0.0-rc.0 release, however there are notable changes to the configuration file and default values outlined below. We hope you'll appreciate the changes (including the secure defaults, flexibility and introduction of a --dev mode). Thanks for your continued feedback and cooperation and please try out this release candidate! We will graduate to 1.0 as soon as possible! ✨

❗ BREAKING ❗

Note

We are entering our release candidate ("RC") stage and expect this to be the last of our breaking changes. Overall, most of the breaking changes in this release revolve around three key factors which were motivators for most of the changes:

1. Having safe and security defaults which are suitable for production
2. Polishing our YAML configuration ergonomics and patterns
3. The introduction of a development mode activated with the --dev flag

See the full changelog below for details on these (including the "Features" section for the --dev changes!)

Adjusted socket ("listener") addresses for more secure default behaviors

• The Router will not listen on "all interfaces" in its default configuration (i.e., by binding to 0.0.0.0). You may specify a specific socket by specifying the interface:port combination. If you desire behavior which binds to all interfaces, your configuration can specify a socket of 0.0.0.0:4000 (for port 4000 on all interfaces).
• By default, Prometheus (if enabled) no longer listens on the same socket as the GraphQL socket. You can change this behavior by binding it to the same socket as your GraphQL socket in your configuration.
• The health check endpoint is no longer available on the same socket as the GraphQL endpoint (In fact, the health check suggestion has changed in ways that are described elsewhere in this release's notes. Please review them separately!)

Safer out-of-the box defaults with sandbox and introspection disabled (PR #1748)

To reflect the fact that it is not recomended to have introspection on in production (and since Sandbox uses introspection to power its development features) the sandbox and introspection configuration are now disabled unless you are running the Router with --dev.

If you would like to force them on even when outside of --dev mode, you can set them to true explicitly in your YAML configuration:

sandbox:
  enabled: true
supergraph:
  introspection: true

By @bnjjj in https://github.com/apollographql/router/pull/1748

Landing page ("home page") replaces Sandbox in default "production" mode (PR #1768)

As an extension of Sandbox and Introspection being disabled by default (see above), the Router now displays a simple landing page when running in its default mode. When you run the Apollo Router with the new --dev flag (see "Features" section below) you will still see the existing "Apollo Studio Sandbox" experience.

We will offer additional options to customize the landing page in the future but for now you can disable the homepage entirely (leaving a very generic page with a GraphQL message) by disabling the homepage entirely in your configuration:

homepage:
  enabled: false

By @o0Ignition0o in https://github.com/apollographql/router/pull/1768

Listeners, paths and paths can be configured individually (Issue #1500)

It is now possible to individually configure the following features' socket/listener addresses (i.e., the IP address and port) in addition to the URL path:

• GraphQL execution (default: http://127.0.0.1:4000/)
• Sandbox (default when using --dev: http://127.0.0.1:4000/)
• Prometheus (default when enabled: http://127.0.0.1:9090/metrics)

Examples of how to configure these can be seen in the YAML configuration overhaul section of this changelog (just below) as well as in our documentation.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1718

Overhaul/reorganization of YAML configuration (#1500)

To facilitate the changes in the previous bullet-points, we have moved configuration parameters which previously lived in the server section to new homes in the configuration, including listen, graphql_path, landing_page, and introspection. Additionally, preview_defer_support has moved, but is on by default and no longer necessary to be set explicitly unless you wish to disable it.

As another section (below) notes, we have removed the health check and instead recommend users to configure their health checks (in, e.g, Kubernetes, Docker, etc.) to use a simple GraphQL query: /?query={__typename}. Read more about that in the other section, however this is reflected by its removal in the configuration.

To exemplify the changes, this previous configuration will turn into the configuration that follows it:

Before

server:
  listen: 127.0.0.1:4000
  graphql_path: /graphql
  health_check_path: /health # Health check has been deprecated.  See below.
  introspection: false
  preview_defer_support: true
  landing_page: true
telemetry:
  metrics:
    prometheus:
      enabled: true

After

# This section is just for Sandbox configuration
sandbox:
  listen: 127.0.0.1:4000
  path: /
  enabled: false # Disabled by default, but on with `--dev`.

# This section represents general supergraph GraphQL execution
supergraph:
  listen: 127.0.0.1:4000
  path: /
  introspection: false
  # Can be removed unless it needs to be set to `false`.
  preview_defer_support: true

# The health check has been removed.  See the section below in the CHANGELOG
# for more information on how to configure health checks going forward.

# Prometheus scraper endpoint configuration
# The `listen` and `path` are not necessary if `127.0.0.1:9090/metrics` is okay
telemetry:
  metrics:
    prometheus:
      listen: 127.0.0.1:9090
      path: /metrics
      enabled: true

By @o0Ignition0o in https://github.com/apollographql/router/pull/1718

Environment variable expansion adjustments (#1759)

• Environment expansions must be prefixed with env..

• File expansions must be prefixed with file..

• The "default" designator token changes from : to :-. For example:

  ${env.USER_NAME:Nandor} => ${env.USER_NAME:-Nandor}

• Failed expansions now result in an error

  Previously expansions that failed due to missing environment variables were silently skipped. Now they result in a configuration error. Add a default value using the above syntax if optional expansion is needed.

By @BrynCooke in https://github.com/apollographql/router/pull/1763

Dedicated health check endpoint removed with new recommendation to use /query={__typename} query (Issue #1765)

We have removed the dedicated health check endpoint and now recommend users to configure their health checks (in, e.g, Kubernetes, Docker) to use a simple GraphQL query instead.

Use the following query with a content-type: application/json header as a health check instead of /.well-known/apollo/server-health:

/?query={__typename}

The Kubernetes documentation and related Helm charts have been updated to reflect this change.

Using this query has the added benefit of actually testing GraphQL. If this query returns with an HTTP 200 OK, it is just as reliable (and even more meaningful) than the previous /.well-known/apollo/server-health endpoint. It's important to include the content-type: application/json header to satisfy the Router's secure requirements that offer CSRF protections.

In the future, we will likely reintroduce a dedicated health check "liveliness" endpoint along with a meaningful "readiness" health check at the same time. In the meantime, the query above is technically more durable than the health check we offered previously.

By @abernix in https://github.com/apollographql/router/pull/TODO

Promote include_subgraph_errors out of "experimental" status (Issue #1773)

The include_subraph_errors plugin has been promoted out of "experimental" and will require a small configuration changes. For example:

-plugins:
-  experimental.include_subgraph_errors:
-    all: true # Propagate errors from all subraphs
-    subgraphs:
-      products: false # Do not propagate errors from the products subgraph
+include_subgraph_errors:
+  all: true # Propagate errors from all subraphs
+  subgraphs:
+    products: false # Do not propagate errors from the products subgraph

By @garypen in https://github.com/apollographql/router/pull/1776

apollo-spaceport and uplink are now part of apollo-router (Issue #491)

Instead of being dependencies, they are now part of the apollo-router crate. They were not meant to be used independently.

By @SimonSapin in https://github.com/apollographql/router/pull/1751

Remove over-exposed functions from the public API (PR #1746)

The following functions are only required for router implementation, so removing from external API:

subgraph::new_from_response
supergraph::new_from_response
supergraph::new_from_graphql_response

By @garypen in https://github.com/apollographql/router/pull/1746

Span client_name and client_version attributes renamed (#1514)

OpenTelemetry attributes should be grouped by . rather than _, therefore the following attributes have changed:

• client_name => client.name
• client_version => client.version

By @BrynCooke in https://github.com/apollographql/router/pull/1514

Otel configuration updated to use expansion (#1772)

File and env access in configuration now use the generic expansion mechanism introduced in #1759.

      grpc:
        key:
          file: "foo.txt"
        ca:
          file: "bar.txt"
        cert:
          file: "baz.txt"

Becomes:

      grpc:
        key: "${file.foo.txt}"
        ca: "${file.bar.txt}"
        cert: "${file.baz.txt}"

or

      grpc:
        key: "${env.FOO}"
        ca: "${env.BAR}"
        cert: "${env.BAZ}"

By @BrynCooke in https://github.com/apollographql/router/pull/1774

🚀 Features

Adds a development mode that can be enabled with the --dev flag (#1474)

By default, the Apollo Router is configured with production best-practices. When developing, it is often desired to have some of those features relaxed to make it easier to iterate. A --dev flag has been introduced to make the user experience easier while maintaining a default configuration which targets a productionized environment.

The --dev mode will enable a few options for development which are not normally on by default:

• The Apollo Sandbox Explorer will be served instead of the Apollo Router landing page, allowing you to run queries against your development Router.
• Introspection will be enabled, allowing client tooling (and Sandbox!) to obtain the latest version of the schema.
• Hot-reloading of configuration will be enabled. (Also available with --hot-reload when running without --dev)
• It will be possible for Apollo Sandbox Explorer to request a query plan to be returned with any operations it executes. These query plans will allow you to observe how the operation will be executed against the underlying subgraphs.
• Errors received from subgraphs will not have their contents redacted to facilitate debugging.

Additional considerations will be made in the future as we introduce new features that might necessitate a "development" workflow which is different than the default mode of operation. We will try to minimize these differences to avoid surprises in a production deployment while providing an execellent development experience. In the future, the (upcoming) rover dev experience will become our suggested pattern, but this should serve the purpose in the near term.

By @bnjjj and @EverlastingBugstopper and @abernix in https://github.com/apollographql/router/pull/1748

Apollo Studio Federated Tracing (#1514)

Add support of federated tracing in Apollo Studio:

telemetry:
    apollo:
        # The percentage of requests will include HTTP request and response headers in traces sent to Apollo Studio.
        # This is expensive and should be left at a low value.
        # This cannot be higher than tracing->trace_config->sampler
        field_level_instrumentation_sampler: 0.01 # (default)

        # Include HTTP request and response headers in traces sent to Apollo Studio
        send_headers: # other possible values are all, only (with an array), except (with an array), none (by default)
            except: # Send all headers except referer
            - referer

        # Send variable values in Apollo in traces sent to Apollo Studio
        send_variable_values: # other possible values are all, only (with an array), except (with an array), none (by default)
            except: # Send all variable values except for variable named first
            - first
    tracing:
        trace_config:
            sampler: 0.5 # The percentage of requests that will generate traces (a rate or `always_on` or `always_off`)

By @BrynCooke & @bnjjj & @o0Ignition0o in https://github.com/apollographql/router/pull/1514

Provide access to the supergraph SDL from rhai scripts (Issue #1735)

There is a new global constant apollo_sdl which can be use to read the supergraph SDL as a string.

By @garypen in https://github.com/apollographql/router/pull/1737

Add support for tokio-console (PR #1632)

To aid in debugging the router, this adds support for tokio-console, enabled by a Cargo feature.

To run the router with tokio-console, build it with RUSTFLAGS="--cfg tokio_unstable" cargo run --features console.

By @Geal in https://github.com/apollographql/router/pull/1632

Restore the ability to specify custom schema and configuration sources (#1733)

You may now, once again, specify custom schema and config sources when constructing an executable. We had previously omitted this behavior in our API pruning with the expectation that it was still possible to specify via command line arguments and we almost immediately regretted it. We're happy to have it back!

Executable::builder()
  .shutdown(ShutdownSource::None)
  .schema(SchemaSource::Stream(schemas))
  .config(ConfigurationSource::Stream(configs))
  .start()
  .await

By @BrynCooke in https://github.com/apollographql/router/pull/1734

Environment variable expansion prefixing (#1759)

The environment variable APOLLO_ROUTER_CONFIG_ENV_PREFIX can be used to prefix environment variable lookups during configuration expansion. This feature is undocumented and unsupported and may change at any time. We do not recommend using this.

For example:

APOLLO_ROUTER_CONFIG_ENV_PREFIX=MY_PREFIX

Would cause: ${env.FOO} to be mapped to ${env.MY_PREFIX_FOO} when expansion is performed.

By @BrynCooke in https://github.com/apollographql/router/pull/1763

Environment variable expansion mode configuration (#1772)

The environment variable APOLLO_ROUTER_CONFIG_SUPPORTED_MODES can be used to restrict which modes can be used for environment expansion. This feature is undocumented and unsupported and may change at any time. We do not recommend using this.

For example:

APOLLO_ROUTER_CONFIG_SUPPORTED_MODES=env,file env and file expansion APOLLO_ROUTER_CONFIG_SUPPORTED_MODES=env - only env variable expansion allowed

By @BrynCooke in https://github.com/apollographql/router/pull/1774

🐛 Fixes

Support execution of the bare __typename field (Issue #1761)

For queries like query { __typename }, we now perform the expected behavior and return a GraphQL response even if the introspection has been disabled. (introspection: false should only apply to schema introspeciton not type-name introspection.)

By @bnjjj in https://github.com/apollographql/router/pull/1762

Set hasNext for the last chunk of a deferred response (#1687 #1745)

There will no longer be an empty last response {"hasNext": false} and the hasNext field will be set on the last deferred response. There can still be one edge case where that empty message can occur, if some deferred queries were cancelled too quickly. Generally speaking, clients should expect this to happen to allow future behaviors and this is specified in the @defer draft specification.

By @bnjjj in https://github.com/apollographql/router/pull/1687 By @Geal in https://github.com/apollographql/router/pull/1745

🛠 Maintenance

Add errors vec in QueryPlannerResponse to handle errors in query_planning_service (PR #1504)

We changed QueryPlannerResponse to:

• Add a Vec<apollo_router::graphql::Error>
• Make the query plan optional, so that it is not present when the query planner encountered a fatal error. Such an error would be in the Vec

This should improve the messages returned during query planning.

By @bnjjj in https://github.com/apollographql/router/pull/1504

Store the Apollo usage reporting Protobuf interface file in the repository

Previously this file was downloaded when compiling the Router, but we had no good way to automatically check when to re-download it without causing the Router to be compiled all the time.

Instead a copy now resides in the repository, with a test checking that it is up to date. This file can be updated by running this command then sending a PR:

curl -f https://usage-reporting.api.apollographql.com/proto/reports.proto \
    > apollo-router/src/spaceport/proto/reports.proto

By @SimonSapin

Disable compression on multipart/mixed HTTP responses (Issue #1572)

The Router now reverts to using unpatched async-compression, and instead disables compression of multipart responses. We aim to re-enable compression soon, with a proper solution that is being designed in https://github.com/Nemo157/async-compression/issues/154.

As context to why we've made this change: features such as @defer require the Apollo Router to send a stream of multiple GraphQL responses in a single HTTP response with the body being a single byte stream. Due to current limitations with our upstream compression library, that entire byte stream is compressed as a whole, which causes the entire deferred response to be held back before being returned. This obviously isn't ideal for the @defer feature which tries to get reponses to client soon possible.

This change replaces our previous work-around which involved a patched async-compression, which was not trivial to apply when using the Router as a dependency since Cargo patching is done in a project’s root Cargo.toml.

Again, we aim to re-visit this as soon as possible but found this to be the more approachable work-around.

By @SimonSapin in https://github.com/apollographql/router/pull/1749

👋 We're getting closer to our release candidate stages so there are far less breaking changes to the API in these versions, rather changes to configuration. We'll have a bit more in the next releases, but nothing as bad as the bumps from pre-v1.0.0-alpha.x versions. Thanks for your feedback and cooperation! ✨

❗ BREAKING ❗

Unified supergraph and execution response types (PR #1708)

apollo_router::services::supergraph::Response and apollo_router::services::execution::Response were two structs with identical fields and almost-identical methods. The main difference was that builders were fallible for the former but not the latter.

They are now the same type (with one location a type alias of the other), with fallible builders. Callers may need to add either a operator ? (in plugins) or an .unwrap() call (in tests).

 let response = execution::Response::builder()
     .error(error)
     .status_code(StatusCode::BAD_REQUEST)
     .context(req.context)
-    .build();
+    .build()?;

By @SimonSapin in https://github.com/apollographql/router/pull/1708

Rename originating_request to supergraph_request on various plugin Request structures (Issue #1713)

We feel that supergraph_request makes it more clear that this is the request received from the client.

By @garypen in https://github.com/apollographql/router/pull/1715

Prometheus is no longer defaulting to the GraphQL endpoint and listener address (Issue #1645)

The Router's Prometheus interface is now exposed at 127.0.0.1:9090/metrics, rather than http://0.0.0.0:4000/plugins/apollo.telemetry/prometheus. This should be both more secure and also more generally compatible with the default settings that Prometheus expects (which also uses port 9090 and just /metrics as its defaults).

To expose to a non-localhost interface, it is necessary to explicitly opt-into binding to a socket address of 0.0.0.0:9090 (i.e., all interfaces on port 9090) or a specific available interface (e.g., 192.168.4.1) on the host.

Have a look at the Features section (below) to learn how to customize the listen address and the path.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1654

🚀 Features

New plugin helper: map_first_graphql_response (Issue #1564)

In supergraph and execution services, the service response contains not just one GraphQL response but a stream of them, in order to support features such as @defer.

This new method of ServiceExt and ServiceBuilderExt in apollo_router::layers wraps a service and calls a callback when the first GraphQL response in the stream returned by the inner service becomes available. The callback can then access the HTTP parts (headers, status code, etc) or the first GraphQL response before returning them.

See the doc-comments in apollo-router/src/layers/mod.rs for more.

By @SimonSapin in https://github.com/apollographql/router/pull/1708

Users can customize the Prometheus listener address and URL path (Issue #1645)

You can now customize the Prometheus listener socket address and URL path in your YAML configuration:

telemetry:
  metrics:
    prometheus:
      listen: 127.0.0.1:9090 # default
      path: /metrics # default
      enabled: true

By @o0Ignition0o in https://github.com/apollographql/router/pull/1654

Add an apollo_router::graphql::ResponseStream type alias (PR #1697)

It is equivalent to BoxStream<'static, graphql::Response> and makes some type signatures slightly simpler.

By @SimonSapin in https://github.com/apollographql/router/pull/1697

🐛 Fixes

Fix metrics duration for router request (#1705)

With the introduction of BoxStream for @defer we introduced a bug when computing HTTP request duration metrics where we failed to wait for the first response in the BoxStream.

By @bnjjj in https://github.com/apollographql/router/pull/1705

Numerous fixes to preview @defer query planning (Issue #1698)

Updated to Federation 2.1.2-alpha.0 which brings in a number of fixes for the preview @defer support. These fixes include:

• Empty selection set produced with @defer'd query federation#2123
• Include directive with operation argument errors out in Fed 2.1 federation#2124
• query plan sequencing affected with __typename in fragment federation#2128
• Router Returns Error if __typename Omitted router#1668

By @abernix in https://github.com/apollographql/router/pull/1711

👋 We're getting closer to our release candidate stages so there are far less breaking changes to the API in these versions, rather changes to configuration. We'll have a bit more in the next releases, but nothing as bad as the bumps from 0.15.x, through 0.16.0 and on to v1.0.0-alpha.0. Thanks for your feedback and cooperation! ✨

🚀 Features

Add service_name and service_namespace in telemetry.metrics.common (Issue #1490)

Add service_name and service_namespace in telemetry.metrics.common to reflect the same configuration than tracing.

telemetry:
  metrics:
    common:
      # (Optional, default to "apollo-router") Set the service name to easily find metrics related to the apollo-router in your metrics dashboards
      service_name: "apollo-router"
      # (Optional)
      service_namespace: "apollo"

By @bnjjj in https://github.com/apollographql/router/pull/1492

🐛 Fixes

Fix distributed tracing header propagation (#1701)

Span context is now correctly propagated if you're trying to propagate tracing context to the router.

By @bnjjj in https://github.com/apollographql/router/pull/1701

🛠 Maintenance

Replace startup crate with ctor crate (#1704)

At startup, the router registers plugins. The crate we used to use (startup) has been yanked from crates.io and archived on GitHub. We're unsure why the package was yanked, but we've decided to move to the ctor crate, which is more widely adopted and maintained.

This should fix the sudden errors for those who were using the router as a library or attempting to scaffold a new plugin using cargo scaffold.

By @garypen in https://github.com/apollographql/router/pull/1704

macOS: Update Xcode build version from 11.7 to 13.4 (PR #1702)

We now build our macOS binaries with Xcode 13.4 rather than 11.7. This may result in the Router not working on very old versions of macOS but we'd rather get this out of the way before CircleCI potentially deprecates 11.x images themselves and we're unable to test on them anymore.

By @abernix in https://github.com/apollographql/router/pull/1702

👋 We're getting closer to our release candidate stages so there are far less breaking changes to the API in this version, rather changes to configuration. We'll have a bit more in the next release, but nothing as bad as the bumps from 0.15.x, through 0.16.0 and on to v1.0.0-alpha.0

❗ BREAKING ❗

Preserve plugin response Vary headers (PR #1660)

It is now possible to set a Vary header in a client response from a plugin.

Note: This is a breaking change because the prior behaviour provided three default Vary headers and we've had to drop those to enable this change. If, after all plugin processing, there is no Vary header, the router will add one with a value of "origin", as is best-practice for cache control headers with CORS.

By @garypen in https://github.com/apollographql/router/pull/1660

Fix the supported defer specification version to 20220824 (PR #1652)

Since the router will ship before the @defer specification is done, we add a parameter to the Accept and Content-Type headers to indicate which specification version is accepted.

The specification is fixed to graphql/graphql-spec@01d7b98

The router will now return a response with the status code 406 Not Acceptable if the Accept header does not match.

By @Geal in https://github.com/apollographql/router/pull/1652

Change default enablement and promote experimental_defer_support to preview_defer_support (PR #1673)

Following up on a tremendous amount of work tracked in https://github.com/apollographql/router/issues/80 - which brought various stages of @defer support to the Router - this changes our designation of its status from "Experimental" to "Preview". It's worth noting that the @defer specification has just graduated to "Stage 2 (Draft)" mode in the GraphQL Working Group, so changes may still be expected and there are two stages ahead. To help things progress:

• We've lifted the previous requirement that users opt into defer support by setting experimental_defer_support: true in the server section of their configuration. It is now on by default.

• The option is now called preview_defer_support and it can be set to false to specifically opt out of it existing at all. This might be desired if you would prefer that it not even show up in introspection or be possible to use even if a client requests it.

• Using @defer support requires clients set the appropriate HTTP accept header to use it. This puts the burden of understanding the risks of an early-preview on the clients who will need to consume the Router's responses. This is particularly important for clients who have long-lived support requirements (like native mobile apps).

  To see which headers are required, see https://github.com/apollographql/router/issues/1648.

By @abernix in https://github.com/apollographql/router/pull/1685

🚀 Features

Return an error when nullifying a non-null field (Issue #1304)

Nullability rules may remove parts of the response without indicating why. Error messages now indicate which part of the response triggered nullability rules.

By @Geal in https://github.com/apollographql/router/pull/1537

router now provides TraceId (PR #1663)

If you need a reliable way to link together the various stages of pipeline processing, you can now use

apollo_router::tracer::TraceId::new()

By @garypen in https://github.com/apollographql/router/pull/1663

🐛 Fixes

Docker images: Use absolute path for ENTRYPOINT (PR #1684)

This restores the absolute path in ENTRYPOINT in our Dockerfiles (and published images) to allow users to change their working directory without consequence (and without needing to change it back to /dist or override the entrypoint).

By @110y in https://github.com/apollographql/router/pull/1684

Update our helm documentation to illustrate how to use our registry (#1643)

Updated documentation for helm charts to point to Apollo OCI registry.

By @garypen in https://github.com/apollographql/router/pull/1649

Update router-bridge to query-planner v2.1.1 (PR #1650 PR #1672)

The 2.1.0 release of the query planner comes with fixes to fragment interpretation and reduced memory usage. The 2.1.1 release of the query planner fixes an issue with the @defer directive's if argument being ignored.

By @Geal in https://github.com/apollographql/router/pull/1650 and https://github.com/apollographql/router/pull/1672

Do not nullify the entire query if the root operation is not present (PR #1674)

If a root field was not returned by the subgraph (e.g., when there's an error) the entire data object should not be nullified. Instead, the root field that should be null (unless it is non nullable).

By @Geal in https://github.com/apollographql/router/pull/1674

Propagate graphql response regardless of the subgraph HTTP status code. (#1664)

Subgraph service calls no longer return an error when the received HTTP status code isn't 200. The GraphQL specification does not specify HTTP status code behavior since the GraphQL specification is transport agnostic.

This commit removes our HTTP status code check in the subgraph_service.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1664

🛠 Maintenance

Remove cache layer (PR #1647)

ServiceBuilderExt::cache was removed in v0.16.0. The unused CacheLayer has now also been removed.

By @garypen in https://github.com/apollographql/router/pull/1647

Refactor SupergraphService (PR #1615)

The SupergraphService code became too complex, so much that rustfmt could not modify it anymore. This breaks up the code in more manageable functions.

By @Geal in https://github.com/apollographql/router/pull/1615

Conditionally use HorizontalPodAutoscaler api version autoscaling/v2 (PR #1635)

The helm chart HorizontalPodAutoscaler resource now will use API version autoscaling/v2 on Kubernetes hosts greater than 1.23 when the version is available. Fallback to version autoscaling/v2beta1 will still be utilised when this version is unavailable

By @damienpontifex in https://github.com/apollographql/router/pull/1635

❗ BREAKING ❗

Move cors configuration from server to root-level (PR #1586)

The cors configuration is now located at the root-level of the configuration file, rather than inside server.

For example:

- server:
-   cors:
-     origins:
-       - https://yourdomain.com
+ cors:
+   origins:
+     - https://yourdomain.com

By @garypen in https://github.com/apollographql/router/pull/1586

Exit the router after logging panic details (PR #1602)

The Router will now terminate in the (unlikely) case where it panics.

By @garypen in https://github.com/apollographql/router/pull/1602

Rename the endpoint parameter to graphql_path (#1606)

The endpoint parameter within the server portion of the YAML configuration has been renamed to graphql_path to more accurately reflect its behavior.

If you used this option, the necessary change would look like:

- server:
-   endpoint: /graphql
+ server:
+   graphql_path: /graphql

By @abernix in https://github.com/apollographql/router/pull/1609

Remove activate() from the plugin API (PR #1569)

Recent changes to configuration reloading means that the only known consumer of this API, telemetry, is no longer using it.

Let's remove it since it's simple to add back if later required.

By @garypen in https://github.com/apollographql/router/pull/1569

Rename TestHarness methods (PR #1579)

Some methods of apollo_router::TestHarness were renamed:

• extra_supergraph_plugin → supergraph_hook
• extra_execution_plugin → execution_hook
• extra_subgraph_plugin → subgraph_hook

By @SimonSapin in https://github.com/apollographql/router/pull/1579

Request and Response types from apollo_router::http_ext are private (Issue #1589)

These types were wrappers around the Request and Response types from the http crate. Now the latter are used directly instead.

By @SimonSapin in https://github.com/apollographql/router/pull/1589

Changes to IntoHeaderName and IntoHeaderValue (PR #1607)

Note: These types are typically not used directly, so we expect most user code to require no changes.

• Move from apollo_router::http_ext to apollo_router::services
• Rename to TryIntoHeaderName and TryIntoHeaderValue
• Make contents opaque
• Replace generic From<T: Display> conversion with multiple specific conversions that are implemented by http::headers::Header{Name,Value}.

By @SimonSapin in https://github.com/apollographql/router/pull/1607

QueryPlan::usage_reporting and QueryPlannerContent are private (Issue #1556)

These items have been removed from the public API of apollo_router::services::execution.

By @SimonSapin in https://github.com/apollographql/router/pull/1568

Insert the full target triplet in the package name, and prefix with v (Issue #1385)

The release tarballs now contain the full target triplet in their name along with a v prefix to be consistent with our other packaging techniques (e.g., Rover).

For example:

• router-0.16.0-x86_64-linux.tar.gz becomes router-v0.16.0-x86_64-unknown-linux-gnu.tar.gz
• router-0.16.0-x86_64-macos.tar.gz becomesrouter-v0.16.0-x86_64-apple-darwin.tar.gz
• router-0.16.0-x86_64-windows.tar.gz becomesrouter-v0.16.0-x86_64-pc-windows-msvc.tar.gz

By @abernix and @Geal in https://github.com/apollographql/router/pull/1433 (which re-lands work done in https://github.com/apollographql/router/pull/1393)

Many structs and enums are now #[non_exhaustive] (Issue #1550)

This means we may adjust struct fields or enum variants in additive ways in the future without breaking changes. To prepare for that eventuality:

1. When using a struct pattern (such as for deconstructing a value into its fields), use .. to allow further fields:

-let PluginInit { config, supergraph_sdl } = init;
+let PluginInit { config, supergraph_sdl, .. } = init;

2. Use field access instead:

-let PluginInit { config, supergraph_sdl } = init;
+let config = init.config;
+let supergraph_sdl = init.supergraph_sdl;

3. When constructing a struct, use a builder or constructor method instead of struct literal syntax:

-let error = graphql::Error {
-    message: "something went wrong".to_string(),
-    ..Default::default()
-};
+let error = graphql::Error::builder()
+    .message("something went wrong")
+    .build();

4. When matching on an enum, add a wildcard match arm:

match error {
    ApolloRouterError::StartupError => "StartupError",
    ApolloRouterError::HttpServerLifecycleError => "HttpServerLifecycleError",
    ApolloRouterError::NoConfiguration => "NoConfiguration",
    ApolloRouterError::NoSchema => "NoSchema",
    ApolloRouterError::ServiceCreationError(_) => "ServiceCreationError",
    ApolloRouterError::ServerCreationError(_) => "ServerCreationError",
+    _ => "other error",
}

By @SimonSapin in https://github.com/apollographql/router/pull/1614

Some error enums or variants were removed (Issue #81)

They were not used anymore in the public API (or at all).

By @SimonSapin in https://github.com/apollographql/router/pull/1621

🚀 Features

Instrument the rhai plugin with a tracing span (PR #1598)

If you have an active rhai script in your router, you will now see a "rhai plugin" span in tracing.

By @garypen in https://github.com/apollographql/router/pull/1598

🐛 Fixes

Only send one report for a response with deferred responses (PR #1576)

The router was sending one report per response (even deferred ones), while Studio was expecting one report for the entire response. The router now sends one report which is inclusive of the latency of the entire operation.

By @Geal in https://github.com/apollographql/router/pull/1576

Include formatted query plan when exposing the query plan (#1557)

Move the location of the text field when exposing the query plan and fill it with a formatted query plan.

By @bnjjj in https://github.com/apollographql/router/pull/1557

Change state machine log messages to trace (#1578)

We no longer show internal state machine log events at the info level since they are unnecessary during normal operation. They are instead emitted at the trace level and can be enabled selectively using the --log trace flag.

By @abernix in https://github.com/apollographql/router/pull/1597

Formatting problem fix of scalar fields selected several times (PR #1583)

Fixed a bug where querying scalar fields several times would put nulls instead of expected values.

By @eole1712 in https://github.com/apollographql/router/pull/1585

Fix typo on HTTP errors from subgraph (#1593)

Remove the closed parenthesis at the end of error messages resulting from HTTP errors from subgraphs.

By @nmoutschen in https://github.com/apollographql/router/pull/1593

Only send one report for a response with deferred responses (PR #1596)

Deferred responses come as multipart/mixed elements and are sent as individual HTTP response chunks. When a client receives one chunk, that chunk should contain the next delimiter. This gives the client the ability to start processing the response instead of waiting for the next chunk just for the delimiter.

By @Geal in https://github.com/apollographql/router/pull/1596

Patch async-compression to compress responses in streaming (PR #1604)

The async-compression crate is a dependency used for HTTP response compression. Its implementation accumulates the entire compressed response in memory before sending it. However, this created problems for @defer responses since we want those responses to come as soon as possible, rather than waiting until the entire total response has been received and compressed.

By @Geal in https://github.com/apollographql/router/pull/1604

Queries with @defer must have the accept: multipart/mixed header (PR #1610)

Since deferred responses can come back as multipart responses, we must check that the client supports that content-type. This will allow older clients to show a meaningful error message instead of a parsing error if the @defer directive is used but they don't support it.

By @Geal in https://github.com/apollographql/router/pull/1610

🛠 Maintenance

Depend on published router-bridge (PR #1613)

The router-bridge package is now published which means the router repository no longer depends on having Node.js installed to build.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1613

Re-organize our release steps checklist (PR #1605)

We've got a lot of manual steps we need to do in order to release the Router binaries, but we can at least organize them meaningfuly for ourselves to follow! This is only a Router-team concern today!

By @abernix in https://github.com/apollographql/router/pull/1605)

We're getting closer and closer to our 1.0 release and with that we have a lot of polish that we're applying to our API to get it ready for it to be a durable surface area for our consumers to depend on. Due to various learnings we've had during the pre-1.0 phases of the Router, we are evolving our API to match what we now know.

We do not intend on doing this much moving around of things again soon, but anyone who has been following the repository the last couple weeks knows there has been a lot of activity and discussion about where things should live. This means that this release has an abnormally high number of breaking changes, though we believe you'll find most of them to be relatively straightforward to pivot away from.

Please review the full change log to get all the details, but for the most part the changes in this release consist of:

• a lot of renames of existing symbols
• the re-location of exported symbols to more appropriate modules
• the privatization of functions which we don't believe users needed directly (see below if any of these turn out to be a problem).

During each step of the migration, we recommend searching this changelog for a symbol to find advice on how to migrate it. We've tried to make the instructions and path forward as clear as possible.

• If you find yourself needing help migrating to the new patterns, please first take a close look at the examples provided in this change log and if you still need help, please open a discussion.
• If you find yourself unable to do something you had previously been able to do, please open an issue. Please make sure you include your use-case so we can understand better and document it for posterity!

We appreciate your patience working through these and we're excited for the steps ahead!

❗ BREAKING ❗

Remove QueryPlannerService (PR #1552)

This service was redundant, since anything done as part of the QueryPlannerService could be done either at the SupergraphService or at the ExecutionService level.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1552

Rename map_future_with_context to map_future_with_request_data (PR #1547)

The function is not very well named since it's in fact used to extract any data from a request for use in a future. This rename makes it clear.

By @garypen in https://github.com/apollographql/router/pull/1547

Rename traffic shaping deduplication options (PR #1540)

In the traffic shaping module:

• variables_deduplication configuration option is renamed to deduplicate_variables.
• query_deduplication configuration option is renamed to deduplicate_query.

- traffic_shaping:
-   variables_deduplication: true # Enable the variables deduplication optimization
-   all:
-     query_deduplication: true # Enable query deduplication for all subgraphs.
-   subgraphs:
-     products:
-       query_deduplication: false # Disable query deduplication for products.
+ traffic_shaping:
+   deduplicate_variables: true # Enable the variables deduplication optimization
+   all:
+     deduplicate_query: true # Enable query deduplication for all subgraphs.
+   subgraphs:
+     products:
+       deduplicate_query: false # Disable query deduplication for products.

By @garypen in https://github.com/apollographql/router/pull/1540

Make query_plan_options private and wrap QueryPlanContent in an opaque type (PR #1486)

QueryPlanOptions::query_plan_options is no longer public. If you still necessitate usage of this, please open an issue with your use case.

By @bnjjj in https://github.com/apollographql/router/pull/1486

Removed delay_interval in telemetry configuration. (PR #1498)

It was doing nothing.

telemetry:
  metrics:
    common:
      # Removed, will now cause an error on Router startup:
      delay_interval:
        secs: 9
        nanos: 500000000

By @SimonSapin in https://github.com/apollographql/router/pull/1498

Remove telemetry configuration hot reloading (PR #1463)

Configuration hot reloading is not very useful for telemetry, and is the source of regular bugs that are hard to fix.

This removes the support for configuration reloading entirely. Now, the router will reject a configuration reload with an error log if the telemetry configuration changed.

It is now possible to create a subscriber and pass it explicitely to the telemetry plugin when creating it. It will then be modified to integrate the telemetry plugin's layer.

By @geal in https://github.com/apollographql/router/pull/1463

Reorder query planner execution (PR #1484)

Query planning is deterministic and only depends on the query, operation name and query planning options. As such, we can cache the result of the entire process.

This changes the pipeline to apply query planner plugins between the cache and the bridge planner, so those plugins will only be called once on the same query. If changes must be done per query, they should happen in a supergraph service.

By @Geal in https://github.com/apollographql/router/pull/1464

Remove Buffer from Mock*Service (PR #1440

This removes the usage of tower_test::mock::Mock in mocked services because it isolated the service in a task so panics triggered by mockall were not transmitted up to the unit test that should catch it. This rewrites the mocked services API to remove the build() method, and make them clonable if needed, using an expect_clone call with mockall.

By @Geal in https://github.com/apollographql/router/pull/1440

Some items were renamed or moved (PR #1487 PR #1534 PR #1555 PR #1563)

At the crate root:

• SchemaKind → SchemaSource
• SchemaKind::String(String) → SchemaSource::Static { schema_sdl: String }
• ConfigurationKind → ConfigurationSource
• ConfigurationKind::Instance → ConfigurationSource::Static
• ShutdownKind → ShutdownSource
• ApolloRouter → RouterHttpServer

In the apollo_router::plugin::Plugin trait:

• router_service → supergraph_service

In the apollo_router::services module, to new public sub-modules:

• SupergraphRequest → supergraph::Request
• SupergraphResponse → supergraph::Response
• ExecutionRequest → execution::Request
• ExecutionResponse → execution::Response
• SubgraphRequest → subgraph::Request
• SubgraphResponse → subgraph::Response

For convenience, these new sub-modules each contain type aliases base on their respective Request and Response types.

pub type BoxService = tower::util::BoxService<Request, Response, tower::BoxError>;
pub type BoxCloneService = tower::util::BoxCloneService<Request, Response, tower::BoxError>;
pub type ServiceResult = Result<Response, tower::BoxError>;

Migration example:

-use tower::util::BoxService;
-use tower::BoxError;
-use apollo_router::services::{RouterRequest, RouterResponse};
+use apollo_router::services::router;
 
-async fn example(service: BoxService<RouterRequest, RouterResponse, BoxError>) -> RouterResponse {
+async fn example(service: router::BoxService) -> router::Response {
-    let request = RouterRequest::builder()/*…*/.build();
+    let request = router::Request::builder()/*…*/.build();
     service.oneshot(request).await
 }

By @SimonSapin in https://github.com/apollographql/router/pull/1487, https://github.com/apollographql/router/pull/1534, https://github.com/apollographql/router/pull/1555, https://github.com/apollographql/router/pull/1563

Some items were removed from the public API (PR #1487 PR #1535)

If you used some of them and don’t find a replacement, please file an issue with details about the use case.

apollo_router::Configuration::boxed
apollo_router::Configuration::is_compatible
apollo_router::errors::CacheResolverError
apollo_router::errors::JsonExtError
apollo_router::errors::ParsesError::print
apollo_router::errors::PlanError
apollo_router::errors::PlannerError
apollo_router::errors::PlannerErrors
apollo_router::errors::QueryPlannerError
apollo_router::errors::ServiceBuildError
apollo_router::json_ext
apollo_router::layers::ServiceBuilderExt::cache
apollo_router::mock_service!
apollo_router::plugins
apollo_router::plugin::plugins
apollo_router::plugin::PluginFactory
apollo_router::plugin::DynPlugin
apollo_router::plugin::Handler
apollo_router::plugin::test::IntoSchema
apollo_router::plugin::test::MockSubgraphFactory
apollo_router::plugin::test::PluginTestHarness
apollo_router::query_planner::QueryPlan::execute
apollo_router::services
apollo_router::Schema

By @SimonSapin

Router startup API changes (PR #1487)

The RouterHttpServer::serve method and its return type RouterHandle were removed, their functionality merged into RouterHttpServer (formerly ApolloRouter). The builder for RouterHttpServer now ends with a start method instead of build. This method immediatly starts the server in a new Tokio task.

 RouterHttpServer::builder()
     .configuration(configuration)
     .schema(schema)
-    .build()
-    .serve()
+    .start()
     .await

By @SimonSapin in https://github.com/apollographql/router/pull/1487

router_builder_fn replaced by shutdown in the Executable builder (PR #1487)

The builder for apollo_router::Executable had a router_builder_fn method allowing the specification of how a RouterHttpServer (previously ApolloRouter) was to be created with a provided configuration and schema. Since the only possible variation was specifying when the server should shut down (with a ShutdownSource parameter) the router_builder_fn was replaced with a new shutdown method.

 use apollo_router::Executable;
-use apollo_router::RouterHttpServer;
 use apollo_router::ShutdownSource;

 Executable::builder()
-    .router_builder_fn(|configuration, schema| RouterHttpServer::builder()
-        .configuration(configuration)
-        .schema(schema)
-        .shutdown(ShutdownSource::None)
-        .start())
+    .shutdown(ShutdownSource::None)
     .start()
     .await

By @SimonSapin in https://github.com/apollographql/router/pull/1487

Removed constructors when there is a public builder (PR #1487)

Many types in the Router API can be constructed with the builder pattern. We use the buildstructor crate to auto-generate builder boilerplate based on the parameters of a constructor. These constructors have been made private so that users must go through the builder instead, which will allow us to add parameters in the future without a breaking API change. If you were using one of these constructors, the migration generally looks like this:

-apollo_router::graphql::Error::new(m, vec![l], Some(p), Default::default())
+apollo_router::graphql::Error::build()
+    .message(m)
+    .location(l)
+    .path(p)
+    .build()

By @SimonSapin in https://github.com/apollographql/router/pull/1487

Removed deprecated type aliases (PR #1487)

A few versions ago, some types were moved from the crate root to a new graphql module. To help the transition, type aliases were left at the old location with a deprecation warning. These aliases are now removed and remaining imports must be changed to the new locations:

-use apollo_router::Error;
-use apollo_router::Request;
-use apollo_router::Response;
+use apollo_router::graphql::Error;
+use apollo_router::graphql::Request;
+use apollo_router::graphql::Response;

Alternatively, import the module with use apollo_router::graphql then use qualified paths such as graphql::Request. This can help disambiguate when multiple types share a name.

By @SimonSapin in https://github.com/apollographql/router/pull/1487

RouterRequest::fake_builder defaults to Content-Type: application/json (PR #1487)

apollo_router::services::RouterRequest has a builder for creating a “fake” request during tests. When no Content-Type header is specified, this builder will now default to application/json. This will help tests where a request goes through mandatory plugins, including CSRF protection, which makes the request be accepted by CSRF protection.

If a test requires a request specifically without a Content-Type header, this default can be removed from a RouterRequest after building it:

let mut router_request = RouterRequest::fake_builder().build();
router_request.originating_request.headers_mut().remove("content-type");

By @SimonSapin in https://github.com/apollographql/router/pull/1487

Plugins return a service to create custom endpoints (Issue #1481)

Rust plugins can implement the Plugin::custom_endpoint trait method to handle non-GraphQL HTTP requests.

Previously, the return type of this method was Option<apollo_router::plugin::Handler>, where a Handler could be created with:

impl Handler {
    pub fn new(service: tower::util::BoxService<
        apollo_router::http_ext::Request<bytes::Bytes>, 
        apollo_router::http_ext::Response<bytes::Bytes>, 
        tower::BoxError
    >) -> Self {/* … */}
}

Handler has been removed from the public API and plugins now return a BoxService directly. Additionally, the type for HTTP request and response bodies was changed from bytes::Bytes to hyper::Body which is more flexible and is compatible with streams (which are necessary in future versions of the Router).

The changes needed if using custom endpoints are:

• Replace Handler::new(service) with service
• To read the full request body, use hyper::body::to_bytes or hyper::body::aggregate.
• A response Body can be created through conversion traits from various types. For example: "string".into()

By @SimonSapin in https://github.com/apollographql/router/pull/1533

🚀 Features

rhai logging functions now accept Dynamic parameters (PR #1521)

Prior to this change, rhai logging functions worked with string parameters. This change means that any valid rhai object may now be passed as a logging parameter.

By @garypen

Reduce initial memory footprint by lazily populating introspection query cache (Issue #1517)

In an early alpha release of the Router, we only executed certain "known" introspection queries because of prior technical constraints that prohibited us from doing something more flexible. Because the set of introspection queries was "known", it made sense to cache them.

As of https://github.com/apollographql/router/pull/802, this special-casing is (thankfully) no longer necessary and we no longer need to know (and constrain!) the introspection queries that the Router supports.

We could have kept caching those "known" queries, however we were finding that the resulting cache size was quite large and making the Router's minimum memory footprint larger than need be since we were caching many introspection results which the Router instance would never encounter.

This change removes the cache entirely and allows introspection queries served by the Router to merely be lazily calculated and cached on-demand, thereby reducing the initial memory footprint. Disabling introspection entirely will prevent any use of this cache since no introspection will be possible.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1517

Expose query plan in extensions of GraphQL response (experimental) (PR #1470)

When enabled in configuration, it is now possible to expose the query plan in the GraphQL response extensions. This is only experimental at the moment, and we plan to integrate it into an upcoming version of Apollo Studio. Currently, no documentation is available.

By @bnjjj in https://github.com/apollographql/router/pull/1470

Add support of global rate limit and timeout. PR #1347

Additions to the traffic shaping plugin:

• Global rate limit - If you want to rate limit requests to subgraphs or to the router itself.
• Timeout: - Set a timeout to subgraphs and router requests.

traffic_shaping:
  router: # Rules applied to requests from clients to the router
    global_rate_limit: # Accept a maximum of 10 requests per 5 secs. Excess requests must be rejected.
      capacity: 10
      interval: 5s # Value in milliseconds must be greater than 0 and less than the max of a 64-bit integer (2^64-1).
    timeout: 50s # If a request to the router takes more than 50secs then cancel the request (30 sec by default)
  subgraphs: # Rules applied to requests from the router to individual subgraphs
    products:
      global_rate_limit: # Accept a maximum of 10 requests per 5 secs from the router. Excess requests must be rejected.
        capacity: 10
        interval: 5s # Value in milliseconds must be greater than 0 and less than the max of a 64-bit integer (2^64-1).
      timeout: 50s # If a request to the subgraph 'products' takes more than 50secs then cancel the request (30 sec by default)

By @bnjjj in https://github.com/apollographql/router/pull/1347

Explicit shutdown for RouterHttpServer handle (PR #1487)

If you explicitly create a RouterHttpServer handle, dropping it while the server is running instructs the server shut down gracefuly. However with the handle dropped, there is no way to wait for shutdown to end or check that it went without error. Instead, the new shutdown async method can be called explicitly to obtain a Result:

 use RouterHttpServer;
 let server = RouterHttpServer::builder().schema("schema").start();
 // …
-drop(server);
+server.shutdown().await.unwrap(); 

By @SimonSapin in https://github.com/apollographql/router/pull/1487

Added apollo_router::TestHarness (PR #1487)

This is a builder for the part of an Apollo Router that handles GraphQL requests, as a tower::Service. This allows tests, benchmarks, etc to manipulate request and response objects in memory without going over the network. See the API documentation for an example. (It can be built with cargo doc --open.)

By @SimonSapin in https://github.com/apollographql/router/pull/1487

Introduce map_deferred_response method for deferred responses (PR #1501)

The map_deferred_response method is now available for the router service and execution service in Rhai. When using the @defer directive, we get the data in a serie of graphql responses. The first one is available with the map_response method, where the HTTP headers and the response body can be modified. The following responses are available through map_deferred_response, which only has access to the response body.

By @geal in https://github.com/apollographql/router/pull/1501

🐛 Fixes

Return HTTP status code 400 when variables validation fails (Issue #1403)

Failure to validate out-of-band variables against both the query and the corresponding schema will now result in an HTTP status code of 400 being returned to the client. This instructs the client not to bother retrying without changing something about what it previously sent since subsequent retries would just fail validation again and again.

By @o0Ignition0o

Include usage reporting data in the context even when the query plan has been cached (#1559)

Include usage reporting data in the context even when the query plan has been cached when calling CachingQueryPlanner.

By @bnjjj in https://github.com/apollographql/router/pull/1559

Accept SIGTERM as shutdown signal (PR #1497)

This will make containers stop faster as they will not have to wait until a SIGKILL to stop the router (which generally comes several seconds later).

By @Geal in https://github.com/apollographql/router/pull/1497

Set the response path for deferred responses (PR #1529)

Some GraphQL clients rely on the response path to find out which fragment created a deferred response, and generate code that checks the type of the value at that path. Previously the router was generating a value that starts at the root for every deferred response. Now it checks the path returned by the query plan execution and creates a response for each value that matches that path. In particular, for deferred fragments on an object inside an array, it will create a separate response for each element of the array.

By @Geal in https://github.com/apollographql/router/pull/1529

Activate defer support in introspection (PR #1557)

Introspection queries will now see the @defer directive if it was activated in the configuration file.

By @Geal in https://github.com/apollographql/router/pull/1557

Support the incremental response field (PR #1551)

Recent changes in the @defer specification now mandate that the deferred responses are transmitted as an array in the new incremental field of the JSON response.

By @Geal in https://github.com/apollographql/router/pull/1551

🛠 Maintenance

These are generally internal improvements to the Router repository on GitHub.

Display licenses.html diff in CI if the check failed (#1524)

The CI check that ensures that the license.html file is up to date now displays what has changed when the file is out of sync.

By @o0Ignition0o

🚀 Features

Helm: Rhai script and Istio virtualservice support (#1478)

You can now pass a Rhai script file to the helm chart. You can also provide an Istio VirtualService configuration, as well as custom Egress rules. Head over to the helm chart default values to get started.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1478

📚 Documentation

Clarify path parameter usage (PR #1473)

Add an inline example of path parameter usage to the section of the docs explaining that you cannot specify a wildcard in the middle of a path.

By @EverlastingBugstopper in https://github.com/apollographql/router/pull/1473

⚠️ SECURITY ⚠️

Landing page: Remove unsanitized example input

The default landing page contained HTML to display a sample curl command which is made visible if the full landing page bundle could not be fetched from Apollo's CDN. The server's URL is directly interpolated into this command inside the browser from window.location.href. On some older browsers such as IE11, this value is not URI-encoded. On such browsers, opening a malicious URL pointing at an Apollo Router could cause execution of attacker-controlled JavaScript. In this release, the fallback page does not display a curl command.

More details are available at the security advisory.

By @o0Ignition0o

Full Changelog: https://github.com/apollographql/router/compare/v0.15.0...v0.15.1

❗ BREAKING ❗

CORS: Deprecate newly-added allow_any_header option and return to previous behavior (PR https://github.com/apollographql/router/pull/1480)

We've re-considered and reverted changes we shipped in the last release with regards to how we handle the Access-Control-Request-Headers request header and its corresponding Access-Control-Allow-Headers response header. We've reverted to the previous releases' behavior, including the removal of the recently-added allow_any_header option.

The previous default behavior was to reflect the client's Access-Control-Request-Headers request header values back in the Access-Control-Allow-Headers response header. This previous behavior is in fact a common default behavior in other CORS libraries as well, including the cors Node.js package and we think it's worth keeping as it was previously, rather than requiring users to specify allow_any_header for the majority of use cases. We believe this to be a safe and secure default that is also more user-friendly.

It is not typically necessary to change this default behavior, but if you wish to allow a more specific set of headers, you can disable the default header reflection and specify a list of headers using the allow_headers option, which will allow only those headers in negotiating a response:

server:
  cors:
    allow_any_origin: true
    # Including this `allow_headers` isn't typically necessary (can be removed) but
    # will *restrict* the permitted Access-Control-Allow-Headers response values.
    allow_headers:
      - Content-Type
      - Authorization
      - x-my-custom-header

By @o0Ignition0o in https://github.com/apollographql/router/pull/1480

Reference-counting for the schema string given to plugins (PR https://github.com/apollographql/router/pull/1462)

The type of the supergraph_sdl field of the apollo_router::plugin::PluginInit struct was changed from String to Arc<String>. This reduces the number of copies of this string we keep in memory, as schemas can get large.

By @SimonSapin in https://github.com/apollographql/router/pull/1462

🐛 Fixes

Update span attributes to be compliant with the opentelemetry for GraphQL specs (PR https://github.com/apollographql/router/pull/1449)

Change attribute name query to graphql.document and operation_name to graphql.operation.name in spans.

By @bnjjj in https://github.com/apollographql/router/pull/1449

Configuration handling enhancements (PR https://github.com/apollographql/router/pull/1454)

Router config handling now:

• Allows completely empty configuration without error.
• Prevents unknown tags at the root of the configuration from being silently ignored.

By @BrynCooke in https://github.com/apollographql/router/pull/1454

📚 Documentation

CORS: Fix trailing slashes, and display defaults (PR https://github.com/apollographql/router/pull/1471)

The CORS documentation now displays a valid origins configuration (without trailing slash!), and the full configuration section displays its default settings.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1471

Add helm OCI example (PR https://github.com/apollographql/router/pull/1457)

Update existing filesystem based example to illustrate how to do the same thing using our OCI stored helm chart.

By @garypen in https://github.com/apollographql/router/pull/1457

❗ BREAKING ❗

Regex allow_any_origin behavior changed (PR #1444)

Setting allow_any_origin to true in the router configuration would previously automatically mirror the requested headers. If you relied on this behavior, you now also need to set allow_any_header to true, as explained in the CORS documentation.

server:
  cors:
    allow_any_origin: true
    allow_any_header: true # mirror client's headers

The default CORS headers configuration of the router allows content-type, apollographql-client-version and apollographql-client-name.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1444

Modify the plugin new method to pass an initialisation structure (PR #1446)

This change alters the new method for plugins to pass a PluginInit struct.

We are making this change so that we can pass more information during plugin startup. The first change is that in addition to passing the plugin configuration, we are now also passing the router supergraph sdl (Schema Definition Language) as a string.

There is a new example (supergraph_sdl) which illustrates how to use this new capability.

By @garypen in https://github.com/apollographql/router/pull/1446

Remove the generic stream type from RouterResponse and ExecutionResponse (PR #1420)

This generic type complicates the API with limited benefit because we use BoxStream everywhere in plugins:

• RouterResponse<BoxStream<'static, Response>> -> RouterResponse
• ExecutionResponse<BoxStream<'static, Response>> -> ExecutionResponse

By @Geal in https://github.com/apollographql/router/pull/1420

Remove the HTTP request from QueryPlannerRequest (PR #1439)

The content of QueryPlannerRequest is used as argument to the query planner and as a cache key, so it should not change depending on the variables or HTTP headers.

By @Geal in https://github.com/apollographql/router/pull/1439

Change PluggableRouterServiceBuilder methods (PR #1437)

with_naive_introspection and with_defer_support where two parameter-less methods of this builder that enabled boolean configuration flags. They have been removed and replaced by with_configuration which takes Arc<apollo_router::Configuration>. A Configuration value can be created from various formats by deserializing with serde. The removed methods correspond to server.introspection and server.experimental_defer_support configuration keys respectively.

By @SimonSapin in https://github.com/apollographql/router/pull/1437

Changes to the SchemaKind enum (PR #1437)

The Instance variant is replaced with a variant named String that contains… a String instead of Box<apollo_router::Schema>, so you no longer need to parse the schema before giving it to the router. Similarly, the Stream variant now contains a stream of Strings instead of a stream of already-parsed Schemas.

By @SimonSapin in https://github.com/apollographql/router/pull/1437

Schema no longer implements FromStr (PR #1437)

This means that str.parse::<apollo_router::Schema>() is no longer available. If you still need a parsed Schema (see above), use apollo_router::Schema(str, &configuration) instead. To use the default apollo_router::Configuration you can call apollo_router::Schema(str, &Default::default()).

By @SimonSapin in https://github.com/apollographql/router/pull/1437

🚀 Features

Publish helm chart to OCI registry (PR #1447)

When we make a release, publish our helm chart to the same OCI registry that we use for our docker images.

For more information about using OCI registries with helm, see the helm documentation.

By @garypen in https://github.com/apollographql/router/pull/1447

Configure Regex based CORS rules (PR #1444)

The router now supports regex based CORS rules, as explained in the docs It also supports the allow_any_header setting that will mirror client's requested headers.

server:
  cors:
    match_origins:
      - "https://([a-z0-9]+[.])*api[.]example[.]com" # any host that uses https and ends with .api.example.com
    allow_any_header: true # mirror client's headers

The default CORS headers configuration of the router allows content-type, apollographql-client-version and apollographql-client-name.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1444

Add support of error section in telemetry to add custom attributes (PR #1443)

The telemetry is now able to hook at the error stage if router or a subgraph is returning an error. Here is an example of configuration:

telemetry:
  metrics:
    prometheus:
      enabled: true
    common:
      attributes:
        subgraph:
          all:
            errors: # Only works if it's a valid GraphQL error
              include_messages: true # Will include the error message in a message attribute
              extensions: # Include extension data
                - name: subgraph_error_extended_type # Name of the attribute
                  path: .type # JSON query path to fetch data from extensions

By @bnjjj in https://github.com/apollographql/router/pull/1443

Experimental support for the @defer directive (PR #1182)

The router can now understand the @defer directive, used to tag parts of a query so the response is split into multiple parts that are sent one by one.

:warning: this is still experimental and not fit for production use yet

To activate it, add this option to the configuration file:

server:
  experimental_defer_support: true

By @Geal in https://github.com/apollographql/router/pull/1182

Rewrite the caching API (PR #1281)

This introduces a new asynchronous caching API that opens the way to multi level caching (in memory and database). The API revolves around an Entry structure that allows query deduplication and lets the client decide how to generate the value to cache, instead of a complicated delegate system inside the cache.

By @Geal in https://github.com/apollographql/router/pull/1281

🐛 Fixes

Update serialization format for telemetry.tracing.otlp.grpc.metadata (PR #1391)

The metadata format now uses IndexMap<String, Vec<String>>.

By @me-diru in https://github.com/apollographql/router/pull/1391

Update the scaffold template so it targets router v0.14.0 (PR #1431)

The cargo scaffold template will target the latest version of the router.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1248

Selection merging on non-object field aliases (PR #1406)

Fixed a bug where merging aliased fields would sometimes put nulls instead of expected values.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1432

A Rhai error instead of a Rust panic ([PR #1414 https://github.com/apollographql/router/pull/1414))

In Rhai plugins, accessors that mutate the originating request are not available when in the subgraph phase. Previously, trying to mutate anyway would cause a Rust panic. This has been changed to a Rhai error instead.

By @SimonSapin in https://github.com/apollographql/router/pull/1414

Optimizations (PR #1423)

• Do not clone the client request during query plan execution
• Do not clone the usage reporting
• Avoid path allocations when iterating over JSON values

The benchmarks show that this change brings a 23% gain in requests per second compared to the main branch.

By @Geal in https://github.com/apollographql/router/pull/1423

do not perform nested fetches if the parent one returned null (PR #1332

In a query of the form:

mutation {
	mutationA {
		mutationB
	}
}

If mutationA returned null, we should not execute mutationB.

By @Ty3uK in https://github.com/apollographql/router/pull/1332

🛠 Maintenance

📚 Documentation

Updates wording and formatting of README.md

By @EverlastingBugstopper in https://github.com/apollographql/router/pull/1445

What's Changed

• CI: Upgrade the macOS image version by @SimonSapin in https://github.com/apollographql/router/pull/1418
• Remove the generic stream type from RouterResponse and ExecutionResponse by @Geal in https://github.com/apollographql/router/pull/1420
• CI: run cargo test for all crates in the workspace by @SimonSapin in https://github.com/apollographql/router/pull/1422
• Simplify boilerplate in the Rhai plugin by @SimonSapin in https://github.com/apollographql/router/pull/1414
• Revert a dbg! that I forgot to remove in #1414 by @SimonSapin in https://github.com/apollographql/router/pull/1424
• Remove experimental for references to rhai by @garypen in https://github.com/apollographql/router/pull/1416
• Fix rustdoc warnings and deny them in cargo xtask lint by @SimonSapin in https://github.com/apollographql/router/pull/1421
• Upgrade moka and crossbeam-* dependencies by @SimonSapin in https://github.com/apollographql/router/pull/1419
• rewrite the caching API by @Geal in https://github.com/apollographql/router/pull/1281
• small optimizations by @Geal in https://github.com/apollographql/router/pull/1423
• fix: update scaffold to use 0.12.0 by @o0Ignition0o in https://github.com/apollographql/router/pull/1431
• Defer: query plan changes by @Geal in https://github.com/apollographql/router/pull/1182
• chore(deps): update dependency otel/opentelemetry-collector to v0.56.0 by @renovate in https://github.com/apollographql/router/pull/1429
• remove the HTTP request from QueryPlannerRequest by @Geal in https://github.com/apollographql/router/pull/1439
• Fix: Selection merge on non object field alias by @o0Ignition0o in https://github.com/apollographql/router/pull/1432
• chore: Update NEXT_CHANGELOG.md formatting. by @abernix in https://github.com/apollographql/router/pull/1442
• docs: updates some readme wording by @EverlastingBugstopper in https://github.com/apollographql/router/pull/1445
• fix: update serialization format by @me-diru in https://github.com/apollographql/router/pull/1391
• plugin new now takes a PluginInit struct (generic over config) by @garypen in https://github.com/apollographql/router/pull/1446
• do not perform nested fetches if the parent one returned null by @Ty3uK in https://github.com/apollographql/router/pull/1332
• feat(telemetry): add error section in custom attributes configuration by @bnjjj in https://github.com/apollographql/router/pull/1443
• Configure Regex based CORS rules by @o0Ignition0o in https://github.com/apollographql/router/pull/1444
• update buildstructor to 0.4.1 and add docs by @garypen in https://github.com/apollographql/router/pull/1451
• Introspection support for includeDeprecated, isDeprecated, and deprecationReason by @SimonSapin in https://github.com/apollographql/router/pull/1452
• helm repo for chart installation (#913) by @garypen in https://github.com/apollographql/router/pull/1447
• Add server.experimental_parser_recursion_limit configuration by @SimonSapin in https://github.com/apollographql/router/pull/1437
• release: v0.14.0 by @garypen in https://github.com/apollographql/router/pull/1455

New Contributors

• @EverlastingBugstopper made their first contribution in https://github.com/apollographql/router/pull/1445
• @me-diru made their first contribution in https://github.com/apollographql/router/pull/1391
• @Ty3uK made their first contribution in https://github.com/apollographql/router/pull/1332

Full Changelog: https://github.com/apollographql/router/compare/v0.12.0...v0.14.0

:warning: This is a test release, not meant for general use

How to test @defer support in the router Add this to the configuration file:

server:
  experimental_defer_support: true

:warning: This is a test release, not meant for general use

How to test @defer support in the router Add this to the configuration file:

server:
  experimental_defer_support: true

Add this to the supergraph schema:

directive @defer(
  label: String
  if: Boolean
) on FRAGMENT_SPREAD | INLINE_FRAGMENT

:warning: this is a test release, not meant for general use

:warning: this is a test release, not meant for general use

[0.12.0] - 2022-08-18

❗ BREAKING ❗

Move experimental.rhai out of experimental PR #1365

You will need to update your YAML configuration file to use the correct name for rhai plugin.

- plugins:
-   experimental.rhai:
-     filename: /path/to/myfile.rhai
+ rhai:
+   scripts: /path/to/directory/containing/all/my/rhai/scripts (./scripts by default)
+   main: <name of main script to execute> (main.rhai by default)

You can now modularise your rhai code. Rather than specifying a path to a filename containing your rhai code, the rhai plugin will now attempt to execute the script specified via main. If modules are imported, the rhai plugin will search for those modules in the scripts directory. for more details about how rhai makes use of modules, look at the rhai documentation.

The simplest migration will be to set scripts to the directory containing your myfile.rhai and to rename your myfile.rhai to main.rhai.

By @garypen in https://github.com/apollographql/router/pull/1365

🐛 Fixes

The opentelemetry-otlp crate needs a http-client feature PR #1392

The opentelemetry-otlp crate only checks at runtime if a HTTP client was added through cargo features. We now use reqwest for that.

By @geal in https://github.com/apollographql/router/pull/1392

Expose the custom endpoints from RouterServiceFactory (PR #1402)

Plugin HTTP endpoints registration was broken during the Tower refactoring. We now make sure that the list of endpoints is generated from the RouterServiceFactory instance.

By @geal in https://github.com/apollographql/router/pull/1402

🛠 Maintenance

Dependency updates PR #1389 PR #1394 PR #1395

Dependency updates were blocked for some time due to incompatibilities:

• #1389: the router-bridge crate needed a new version of deno_core in its workspace that would not fix the version of once_cell. Now that it is done we can update once_cell in the router
• #1395: clap at version 3.2 changed the way values are extracted from matched arguments, which resulted in panics. This is now fixed and we can update clap in the router and related crates
• #1394: broader dependency updates now that everything is locked
• #1410: revert tracing update that caused two telemetry tests to fail (the router binary is not affected)

By @Geal in https://github.com/apollographql/router/pull/1389 https://github.com/apollographql/router/pull/1394 https://github.com/apollographql/router/pull/1395 and @o0Ignition0o in https://github.com/apollographql/router/pull/1410

❗ BREAKING ❗

Relax plugin api mutability PR #1340 PR #1289

the Plugin::*_service() methods were taking a &mut self as argument, but since they work like a tower Layer, they can use &self instead. This change then allows us to move from Buffer to service factories for the query planner, execution and subgraph services.

Services are now created on the fly at session creation, so if any state must be shared between executions, it should be stored in an Arc<Mutex<_>> in the plugin and cloned into the new service in the Plugin::*_service() methods.

By @Geal in https://github.com/apollographql/router/pull/1340 https://github.com/apollographql/router/pull/1289

🚀 Features

Add support to add custom resources on metrics. PR #1354

Resources are almost like attributes but more global. They are directly configured on the metrics exporter which means you'll always have these resources on each of your metrics. This functionality can be used to, for example, apply a service.name to metrics to make them easier to find in larger infrastructure, as demonstrated here:

telemetry:
  metrics:
    common:
      resources:
        # Set the service name to easily find metrics related to the apollo-router in your metrics dashboards
        service.name: "apollo-router"

By @bnjjj in https://github.com/apollographql/router/pull/1354

🐛 Fixes

Fix fragment on interface without typename PR #1371

When the subgraph doesn't return the __typename and the type condition of a fragment is an interface, we should return the values if the entity implements the interface

By @bnjjj in https://github.com/apollographql/router/pull/1371

Fix detection of an introspection query PR #1370

A query that only contains __typename at the root will now special-cased as merely an introspection query and will bypass more complex query-planner execution (its value will just be Query).

By @bnjjj in https://github.com/apollographql/router/pull/1370

Accept nullable list as input PR #1363

Do not throw a validation error when you give null for an input variable of type [Int!].

By @bnjjj in https://github.com/apollographql/router/pull/1363

🛠 Maintenance

Replace Buffers of tower services with service factories (PR #1289 PR #1355)

Tower services should be used by creating a new service instance for each new session instead of going through a Buffer.

By @Geal in https://github.com/apollographql/router/pull/1289 https://github.com/apollographql/router/pull/1355

Execute the query plan's first response directly (PR #1357)

The query plan was previously executed in a spawned task to prepare for the @defer implementation, but we can actually generate the first response right inside the same future.

By @Geal in https://github.com/apollographql/router/pull/1357

Remove deprecated failure crate from the dependency tree PR #1373

This should fix automated reports about GHSA-jq66-xh47-j9f3.

By @yanns in https://github.com/apollographql/router/pull/1373

Render embedded Sandbox instead of landing page (PR #1369)

Open the router URL in a browser and start querying the router from the Apollo Sandbox.

By @mayakoneval in https://github.com/apollographql/router/pull/1369

📚 Documentation

Various documentation edits (PR #1329)

By @StephenBarlow in https://github.com/apollographql/router/pull/1329

❗ BREAKING ❗

Change configuration for custom attributes for metrics in telemetry plugin (PR #1300)

To create a distinction between subgraph metrics and router metrics, a distiction has been made in the configuration. Therefore, a new configuration section called router has been introduced and Router-specific properties are now listed there, as seen here:

telemetry:
  metrics:
    common:
      attributes:
-        static:
-          - name: "version"
-            value: "v1.0.0"
-        from_headers:
-          - named: "content-type"
-            rename: "payload_type"
-            default: "application/json"
-          - named: "x-custom-header-to-add"
+        router:
+          static:
+            - name: "version"
+              value: "v1.0.0"
+          request:
+            header:
+              - named: "content-type"
+                rename: "payload_type"
+                default: "application/json"
+              - named: "x-custom-header-to-add"

By @bnjjj in https://github.com/apollographql/router/pull/1300

Rename http_compat to http_ext (PR #1291)

The module provides extensions to the http crate which are specific to the way we use that crate in the router. This change also cleans up the provided extensions and fixes a few potential sources of error (by removing them) such as the Request::mock() function.

By @garypen in https://github.com/apollographql/router/pull/1291

Rework the entire public API structure (PR #1216, PR #1242, PR #1267, PR #1277, PR #1303)

• Many items have been removed from the public API and made private. If you were relying on these previously-public methods and find that they are no longer available, please open an issue with your use case so we can consider how we want to re-introduce them.

• Many re-exports have been removed. Most notably from the crate root and all of the prelude modules. These items now need to be imported from another location instead, most often the module that defines them.

• Some items have moved and need to be imported from a new location.

For example, here are the changes made to examples/add-timestamp-header/src/main.rs:

-use apollo_router::{plugin::utils, Plugin, RouterRequest, RouterResponse};
+use apollo_router::plugin::test;
+use apollo_router::plugin::Plugin;
+use apollo_router::services::{RouterRequest, RouterResponse};

-let mut mock = utils::test::MockRouterService::new();
+let mut mock = test::MockRouterService::new();

-if let apollo_router::ResponseBody::GraphQL(response) =
+if let apollo_router::services::ResponseBody::GraphQL(response) =
     service_response.next_response().await.unwrap()
 {

If you're unsure where a given item needs to be imported from when porting code, unfold the listing below and use your browser's search function (CTRL+F or ⌘+F).

use apollo_router::ApolloRouter;
use apollo_router::Configuration;
use apollo_router::ConfigurationKind;
use apollo_router::Context;
use apollo_router::Error;
use apollo_router::Executable;
use apollo_router::Request;
use apollo_router::Response;
use apollo_router::Schema;
use apollo_router::SchemaKind;
use apollo_router::ShutdownKind;
use apollo_router::error::CacheResolverError;
use apollo_router::error::FetchError;
use apollo_router::error::JsonExtError;
use apollo_router::error::Location;
use apollo_router::error::ParseErrors;
use apollo_router::error::PlannerErrors;
use apollo_router::error::QueryPlannerError;
use apollo_router::error::SchemaError;
use apollo_router::error::ServiceBuildError;
use apollo_router::error::SpecError;
use apollo_router::graphql::Error;
use apollo_router::graphql::NewErrorBuilder;
use apollo_router::graphql::Request;
use apollo_router::graphql::Response;
use apollo_router::json_ext::Object;
use apollo_router::json_ext::Path;
use apollo_router::json_ext::PathElement;
use apollo_router::layers::ServiceBuilderExt;
use apollo_router::layers::ServiceExt;
use apollo_router::layers::async_checkpoint::AsyncCheckpointLayer;
use apollo_router::layers::async_checkpoint::AsyncCheckpointService;
use apollo_router::layers::cache::CachingLayer;
use apollo_router::layers::cache::CachingService;
use apollo_router::layers::instrument::InstrumentLayer;
use apollo_router::layers::instrument::InstrumentService;
use apollo_router::layers::map_future_with_context::MapFutureWithContextLayer;
use apollo_router::layers::map_future_with_context::MapFutureWithContextService;
use apollo_router::layers::sync_checkpoint::CheckpointLayer;
use apollo_router::layers::sync_checkpoint::CheckpointService;
use apollo_router::main;
use apollo_router::mock_service;
use apollo_router::plugin::DynPlugin;
use apollo_router::plugin::Handler;
use apollo_router::plugin::Plugin;
use apollo_router::plugin::PluginFactory;
use apollo_router::plugin::plugins;
use apollo_router::plugin::register_plugin;
use apollo_router::plugin::serde::deserialize_header_name;
use apollo_router::plugin::serde::deserialize_header_value;
use apollo_router::plugin::serde::deserialize_option_header_name;
use apollo_router::plugin::serde::deserialize_option_header_value;
use apollo_router::plugin::serde::deserialize_regex;
use apollo_router::plugin::test::IntoSchema;
use apollo_router::plugin::test::MockExecutionService;
use apollo_router::plugin::test::MockQueryPlanningService;
use apollo_router::plugin::test::MockRouterService;
use apollo_router::plugin::test::MockSubgraph;
use apollo_router::plugin::test::MockSubgraphService;
use apollo_router::plugin::test::NewPluginTestHarnessBuilder;
use apollo_router::plugin::test::PluginTestHarness;
use apollo_router::plugins::csrf::CSRFConfig;
use apollo_router::plugins::csrf::Csrf;
use apollo_router::plugins::rhai::Conf;
use apollo_router::plugins::rhai::Rhai;
use apollo_router::plugins::telemetry::ROUTER_SPAN_NAME;
use apollo_router::plugins::telemetry::Telemetry;
use apollo_router::plugins::telemetry::apollo::Config;
use apollo_router::plugins::telemetry::config::AttributeArray;
use apollo_router::plugins::telemetry::config::AttributeValue;
use apollo_router::plugins::telemetry::config::Conf;
use apollo_router::plugins::telemetry::config::GenericWith;
use apollo_router::plugins::telemetry::config::Metrics;
use apollo_router::plugins::telemetry::config::MetricsCommon;
use apollo_router::plugins::telemetry::config::Propagation;
use apollo_router::plugins::telemetry::config::Sampler;
use apollo_router::plugins::telemetry::config::SamplerOption;
use apollo_router::plugins::telemetry::config::Trace;
use apollo_router::plugins::telemetry::config::Tracing;
use apollo_router::query_planner::OperationKind;
use apollo_router::query_planner::QueryPlan;
use apollo_router::query_planner::QueryPlanOptions;
use apollo_router::register_plugin;
use apollo_router::services::ErrorNewExecutionResponseBuilder;
use apollo_router::services::ErrorNewQueryPlannerResponseBuilder;
use apollo_router::services::ErrorNewRouterResponseBuilder;
use apollo_router::services::ErrorNewSubgraphResponseBuilder;
use apollo_router::services::ExecutionRequest;
use apollo_router::services::ExecutionResponse;
use apollo_router::services::ExecutionService;
use apollo_router::services::FakeNewExecutionRequestBuilder;
use apollo_router::services::FakeNewExecutionResponseBuilder;
use apollo_router::services::FakeNewRouterRequestBuilder;
use apollo_router::services::FakeNewRouterResponseBuilder;
use apollo_router::services::FakeNewSubgraphRequestBuilder;
use apollo_router::services::FakeNewSubgraphResponseBuilder;
use apollo_router::services::NewExecutionRequestBuilder;
use apollo_router::services::NewExecutionResponseBuilder;
use apollo_router::services::NewExecutionServiceBuilder;
use apollo_router::services::NewQueryPlannerRequestBuilder;
use apollo_router::services::NewQueryPlannerResponseBuilder;
use apollo_router::services::NewRouterRequestBuilder;
use apollo_router::services::NewRouterResponseBuilder;
use apollo_router::services::NewRouterServiceBuilder;
use apollo_router::services::NewSubgraphRequestBuilder;
use apollo_router::services::NewSubgraphResponseBuilder;
use apollo_router::services::PluggableRouterServiceBuilder;
use apollo_router::services::QueryPlannerContent;
use apollo_router::services::QueryPlannerRequest;
use apollo_router::services::QueryPlannerResponse;
use apollo_router::services::ResponseBody;
use apollo_router::services::RouterRequest;
use apollo_router::services::RouterResponse;
use apollo_router::services::RouterService;
use apollo_router::services::SubgraphRequest;
use apollo_router::services::SubgraphResponse;
use apollo_router::services::SubgraphService;
use apollo_router::services::http_ext::FakeNewRequestBuilder;
use apollo_router::services::http_ext::IntoHeaderName;
use apollo_router::services::http_ext::IntoHeaderValue;
use apollo_router::services::http_ext::NewRequestBuilder;
use apollo_router::services::http_ext::Request;
use apollo_router::services::http_ext::Response;
use apollo_router::subscriber::RouterSubscriber;
use apollo_router::subscriber::is_global_subscriber_set;
use apollo_router::subscriber::replace_layer;
use apollo_router::subscriber::set_global_subscriber;

By @SimonSapin

Entry point improvements (PR #1227) (PR #1234) (PR #1239) (PR #1263)

The interfaces around the entry point have been improved for naming consistency and to enable reuse when customization is required. Most users will continue to use:

apollo_router::main()

However, if you want to specify extra customization to configuration/schema/shutdown then you may use Executable::builder() to override behavior.

use apollo_router::Executable;
Executable::builder()
  .router_builder_fn(|configuration, schema| ...) // Optional
  .start().await?

Migration tips:

• Calls to ApolloRouterBuilder::default() should be migrated to ApolloRouter::builder.
• FederatedServerHandle has been renamed to ApolloRouterHandle.
• The ability to supply your own RouterServiceFactory has been removed.
• StateListener. This made the internal state machine unnecessarily complex. listen_address() remains on ApolloRouterHandle.
• FederatedServerHandle::shutdown() has been removed. Instead, dropping ApolloRouterHandle will cause the router to shutdown.
• FederatedServerHandle::ready() has been renamed to FederatedServerHandle::listen_address(), it will return the address when the router is ready to serve requests.
• FederatedServerError has been renamed to ApolloRouterError.
• main_rt should be migrated to Executable::builder()

By @bryncooke in https://github.com/apollographql/router/pull/1227 https://github.com/apollographql/router/pull/1234 https://github.com/apollographql/router/pull/1239 https://github.com/apollographql/router/pull/1263

Non-GraphQL response body variants removed from RouterResponse (PR #1307, PR #1328)

The ResponseBody enum has been removed. It had variants for GraphQL and non-GraphQL responses.

It was used:

• In RouterResponse which now uses apollo_router::graphql::Response instead
• In Handler for plugin custom endpoints which now uses bytes::Bytes instead

Various type signatures will need changes such as:

- RouterResponse<BoxStream<'static, ResponseBody>>
+ RouterResponse<BoxStream<'static, graphql::Response>>

Necessary code changes might look like:

- return ResponseBody::GraphQL(response);
+ return response;

- if let ResponseBody::GraphQL(graphql_response) = res {
-     assert_eq!(&graphql_response.errors[0], expected_error);
- } else {
-     panic!("expected a graphql response");
- }
+ assert_eq!(&res.errors[0], expected_error);

By @SimonSapin

Fixed control flow in helm chart for volume mounts & environment variables (PR #1283)

You will now be able to actually use the helm chart without being on a managed graph.

By @LockedThread in https://github.com/apollographql/router/pull/1283

Fail when unknown fields are encountered in configuration PR #1278

Now if you add an unknown configuration field at the root of your configuration file it will return an error, rather than silently continuing with un-recognized options.

By @bnjjj in https://github.com/apollographql/router/pull/1278

🚀 Features

Allow custom subgraph-specific attributes to be added to emitted metrics PR #1300

Previously, it was only possible to add custom attributes from headers which the router received from the external GraphQL client. Now, you are able to add custom attributes coming from both the headers and the body of either the Router's or the Subgraph's router request or response. You also have the ability to add an attributes from the context. For example:

telemetry:
  metrics:
    common:
      attributes:
        router:
          static:
            - name: "version"
              value: "v1.0.0"
          request:
            header:
              - named: "content-type"
                rename: "payload_type"
                default: "application/json"
              - named: "x-custom-header-to-add"
          response:
            body:
              # Take element from the Router's JSON response body router located at a specific path
              - path: .errors[0].extensions.status
                name: error_from_body
          context:
            # Take element from the context within plugin chains and add it in attributes
            - named: my_key
        subgraph:
          all:
            static:
              # Always insert this static value on all metrics for ALL Subgraphs
              - name: kind
                value: subgraph_request
          subgraphs:
            # Apply these only for the SPECIFIC subgraph named `my_subgraph_name`
            my_subgraph_name:
              request:
                header:
                  - named: "x-custom-header"
                body:
                  # Take element from the request body of the router located at this path (here it's the query)
                  - path: .query
                    name: query
                    default: UNKNOWN

By @bnjjj in https://github.com/apollographql/router/pull/1300

Add support for modifying variables from a plugin PR #1257

Previously, it was not possible to modify variables in a Request from a plugin. This is now supported via both Rust and Rhai plugins.

By @garypen in https://github.com/apollographql/router/pull/1257

🐛 Fixes

Extend fix for compression support to include the DIY Dockerfiles (PR #1352)

Compression support is now shown in the DIY Dockerfiles, as a followup to PR #1279.

By @garypen in https://github.com/apollographql/router/pull/1352

Improve URL parsing in endpoint configuration (PR #1341)

Specifying an endpoint in this form '127.0.0.1:431' resulted in an error: 'relative URL without a base'. The fix enhances the URL parsing logic to check for these errors and re-parses with a default scheme 'http://' so that parsing succeeds.

By @garypen in https://github.com/apollographql/router/pull/1341

Improve configuration validation and environment expansion (PR #1331)

Environment expansion now covers the entire configuration file, and supports non-string types.

This means that it is now possible to use environment variables in the server section of the YAML configuration, including numeric and boolean fields.

Environment variables will always be shown in their original form within error messages to prevent leakage of secrets.

These changes allow more of the configuration file to be validated via JSON-schema, as previously we just skipped errors where fields contained environment variables.

By @bryncooke in https://github.com/apollographql/router/pull/1331

Fix input coercion for a list (PR #1327)

The router is now following coercion rules for lists in accordance with the GraphQL specification. In particular, this fixes the case when an input type of [Int] with only 1 provided as a value will now be properly coerced to [1].

By @bnjjj in https://github.com/apollographql/router/pull/1327

Returns HTTP 400 Bad Request, rather than a 500, when hitting a query planning error (PR #1321)

A query planning error cannot be retried, so this error code more correctly matches the failure mode and indicates to the client that it should not be retried without changing the request.

By @bnjjj in https://github.com/apollographql/router/pull/1321

Re-enable the subgraph error-redaction functionality (PR #1317)

In a re-factoring the include_subgraph_errors plugin was disabled. This meant that subgraph error handling was not working as intended. This change re-enables it and improves the functionality with additional logging. As part of the fix, the plugin initialization mechanism was improved to ensure that plugins start in the required sequence.

By @garypen in https://github.com/apollographql/router/pull/1317

Restrict static introspection to only __schema and __type (PR #1299)

Queries with selected field names starting with __ are recognized as introspection queries. This includes __schema, __type and __typename. However, __typename is introspection at query time which is different from __schema and __type because two of the later can be answered with queries with empty input variables. This change will restrict introspection to only __schema and __type.

By @dingxiangfei2009 in https://github.com/apollographql/router/pull/1299

Fix plugin scaffolding support (PR #1293)

By @garypen in https://github.com/apollographql/router/pull/1293

Support introspection object types (PR #1240)

Introspection queries can use a set of object types defined in the specification. The query parsing code was not recognizing them, resulting in some introspection queries not working.

By @Geal in https://github.com/apollographql/router/pull/1240

Update the scaffold template so it works with streams (#1247)

Release v0.9.4 changed the way we deal with Response objects, which can now be streams. The scaffold template now generates plugins that are compatible with this new Plugin API.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1248

Fix fragment selection on interfaces (PR #1295)

Fragments type conditions were not being checked correctly on interfaces, resulting in invalid null fields added to the response or valid data being incorrectly null-ified.

By @Geal in https://github.com/apollographql/router/pull/1295

Fix fragment selection on queries (PR #1296)

The schema object can specify objects for queries, mutations or subscriptions that are not named Query, Mutation or Subscription. Response formatting now supports it.

By @Geal in https://github.com/apollographql/router/pull/1296

Fix fragment selection on unions (PR #1346)

Fragments type conditions were not checked correctly on unions, resulting in data being absent.

By @Geal in https://github.com/apollographql/router/pull/1346

Reduce poll_ready calls in query deduplication (PR #1350)

The query deduplication service was making assumptions on the underlying service's behaviour, which could result in subgraph services panicking.

By @Geal in https://github.com/apollographql/router/pull/1350

🛠 Maintenance

chore: Run scaffold tests in CI and xtask only (PR #1345)

Run the scaffold tests in CI and through xtask, to keep a steady feedback loop while developping against cargo test.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1345

Update rhai to latest release (1.8.0) (PR #1337

We had been depending on a pinned git version which had a fix we required. This now updates to the latest release which includes the fix upstream.

By @garypen in https://github.com/apollographql/router/pull/1337

Remove typed-builder (PR #1218)

Migrate all typed-builders code to buildstructor.

By @bryncooke in https://github.com/apollographql/router/pull/1218

❗ BREAKING ❗

Move experimental.traffic_shaping out of experimental PR #1229

You will need to update your YAML configuration file to use the correct name for traffic_shaping plugin.

- plugins:
-   experimental.traffic_shaping:
-     variables_deduplication: true # Enable the variables deduplication optimization
-     all:
-       query_deduplication: true # Enable query deduplication for all subgraphs.
-     subgraphs:
-       products:
-         query_deduplication: false # Disable query deduplication for products.
+ traffic_shaping:
+   variables_deduplication: true # Enable the variables deduplication optimization
+   all:
+     query_deduplication: true # Enable query deduplication for all subgraphs.
+   subgraphs:
+     products:
+       query_deduplication: false # Disable query deduplication for products.

Rhai plugin request.sub_headers renamed to request.subgraph.headers PR #1261

Rhai scripts previously supported the request.sub_headers attribute so that subgraph request headers could be accessed. This is now replaced with an extended interface for subgraph requests:

request.subgraph.headers
request.subgraph.body.query
request.subgraph.body.operation_name
request.subgraph.body.variables
request.subgraph.body.extensions
request.subgraph.uri.host
request.subgraph.uri.path

By @garypen in https://github.com/apollographql/router/pull/1261

🚀 Features

Add support of compression PR #1229

Add support of request and response compression for the router and all subgraphs. The router is now able to handle Content-Encoding and Accept-Encoding headers properly. Supported algorithms are gzip, br, deflate. You can also enable compression on subgraphs requests and responses by updating the traffic_shaping configuration:

traffic_shaping:
  all:
    compression: br # Enable brotli compression for all subgraphs
  subgraphs:
    products:
      compression: gzip # Enable gzip compression only for subgraph products

By @bnjjj in https://github.com/apollographql/router/pull/1229

Add support of multiple uplink URLs PR #1210

Add support of multiple uplink URLs with a comma-separated list in APOLLO_UPLINK_ENDPOINTS and for --apollo-uplink-endpoints

Example:

export APOLLO_UPLINK_ENDPOINTS="https://aws.uplink.api.apollographql.com/, https://uplink.api.apollographql.com/"

By @bnjjj in https://github.com/apollographql/router/pull/1210

Add support for adding extra environment variables and volumes to helm chart PR #1245

You can mount your supergraph.yaml into the helm deployment via configmap. Using Kustomize to generate your configmap from your supergraph.yaml is suggested.

Example configmap.yaml snippet:

supergraph.yaml:
    server:
        listen: 0.0.0.0:80

Example helm config:

extraEnvVars:
  - name: APOLLO_ROUTER_SUPERGRAPH_PATH
    value: /etc/apollo/supergraph.yaml
    # sets router log level to debug
  - name: APOLLO_ROUTER_LOG
    value: debug
extraEnvVarsCM: ''
extraEnvVarsSecret: ''

extraVolumes:
  - name: supergraph-volume
    configMap:
      name: some-configmap 
extraVolumeMounts: 
  - name: supergraph-volume
    mountPath: /etc/apollo

By @LockedThread in https://github.com/apollographql/router/pull/1245

🐛 Fixes

Support introspection object types (PR #1240)

Introspection queries can use a set of object types defined in the specification. The query parsing code was not recognizing them, resulting in some introspection queries not working.

By @Geal in https://github.com/apollographql/router/pull/1240

Update the scaffold template so that it works with streams (#1247)

Release v0.9.4 changed the way we deal with Response objects, which can now be streams. The scaffold template has been updated so that it generates plugins that are compatible with the new Plugin API.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1248

Create the ExecutionResponse after the primary response was generated (PR #1260)

The @defer preliminary work had a surprising side effect: when using methods like RouterResponse::map_response, they were executed before the subgraph responses were received, because they work on the stream of responses. This PR goes back to the previous behaviour by awaiting the primary response before creating the ExecutionResponse.

By @Geal in https://github.com/apollographql/router/pull/1260

Use the API schema to generate selections (PR #1255)

When parsing the schema to generate selections for response formatting, we should use the API schema instead of the supergraph schema.

By @Geal in https://github.com/apollographql/router/pull/1255

📚 Documentation

Update README link to the configuration file (PR #1208)

As the structure of the documentation has changed, the link should point to the YAML config file section of the overview.

By [@gscheibel](https://github.com/gscheibel in https://github.com/apollographql/router/pull/1208

❗ BREAKING ❗

Groundwork for @defer support (PR #1175, PR #1206)

To prepare for the implementation of the @defer directive, the ExecutionResponse and RouterResponse types now carry a stream of responses instead of a unique response. For now that stream contains only one item, so there is no change in behaviour. However, the Plugin trait changed to accomodate this, so a couple of steps are required to migrate your plugin so it is compatible with router v0.9.4:

• Add a dependency to futures in your Cargo.toml:

+futures = "0.3.21"

• Import BoxStream, and if your Plugin defines a router_service behavior, import ResponseBody:

+ use futures::stream::BoxStream;
+ use apollo_router::ResponseBody;

• Update the router_service and the execution_service sections of your Plugin (if applicable):

      fn router_service(
         &mut self,
-        service: BoxService<RouterRequest, RouterResponse, BoxError>,
-    ) -> BoxService<RouterRequest, RouterResponse, BoxError> {
+        service: BoxService<RouterRequest, RouterResponse<BoxStream<'static, ResponseBody>>, BoxError>,
+    ) -> BoxService<RouterRequest, RouterResponse<BoxStream<'static, ResponseBody>>, BoxError> {

[...]

     fn execution_service(
         &mut self,
-        service: BoxService<ExecutionRequest, ExecutionResponse, BoxError>,
-    ) -> BoxService<ExecutionRequest, ExecutionResponse, BoxError> {
+        service: BoxService<ExecutionRequest, ExecutionResponse<BoxStream<'static, Response>>, BoxError>,
+    ) -> BoxService<ExecutionRequest, ExecutionResponse<BoxStream<'static, Response>>, BoxError> {

We can now update our unit tests so they work on a stream of responses instead of a single one:

         // Send a request
-        let result = test_harness.call_canned().await?;
-        if let ResponseBody::GraphQL(graphql) = result.response.body() {
+        let mut result = test_harness.call_canned().await?;
+
+        let first_response = result
+            .next_response()
+            .await
+            .expect("couldn't get primary response");
+
+        if let ResponseBody::GraphQL(graphql) = first_response {
             assert!(graphql.data.is_some());
         } else {
             panic!("expected graphql response")
         }

+        // You could keep calling result.next_response() until it yields None if you are expexting more parts.
+        assert!(result.next_response().await.is_none());
         Ok(())
     }

The apollo-router-core crate has been merged into apollo-router (PR #1189)

To upgrade, remove any dependency on the apollo-router-core crate from your Cargo.toml files and change imports like so:

- use apollo_router_core::prelude::*;
+ use apollo_router::prelude::*;

By @SimonSapin in https://github.com/apollographql/router/pull/1189

Fix input validation rules (PR #1211)

The GraphQL specification provides two sets of coercion / validation rules, depending on whether we're dealing with inputs or outputs. We have added validation rules for specified input validations which were not previously implemented. This is a breaking change since slightly invalid input may have validated before but will now be guarded by newly-introduced validation rules.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1211

🚀 Features

Add trace logs for parsing recursion consumption (PR #1222)

The apollo-parser package now implements recursion limits which can be examined after the parsing phase. The router logs these out at trace level. You can see them in your logs by searching for "recursion_limit". For example, when using JSON logging and using jq to filter the output:

router -s ../graphql/supergraph.graphql -c ./router.yaml --log trace | jq -c '. | select(.fields.message == "recursion limit data")'
{"timestamp":"2022-06-10T15:01:02.213447Z","level":"TRACE","fields":{"message":"recursion limit data","recursion_limit":"recursion limit: 4096, high: 0"},"target":"apollo_router::spec::schema"}
{"timestamp":"2022-06-10T15:01:02.261092Z","level":"TRACE","fields":{"message":"recursion limit data","recursion_limit":"recursion limit: 4096, high: 0"},"target":"apollo_router::spec::schema"}
{"timestamp":"2022-06-10T15:01:07.642977Z","level":"TRACE","fields":{"message":"recursion limit data","recursion_limit":"recursion limit: 4096, high: 4"},"target":"apollo_router::spec::query"}

This example output shows that the maximum recursion limit is 4096 and that the query we processed caused us to recurse 4 times.

By @garypen in https://github.com/apollographql/router/pull/1222

Helm chart now has the option to use an existing secrets for API key (PR #1196)

This change allows the use of an already existing secret for the graph API key.

To use existing secrets, update your own values.yaml file or specify the value on your helm install command line. For example:

helm install --set router.managedFederation.existingSecret="my-secret-name" <etc...>`

By @pellizzetti in https://github.com/apollographql/router/pull/1196

Add iterators to Context (PR #1202)

Context can now be iterated over, with two new methods:

• iter()
• iter_mut()

These implementations lean heavily on an underlying DashMap implemetation, so refer to its documentation for more usage details.

By @garypen in https://github.com/apollographql/router/pull/1202

Add an experimental optimization to deduplicate variables in query planner (PR #872)

Get rid of duplicated variables in requests and responses of the query planner. This optimization is disabled by default, if you want to enable it you just need override your configuration:

plugins:
  experimental.traffic_shaping:
    variables_deduplication: true # Enable the variables deduplication optimization

By @bnjjj in https://github.com/apollographql/router/pull/872

Add more customizable metrics (PR #1159)

Added the ability to apply custom attributes/labels to metrics which are derived from header values using the Router's configuration file. For example:

telemetry:
  metrics:
    common:
      attributes:
        static:
          - name: "version"
            value: "v1.0.0"
        from_headers:
          - named: "content-type"
            rename: "payload_type"
            default: "application/json"
          - named: "x-custom-header-to-add"

By @bnjjj in https://github.com/apollographql/router/pull/1159

Allow to set a custom health check path (PR #1164)

Added the possibility to set a custom health check path

server:
  # Default is /.well-known/apollo/server-health
  health_check_path: /health

By @jcaromiq in https://github.com/apollographql/router/pull/1164

🐛 Fixes

Pin clap dependency in Cargo.toml (PR #1232)

A minor release of Clap occured yesterday which introduced a breaking change. This change might lead cargo scaffold users to hit a panic a runtime when the router tries to parse environment variables and arguments.

This patch pins the clap dependency to the version that was available before the release, until the root cause is found and fixed upstream.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1232

Display better error message when on subgraph fetch errors (PR #1201)

Show a helpful error message when a subgraph does not return JSON or a bad status code

By @bnjjj in https://github.com/apollographql/router/pull/1201

Fix CORS configuration to eliminate runtime panic on misconfiguration (PR #1197)

Previously, it was possible to specify a CORS configuration which was syntactically valid, but which could not be enforced at runtime. For example, consider the following invalid configuration where the allow_any_origin and allow_credentials parameters are inherantly incompatible with each other (per the CORS specification):

server:
  cors:
    allow_any_origin: true
    allow_credentials: true

Previously, this would result in a runtime panic. The router will now detect this kind of misconfiguration and report the error without panicking.

By @garypen in https://github.com/apollographql/router/pull/1197

🛠 Maintenance

Groundwork for @defer support (PR #1175PR #1206)

To prepare for the implementation of the @defer directive, the ExecutionResponse and RouterResponse types now carry a stream of responses instead of a unique response. For now that stream contains only one item, so there is no change in behaviour.

By @Geal in https://github.com/apollographql/router/pull/1206

Fix a flappy test to test custom health check path (PR #1176)

Force the creation of SocketAddr to use a new unused port to avoid port collisions during testing.

By @bnjjj in https://github.com/apollographql/router/pull/1176

Add static @skip/@include directive support (PR #1185)

• Rewrite the InlineFragment implementation
• Add support of static check for @include and @skip directives

By @bnjjj in https://github.com/apollographql/router/pull/1185

Update buildstructor to 0.3 (PR #1207)

Update buildstructor to v0.3.

By @BrynCooke in https://github.com/apollographql/router/pull/1207

❗ BREAKING ❗

🚀 Features

Scaffold custom binary support (PR #1104)

Added CLI support for scaffolding a new Router binary project. This provides a starting point for people who want to use the Router as a library and create their own plugins

By @BrynCooke in https://github.com/apollographql/router/pull/1104

rhai Context::upsert() supported with example (Issue #648)

Rhai plugins can now interact with Context::upsert(). We provide an example in ./examples/rhai-surrogate-cache-key to illustrate its use.

By @garypen in https://github.com/apollographql/router/pull/1136

Measure APQ cache hits and registers (Issue #1014)

The APQ layer will now report cache hits and misses to Apollo Studio if telemetry is configured

By @Geal in https://github.com/apollographql/router/pull/1117

Add more information to the subgraph_request span (PR #1119)

Add a new span only for the subgraph request, with all HTTP and net information needed for the OpenTelemetry specs.

By @bnjjj in https://github.com/apollographql/router/pull/1119

🐛 Fixes

Compute default port in span information (Issue #1160)

Compute default port in span information for net.peer.port regarding the scheme of the request URI.

By @bnjjj in https://github.com/apollographql/router/pull/1160

Response Content-Type is, again, application/json (Issue #636)

The router was not setting a content-type on client responses. This fix ensures that a content-type of application/json is set when returning a GraphQL response.

By @bnjjj in https://github.com/apollographql/router/pull/1154

Prevent memory leaks when tasks are cancelled (PR #767)

Cancelling a request could put the router in an unresponsive state where the deduplication layer or cache would make subgraph requests hang.

By @Geal in https://github.com/apollographql/router/pull/767

🛠 Maintenance

Use subgraphs deployed on Fly.io in CI (PR #1090)

The CI needs some Node.js subgraphs for integration tests, which complicates its setup and increases the run time. By deploying, in advance, those subgraphs on Fly.io, we can simplify the CI run.

By @Geal in https://github.com/apollographql/router/pull/1090

Unpin schemars version (Issue #1074)

schemars v0.8.9 caused compile errors due to it validating default types. This change has, however, been rolled back upstream and we can now depend on schemars v0.8.10.

By @o0Ignition0o in https://github.com/apollographql/router/pull/1135

Update Moka to fix occasional panics on AMD hardware (Issue #1137)

Moka has a dependency on Quanta which had an issue with AMD hardware. This is now fixed via https://github.com/moka-rs/moka/issues/119

By @BrynCooke in 6b20dc85

📚 Documentation

rhai Context::upsert() supported with example (Issue #648)

Rhai documentation now illustrates how to use Context::upsert() in rhai code.

By @garypen in https://github.com/apollographql/router/pull/1136