@apollo/federation-internals 2.0.2-alpha.2 → 2.0.4

package/src/__tests__/graphQLJSSchemaToAST.test.ts

@@ -0,0 +1,156 @@
+import {
+  buildClientSchema,
+  buildSchema,
+  GraphQLSchema,
+  introspectionFromSchema,
+  print
+} from "graphql";
+import { graphQLJSSchemaToAST } from "../graphQLJSSchemaToAST";
+import './matchers';
+
+function validateRoundtrip(schemaStr: string, expectedWithoutASTNodes: string | undefined = schemaStr) {
+  const schema = buildSchema(schemaStr);
+  expect(print(graphQLJSSchemaToAST(schema))).toMatchString(schemaStr);
+  if (expectedWithoutASTNodes) {
+    expect(print(graphQLJSSchemaToAST(withoutASTNodes(schema)))).toMatchString(expectedWithoutASTNodes);
+  }
+}
+
+function withoutASTNodes(schema: GraphQLSchema): GraphQLSchema {
+  return buildClientSchema(introspectionFromSchema(schema));
+}
+
+it('round-trip for all type definitions', () => {
+  const schema = `
+    type Query {
+      a: A
+      b: B
+      c: C
+      d(arg: D): Int
+    }
+
+    interface I {
+      x: Int
+    }
+
+    type A implements I {
+      x: Int
+      y: Int
+    }
+
+    union B = A | Query
+
+    enum C {
+      V1
+      V2
+    }
+
+    input D {
+      m: Int
+      n: Int = 3
+    }
+  `;
+
+  validateRoundtrip(schema);
+});
+
+it('round-trip with default arguments', () => {
+  const schemaFct = (v: string) => `
+    type Query {
+      f(arg: V = ${v}): Int
+    }
+
+    input V {
+      x: Int
+      y: Int = 3
+    }
+  `;
+
+  const schema = schemaFct('{x: 2}');
+  // We go through introspection to ensure the AST nodes are
+  // removed, but that also somehow expand default values (which is
+  // fine, we just have to account for it in our assertion).
+  const schemaWithDefaultExpanded = schemaFct('{x: 2, y: 3}');
+
+  validateRoundtrip(schema, schemaWithDefaultExpanded);
+});
+
+it('round-trip for directive definitions and applications', () => {
+  const directiveDefinitions = `directive @schemaDirective(v: Int!) on SCHEMA
+
+    directive @typeDirective repeatable on OBJECT
+
+    directive @fieldDirective(s: String, m: Int = 3) on FIELD_DEFINITION
+  `;
+
+  const schema = `
+    schema @schemaDirective(v: 3) {
+      query: Query
+    }
+
+    type Query @typeDirective @typeDirective {
+      f: Int @fieldDirective(s: "foo")
+      g: Int @deprecated
+    }
+
+    ${directiveDefinitions}
+  `;
+
+  // With the ast nodes removed, we lose custom directive applications
+  const noApplications = `
+    type Query {
+      f: Int
+      g: Int @deprecated
+    }
+
+    ${directiveDefinitions}
+  `;
+
+  validateRoundtrip(schema, noApplications);
+});
+
+it('round-trip with extensions', () => {
+  const common = `scalar federation_FieldSet
+
+    scalar link_Import
+
+    directive @link(url: String!, import: link_Import) on SCHEMA
+
+    directive @key(fields: federation_FieldSet) repeatable on OBJECT
+  `;
+
+  const schema = `
+    extend schema @link(url: "https://specs.apollo.dev", import: ["@key"])
+
+    type Query {
+      t: T
+    }
+
+    type T
+
+    extend type T @key(fields: "id") {
+      id: ID!
+      x: Int
+    }
+
+    ${common}
+  `;
+
+  // No AST means we lose both the directive applications, but also whether something is an
+  // extension or not.
+  const noAST = `
+    type Query {
+      t: T
+    }
+
+    type T {
+      id: ID!
+      x: Int
+    }
+
+    ${common}
+    `;
+
+  validateRoundtrip(schema, noAST);
+});
+

package/src/__tests__/schemaUpgrader.test.ts

@@ -92,7 +92,6 @@ test('upgrade complex schema', () => {
 
   expect(res.subgraphs?.get('s1')?.toString()).toMatchString(`
     schema
-      @link(url: "https://specs.apollo.dev/link/v1.0")
       ${FEDERATION2_LINK_WTH_FULL_IMPORTS}
     {
       query: Query
@@ -149,7 +148,6 @@ test('update federation directive non-string arguments', () => {
 
   expect(res.subgraphs?.get('s')?.toString()).toMatchString(`
     schema
-      @link(url: "https://specs.apollo.dev/link/v1.0")
       ${FEDERATION2_LINK_WTH_FULL_IMPORTS}
     {
       query: Query

package/src/__tests__/subgraphValidation.test.ts

@@ -682,6 +682,19 @@ describe('@core/@link handling', () => {
 
         directive @federation__external(reason: String) on OBJECT | FIELD_DEFINITION
       `,
+      gql`
+        extend schema
+          @link(url: "https://specs.apollo.dev/federation/v2.0")
+
+        type T {
+          k: ID!
+        }
+
+        enum link__Purpose {
+          EXECUTION
+          SECURITY
+        }
+      `,
     ];
 
     // Note that we cannot use `validateFullSchema` as-is for those examples because the order or directive is going
@@ -862,6 +875,27 @@ describe('@core/@link handling', () => {
     ]]);
   });
 
+  it('errors on invalid definition for @link Purpose', () => {
+    const doc = gql`
+      extend schema
+        @link(url: "https://specs.apollo.dev/federation/v2.0")
+
+      type T {
+        k: ID!
+      }
+
+      enum link__Purpose {
+        EXECUTION
+        RANDOM
+      }
+    `;
+
+    expect(buildForErrors(doc, { asFed2: false })).toStrictEqual([[
+      'TYPE_DEFINITION_INVALID',
+      '[S] Invalid definition for type "Purpose": expected values [EXECUTION, SECURITY] but found [EXECUTION, RANDOM].',
+    ]]);
+  });
+
   it('allows any (non-scalar) type in redefinition when expected type is a scalar', () => {
     const doc = gql`
       extend schema
@@ -878,6 +912,30 @@ describe('@core/@link handling', () => {
     // Just making sure this don't error out.
     buildAndValidate(doc);
   });
+
+  it('allows defining a repeatable directive as non-repeatable but validates usages', () => {
+    const doc = gql`
+      type T @key(fields: "k1") @key(fields: "k2") {
+        k1: ID!
+        k2: ID!
+      }
+
+      directive @key(fields: String!) on OBJECT
+    `;
+
+
+    // Test for fed2 (with @key being @link-ed)
+    expect(buildForErrors(doc)).toStrictEqual([[
+      'INVALID_GRAPHQL',
+      '[S] The directive "@key" can only be used once at this location.',
+    ]]);
+
+    // Test for fed1
+    expect(buildForErrors(doc, { asFed2: false })).toStrictEqual([[
+      'INVALID_GRAPHQL',
+      '[S] The directive "@key" can only be used once at this location.',
+    ]]);
+  });
 });
 
 describe('federation 1 schema', () => {

package/src/buildSchema.ts

@@ -19,6 +19,10 @@ import {
   SchemaExtensionNode,
   parseType,
   Kind,
+  TypeDefinitionNode,
+  TypeExtensionNode,
+  EnumTypeExtensionNode,
+  EnumTypeDefinitionNode,
 } from "graphql";
 import { Maybe } from "graphql/jsutils/Maybe";
 import { valueFromASTUntyped } from "./values";
@@ -49,6 +53,7 @@ import {
   Extension,
   ErrGraphQLValidationFailed,
   errorCauses,
+  NamedSchemaElement,
 } from "./definitions";
 
 function buildValue(value?: ValueNode): any {
@@ -70,9 +75,52 @@ export function buildSchemaFromAST(
 ): Schema {
   const errors: GraphQLError[] = [];
   const schema = new Schema(options?.blueprint);
+
+  // Building schema has to proceed in a particular order due to 2 main constraints:
+  // 1. some elements can refer other elements even if the definition of those referenced elements appear later in the AST.
+  //   And in fact, definitions can be cyclic (a type having field whose type is themselves for instance). Which we
+  //   deal with by first adding empty definition for every type and directive name, because handling any of their content.
+  // 2. we accept "incomplete" schema due to `@link` (incomplete in the sense of the graphQL spec). Indeed, `@link` is all
+  //   about importing definitions, but that mean that some element may be _reference_ in the AST without their _definition_
+  //   being in the AST. So we need to ensure we "import" those definitions before we try to "build" references to them.
+
+
   // We do a first pass to add all empty types and directives definition. This ensure any reference on one of
   // those can be resolved in the 2nd pass, regardless of the order of the definitions in the AST.
-  const { directiveDefinitions, schemaDefinitions, schemaExtensions } = buildNamedTypeAndDirectivesShallow(documentNode, schema);
+  const {
+    directiveDefinitions,
+    typeDefinitions,
+    typeExtensions,
+    schemaDefinitions,
+    schemaExtensions,
+  } = buildNamedTypeAndDirectivesShallow(documentNode, schema, errors);
+
+  // We then build the content of enum types, but excluding their directive _applications. The reason we do this
+  // is that:
+  // 1. we can (enum values are self-contained and cannot reference anything that may need to be imported first; this
+  //   is also why we skip directive applications at that point, as those _may_ reference something that hasn't been imported yet)
+  // 2. this allows the code to handle better the case where the `link__Purpose` enum is provided in the AST despite the `@link` 
+  //   _definition_ not being provided. And the reason that is true is that as we later _add_ the `@link` definition, we
+  //   will need to check if `link_Purpose` needs to be added or not, but when it is already present, we check it's definition
+  //   is the expected, but that check will unexpected fail if we haven't finished "building" said type definition.
+  // Do note that we can only do that "early building" for scalar and enum types (and it happens that there is nothing to do
+  // for scalar because they are the only types whose "content" don't reference other types (and again, for definitions
+  // referencing other types, we need to import `@link`-ed definition first). Thankfully, the `@link` directive definition
+  // only rely on a scalar (`Import`) and an enum (`Purpose`) type (if that ever changes, we may have to something more here
+  // to be resilient to weirdly incomplete schema).
+  for (const typeNode of typeDefinitions) {
+    if (typeNode.kind === Kind.ENUM_TYPE_DEFINITION) {
+      buildEnumTypeValuesWithoutDirectiveApplications(typeNode, schema.type(typeNode.name.value) as EnumType);
+    }
+  }
+  for (const typeExtensionNode of typeExtensions) {
+    if (typeExtensionNode.kind === Kind.ENUM_TYPE_EXTENSION) {
+      const toExtend = schema.type(typeExtensionNode.name.value)!;
+      const extension = toExtend.newExtension();
+      extension.sourceAST = typeExtensionNode;
+      buildEnumTypeValuesWithoutDirectiveApplications(typeExtensionNode, schema.type(typeExtensionNode.name.value) as EnumType, extension);
+    }
+  }
 
   // We then deal with directive definition first. This is mainly for the sake of core schemas: the core schema
   // handling in `Schema` detects that the schema is a core one when it see the application of `@core(feature: ".../core/...")`
@@ -105,32 +153,14 @@ export function buildSchemaFromAST(
     buildDirectiveApplicationsInDirectiveDefinition(directiveDefinitionNode, schema.directive(directiveDefinitionNode.name.value)!, errors);
   }
 
-  for (const definitionNode of documentNode.definitions) {
-    switch (definitionNode.kind) {
-      case 'OperationDefinition':
-      case 'FragmentDefinition':
-        errors.push(new GraphQLError("Invalid executable definition found while building schema", definitionNode));
-        continue;
-      case 'ScalarTypeDefinition':
-      case 'ObjectTypeDefinition':
-      case 'InterfaceTypeDefinition':
-      case 'UnionTypeDefinition':
-      case 'EnumTypeDefinition':
-      case 'InputObjectTypeDefinition':
-        buildNamedTypeInner(definitionNode, schema.type(definitionNode.name.value)!, schema.blueprint, errors);
-        break;
-      case 'ScalarTypeExtension':
-      case 'ObjectTypeExtension':
-      case 'InterfaceTypeExtension':
-      case 'UnionTypeExtension':
-      case 'EnumTypeExtension':
-      case 'InputObjectTypeExtension':
-        const toExtend = schema.type(definitionNode.name.value)!;
-        const extension = toExtend.newExtension();
-        extension.sourceAST = definitionNode;
-        buildNamedTypeInner(definitionNode, toExtend, schema.blueprint, errors, extension);
-        break;
-    }
+  for (const typeNode of typeDefinitions) {
+    buildNamedTypeInner(typeNode, schema.type(typeNode.name.value)!, schema.blueprint, errors);
+  }
+  for (const typeExtensionNode of typeExtensions) {
+    const toExtend = schema.type(typeExtensionNode.name.value)!;
+    const extension = toExtend.newExtension();
+    extension.sourceAST = typeExtensionNode;
+    buildNamedTypeInner(typeExtensionNode, toExtend, schema.blueprint, errors, extension);
   }
 
   // Note: we could try calling `schema.validate()` regardless of errors building the schema and merge the resulting
@@ -149,18 +179,27 @@ export function buildSchemaFromAST(
   return schema;
 }
 
-function buildNamedTypeAndDirectivesShallow(documentNode: DocumentNode, schema: Schema): {
+function buildNamedTypeAndDirectivesShallow(documentNode: DocumentNode, schema: Schema, errors: GraphQLError[]): {
   directiveDefinitions: DirectiveDefinitionNode[],
+  typeDefinitions: TypeDefinitionNode[],
+  typeExtensions: TypeExtensionNode[],
   schemaDefinitions: SchemaDefinitionNode[],
   schemaExtensions: SchemaExtensionNode[],
 }  {
   const directiveDefinitions = [];
+  const typeDefinitions = [];
+  const typeExtensions = [];
   const schemaDefinitions = [];
   const schemaExtensions = [];
   for (const definitionNode of documentNode.definitions) {
     switch (definitionNode.kind) {
+      case 'OperationDefinition':
+      case 'FragmentDefinition':
+        errors.push(new GraphQLError("Invalid executable definition found while building schema", definitionNode));
+        continue;
       case 'SchemaDefinition':
         schemaDefinitions.push(definitionNode);
+        schema.schemaDefinition.preserveEmptyDefinition = true;
         break;
       case 'SchemaExtension':
         schemaExtensions.push(definitionNode);
@@ -171,17 +210,48 @@ function buildNamedTypeAndDirectivesShallow(documentNode: DocumentNode, schema:
       case 'UnionTypeDefinition':
       case 'EnumTypeDefinition':
       case 'InputObjectTypeDefinition':
+        typeDefinitions.push(definitionNode);
+        let type = schema.type(definitionNode.name.value);
+        // Note that the type may already exists due to an extension having been processed first, but we know we
+        // have seen 2 definitions (which is invalid) if the definition has `preserverEmptyDefnition` already set
+        // since it's only set for definitions, not extensions. 
+        // Also note that we allow to redefine built-ins.
+        if (!type || type.isBuiltIn) {
+          type = schema.addType(newNamedType(withoutTrailingDefinition(definitionNode.kind), definitionNode.name.value));
+        } else if (type.preserveEmptyDefinition)  {
+          // Note: we reuse the same error message than graphQL-js would output
+          throw new GraphQLError(`There can be only one type named "${definitionNode.name.value}"`);
+        }
+        // It's possible for the type definition to be empty, because it is valid graphQL to have:
+        //   type Foo
+        //
+        //   extend type Foo {
+        //     bar: Int
+        //   }
+        // and we need a way to distinguish between the case above, and the case where only an extension is provided.
+        // `preserveEmptyDefinition` serves that purpose.
+        // Note that we do this even if the type was already existing because an extension could have been processed
+        // first and have created the definition, but we still want to remember that the definition _does_ exists.
+        type.preserveEmptyDefinition = true;
+        break;
       case 'ScalarTypeExtension':
       case 'ObjectTypeExtension':
       case 'InterfaceTypeExtension':
       case 'UnionTypeExtension':
       case 'EnumTypeExtension':
       case 'InputObjectTypeExtension':
-        // Note that because of extensions, this may be called multiple times for the same type.
-        // But at the same time, we want to allow redefining built-in types, because some users do it.
+        typeExtensions.push(definitionNode);
         const existing = schema.type(definitionNode.name.value);
-        if (!existing || existing.isBuiltIn) {
+        // In theory, graphQL does not let you have an extension without a corresponding definition. However,
+        // 1) this is validated later, so there is no real reason to do it here and
+        // 2) we actually accept it for federation subgraph (due to federation 1 mostly as it's not strictly needed
+        //   for federation 22, but it is still supported to ease migration there too).
+        // So if the type exists, we simply create it. However, we don't set `preserveEmptyDefinition` since it
+        // is _not_ a definition.
+        if (!existing) {
           schema.addType(newNamedType(withoutTrailingDefinition(definitionNode.kind), definitionNode.name.value));
+        } else if (existing.isBuiltIn) {
+          throw new GraphQLError(`Cannot extend built-in type "${definitionNode.name.value}"`);
         }
         break;
       case 'DirectiveDefinition':
@@ -192,6 +262,8 @@ function buildNamedTypeAndDirectivesShallow(documentNode: DocumentNode, schema:
   }
   return {
     directiveDefinitions,
+    typeDefinitions,
+    typeExtensions,
     schemaDefinitions,
     schemaExtensions,
   }
@@ -293,6 +365,15 @@ function buildNamedTypeInner(
   extension?: Extension<any>,
 ) {
   switch (definitionNode.kind) {
+    case 'EnumTypeDefinition':
+    case 'EnumTypeExtension':
+      // We built enum values earlier in the `buildEnumTypeValuesWithoutDirectiveApplications`, but as the name
+      // of that method implies, we just need to finish building directive applications.
+      const enumType = type as EnumType;
+      for (const enumVal of definitionNode.values ?? []) {
+        buildAppliedDirectives(enumVal, enumType.value(enumVal.name.value)!, errors);
+      }
+      break;
     case 'ObjectTypeDefinition':
     case 'ObjectTypeExtension':
     case 'InterfaceTypeDefinition':
@@ -337,18 +418,6 @@ function buildNamedTypeInner(
         );
       }
       break;
-    case 'EnumTypeDefinition':
-    case 'EnumTypeExtension':
-      const enumType = type as EnumType;
-      for (const enumVal of definitionNode.values ?? []) {
-        const v = enumType.addValue(enumVal.name.value);
-        if (enumVal.description) {
-          v.description = enumVal.description.value;
-        }
-        v.setOfExtension(extension);
-        buildAppliedDirectives(enumVal, v, errors);
-      }
-      break;
     case 'InputObjectTypeDefinition':
     case 'InputObjectTypeExtension':
       const inputObjectType = type as InputObjectType;
@@ -360,10 +429,33 @@ function buildNamedTypeInner(
       break;
   }
   buildAppliedDirectives(definitionNode, type, errors, extension);
+  buildDescriptionAndSourceAST(definitionNode, type);
+}
+
+function buildEnumTypeValuesWithoutDirectiveApplications(
+  definitionNode: EnumTypeDefinitionNode | EnumTypeExtensionNode,
+  type: EnumType,
+  extension?: Extension<any>,
+) {
+  const enumType = type as EnumType;
+  for (const enumVal of definitionNode.values ?? []) {
+    const v = enumType.addValue(enumVal.name.value);
+    if (enumVal.description) {
+      v.description = enumVal.description.value;
+    }
+    v.setOfExtension(extension);
+  }
+  buildDescriptionAndSourceAST(definitionNode, type);
+}
+
+function buildDescriptionAndSourceAST<T extends NamedSchemaElement<T, Schema, unknown>>(
+  definitionNode: DefinitionNode & NodeWithDescription,
+  dest: T,
+) {
   if (definitionNode.description) {
-    type.description = definitionNode.description.value;
+    dest.description = definitionNode.description.value;
   }
-  type.sourceAST = definitionNode;
+  dest.sourceAST = definitionNode;
 }
 
 function buildFieldDefinitionInner(
@@ -458,8 +550,7 @@ function buildDirectiveDefinitionInnerWithoutDirectiveApplications(
   directive.repeatable = directiveNode.repeatable;
   const locations = directiveNode.locations.map(({ value }) => value as DirectiveLocation);
   directive.addLocations(...locations);
-  directive.description = directiveNode.description?.value;
-  directive.sourceAST = directiveNode;
+  buildDescriptionAndSourceAST(directiveNode, directive);
 }
 
 function buildDirectiveApplicationsInDirectiveDefinition(

package/src/coreSpec.ts

@@ -3,7 +3,7 @@ import { URL } from "url";
 import { CoreFeature, Directive, DirectiveDefinition, EnumType, ErrGraphQLAPISchemaValidationFailed, ErrGraphQLValidationFailed, InputType, ListType, NamedType, NonNullType, ScalarType, Schema, SchemaDefinition, SchemaElement } from "./definitions";
 import { sameType } from "./types";
 import { err } from '@apollo/core-schema';
-import { assert } from './utils';
+import { assert, firstOf } from './utils';
 import { ERRORS } from "./error";
 import { valueToString } from "./values";
 import { coreFeatureDefinitionIfKnown, registerKnownFeature } from "./knownCoreFeatures";
@@ -361,8 +361,8 @@ export class CoreSpecDefinition extends FeatureDefinition {
 
   // TODO: we may want to allow some `import` as argument to this method. When we do, we need to watch for imports of
   // `Purpose` and `Import` and add the types under their imported name.
-  addToSchema(schema: Schema, as?: string): GraphQLError[] {
-    const errors = this.addDefinitionsToSchema(schema, as);
+  addToSchema(schema: Schema, alias?: string): GraphQLError[] {
+    const errors = this.addDefinitionsToSchema(schema, alias);
     if (errors.length > 0) {
       return errors;
     }
@@ -370,10 +370,45 @@ export class CoreSpecDefinition extends FeatureDefinition {
     // Note: we don't use `applyFeatureToSchema` because it would complain the schema is not a core schema, which it isn't
     // until the next line.
     const args = { [this.urlArgName()]: this.toString() } as unknown as CoreOrLinkDirectiveArgs;
-    if (as) {
-      args.as = as;
+    if (alias) {
+      args.as = alias;
+    }
+
+    // This adds `@link(url: "https://specs.apollo.dev/link/v1.0")` to the "schema" definition. And we have
+    // a choice to add it either the main definition, or to an `extend schema`.
+    //
+    // In theory, always adding it to the main definition should be safe since even if some root operations
+    // can be defined in extensions, you shouldn't have an extension without a definition, and so we should
+    // never be in a case where _all_ root operations are defined in extensions (which would be a problem
+    // for printing the definition itsef since it's syntactically invalid to have a schema definition with
+    // no operations).
+    //
+    // In practice however, graphQL-js has historically accepted extensions without definition for schema,
+    // and we even abuse this a bit with federation out of convenience, so we could end up in the situation
+    // where if we put the directive on the definition, it cannot be printed properly due to the user having
+    // defined all its root operations in an extension.
+    //
+    // We could always add the directive to an extension, and that could kind of work but:
+    // 1. the core/link spec says that the link-to-link application should be the first `@link` of the
+    //   schema, but if user put some `@link` on their schema definition but we always put the link-to-link
+    //   on an extension, then we're kind of not respecting our own spec (in practice, our own code can
+    //   actually handle this as it does not strongly rely on that "it should be the first" rule, but that
+    //   would set a bad example).
+    // 2. earlier versions (pre-#1875) were always putting that directive on the definition, and we wanted
+    //   to avoid suprising users by changing that for not reason.
+    //
+    // So instead, we put the directive on the schema definition unless some extensions exists but no
+    // definition does (that is, no non-extension elements are populated).
+    const schemaDef =  schema.schemaDefinition;
+    // Side-note: this test must be done _before_ we call `applyDirective`, otherwise it would take it into
+    // account.
+    const hasDefinition = schemaDef.hasNonExtensionElements();
+    const directive = schemaDef.applyDirective(alias ?? this.url.name, args, true);
+    if (!hasDefinition && schemaDef.hasExtensionElements()) {
+      const extension = firstOf(schemaDef.extensions());
+      assert(extension, '`hasExtensionElements` should not have been `true`');
+      directive.setOfExtension(extension);
     }
-    schema.schemaDefinition.applyDirective(as ?? this.url.name, args, true);
     return [];
   }