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

package/src/federation.ts

@@ -1013,6 +1013,56 @@ function isFedSpecLinkDirective(directive: Directive<SchemaDefinition>): directi
 }
 
 function completeFed1SubgraphSchema(schema: Schema): GraphQLError[] {
+
+  // We special case @key, @requires and @provides because we've seen existing user schema where those
+  // have been defined in an invalid way, but in a way that fed1 wasn't rejecting. So for convenience,
+  // if we detect one of those case, we just remove the definition and let the code afteward add the
+  // proper definition back.
+  // Note that, in a perfect world, we'd do this within the `SchemaUpgrader`. But the way the code
+  // is organised, this method is called before we reach the `SchemaUpgrader`, and it doesn't seem
+  // worth refactoring things drastically for that minor convenience.
+  for (const spec of [keyDirectiveSpec, providesDirectiveSpec, requiresDirectiveSpec]) {
+    const directive = schema.directive(spec.name);
+    if (!directive) {
+      continue;
+    }
+
+    // We shouldn't have applications at the time of this writing because `completeSubgraphSchema`, which calls this,
+    // is only called:
+    // 1. during schema parsing, by `FederationBluePrint.onDirectiveDefinitionAndSchemaParsed`, and that is called
+    //   before we process any directive applications.
+    // 2. by `setSchemaAsFed2Subgraph`, but as the name imply, this trickles to `completeFed2SubgraphSchema`, not
+    //   this one method.
+    // In other words, there is currently no way to create a full fed1 schema first, and get that method called
+    // second. If that changes (no real reason but...), we'd have to modify this because when we remove the
+    // definition to re-add the "correct" version, we'd have to re-attach existing applications (doable but not
+    // done). This assert is so we notice it quickly if that ever happens (again, unlikely, because fed1 schema
+    // is a backward compatibility thing and there is no reason to expand that too much in the future).
+    assert(directive.applications().length === 0, `${directive} shouldn't have had validation at that places`);
+
+    // The patterns we recognize and "correct" (by essentially ignoring the definition)
+    // are:
+    //  1. if the definition has no arguments at all.
+    //  2. if the `fields` argument is declared as nullable.
+    //  3. if the `fields` argument type is named "FieldSet" instead of "_FieldSet".
+    //
+    // Note that they all correspong to things we've seen in use schema.
+    const fieldType = directive.argument('fields')?.type?.toString();
+    // Note that to be on the safe side, we check that `fields` is the only argument. That's
+    // because while fed2 accepts the optional `resolvable` arg for @key, fed1 only ever
+    // accepted that one argument for all those directives. But if the use had definited
+    // more arguments _and_ provided value for such extra argument in some applications,
+    // us removing the definition would create validation errors that would be hard to
+    // understand for the user.
+    const fieldTypeIsWrongInKnownWays = !!fieldType
+      && directive.arguments().length === 1
+      && (fieldType === 'String' || fieldType === '_FieldSet' || fieldType === 'FieldSet');
+
+    if (directive.arguments().length === 0 || fieldTypeIsWrongInKnownWays) {
+      directive.remove();
+    }
+  }
+
   return [
     fieldSetTypeSpec.checkOrAdd(schema, '_' + fieldSetTypeSpec.name),
     keyDirectiveSpec.checkOrAdd(schema),

package/src/genErrorCodeDoc.ts

@@ -12,10 +12,10 @@ When Apollo Gateway attempts to **compose** the schemas provided by your [subgra
 * The resulting supergraph schema is valid
 * The gateway has all of the information it needs to execute operations against the resulting schema
 
-If Apollo Gateway encounters an error, composition fails. This document lists subgraphs and composition error codes and their root causes.
+If Apollo Gateway encounters an error, composition fails. This document lists subgraph validation and composition error codes, along with their root causes.
 `;
 
-function makeMardownArray(
+function makeMarkdownArray(
   headers: string[],
   rows: string[][]
 ): string {
@@ -45,12 +45,15 @@ rows.sort(sortRowsByCode);
 
 const errorsSection = `## Errors
 
-The following errors may be raised by composition:
+The following errors might be raised during composition:
 
-` + makeMardownArray(
+<div class="sticky-table">
+
+${makeMarkdownArray(
   [ 'Code', 'Description', 'Since', 'Comment' ],
   rows
-);
+)}
+</div>`;
 
 const removedErrors = REMOVED_ERRORS
   .map(([code, comment]) => ['`' + code + '`', comment])
@@ -58,9 +61,12 @@ const removedErrors = REMOVED_ERRORS
 
 const removedSection = `## Removed codes
 
-The following section lists code that have been removed and are not longer generated by the gateway version this is the documentation for.
+The following error codes have been removed and are no longer generated by the most recent version of the \`@apollo/gateway\` library:
+
+<div class="sticky-table">
 
-` + makeMardownArray(['Removed Code', 'Comment'], removedErrors);
+${makeMarkdownArray(['Removed Code', 'Comment'], removedErrors)}
+</div>`;
 
 console.log(
   header + '\n\n'

package/src/inaccessibleSpec.ts

@@ -211,8 +211,18 @@ function validateInaccessibleElements(
     ) {
       // These are top-level elements. If they're not @inaccessible, the only
       // way they won't be in the API schema is if they're definitions of some
-      // core feature.
-      return !isFeatureDefinition(element);
+      // core feature. However, we do intend on introducing mechanisms for
+      // exposing core feature elements in the API schema in the near feature.
+      // Because such mechanisms aren't completely nailed down yet, we opt to
+      // pretend here that all core feature elements are in the API schema for
+      // simplicity sake.
+      //
+      // This has the effect that if a non-core schema element is referenced by
+      // a core schema element, that non-core schema element can't be marked
+      // @inaccessible, despite that the core schema element may likely not be
+      // in the API schema. This may be relaxed in a later version of the
+      // inaccessible spec.
+      return true;
     } else if (
       (element instanceof FieldDefinition) ||
       (element instanceof ArgumentDefinition) ||

package/src/operations.ts

@@ -42,6 +42,7 @@ import {
   typenameFieldName,
   NamedType,
 } from "./definitions";
+import { sameType } from "./types";
 import { assert, mapEntries, MapWithCachedArrays, MultiMap } from "./utils";
 import { argumentsEquals, argumentsFromAST, isValidValue, valueToAST, valueToString } from "./values";
 
@@ -305,6 +306,37 @@ export function sameOperationPaths(p1: OperationPath, p2: OperationPath): boolea
   return true;
 }
 
+export function concatOperationPaths(head: OperationPath, tail: OperationPath): OperationPath {
+  // While this is mainly a simple array concatenation, we optimize slightly by recognizing if the
+  // tail path starts by a fragment selection that is useless given the end of the head path.
+  if (head.length === 0) {
+    return tail;
+  }
+  if (tail.length === 0) {
+    return head;
+  }
+  const lastOfHead = head[head.length - 1];
+  const firstOfTail = tail[0];
+  if (isUselessFollowupElement(lastOfHead, firstOfTail)) {
+    tail = tail.slice(1);
+  }
+  return head.concat(tail);
+}
+
+function isUselessFollowupElement(first: OperationElement, followup: OperationElement): boolean {
+  const typeOfFirst = first.kind === 'Field'
+    ? baseType(first.definition.type!)
+    : first.typeCondition;
+
+  // The followup is useless if it's a fragment (with no directives we would want to preserve) whose type
+  // is already that of the first element.
+  return !!typeOfFirst
+    && followup.kind === 'FragmentElement'
+    && !!followup.typeCondition
+    && followup.appliedDirectives.length === 0
+    && sameType(typeOfFirst, followup.typeCondition);
+}
+
 export type RootOperationPath = {
   rootKind: SchemaRootKind,
   path: OperationPath
@@ -504,7 +536,56 @@ export class NamedFragments {
   }
 }
 
-export class SelectionSet {
+abstract class Freezable<T> {
+  private _isFrozen: boolean = false;
+
+  protected abstract us(): T;
+
+  /**
+   * Freezes this selection/selection set, making it immutable after that point (that is, attempts to modify it will error out).
+   *
+   * This method should be used when a selection/selection set should not be modified. It ensures both that:
+   *  1. direct attempts to modify the selection afterward fails (at runtime, but the goal is to fetch bugs early and easily).
+   *  2. if this selection/selection set is "added" to another non-frozen selection (say, if this is input to `anotherSet.mergeIn(this)`),
+   *   then it is automatically cloned first (thus ensuring this copy is not modified). Note that this properly is not guaranteed for
+   *   non frozen selections. Meaning that if one does `s1.mergeIn(s2)` and `s2` is not frozen, then `s1` may (or may not) reference
+   *   `s2` directly (without cloning) and thus later modifications to `s1` may (or may not) modify `s2`. This
+   *   do-not-defensively-clone-by-default behaviour is done for performance reasons.
+   *
+   * Note that freezing is a "deep" operation, in that the whole structure of the selection/selection set is frozen by this method
+   * (and so this is not an excessively cheap operation).
+   *
+   * @return this selection/selection set (for convenience, to allow method chaining).
+   */
+  freeze(): T {
+    if (!this.isFrozen()) {
+      this.freezeInternals();
+      this._isFrozen = true;
+    }
+    return this.us();
+  }
+
+  protected abstract freezeInternals(): void;
+
+  /**
+   * Whether this selection/selection set is frozen. See `freeze` for details.
+   */
+  isFrozen(): boolean {
+    return this._isFrozen;
+  }
+
+  /**
+   * A shortcut for returning a mutable version of this selection/selection set by cloning it if it is frozen, but returning this set directly
+   * if it is not frozen.
+   */
+  cloneIfFrozen(): T {
+    return this.isFrozen() ? this.clone() : this.us();
+  }
+
+  abstract clone(): T;
+}
+
+export class SelectionSet extends Freezable<SelectionSet> {
   // The argument is either the responseName (for fields), or the type name (for fragments), with the empty string being used as a special
   // case for a fragment with no type condition.
   private readonly _selections = new MultiMap<string, Selection>();
@@ -515,9 +596,14 @@ export class SelectionSet {
     readonly parentType: CompositeType,
     readonly fragments?: NamedFragments
   ) {
+    super();
     validate(!isLeafType(parentType), () => `Cannot have selection on non-leaf type ${parentType}`);
   }
 
+  protected us(): SelectionSet {
+    return this;
+  }
+
   selections(reversedOrder: boolean = false): readonly Selection[] {
     if (!this._cachedSelections) {
       const selections = new Array(this._selectionCount);
@@ -604,18 +690,66 @@ export class SelectionSet {
     return withExpanded;
   }
 
+  /**
+   * Returns the selection select from filtering out any selection that does not match the provided predicate.
+   *
+   * Please that this method will expand *ALL* fragments as the result of applying it's filtering. You should
+   * call `optimize` on the result if you want to re-apply some fragments.
+   */
+  filter(predicate: (selection: Selection) => boolean): SelectionSet {
+    const filtered = new SelectionSet(this.parentType, this.fragments);
+    for (const selection of this.selections()) {
+      const filteredSelection = selection.filter(predicate);
+      if (filteredSelection) {
+        filtered.add(filteredSelection);
+      }
+    }
+    return filtered;
+  }
+
+  protected freezeInternals(): void {
+    for (const selection of this.selections()) {
+      selection.freeze();
+    }
+  }
+
+  /**
+   * Adds the selections of the provided selection set to this selection, merging common selection as necessary.
+   *
+   * Please note that by default, the selection from the input may (or may not) be directly referenced by this selection
+   * set after this method return. That is, future modification of this selection set may end up modifying the input
+   * set due to direct aliasing. If direct aliasing should be prevented, the input selection set should be frozen (see
+   * `freeze` for details).
+   */
   mergeIn(selectionSet: SelectionSet) {
     for (const selection of selectionSet.selections()) {
       this.add(selection);
     }
   }
 
+  /**
+   * Adds the provided selections to this selection, merging common selection as necessary.
+   *
+   * This is very similar to `mergeIn` except that it takes a direct array of selection, and the direct aliasing
+   * remarks from `mergeInd` applies here too.
+   */
   addAll(selections: Selection[]): SelectionSet {
     selections.forEach(s => this.add(s));
     return this;
   }
 
+  /**
+   * Adds the provided selection to this selection, merging it to any existing selection of this set as appropriate.
+   *
+   * Please note that by default, the input selection may (or may not) be directly referenced by this selection
+   * set after this method return. That is, future modification of this selection set may end up modifying the input
+   * selection due to direct aliasing. If direct aliasing should be prevented, the input selection should be frozen
+   * (see `freeze` for details).
+   */
   add(selection: Selection): Selection {
+    // It's a bug to try to add to a frozen selection set
+    assert(!this.isFrozen(), () => `Cannot add to frozen selection: ${this}`);
+
     const toAdd = selection.updateForAddingTo(this);
     const key = toAdd.key();
     const existing: Selection[] | undefined = this._selections.get(key);
@@ -902,7 +1036,7 @@ export function selectionSetOfPath(path: OperationPath, onPathEnd?: (finalSelect
 
 export type Selection = FieldSelection | FragmentSelection;
 
-export class FieldSelection {
+export class FieldSelection extends Freezable<FieldSelection> {
   readonly kind = 'FieldSelection' as const;
   readonly selectionSet?: SelectionSet;
 
@@ -910,9 +1044,14 @@ export class FieldSelection {
     readonly field: Field<any>,
     initialSelectionSet? : SelectionSet
   ) {
+    super();
     const type = baseType(field.definition.type!);
     // Field types are output type, and a named typethat is an output one and isn't a leaf is guaranteed to be selectable.
-    this.selectionSet = isLeafType(type) ? undefined : (initialSelectionSet ? initialSelectionSet : new SelectionSet(type as CompositeType));
+    this.selectionSet = isLeafType(type) ? undefined : (initialSelectionSet ? initialSelectionSet.cloneIfFrozen() : new SelectionSet(type as CompositeType));
+  }
+
+  protected us(): FieldSelection {
+    return this;
   }
 
   key(): string {
@@ -940,6 +1079,20 @@ export class FieldSelection {
       : new FieldSelection(this.field, optimizedSelection);
   }
 
+  filter(predicate: (selection: Selection) => boolean): FieldSelection | undefined {
+    if (!predicate(this)) {
+      return undefined;
+    }
+    if (!this.selectionSet) {
+      return this;
+    }
+    return new FieldSelection(this.field, this.selectionSet.filter(predicate));
+  }
+
+  protected freezeInternals(): void {
+    this.selectionSet?.freeze();
+  }
+
   expandFragments(names?: string[], updateSelectionSetFragments: boolean = true): FieldSelection {
     const expandedSelection = this.selectionSet ? this.selectionSet.expandFragments(names, updateSelectionSetFragments) : undefined;
     return this.selectionSet === expandedSelection
@@ -975,7 +1128,9 @@ export class FieldSelection {
 
   updateForAddingTo(selectionSet: SelectionSet): FieldSelection {
     const updatedField = this.field.updateForAddingTo(selectionSet);
-    return this.field === updatedField ? this : new FieldSelection(updatedField, this.selectionSet);
+    return this.field === updatedField
+      ? this.cloneIfFrozen()
+      : new FieldSelection(updatedField, this.selectionSet?.cloneIfFrozen());
   }
 
   toSelectionNode(): FieldNode {
@@ -1034,7 +1189,7 @@ export class FieldSelection {
   }
 }
 
-export abstract class FragmentSelection {
+export abstract class FragmentSelection extends Freezable<FragmentSelection> {
   readonly kind = 'FragmentSelection' as const;
 
   abstract key(): string;
@@ -1055,6 +1210,9 @@ export abstract class FragmentSelection {
 
   abstract validate(): void;
 
+  protected us(): FragmentSelection {
+    return this;
+  }
 
   usedVariables(): Variables {
     return mergeVariables(this.element().variables(), this.selectionSet.usedVariables());
@@ -1062,7 +1220,21 @@ export abstract class FragmentSelection {
 
   updateForAddingTo(selectionSet: SelectionSet): FragmentSelection {
     const updatedFragment = this.element().updateForAddingTo(selectionSet);
-    return this.element() === updatedFragment ? this : new InlineFragmentSelection(updatedFragment, this.selectionSet);
+    return this.element() === updatedFragment
+      ? this.cloneIfFrozen()
+      : new InlineFragmentSelection(updatedFragment, this.selectionSet.cloneIfFrozen());
+  }
+
+  filter(predicate: (selection: Selection) => boolean): InlineFragmentSelection | undefined {
+    if (!predicate(this)) {
+      return undefined;
+    }
+    // Note that we essentially expand all fragments as part of this.
+    return new InlineFragmentSelection(this.element(), this.selectionSet.filter(predicate));
+  }
+
+  protected freezeInternals() {
+    this.selectionSet.freeze();
   }
 
   equals(that: Selection): boolean {
@@ -1095,7 +1267,7 @@ class InlineFragmentSelection extends FragmentSelection {
     super();
     // TODO: we should do validate the type of the initial selection set.
     this._selectionSet = initialSelectionSet
-      ? initialSelectionSet
+      ? initialSelectionSet.cloneIfFrozen()
       : new SelectionSet(fragmentElement.typeCondition ? fragmentElement.typeCondition : fragmentElement.parentType);
   }
 
@@ -1144,7 +1316,6 @@ class InlineFragmentSelection extends FragmentSelection {
     };
   }
 
-
   optimize(fragments: NamedFragments): FragmentSelection {
     const optimizedSelection = this.selectionSet.optimize(fragments);
     const typeCondition = this.element().typeCondition;

package/src/schemaUpgrader.ts

@@ -7,6 +7,7 @@ import {
 import { ERRORS } from "./error";
 import {
   baseType,
+  CompositeType,
   Directive,
   errorCauses,
   Extension,
@@ -33,6 +34,7 @@ import {
 } from "./federation";
 import { assert, firstOf, MultiMap } from "./utils";
 import { FEDERATION_SPEC_TYPES } from "./federationSpec";
+import { valueEquals } from "./values";
 
 export type UpgradeResult = UpgradeSuccess | UpgradeFailure;
 
@@ -66,6 +68,7 @@ export type UpgradeChange =
   | ProvidesOrRequiresOnInterfaceFieldRemoval
   | ProvidesOnNonCompositeRemoval
   | FieldsArgumentCoercionToString
+  | RemovedTagOnExternal
 ;
 
 export class ExternalOnTypeExtensionRemoval {
@@ -198,6 +201,16 @@ export class FieldsArgumentCoercionToString {
   }
 }
 
+export class RemovedTagOnExternal {
+  readonly id = 'REMOVED_TAG_ON_EXTERNAL' as const;
+
+  constructor(readonly application: string, readonly element: string) {}
+
+  toString() {
+    return `Removed ${this.application} application on @external "${this.element}" as the @tag application is on another definition`;
+  }
+}
+
 export function upgradeSubgraphsIfNecessary(inputs: Subgraphs): UpgradeResult {
   const changes: Map<string, UpgradeChanges> = new Map();
   if (inputs.values().every((s) => s.isFed2Subgraph())) {
@@ -265,6 +278,11 @@ function resolvesField(subgraph: Subgraph, field: FieldDefinition<ObjectType>):
   return !!f && (!metadata.isFieldExternal(f) || metadata.isFieldPartiallyExternal(f));
 }
 
+function getField(schema: Schema, typeName: string, fieldName: string): FieldDefinition<CompositeType> | undefined {
+  const type = schema.type(typeName);
+  return type && isCompositeType(type) ? type.field(fieldName) : undefined;
+}
+
 class SchemaUpgrader {
   private readonly changes = new MultiMap<UpgradeChangeID, UpgradeChange>();
   private readonly schema: Schema;
@@ -384,6 +402,8 @@ class SchemaUpgrader {
 
     this.addShareable();
 
+    this.removeTagOnExternal();
+
     // If we had errors during the upgrade, we throw them before trying to validate the resulting subgraph, because any invalidity in the
     // migrated subgraph may well due to those migration errors and confuse users.
     if (this.errors.length > 0) {
@@ -670,4 +690,29 @@ class SchemaUpgrader {
       }
     }
   }
+
+  private removeTagOnExternal() {
+    const tagDirective = this.schema.directive('tag');
+    if (!tagDirective) {
+      return;
+    }
+
+    for (const application of tagDirective.applications()) {
+      const element = application.parent;
+      if (!(element instanceof FieldDefinition)) {
+        continue;
+      }
+      if (this.external(element)) {
+        const tagIsUsedInOtherDefinition = this.otherSubgraphs
+          .map((s) => getField(s.schema, element.parent.name, element.name))
+          .filter((f) => !(f && f.hasAppliedDirective('external')))
+          .some((f) => f && f.appliedDirectivesOf('tag').some((d) => valueEquals(application.arguments(), d.arguments())));
+
+        if (tagIsUsedInOtherDefinition) {
+          this.addChange(new RemovedTagOnExternal(application.toString(), element.coordinate));
+          application.remove();
+        }
+      }
+    }
+  }
 }