feat(gateway): Implement @core v0.2, including "for" and core__Purpose support

docs/source/index.mdx

@@ -173,13 +173,13 @@ This outputs the following supergraph schema that our gateway can use to route q
 
 ```graphql
 schema
-  @core(feature: "https://specs.apollo.dev/core/v0.1"),
-  @core(feature: "https://specs.apollo.dev/join/v0.1")
+  @core(feature: "https://specs.apollo.dev/core/v0.2"),
+  @core(feature: "https://specs.apollo.dev/join/v0.1", for: EXECUTION)
 {
   query: Query
 }
 
-directive @core(feature: String!) repeatable on SCHEMA
+directive @core(feature: String!, as: String, for: core__Purpose) repeatable on SCHEMA
 
 directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet) on FIELD_DEFINITION
 
@@ -189,6 +189,11 @@ directive @join__owner(graph: join__Graph!) on OBJECT | INTERFACE
 
 directive @join__graph(name: String!, url: String!) on ENUM_VALUE
 
+enum core__Purpose {
+  EXECUTION
+  SECURITY
+}
+
 scalar join__FieldSet
 
 enum join__Graph {

docs/source/quickstart.mdx

@@ -257,13 +257,13 @@ Rover outputs the following schema:
 
 ```graphql
 schema
-  @core(feature: "https://specs.apollo.dev/core/v0.1"),
-  @core(feature: "https://specs.apollo.dev/join/v0.1")
+  @core(feature: "https://specs.apollo.dev/core/v0.2"),
+  @core(feature: "https://specs.apollo.dev/join/v0.1", for: EXECUTION)
 {
   query: Query
 }
 
-directive @core(feature: String!) repeatable on SCHEMA
+directive @core(feature: String!, as: String, for: core__Purpose) repeatable on SCHEMA
 
 directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet) on FIELD_DEFINITION
 
@@ -273,6 +273,11 @@ directive @join__owner(graph: join__Graph!) on OBJECT | INTERFACE
 
 directive @join__graph(name: String!, url: String!) on ENUM_VALUE
 
+enum core__Purpose {
+  EXECUTION
+  SECURITY
+}
+
 enum CURRENCY_CODE {
   USD
 }

federation-integration-testsuite-js/src/fixtures/special-cases/supergraphWithInaccessible.ts

@@ -22,7 +22,7 @@ const [inaccessibleDefinition, schemaDefinition] = parse(`#graphql
   directive @inaccessible on FIELD_DEFINITION | OBJECT | INTERFACE | UNION
   schema
     # inaccessibleCoreUsage
-    @core(feature: "https://specs.apollo.dev/inaccessible/v0.1")
+    @core(feature: "https://specs.apollo.dev/inaccessible/v0.1", for: SECURITY)
     # inaccessibleUsage
     @inaccessible {
       query: Query

federation-integration-testsuite-js/src/snapshotSerializers/graphqlErrorSerializer.ts

@@ -7,6 +7,11 @@ export default {
   },
 
   print(value: GraphQLError, print) {
+    // Support printing GraphQLError.causes (from core-schema-js)
+    if ('causes' in value) {
+      // @ts-ignore
+      return print(value.causes.map((cause) => cause.message));
+    }
     return print({
       message: value.message,
       code: value.extensions ? value.extensions.code : 'MISSING_ERROR',

federation-js/src/coreSpec.ts

@@ -3,15 +3,36 @@ import {
   DirectiveLocation,
   GraphQLNonNull,
   GraphQLString,
+  GraphQLEnumType,
 } from 'graphql';
 
+const CorePurpose = new GraphQLEnumType({
+  name: 'core__Purpose',
+  values: {
+    EXECUTION: {
+      description:
+        '`EXECUTION` features provide metadata necessary to for operation execution.',
+    },
+    SECURITY: {
+      description:
+        '`SECURITY` features provide metadata necessary to securely resolve fields.',
+    },
+  },
+});
+
 export const CoreDirective = new GraphQLDirective({
   name: 'core',
   locations: [DirectiveLocation.SCHEMA],
   args: {
     feature: {
       type: new GraphQLNonNull(GraphQLString),
     },
+    as: {
+      type: GraphQLString,
+    },
+    for: {
+      type: CorePurpose,
+    },
   },
   isRepeatable: true,
 });

federation-js/src/service/__tests__/printSupergraphSdl.test.ts

@@ -29,15 +29,15 @@ describe('printSupergraphSdl', () => {
   it('prints a fully composed schema correctly', () => {
     expect(supergraphSdl).toMatchInlineSnapshot(`
       "schema
-        @core(feature: \\"https://specs.apollo.dev/core/v0.1\\"),
-        @core(feature: \\"https://specs.apollo.dev/join/v0.1\\"),
+        @core(feature: \\"https://specs.apollo.dev/core/v0.2\\"),
+        @core(feature: \\"https://specs.apollo.dev/join/v0.1\\", for: EXECUTION),
         @core(feature: \\"https://specs.apollo.dev/tag/v0.1\\")
       {
         query: Query
         mutation: Mutation
       }
 
-      directive @core(feature: String!) repeatable on SCHEMA
+      directive @core(feature: String!, as: String, for: core__Purpose) repeatable on SCHEMA
 
       directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet) on FIELD_DEFINITION
 
@@ -104,6 +104,18 @@ describe('printSupergraphSdl', () => {
         retailPrice: String @join__field(graph: REVIEWS, requires: \\"price\\")
       }
 
+      enum core__Purpose {
+        \\"\\"\\"
+        \`EXECUTION\` features provide metadata necessary to for operation execution.
+        \\"\\"\\"
+        EXECUTION
+
+        \\"\\"\\"
+        \`SECURITY\` features provide metadata necessary to securely resolve fields.
+        \\"\\"\\"
+        SECURITY
+      }
+
       type Error {
         code: Int
         message: String
@@ -330,14 +342,14 @@ describe('printSupergraphSdl', () => {
 
     expect(supergraphSdl).toMatchInlineSnapshot(`
       "schema
-        @core(feature: \\"https://specs.apollo.dev/core/v0.1\\"),
-        @core(feature: \\"https://specs.apollo.dev/join/v0.1\\")
+        @core(feature: \\"https://specs.apollo.dev/core/v0.2\\"),
+        @core(feature: \\"https://specs.apollo.dev/join/v0.1\\", for: EXECUTION)
       {
         query: Query
         mutation: Mutation
       }
 
-      directive @core(feature: String!) repeatable on SCHEMA
+      directive @core(feature: String!, as: String, for: core__Purpose) repeatable on SCHEMA
 
       directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet) on FIELD_DEFINITION
 
@@ -400,6 +412,18 @@ describe('printSupergraphSdl', () => {
         retailPrice: String @join__field(graph: REVIEWS, requires: \\"price\\")
       }
 
+      enum core__Purpose {
+        \\"\\"\\"
+        \`EXECUTION\` features provide metadata necessary to for operation execution.
+        \\"\\"\\"
+        EXECUTION
+
+        \\"\\"\\"
+        \`SECURITY\` features provide metadata necessary to securely resolve fields.
+        \\"\\"\\"
+        SECURITY
+      }
+
       type Error {
         code: Int
         message: String

federation-js/src/service/printSupergraphSdl.ts

@@ -179,14 +179,21 @@ function printCoreDirectives(schema: GraphQLSchema) {
     otherKnownDirectiveNames.includes(name),
   );
   const otherKnownDirectiveSpecUrls = otherKnownDirectivesToInclude.map(
-    (name) => `https://specs.apollo.dev/${name}/v0.1`,
+    (name) => ({
+      feature: `https://specs.apollo.dev/${name}/v0.1`,
+    }),
   );
 
   return [
-    'https://specs.apollo.dev/core/v0.1',
-    'https://specs.apollo.dev/join/v0.1',
+    { feature: 'https://specs.apollo.dev/core/v0.2' },
+    { feature: 'https://specs.apollo.dev/join/v0.1', purpose: 'EXECUTION' },
     ...otherKnownDirectiveSpecUrls,
-  ].map((feature) => `\n  @core(feature: ${printStringLiteral(feature)})`);
+  ].map(
+    ({ feature, purpose }) =>
+      `\n  @core(feature: ${printStringLiteral(feature)}${
+        purpose ? `, for: ${purpose}` : ''
+      })`,
+  );
 }
 
 export function printType(

gateway-js/CHANGELOG.md

@@ -4,7 +4,7 @@
 
 > The changes noted within this `vNEXT` section have not been released yet.  New PRs and commits which introduce changes should include an entry in this `vNEXT` section as part of their development.  When a release is being prepared, a new header will be (manually) created below and the appropriate changes within that release will be moved into the new section.
 
-- _Nothing yet! Stay tuned!_
+- Introduce @core v0.2 support with the "for:" directive argument. The "for:" argument allows a @core directive to specify its criticality to the gateway (or any consumer). "for:" is optional - its absence means that the directive requires no additional support from the consumer. Its two available options `EXECUTION` and `SECURITY` both require explicit support from the consumer, else the consumer should fail to start / update to this unsupported schema. [PR #957](https://github.com/apollographql/federation/pull/942)
 
 ## v0.37.0
 

gateway-js/package.json

@@ -25,6 +25,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@apollo/core-schema": "^0.1.0",
     "@apollo/federation": "file:../federation-js",
     "@apollo/query-planner": "file:../query-planner-js",
     "@opentelemetry/api": "^1.0.1",

gateway-js/src/__tests__/loadSupergraphSdlFromStorage.test.ts

@@ -36,15 +36,15 @@ describe('loadSupergraphSdlFromStorage', () => {
       Object {
         "id": "originalId-1234",
         "supergraphSdl": "schema
-        @core(feature: \\"https://specs.apollo.dev/core/v0.1\\"),
-        @core(feature: \\"https://specs.apollo.dev/join/v0.1\\"),
+        @core(feature: \\"https://specs.apollo.dev/core/v0.2\\"),
+        @core(feature: \\"https://specs.apollo.dev/join/v0.1\\", for: EXECUTION),
         @core(feature: \\"https://specs.apollo.dev/tag/v0.1\\")
       {
         query: Query
         mutation: Mutation
       }
 
-      directive @core(feature: String!) repeatable on SCHEMA
+      directive @core(feature: String!, as: String, for: core__Purpose) repeatable on SCHEMA
 
       directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet) on FIELD_DEFINITION
 
@@ -111,6 +111,18 @@ describe('loadSupergraphSdlFromStorage', () => {
         retailPrice: String @join__field(graph: REVIEWS, requires: \\"price\\")
       }
 
+      enum core__Purpose {
+        \\"\\"\\"
+        \`EXECUTION\` features provide metadata necessary to for operation execution.
+        \\"\\"\\"
+        EXECUTION
+
+        \\"\\"\\"
+        \`SECURITY\` features provide metadata necessary to securely resolve fields.
+        \\"\\"\\"
+        SECURITY
+      }
+
       type Error {
         code: Int
         message: String