@apollo/federation-internals 2.0.0-preview.1 → 2.0.0-preview.10

package/src/coreSpec.ts

@@ -1,10 +1,14 @@
 import { ASTNode, DirectiveLocation, GraphQLError, StringValueNode } from "graphql";
 import { URL } from "url";
-import { CoreFeature, Directive, DirectiveDefinition, EnumType, ListType, NamedType, NonNullType, ScalarType, Schema, SchemaDefinition } from "./definitions";
+import { CoreFeature, Directive, DirectiveDefinition, EnumType, ErrGraphQLValidationFailed, InputType, ListType, NamedType, NonNullType, ScalarType, Schema, SchemaDefinition } from "./definitions";
 import { sameType } from "./types";
 import { err } from '@apollo/core-schema';
 import { assert } from './utils';
 import { ERRORS } from "./error";
+import { valueToString } from "./values";
+import { coreFeatureDefinitionIfKnown, registerKnownFeature } from "./knownCoreFeatures";
+import { didYouMean, suggestionList } from "./suggestions";
+import { ArgumentSpecification, createDirectiveSpecification, createEnumTypeSpecification, createScalarTypeSpecification, DirectiveSpecification, TypeSpecification } from "./directiveAndTypeSpecification";
 
 export const coreIdentity = 'https://specs.apollo.dev/core';
 export const linkIdentity = 'https://specs.apollo.dev/link';
@@ -61,7 +65,9 @@ export abstract class FeatureDefinition {
     return nameInSchema != undefined && (directive.name === nameInSchema || directive.name.startsWith(`${nameInSchema}__`));
   }
 
-  abstract addElementsToSchema(schema: Schema): void;
+  abstract addElementsToSchema(schema: Schema): GraphQLError[];
+
+  abstract allElementNames(): string[];
 
   protected nameInSchema(schema: Schema): string | undefined {
     const feature = this.featureInSchema(schema);
@@ -73,9 +79,9 @@ export abstract class FeatureDefinition {
     return feature ? feature.directiveNameInSchema(directiveName) : undefined;
   }
 
-  protected typeNameInSchema(schema: Schema, directiveName: string): string | undefined {
+  protected typeNameInSchema(schema: Schema, typeName: string): string | undefined {
     const feature = this.featureInSchema(schema);
-    return feature ? feature.typeNameInSchema(directiveName) : undefined;
+    return feature ? feature.typeNameInSchema(typeName) : undefined;
   }
 
   protected rootDirective<TApplicationArgs extends {[key: string]: any}>(schema: Schema): DirectiveDefinition<TApplicationArgs> | undefined {
@@ -101,6 +107,14 @@ export abstract class FeatureDefinition {
     return schema.addDirectiveDefinition(this.directiveNameInSchema(schema, name)!);
   }
 
+  protected addDirectiveSpec(schema: Schema, spec: DirectiveSpecification): GraphQLError[] {
+    return spec.checkOrAdd(schema, this.directiveNameInSchema(schema, spec.name));
+  }
+
+  protected addTypeSpec(schema: Schema, spec: TypeSpecification): GraphQLError[] {
+    return spec.checkOrAdd(schema, this.typeNameInSchema(schema, spec.name));
+  }
+
   protected addScalarType(schema: Schema, name: string): ScalarType {
     return schema.addType(new ScalarType(this.typeNameInSchema(schema, name)!));
   }
@@ -144,33 +158,115 @@ export type CoreImport = {
   as?: string,
 };
 
-export function extractCoreFeatureImports(directive: Directive<SchemaDefinition, CoreOrLinkDirectiveArgs>): CoreImport[] {
+export function extractCoreFeatureImports(url: FeatureUrl, directive: Directive<SchemaDefinition, CoreOrLinkDirectiveArgs>): CoreImport[] {
+  // Note: up to this point, we've kind of cheated with typing and force-casted the arguments to `CoreOrLinkDirectiveArgs`, and while this
+  // graphQL type validations ensure this is "mostly" true, the `import' arg is an exception becuse it uses the `link__Import` scalar,
+  // and so there is no fine-grained graphQL-side validation of the values. So we'll need to double-check that the values are indeed
+  // either a string or a valid `CoreImport` value.
   const args = directive.arguments();
-  if (!('import' in args)) {
+  if (!('import' in args) || !args.import) {
     return [];
   }
-  const importArg = args.import;
-  const imports: CoreImport[] = importArg ? importArg.map((a) => typeof a === 'string' ? { name: a } : a) : [];
-  for (const i of imports) {
-    if (!i.as) {
+  const importArgValue = args.import;
+  const definition = coreFeatureDefinitionIfKnown(url);
+  const knownElements = definition?.allElementNames();
+  const errors: GraphQLError[] = [];
+  const imports: CoreImport[] = [];
+
+  importArgLoop:
+  for (const elt of importArgValue) {
+    if (typeof elt === 'string') {
+      imports.push({ name: elt });
+      validateImportedName(elt, knownElements, errors, directive);
       continue;
     }
-    if (i.name.charAt(0) === '@' && i.as.charAt(0) !== '@') {
-      throw ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
-        message: `Invalid @link import renaming: directive ${i.name} imported name should starts with a '@' character, but got "${i.as}"`,
+    if (typeof elt !== 'object') {
+      errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+        message: `Invalid sub-value ${valueToString(elt)} for @link(import:) argument: values should be either strings or input object values of the form { name: "<importedElement>", as: "<alias>" }.`,
         nodes: directive.sourceAST
-      });
+      }));
+      continue;
+    }
+    let name: string | undefined;
+    for (const [key, value] of Object.entries(elt)) {
+      switch (key) {
+        case 'name':
+          if (typeof value !== 'string') {
+            errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+              message: `Invalid value for the "name" field for sub-value ${valueToString(elt)} of @link(import:) argument: must be a string.`,
+              nodes: directive.sourceAST
+            }));
+            continue importArgLoop;
+          }
+          name = value;
+          break;
+        case 'as':
+          if (typeof value !== 'string') {
+            errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+              message: `Invalid value for the "as" field for sub-value ${valueToString(elt)} of @link(import:) argument: must be a string.`,
+              nodes: directive.sourceAST
+            }));
+            continue importArgLoop;
+          }
+          break;
+        default:
+          errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+            message: `Unknown field "${key}" for sub-value ${valueToString(elt)} of @link(import:) argument.`,
+            nodes: directive.sourceAST
+          }));
+          continue importArgLoop;
+      }
     }
-    if (i.name.charAt(0) !== '@' && i.as.charAt(0) === '@') {
-      throw ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
-        message: `Invalid @link import renaming: type ${i.name} imported name should not starts with a '@' character, but got "${i.as}" (or, if @${i.name} is a directive, then it should be refered to with a '@')`,
+    if (name) {
+      const i = elt as CoreImport;
+      imports.push(i);
+      if (i.as) {
+        if (i.name.charAt(0) === '@' && i.as.charAt(0) !== '@') {
+          errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+            message: `Invalid @link import renaming: directive "${i.name}" imported name should start with a '@' character, but got "${i.as}".`,
+            nodes: directive.sourceAST
+          }));
+        }
+        else if (i.name.charAt(0) !== '@' && i.as.charAt(0) === '@') {
+          errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+            message: `Invalid @link import renaming: type "${i.name}" imported name should not start with a '@' character, but got "${i.as}" (or, if @${i.name} is a directive, then it should be referred to with a '@').`,
+            nodes: directive.sourceAST
+          }));
+        }
+      }
+      validateImportedName(name, knownElements, errors, directive);
+    } else {
+      errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+        message: `Invalid sub-value ${valueToString(elt)} for @link(import:) argument: missing mandatory "name" field.`,
         nodes: directive.sourceAST
-      });
+      }));
     }
   }
+
+  if (errors.length > 0) {
+    throw ErrGraphQLValidationFailed(errors);
+  }
   return imports;
 }
 
+function validateImportedName(name: string, knownElements: string[] | undefined, errors: GraphQLError[], directive: Directive<SchemaDefinition>) {
+  if (knownElements && !knownElements.includes(name)) {
+    let details = '';
+    if (!name.startsWith('@') && knownElements.includes('@' + name)) {
+      details = ` Did you mean directive "@${name}"?`;
+    } else {
+      const suggestions = suggestionList(name, knownElements);
+      if (suggestions) {
+        details = didYouMean(suggestions);
+      }
+    }
+    errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+      message: `Cannot import unknown element "${name}".${details}`,
+      nodes: directive.sourceAST
+    }));
+  }
+}
+
 export function isCoreSpecDirectiveApplication(directive: Directive<SchemaDefinition, any>): directive is Directive<SchemaDefinition, CoreOrLinkDirectiveArgs> {
   const definition = directive.definition;
   if (!definition) {
@@ -184,7 +280,7 @@ export function isCoreSpecDirectiveApplication(directive: Directive<SchemaDefini
     return false;
   }
   const urlArg = definition.argument('url') ?? definition.argument('feature');
-  if (!urlArg || !sameType(urlArg.type!, new NonNullType(directive.schema().stringType()))) {
+  if (!urlArg || !isValidUrlArgumentType(urlArg.type!, directive.schema())) {
     return false;
   }
 
@@ -201,53 +297,112 @@ export function isCoreSpecDirectiveApplication(directive: Directive<SchemaDefini
   }
 }
 
+function isValidUrlArgumentType(type: InputType, schema: Schema): boolean {
+  // Note that the 'url' arg is defined as nullable (mostly for future proofing reasons) but we allow use to provide a definition
+  // where it's non-nullable (and in practice, @core (which we never generate anymore, but recognize) definition technically uses
+  // with a non-nullable argument, and some fed2 previews did if for @link, so this ensure we handle reading schema generated
+  // by those versions just fine).
+  return sameType(type, schema.stringType())
+    || sameType(type, new NonNullType(schema.stringType()));
+}
+
+const linkPurposeTypeSpec = createEnumTypeSpecification({
+  name: 'Purpose',
+  values: corePurposes.map((name) => ({ name, description: purposesDescription(name)}))
+});
+
+const linkImportTypeSpec = createScalarTypeSpecification({ name: 'Import' });
+
 export class CoreSpecDefinition extends FeatureDefinition {
+  private readonly directiveDefinitionSpec: DirectiveSpecification;
+
   constructor(version: FeatureVersion, identity: string = linkIdentity, name: string = linkDirectiveDefaultName) {
     super(new FeatureUrl(identity, name, version));
+    this.directiveDefinitionSpec = createDirectiveSpecification({
+      name,
+      locations: [DirectiveLocation.SCHEMA],
+      repeatable: true,
+      argumentFct: (schema, nameInSchema) => this.createDefinitionArgumentSpecifications(schema, nameInSchema),
+    });
+  }
+
+  private createDefinitionArgumentSpecifications(schema: Schema, nameInSchema?: string): { args: ArgumentSpecification[], errors: GraphQLError[] } {
+    const args: ArgumentSpecification[] = [
+      { name: this.urlArgName(), type: schema.stringType() },
+      { name: 'as', type: schema.stringType() },
+    ];
+    if (this.supportPurposes()) {
+      const purposeName = `${nameInSchema ?? this.url.name}__${linkPurposeTypeSpec.name}`;
+      const errors = linkPurposeTypeSpec.checkOrAdd(schema, purposeName);
+      if (errors.length > 0) {
+        return { args, errors }
+      }
+      args.push({ name: 'for', type: schema.type(purposeName) as InputType });
+    }
+    if (this.supportImport()) {
+      const importName = `${nameInSchema ?? this.url.name}__${linkImportTypeSpec.name}`;
+      const errors = linkImportTypeSpec.checkOrAdd(schema, importName);
+      if (errors.length > 0) {
+        return { args, errors }
+      }
+      args.push({ name: 'import', type: new ListType(schema.type(importName)!) });
+    }
+    return { args, errors: [] };
   }
 
-  addElementsToSchema(_: Schema): void {
+  addElementsToSchema(_: Schema): GraphQLError[] {
     // Core is special and the @core directive is added in `addToSchema` below
+    return [];
+  }
+
+  // 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);
+    if (errors.length > 0) {
+      return errors;
+    }
+
+    // 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;
+    }
+    schema.schemaDefinition.applyDirective(as ?? this.url.name, args, true);
+    return [];
   }
 
-  addToSchema(schema: Schema, as?: string) {
-    const existing = schema.coreFeatures;
-    if (existing) {
-      if (existing.coreItself.url.identity === this.identity) {
+  addDefinitionsToSchema(schema: Schema, as?: string): GraphQLError[] {
+    const existingCore = schema.coreFeatures;
+    if (existingCore) {
+      if (existingCore.coreItself.url.identity === this.identity) {
         // Already exists with the same version, let it be.
-        return;
+        return [];
       } else {
-        throw buildError(`Cannot add feature ${this} to the schema, it already uses ${existing.coreItself.url}`);
+        return [ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+          message: `Cannot add feature ${this} to the schema, it already uses ${existingCore.coreItself.url}`
+        })];
       }
     }
 
     const nameInSchema = as ?? this.url.name;
-    const core = schema.addDirectiveDefinition(nameInSchema).addLocations(DirectiveLocation.SCHEMA);
-    core.repeatable = true;
-    core.addArgument(this.urlArgName(), new NonNullType(schema.stringType()));
-    core.addArgument('as', schema.stringType());
+    return this.directiveDefinitionSpec.checkOrAdd(schema, nameInSchema);
+  }
+
+  /**
+   * The list of all the element names that can be "imported" from this feature. Importantly, directive names
+   * must start with a `@`.
+   */
+  allElementNames(): string[] {
+    const names = [ `@${this.url.name}` ];
     if (this.supportPurposes()) {
-      const purposeEnum = schema.addType(new EnumType(`${nameInSchema}__Purpose`));
-      for (const purpose of corePurposes) {
-        purposeEnum.addValue(purpose).description = purposesDescription(purpose);
-      }
-      core.addArgument('for', purposeEnum);
+      names.push('Purpose');
     }
     if (this.supportImport()) {
-      if (schema.type(`${nameInSchema}__Import`)) {
-        console.trace();
-      }
-      const importType = schema.addType(new ScalarType(`${nameInSchema}__Import`));
-      core.addArgument('import', new ListType(importType));
+      names.push('Import');
     }
-
-    // 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;
-    }
-    schema.schemaDefinition.applyDirective(nameInSchema, args);
+    return names;
   }
 
   private supportPurposes() {
@@ -280,7 +435,7 @@ export class CoreSpecDefinition extends FeatureDefinition {
     return feature.url.version;
   }
 
-  applyFeatureToSchema(schema: Schema, feature: FeatureDefinition, as?: string, purpose?: CorePurpose) {
+  applyFeatureToSchema(schema: Schema, feature: FeatureDefinition, as?: string, purpose?: CorePurpose): GraphQLError[] {
     const coreDirective = this.coreDirective(schema);
     const args = {
       [this.urlArgName()]: feature.toString(),
@@ -290,7 +445,7 @@ export class CoreSpecDefinition extends FeatureDefinition {
       args.for = purpose;
     }
     schema.schemaDefinition.applyDirective(coreDirective, args);
-    feature.addElementsToSchema(schema);
+    return feature.addElementsToSchema(schema);
   }
 
   extractFeatureUrl(args: CoreOrLinkDirectiveArgs): FeatureUrl {
@@ -548,6 +703,9 @@ export const CORE_VERSIONS = new FeatureDefinitions<CoreSpecDefinition>(coreIden
 export const LINK_VERSIONS = new FeatureDefinitions<CoreSpecDefinition>(linkIdentity)
   .add(new CoreSpecDefinition(new FeatureVersion(1, 0)));
 
+registerKnownFeature(CORE_VERSIONS);
+registerKnownFeature(LINK_VERSIONS);
+
 export function removeFeatureElements(schema: Schema, feature: CoreFeature) {
   // Removing directives first, so that when we remove types, the checks that there is no references don't fail due a directive of a the feature
   // actually using the type.