Implement progressive @override (#2911)

Add new optional `label` arg to `@override` which is a `String`. Capture
label in the supergraph via the new `@join__field` arg `overrideLabel`
so these values can be used during query graph creation and query
planning.

Reviewed in two separate PRs:
#2879
#2902

---------

Co-authored-by: Sachin D. Shinde <sachin@apollographql.com>

.changeset/empty-dodos-turn.md

@@ -0,0 +1,22 @@
+---
+"@apollo/query-planner": minor
+"@apollo/query-graphs": minor
+"@apollo/composition": minor
+"@apollo/federation-internals": minor
+"@apollo/subgraph": minor
+"@apollo/gateway": minor
+---
+
+Implement progressive `@override` functionality
+
+The progressive `@override` feature brings a new argument to the `@override` directive: `label: String`. When a label is added to an `@override` application, the override becomes conditional, depending on parameters provided to the query planner (a set of which labels should be overridden). Note that this feature will be supported in router for enterprise users only.
+
+Out-of-the-box, the router will support a percentage-based use case for progressive `@override`. For example:
+```graphql
+type Query {
+  hello: String @override(from: "original", label: "percent(5)")
+}
+```
+The above example will override the root `hello` field from the "original" subgraph 5% of the time.
+
+More complex use cases will be supported by the router via the use of coprocessors/rhai to resolve arbitrary labels to true/false values (i.e. via a feature flag service).

.cspell/cspell-dict.txt

@@ -190,6 +190,7 @@ Reviwed
 Rhai
 righ
 rulesof
+runtimes
 samee
 Sant
 SATISFIABILITY

composition-js/src/__tests__/compose.test.ts

@@ -80,7 +80,7 @@ describe('composition', () => {
 
       directive @join__enumValue(graph: join__Graph!) repeatable on ENUM_VALUE
 
-      directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet, type: String, external: Boolean, override: String, usedOverridden: Boolean) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION
+      directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet, type: String, external: Boolean, override: String, usedOverridden: Boolean, overrideLabel: String) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION
 
       directive @join__graph(name: String!, url: String!) on ENUM_VALUE
 
@@ -232,7 +232,7 @@ describe('composition', () => {
 
       directive @join__enumValue(graph: join__Graph!) repeatable on ENUM_VALUE
 
-      directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet, type: String, external: Boolean, override: String, usedOverridden: Boolean) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION
+      directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet, type: String, external: Boolean, override: String, usedOverridden: Boolean, overrideLabel: String) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION
 
       directive @join__graph(name: String!, url: String!) on ENUM_VALUE