Docs and changeset

.changesets/feat_glasser_pq_client_name.md

@@ -0,0 +1,13 @@
+### Client name support for Persisted Query Lists ([PR #6198](https://github.com/apollographql/router/pull/6198))
+
+The persisted query manifest fetched from Uplink can now contain a `clientName` field in each operation. Two operations with the same `id` but different `clientName` are considered to be distinct operations (and may have distinct bodies).
+
+Router resolves the client name by taking the first of these which exists:
+- Reading the `apollo_persisted_queries::client_name` context key (which may be set by a `router_service` plugin)
+- Reading the HTTP header named by `telemetry.apollo.client_name_header` (which defaults to `apollographql-client-name`)
+
+If a client name can be resolved for a request, Router first tries to find a persisted query with the specified ID and the resolved client name.
+
+If there is no operation with that ID and client name, or if a client name cannot be resolved, Router tries to find a persisted query with the specified ID and no client name specified.  (This means that existing PQ lists that do not contain client names will continue to work.)
+
+By [@glasser](https://github.com/glasser) in https://github.com/apollographql/router/pull/6198

docs/source/routing/observability/client-awareness.mdx

@@ -8,6 +8,8 @@ import { Link } from "gatsby";
 
 The GraphOS Router and Apollo Router Core support [client awareness](/graphos/metrics/client-awareness/) by default. If the client sets the headers `apollographql-client-name` and `apollographql-client-version` in its HTTP requests, GraphOS Studio can separate the metrics and operations per client.
 
+This client name is also used by the [Persisted Queries](/docs/graphos/routing/security/persisted-queries.mdx) feature.
+
 ## Overriding client awareness headers
 
 Different header names can be used by updating the configuration file. If those headers will be sent by a browser, they must be allowed in the [CORS (Cross Origin Resource Sharing) configuration](/router/configuration/cors), as follows:

docs/source/routing/security/persisted-queries.mdx

@@ -138,6 +138,20 @@ To enable safelisting, you _must_ turn off [automatic persisted queries](/router
 
 </Note>
 
+### Customization via request context
+
+GraphOS Router can be [customized](/graphos/routing/customization/overview) via several mechanisms such as [Rhai scripts](/graphos/routing/customization/rhai) and [coprocessors](/docs/graphos/routing/customization/coprocessor). These plugins can affect your router's persistent query processing by writing to the request context.
+
+#### `apollo_persisted_queries::client_name`
+
+When publishing operations to a PQL, you can specify a client name associated with the operation (by including a `clientName` field in the individual operation in your [manifest](/docs/graphos/platform/security/persisted-queries#per-operation-properties), or by including the `--for-client-name` option to `rover persisted-queries publish`). If an operation has a client name, it will only be executed by requests that specify that client name. (Your PQL can contain multiple operations with the same ID and different client names.)
+
+Your customization (Rhai script, coprocessor, etc) can examine a request during the [Router Service stage](/docs/graphos/routing/customization/overview#request-path) of the request path and set the `apollo_persisted_queries::client_name` value in the request context to the request's client name.
+
+If this context value is not set by a customization, your router will use the same client name used for [client awareness](/docs/graphos/routing/observability/client-awareness) in observability. This client name is read from an HTTP header specified by `telemetry.apollo.client_name_header`, or `apollographql-client-name` by default.
+
+If your request specifies an ID and a client name but there is no operation in the PQL with that ID and client name, your router will look to see if there is an operation with that ID and no client name specified, and use that if it finds it.
+
 ## Limitations
 
 * **Unsupported with offline license**. An GraphOS Router using an [offline Enterprise license](/router/enterprise-features/#offline-enterprise-license) cannot use safelisting with persisted queries. The feature relies on Apollo Uplink to fetch persisted query manifests, so it doesn't work as designed when the router is disconnected from Uplink.