Clarify coprocessor config context: true behaviour

.changesets/config_renee_warn_on_coprocessor_context_true.md

@@ -0,0 +1,25 @@
+### Log warnings for deprecated coprocessor context configuration ([PR #7349](https://github.com/apollographql/router/pull/7349))
+
+`context: true` is an alias for `context: deprecated` but should not be used. The router now logs a runtime warning on startup if you do use it.
+
+Instead of:
+
+```yaml
+coprocessor:
+  supergraph:
+    request:
+      context: true # ❌
+```
+
+Explicitly use `deprecated` or `all`:
+
+```yaml
+coprocessor:
+  supergraph:
+    request:
+      context: deprecated # ✅
+```
+
+See [the 2.x upgrade guide](https://www.apollographql.com/docs/graphos/routing/upgrade/from-router-v1#context-keys-for-coprocessors) for more detailed upgrade steps.
+
+By [@goto-bus-stop](https://github.com/goto-bus-stop) in https://github.com/apollographql/router/pull/7349

apollo-router/src/plugins/coprocessor/mod.rs

@@ -115,6 +115,71 @@ impl Plugin for CoprocessorPlugin<HTTPClientService> {
             builder.wrap_connector(http_connector)
         };
 
+        if matches!(
+            init.config.router.request.context,
+            ContextConf::Deprecated(true)
+        ) {
+            tracing::warn!(
+                "Configuration `coprocessor.router.request.context: true` is deprecated. See https://go.apollo.dev/o/coprocessor-context"
+            );
+        }
+        if matches!(
+            init.config.router.response.context,
+            ContextConf::Deprecated(true)
+        ) {
+            tracing::warn!(
+                "Configuration `coprocessor.router.response.context: true` is deprecated. See https://go.apollo.dev/o/coprocessor-context"
+            );
+        }
+        if matches!(
+            init.config.supergraph.request.context,
+            ContextConf::Deprecated(true)
+        ) {
+            tracing::warn!(
+                "Configuration `coprocessor.supergraph.request.context: true` is deprecated. See https://go.apollo.dev/o/coprocessor-context"
+            );
+        }
+        if matches!(
+            init.config.supergraph.response.context,
+            ContextConf::Deprecated(true)
+        ) {
+            tracing::warn!(
+                "Configuration `coprocessor.supergraph.response.context: true` is deprecated. See https://go.apollo.dev/o/coprocessor-context"
+            );
+        }
+        if matches!(
+            init.config.execution.request.context,
+            ContextConf::Deprecated(true)
+        ) {
+            tracing::warn!(
+                "Configuration `coprocessor.execution.request.context: true` is deprecated. See https://go.apollo.dev/o/coprocessor-context"
+            );
+        }
+        if matches!(
+            init.config.execution.response.context,
+            ContextConf::Deprecated(true)
+        ) {
+            tracing::warn!(
+                "Configuration `coprocessor.execution.response.context: true` is deprecated. See https://go.apollo.dev/o/coprocessor-context"
+            );
+        }
+        if matches!(
+            init.config.subgraph.all.request.context,
+            ContextConf::Deprecated(true)
+        ) {
+            tracing::warn!(
+                "Configuration `coprocessor.subgraph.all.request.context: true` is deprecated. See https://go.apollo.dev/o/coprocessor-context"
+            );
+        }
+        if matches!(
+            init.config.subgraph.all.response.context,
+            ContextConf::Deprecated(true)
+        ) {
+            tracing::warn!(
+                "Configuration `coprocessor.subgraph.all.response.context: true` is deprecated. See https://go.apollo.dev/o/coprocessor-context"
+            );
+        }
+
         let http_client = ServiceBuilder::new()
             .map_response(
                 |http_response: http::Response<hyper::body::Incoming>| -> http::Response<RouterBody> {

docs/source/routing/customization/coprocessor.mdx

@@ -136,9 +136,19 @@ coprocessor:
 
 ### Context configuration
 
-You can configure what you want to send from the context to your coprocessor. By default it's disabled (`false`) and doesn't send any context keys to the coprocessor. You now have the ability to give an array
-containing all the context keys you want to send to your coprocessor. Sending only a selective list of context keys will increase the performances because it will lower the size of payloads between the router and coprocessor.
-You can also set `context: deprecated` if you still want to use deprecated context key names from router 1.x. If you want to pass all context keys with new naming just set `context: all`.
+The router request context is used to share data across stages of the request pipeline. The coprocessor can also use this context.
+By default, the context is not sent to the coprocessor (`context: false`).
+You can send _all_ context keys to your coprocessor using `context: all`.
+You can also specify exactly which context keys you wish to send to a coprocessor by listing them under the `selective` key. This will reduce the size of the request/response and may improve performance.
+
+If you're upgrading from router 1.x, the [context key names changed](/docs/graphos/routing/upgrade/from-router-v1#renamed-context-keys) in router v2.0. You can specify `context: deprecated` to send all context with the old names, compatible with v1.x. Context keys are translated to their v1.x names before being sent to the coprocessor, and translated back to the v2.x names after being received from the coprocessor.
+
+<Note>
+
+`context: true` from router 1.x is still supported by the configuration, and is an alias for `context: deprecated`.
+We strongly recommend using `context: deprecated` or `context: all` instead.
+
+</Note>
 
 Example:
 
@@ -167,14 +177,16 @@ coprocessor:
 ```
 
 <Note>
-    If you use the `selective` configuration, you'll have to specify new context key names (>=2.x) it doesn't work with deprecated keys. So for example if you try to specify `operation_name` instead of `apollo::supergraph::operation_name` it won't map to the new context key.
+
+If you use the `selective` configuration, you must use the new context key names from v2.x. It does not support the `deprecated` keys from v1.x. So for example, if you try to specify `operation_name` instead of `apollo::supergraph::operation_name`, it won't map to the new context key.
+
 </Note>
 
 ### Client configuration
 
 <HttpConnection type="coprocessor" />
 
-For example, to enable h2c (http2 cleartext) communication with a coprocessor you can use this configuration::
+For example, to enable h2c (http2 cleartext) communication with a coprocessor you can use this configuration:
 
 ```yaml title="router.yaml"
 coprocessor:

docs/source/routing/upgrade/from-router-v1.mdx

@@ -406,6 +406,12 @@ The [context key renames](#renamed-context-keys) may impact your coprocessor log
 
 You can specify `context: deprecated` to send all context with the old names, compatible with v1.x. Context keys are translated to their v1.x names before being sent to the coprocessor, and translated back to the v2.x names after being received from the coprocessor.
 
+<Note>
+
+`context: true` is an alias for `context: deprecated`. In a future major release, the `context: true` setting will be removed.
+
+</Note>
+
 You can now also specify exactly which context keys you wish to send to a coprocessor by listing them under the `selective` key. This will reduce the size of the request/response and may improve performance.
 
 **Upgrade step**: Either upgrade your coprocessor to use the new context keys, or add `context: deprecated` to your coprocessor configuration.