Progressive override (query planning / validation) (#2902)

Implement progressive override functionality in QP and validation logic

Co-authored-by: Sachin D. Shinde <[email protected]>

Author: trevor-scheer

.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__/override.compose.test.ts

@@ -954,7 +954,7 @@ describe("composition involving @override directive", () => {
           @join__type(graph: SUBGRAPH2, key: \\"k\\")
         {
           k: ID
-          a: Int @join__field(graph: SUBGRAPH1, override: \\"Subgraph2\\", overrideLabel: \\"foo\\")
+          a: Int @join__field(graph: SUBGRAPH1, override: \\"Subgraph2\\", overrideLabel: \\"foo\\") @join__field(graph: SUBGRAPH2, overrideLabel: \\"foo\\")
           b: Int @join__field(graph: SUBGRAPH2)
         }"
       `);
@@ -971,6 +971,70 @@ describe("composition involving @override directive", () => {
           b: Int
         }
       `);
+
+      expect(result.supergraphSdl).toMatchInlineSnapshot(`
+        "schema
+          @link(url: \\"https://specs.apollo.dev/link/v1.0\\")
+          @link(url: \\"https://specs.apollo.dev/join/v0.4\\", for: EXECUTION)
+        {
+          query: Query
+        }
+
+        directive @join__directive(graphs: [join__Graph!], name: String!, args: join__DirectiveArguments) repeatable on SCHEMA | OBJECT | INTERFACE | FIELD_DEFINITION
+
+        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, overrideLabel: String) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION
+
+        directive @join__graph(name: String!, url: String!) on ENUM_VALUE
+
+        directive @join__implements(graph: join__Graph!, interface: String!) repeatable on OBJECT | INTERFACE
+
+        directive @join__type(graph: join__Graph!, key: join__FieldSet, extension: Boolean! = false, resolvable: Boolean! = true, isInterfaceObject: Boolean! = false) repeatable on OBJECT | INTERFACE | UNION | ENUM | INPUT_OBJECT | SCALAR
+
+        directive @join__unionMember(graph: join__Graph!, member: String!) repeatable on UNION
+
+        directive @link(url: String, as: String, for: link__Purpose, import: [link__Import]) repeatable on SCHEMA
+
+        scalar join__DirectiveArguments
+
+        scalar join__FieldSet
+
+        enum join__Graph {
+          SUBGRAPH1 @join__graph(name: \\"Subgraph1\\", url: \\"https://Subgraph1\\")
+          SUBGRAPH2 @join__graph(name: \\"Subgraph2\\", url: \\"https://Subgraph2\\")
+        }
+
+        scalar link__Import
+
+        enum link__Purpose {
+          \\"\\"\\"
+          \`SECURITY\` features provide metadata necessary to securely resolve fields.
+          \\"\\"\\"
+          SECURITY
+
+          \\"\\"\\"
+          \`EXECUTION\` features provide metadata necessary for operation execution.
+          \\"\\"\\"
+          EXECUTION
+        }
+
+        type Query
+          @join__type(graph: SUBGRAPH1)
+          @join__type(graph: SUBGRAPH2)
+        {
+          t: T @join__field(graph: SUBGRAPH1)
+        }
+
+        type T
+          @join__type(graph: SUBGRAPH1, key: \\"k\\")
+          @join__type(graph: SUBGRAPH2, key: \\"k\\")
+        {
+          k: ID
+          a: Int @join__field(graph: SUBGRAPH1, override: \\"Subgraph2\\", overrideLabel: \\"foo\\") @join__field(graph: SUBGRAPH2, overrideLabel: \\"foo\\")
+          b: Int @join__field(graph: SUBGRAPH2)
+        }"
+      `);
     });
 
     describe("label validation", () => {
@@ -1088,5 +1152,103 @@ describe("composition involving @override directive", () => {
         }
       );
     });
+
+    describe("composition validation", () => {
+      it("forced jump from S1 -> S2 -> S1 due to @override usages", () => {
+        const subgraph1 = {
+          name: "Subgraph1",
+          url: "https://Subgraph1",
+          typeDefs: gql`
+            type Query {
+              t: T
+            }
+
+            type T @key(fields: "id") {
+              id: ID
+              a: A @override(from: "Subgraph2", label: "foo")
+            }
+
+            type A @key(fields: "id") {
+              id: ID
+              b: Int
+            }
+          `,
+        };
+
+        const subgraph2 = {
+          name: "Subgraph2",
+          url: "https://Subgraph2",
+          typeDefs: gql`
+            type T @key(fields: "id") {
+              id: ID
+              a: A
+            }
+
+            type A @key(fields: "id") {
+              id: ID
+              b: Int @override(from: "Subgraph1", label: "foo")
+            }
+          `,
+        };
+
+        const result = composeAsFed2Subgraphs([subgraph1, subgraph2]);
+        assertCompositionSuccess(result);
+      });
+
+      it("errors on overridden fields in @requires FieldSet", () => {
+        const subgraph1 = {
+          name: "Subgraph1",
+          url: "https://Subgraph1",
+          typeDefs: gql`
+            type Query {
+              t: T
+            }
+
+            type T @key(fields: "id") {
+              id: ID
+              a: A @override(from: "Subgraph2", label: "foo")
+            }
+
+            type A @key(fields: "id") {
+              id: ID
+              b: Int
+              c: Int
+            }
+          `,
+        };
+
+        const subgraph2 = {
+          name: "Subgraph2",
+          url: "https://Subgraph2",
+          typeDefs: gql`
+            type T @key(fields: "id") {
+              id: ID
+              a: A
+              b: Int @requires(fields: "a { c }")
+            }
+
+            type A @key(fields: "id") {
+              id: ID
+              b: Int @override(from: "Subgraph1", label: "foo")
+              c: Int @external
+            }
+          `,
+        };
+
+        const result = composeAsFed2Subgraphs([subgraph1, subgraph2]);
+        expect(result.errors).toBeDefined();
+        expect(result.errors![0]).toMatchInlineSnapshot(`
+          [GraphQLError: The following supergraph API query:
+          {
+            t {
+              b
+            }
+          }
+          cannot be satisfied by the subgraphs because:
+          - from subgraph "Subgraph1": cannot find field "T.b".
+          - from subgraph "Subgraph2": cannot satisfy @require conditions on field "T.b".]
+        `);
+      });
+    });
   });
 });

composition-js/src/merging/merge.ts

@@ -1301,12 +1301,14 @@ class Merger {
             const percentRegex = /^percent\((\d{1,2}(\.\d{1,8})?|100)\)$/;
             if (labelRegex.test(overrideLabel)) {
               result.setOverrideLabel(idx, overrideLabel);
+              result.setOverrideLabel(fromIdx, overrideLabel);
             } else if (percentRegex.test(overrideLabel)) {
               const parts = percentRegex.exec(overrideLabel);
               if (parts) {
                 const percent = parseFloat(parts[1]);
                 if (percent >= 0 && percent <= 100) {
                   result.setOverrideLabel(idx, overrideLabel);
+                  result.setOverrideLabel(fromIdx, overrideLabel);
                 }
               }
             }
@@ -1589,7 +1591,7 @@ class Merger {
     if (!allTypesEqual) {
       return true;
     }
-    if (mergeContext.some(({ usedOverridden }) => usedOverridden)) {
+    if (mergeContext.some(({ usedOverridden, overrideLabel }) => usedOverridden || !!overrideLabel)) {
       return true;
     }
 
@@ -1642,7 +1644,8 @@ class Merger {
     for (const [idx, source] of sources.entries()) {
       const usedOverridden = mergeContext.isUsedOverridden(idx);
       const unusedOverridden = mergeContext.isUnusedOverridden(idx);
-      if (!source || unusedOverridden) {
+      const overrideLabel = mergeContext.overrideLabel(idx);
+      if (!source || (unusedOverridden && !overrideLabel)) {
         continue;
       }