apollographql/router v1.37.0 on GitHub

🚀 Features

General availability of subscription callback protocol (Issue #3884)

The subscription callback protocol feature is now generally available (GA).

The configuration of subscription callback protocol in GA is incompatible with its configuration from its preview. Follow the next section to migrate from preview to GA.

Migrate from preview to GA

You must update your router configuration with the following steps:

Change the name of the option from subscription.mode.preview_callback to subscription.mode.callback.
Failure to use the updated option name when running the router will result in an error and the router won't start.
In the example of the GA configuration below, the option is renamed as callback.
Update the public_url field to include the full URL of your callback endpoint.
Previously in preview, the public URL used by the router was the automatic concatenation of the public_url and path fields. In GA, the behavior has changed, and the router uses exactly the value set in public_url. This enables you to configure your own public URL, for example if you have a proxy in front of the router and want to configure redirection with the public URL.
In the example of the GA configuration below, the path /custom_callback is no longer automatically appended to public_url, so instead it has to be set explicitly as public_url: http://127.0.0.1:4000/custom_callback.
Configure the new heartbeat_interval field to set the period that a heartbeat must be sent to the callback endpoint for the subscription operation.
The default heartbeat interval is 5 seconds. Heartbeats can be disabled by setting heartbeat_interval: disabled.

subscription:
  enabled: true
  mode:
    callback: #highlight-line
      public_url: http://127.0.0.1:4000/custom_callback
      listen: 0.0.0.0:4000
      path: /custom_callback
      heartbeat_interval: 5secs # can be "disabled", by default it's 5secs

Changes in callback protocol specifications

The subscription specification has been updated with the following observable changes:

The router will always answer with the header subscription-protocol: callback/1.0 on the callback endpoint.
Extensions data now includes the heartbeat interval (in milliseconds) that you can globally configure. We also switch from snake_case to camelCase notation. An example of a payload sent to the subgraph using callback mode:

{
    "query": "subscription { userWasCreated { name reviews { body } } }",
    "extensions": {
        "subscription": {
            "callbackUrl": "http://localhost:4000/callback/c4a9d1b8-dc57-44ab-9e5a-6e6189b2b945",
            "subscriptionId": "c4a9d1b8-dc57-44ab-9e5a-6e6189b2b945",
            "verifier": "XXX",
            "heartbeatIntervalMs": 5000
        }
    }
}

When the router is sending a subscription to a subgraph in callback mode, it now includes a specific accept header set to application/json;callbackSpec=1.0 that let's you automatically detect if it's using callback mode or not.

By @bnjjj in #4272

Expose Context ID to Rhai scripts (Issue #4370)

We recently added an ID to Context which uniquely identifies the context for the duration of a request/response lifecycle. This is now accessible on Request or Response objects inside Rhai scripts.

For example:

// Map Request for the Supergraph Service
fn supergraph_service(service) {
    const request_callback = Fn("process_request");
    service.map_request(request_callback);
}

// Generate a log for each Supergraph request with the request ID
fn process_request(request) {
    print(`request id :  ${request.id}`);
}

Note: We expose this Context data directly from Request and Response objects, rather than on the Context object, to avoid the possibility of name collisions (e.g., with "id") in the context data itself.

By @garypen in #4374

Add support for downloading supergraph schema from a list of URLs (Issue #4219)

The APOLLO_ROUTER_SUPERGRAPH_URLS environment variable has been introduced to support downloading supergraph schema from a list of URLs. This is useful for users who require supergraph deployments to be synchronized via GitOps workflows.

You configure APOLLO_ROUTER_SUPERGRAPH_URLS with a comma separated list of URLs that will be polled in order to try and retrieve the supergraph schema, and you configure the polling interval by setting APOLLO_UPLINK_POLL_INTERVAL (default: 10s).

By @BrynCooke in #4377

Offline license support (Issue #4219)

⚠️ This is an Enterprise feature of the Apollo Router available on an as-needed basis. It requires the feature be enabled on an organization with a GraphOS Enterprise plan. Send a request to your Apollo contact to enable it for your GraphOS Studio organization.

Running your Apollo Router fleet while fully connected to GraphOS is the best choice for most Apollo users. To support various other scenarios, this release of the Router introduces GraphOS offline Enterprise licenses. An offline license enables routers to start and serve traffic without a persistent connection to GraphOS.

For complete details on the feature, including how it varies from being fully-connected to GraphOS, see Offline Enterprise license.

By @BrynCooke in #4372

🐛 Fixes

Fix reporting of subscription traces to Apollo (Issue #4339)

Fixes the reporting of subscription traces in Apollo usage reports to match what is reported in OpenTelemetry.

By @bonnici in #4328

Abstract spreads in queried objects no longer returning erroneous nulls (Issue #4348)

When you had an inline fragment on an union type in a fragment spread the response returned to the client was not fully accurate against the schema, or the GraphQL specification, which resulted in client errors and unexpected null values (either on fields or objects whose members existed on other concrete types of the union). This is now resolved and accounted for correctly, and additional tests have been added.

By @bnjjj in #4401

Fix TLS session ticket retries (Issue #4305)

In some cases, the router could retry TLS connections indefinitely with an invalid session ticket, making it impossible to contact a subgraph. We've provided a fix to the upstream rustls project with a fix, and brought in the updated dependency when it was published in v0.21.10.

By @Geal in #4362

🛠 Maintenance

Fixed update telemetry config in Helm chart (PR #4360)

Previously, if using the new telemetry configuration (notably telemetry.exporters), the Helm chart would result in both old and new configuration at the same time. This was invalid and prevented the router from starting up. In this release, the Helm chart outputs the appropriate structure based on user-provided configuration.

By @lennyburdette in #4360

Update zerocopy dependency (PR #4403)

This changeset updates zerocopy to 0.7.31, which has a fix for https://rustsec.org/advisories/RUSTSEC-2023-0074.

By @o0Ignition0o in #4403

📚 Documentation

Add links to related content in subgraph error inclusion docs (PR #4206)

The Subgraph error inclusion doc has been updated with links to related content about why you might not be seeing error message in logs or GraphOS and how you can configure their settings.

By @smyrick in #4206

Document `experimental_when_header` logging configuration option (Issue #4342)

In router v1.35.0, we introduced the¬ experimental logging configuration option experimental_when_header without documentation. Its documentation has been added here.

By @bnjjj in #4359

🧪 Experimental

Expose query plan and paths limits (PR #4367)

Two new configuration options have been added to reduce the impact of complex queries on the planner:

experimental_plans_limit limits the number of generated plans. (Note: already generated plans remain valid, but they may not be optimal.)
experimental_paths_limit stops the planning process entirely if the number of possible paths for a selection in the schema gets too large.

By @Geal in #4367