@apollo/gateway 0.300.0-alpha.3 → 2.0.0-alpha.3

package/src/config.ts

@@ -0,0 +1,227 @@
+import { GraphQLError, GraphQLSchema } from "graphql";
+import { HeadersInit } from "node-fetch";
+import { fetch } from 'apollo-server-env';
+import { GraphQLRequestContextExecutionDidStart, Logger } from "apollo-server-types";
+import { GraphQLDataSource } from './datasources/types';
+import { QueryPlan } from '@apollo/query-planner';
+import { OperationContext } from './operationContext';
+import { ServiceMap } from './executeQueryPlan';
+import { ServiceDefinition } from "@apollo/federation-internals";
+
+export type ServiceEndpointDefinition = Pick<ServiceDefinition, 'name' | 'url'>;
+
+export type Experimental_DidResolveQueryPlanCallback = ({
+  queryPlan,
+  serviceMap,
+  operationContext,
+  requestContext,
+}: {
+  readonly queryPlan: QueryPlan;
+  readonly serviceMap: ServiceMap;
+  readonly operationContext: OperationContext;
+  readonly requestContext: GraphQLRequestContextExecutionDidStart<
+    Record<string, any>
+  >;
+}) => void;
+
+interface ImplementingServiceLocation {
+  name: string;
+  path: string;
+}
+
+export interface CompositionMetadata {
+  formatVersion: number;
+  id: string;
+  implementingServiceLocations: ImplementingServiceLocation[];
+  schemaHash: string;
+}
+
+export type Experimental_DidFailCompositionCallback = ({
+  errors,
+  serviceList,
+  compositionMetadata,
+}: {
+  readonly errors: GraphQLError[];
+  readonly serviceList: ServiceDefinition[];
+  readonly compositionMetadata?: CompositionMetadata;
+}) => void;
+
+export interface ServiceDefinitionCompositionInfo {
+  serviceDefinitions: ServiceDefinition[];
+  schema: GraphQLSchema;
+  compositionMetadata?: CompositionMetadata;
+}
+
+export interface SupergraphSdlCompositionInfo {
+  schema: GraphQLSchema;
+  compositionId: string;
+  supergraphSdl: string;
+}
+
+export type CompositionInfo =
+  | ServiceDefinitionCompositionInfo
+  | SupergraphSdlCompositionInfo;
+
+export type Experimental_DidUpdateCompositionCallback = (
+  currentConfig: CompositionInfo,
+  previousConfig?: CompositionInfo,
+) => void;
+
+export type CompositionUpdate = ServiceDefinitionUpdate | SupergraphSdlUpdate;
+
+export interface ServiceDefinitionUpdate {
+  serviceDefinitions?: ServiceDefinition[];
+  compositionMetadata?: CompositionMetadata;
+  isNewSchema: boolean;
+}
+
+export interface SupergraphSdlUpdate {
+  id: string;
+  supergraphSdl: string;
+}
+
+export function isSupergraphSdlUpdate(update: CompositionUpdate): update is SupergraphSdlUpdate {
+  return 'supergraphSdl' in update;
+}
+
+export function isServiceDefinitionUpdate(
+  update: CompositionUpdate,
+): update is ServiceDefinitionUpdate {
+  return 'isNewSchema' in update;
+}
+
+/**
+ * **Note:** It's possible for a schema to be the same (`isNewSchema: false`) when
+ * `serviceDefinitions` have changed. For example, during type migration, the
+ * composed schema may be identical but the `serviceDefinitions` would differ
+ * since a type has moved from one service to another.
+ */
+export type Experimental_UpdateServiceDefinitions = (
+  config: DynamicGatewayConfig,
+) => Promise<ServiceDefinitionUpdate>;
+
+export type Experimental_UpdateSupergraphSdl = (
+  config: DynamicGatewayConfig,
+) => Promise<SupergraphSdlUpdate>;
+
+export type Experimental_UpdateComposition = (
+  config: DynamicGatewayConfig,
+) => Promise<CompositionUpdate>;
+
+interface GatewayConfigBase {
+  debug?: boolean;
+  logger?: Logger;
+  // TODO: expose the query plan in a more flexible JSON format in the future
+  // and remove this config option in favor of `exposeQueryPlan`. Playground
+  // should cutover to use the new option when it's built.
+  __exposeQueryPlanExperimental?: boolean;
+  buildService?: (definition: ServiceEndpointDefinition) => GraphQLDataSource;
+
+  // experimental observability callbacks
+  experimental_didResolveQueryPlan?: Experimental_DidResolveQueryPlanCallback;
+  experimental_didFailComposition?: Experimental_DidFailCompositionCallback;
+  experimental_didUpdateComposition?: Experimental_DidUpdateCompositionCallback;
+  experimental_pollInterval?: number;
+  experimental_approximateQueryPlanStoreMiB?: number;
+  experimental_autoFragmentization?: boolean;
+  fetcher?: typeof fetch;
+  serviceHealthCheck?: boolean;
+}
+
+export interface RemoteGatewayConfig extends GatewayConfigBase {
+  serviceList: ServiceEndpointDefinition[];
+  introspectionHeaders?:
+    | HeadersInit
+    | ((service: ServiceEndpointDefinition) => Promise<HeadersInit> | HeadersInit);
+}
+
+export interface ManagedGatewayConfig extends GatewayConfigBase {
+  /**
+   * This configuration option shouldn't be used unless by recommendation from
+   * Apollo staff.
+   */
+  schemaConfigDeliveryEndpoint?: string; // deprecated
+  uplinkEndpoints?: string[];
+  uplinkMaxRetries?: number;
+}
+
+interface ManuallyManagedServiceDefsGatewayConfig extends GatewayConfigBase {
+  experimental_updateServiceDefinitions: Experimental_UpdateServiceDefinitions;
+}
+
+interface ManuallyManagedSupergraphSdlGatewayConfig extends GatewayConfigBase {
+  experimental_updateSupergraphSdl: Experimental_UpdateSupergraphSdl
+}
+
+type ManuallyManagedGatewayConfig =
+  | ManuallyManagedServiceDefsGatewayConfig
+  | ManuallyManagedSupergraphSdlGatewayConfig;
+
+interface LocalGatewayConfig extends GatewayConfigBase {
+  localServiceList: ServiceDefinition[];
+}
+
+interface SupergraphSdlGatewayConfig extends GatewayConfigBase {
+  supergraphSdl: string;
+}
+
+export type StaticGatewayConfig = LocalGatewayConfig | SupergraphSdlGatewayConfig;
+
+type DynamicGatewayConfig =
+| ManagedGatewayConfig
+| RemoteGatewayConfig
+| ManuallyManagedGatewayConfig;
+
+export type GatewayConfig = StaticGatewayConfig | DynamicGatewayConfig;
+
+export function isLocalConfig(config: GatewayConfig): config is LocalGatewayConfig {
+  return 'localServiceList' in config;
+}
+
+export function isRemoteConfig(config: GatewayConfig): config is RemoteGatewayConfig {
+  return 'serviceList' in config;
+}
+
+export function isSupergraphSdlConfig(config: GatewayConfig): config is SupergraphSdlGatewayConfig {
+  return 'supergraphSdl' in config;
+}
+
+// A manually managed config means the user has provided a function which
+// handles providing service definitions to the gateway.
+export function isManuallyManagedConfig(
+  config: GatewayConfig,
+): config is ManuallyManagedGatewayConfig {
+  return (
+    'experimental_updateServiceDefinitions' in config ||
+    'experimental_updateSupergraphSdl' in config
+  );
+}
+
+// Managed config strictly means managed by Studio
+export function isManagedConfig(
+  config: GatewayConfig,
+): config is ManagedGatewayConfig {
+  return (
+    'schemaConfigDeliveryEndpoint' in config ||
+    (!isRemoteConfig(config) &&
+      !isLocalConfig(config) &&
+      !isSupergraphSdlConfig(config) &&
+      !isManuallyManagedConfig(config))
+  );
+}
+
+// A static config is one which loads synchronously on start and never updates
+export function isStaticConfig(config: GatewayConfig): config is StaticGatewayConfig {
+  return isLocalConfig(config) || isSupergraphSdlConfig(config);
+}
+
+// A dynamic config is one which loads asynchronously and (can) update via polling
+export function isDynamicConfig(
+  config: GatewayConfig,
+): config is DynamicGatewayConfig {
+  return (
+    isRemoteConfig(config) ||
+    isManagedConfig(config) ||
+    isManuallyManagedConfig(config)
+  );
+}

package/src/core/__tests__/core.test.ts

@@ -0,0 +1,412 @@
+import { ApolloGateway } from '../../..';
+import { graphqlErrorSerializer } from 'apollo-federation-integration-testsuite';
+
+expect.addSnapshotSerializer(graphqlErrorSerializer);
+
+describe('core v0.1', () => {
+  it('throws no errors when using a valid @core v0.1 document', () => {
+    const supergraphSdl = `#graphql
+      schema
+        @core(feature: "https://specs.apollo.dev/core/v0.1")
+        @core(feature: "https://specs.apollo.dev/join/v0.1") {
+        query: Query
+      }
+
+      directive @core(feature: String!) repeatable on SCHEMA
+
+      directive @join__field(
+        graph: join__Graph
+        requires: join__FieldSet
+        provides: join__FieldSet
+      ) on FIELD_DEFINITION
+
+      directive @join__type(
+        graph: join__Graph!
+        key: join__FieldSet
+      ) repeatable on OBJECT | INTERFACE
+
+      directive @join__owner(graph: join__Graph!) on OBJECT | INTERFACE
+
+      directive @join__graph(name: String!, url: String!) on ENUM_VALUE
+
+      directive @tag(
+        name: String!
+      ) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION
+
+      enum CacheControlScope {
+        PRIVATE
+        PUBLIC
+      }
+
+      scalar join__FieldSet
+
+      enum join__Graph {
+        WORLD @join__graph(name: "world", url: "https://world.api.com.invalid")
+      }
+
+      type Query {
+        hello: String! @join__field(graph: WORLD)
+      }
+    `;
+
+    const gateway = new ApolloGateway({
+      supergraphSdl,
+    });
+
+    expect(gateway.load()).resolves.toBeTruthy();
+  });
+
+  it('throws an error when the `for:` @core argument is used in a v0.1 document', () => {
+    const supergraphSdl = `#graphql
+      schema
+        @core(feature: "https://specs.apollo.dev/core/v0.1")
+        @core(feature: "https://specs.apollo.dev/join/v0.1", for: EXECUTION)
+        @core(
+          feature: "https://specs.apollo.dev/something-unsupported/v0.1"
+          for: SECURITY
+        ) {
+        query: Query
+      }
+
+      directive @core(feature: String!) repeatable on SCHEMA
+
+      directive @join__field(
+        graph: join__Graph
+        requires: join__FieldSet
+        provides: join__FieldSet
+      ) on FIELD_DEFINITION
+
+      directive @join__type(
+        graph: join__Graph!
+        key: join__FieldSet
+      ) repeatable on OBJECT | INTERFACE
+
+      directive @join__owner(graph: join__Graph!) on OBJECT | INTERFACE
+
+      directive @join__graph(name: String!, url: String!) on ENUM_VALUE
+
+      directive @tag(
+        name: String!
+      ) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION
+
+      enum CacheControlScope {
+        PRIVATE
+        PUBLIC
+      }
+
+      scalar join__FieldSet
+
+      enum join__Graph {
+        WORLD @join__graph(name: "world", url: "https://world.api.com.invalid")
+      }
+
+      type Query {
+        hello: String! @join__field(graph: WORLD)
+      }
+    `;
+
+    const gateway = new ApolloGateway({
+      supergraphSdl,
+    });
+
+    expect(() => gateway.load()).rejects.toMatchInlineSnapshot(`
+      Array [
+        "the \`for:\` argument is unsupported by version v0.1 of the core spec. Please upgrade to at least @core v0.2 (https://specs.apollo.dev/core/v0.2).",
+        "feature https://specs.apollo.dev/something-unsupported/v0.1 is for: SECURITY but is unsupported",
+      ]
+    `);
+  });
+});
+
+describe('core v0.2', () => {
+  it("doesn't throw errors when using supported features", async () => {
+    const supergraphSdl = `#graphql
+      schema
+        @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
+      }
+
+      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
+
+      directive @join__type(
+        graph: join__Graph!
+        key: join__FieldSet
+      ) repeatable on OBJECT | INTERFACE
+
+      directive @join__owner(graph: join__Graph!) on OBJECT | INTERFACE
+
+      directive @join__graph(name: String!, url: String!) on ENUM_VALUE
+
+      directive @tag(
+        name: String!
+      ) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION
+
+      enum CacheControlScope {
+        PRIVATE
+        PUBLIC
+      }
+
+      enum core__Purpose {
+        """
+        \`EXECUTION\` features provide metadata necessary to for operation execution.
+        """
+        EXECUTION
+
+        """
+        \`SECURITY\` features provide metadata necessary to securely resolve fields.
+        """
+        SECURITY
+      }
+
+      scalar join__FieldSet
+
+      enum join__Graph {
+        WORLD @join__graph(name: "world", url: "https://world.api.com.invalid")
+      }
+
+      type Query {
+        hello: String! @join__field(graph: WORLD)
+      }
+    `;
+
+    const gateway = new ApolloGateway({
+      supergraphSdl,
+    });
+
+    expect(gateway.load()).resolves.toBeTruthy();
+  });
+
+  it("doesn't throw errors when using unsupported features which have no `for:` argument", async () => {
+    const supergraphSdl = `#graphql
+      schema
+        @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")
+        @core(feature: "https://specs.apollo.dev/unsupported-feature/v0.1") {
+        query: Query
+      }
+
+      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
+
+      directive @join__type(
+        graph: join__Graph!
+        key: join__FieldSet
+      ) repeatable on OBJECT | INTERFACE
+
+      directive @join__owner(graph: join__Graph!) on OBJECT | INTERFACE
+
+      directive @join__graph(name: String!, url: String!) on ENUM_VALUE
+
+      directive @tag(
+        name: String!
+      ) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION
+
+      enum CacheControlScope {
+        PRIVATE
+        PUBLIC
+      }
+
+      enum core__Purpose {
+        """
+        \`EXECUTION\` features provide metadata necessary to for operation execution.
+        """
+        EXECUTION
+
+        """
+        \`SECURITY\` features provide metadata necessary to securely resolve fields.
+        """
+        SECURITY
+      }
+
+      scalar join__FieldSet
+
+      enum join__Graph {
+        WORLD @join__graph(name: "world", url: "https://world.api.com.invalid")
+      }
+
+      type Query {
+        hello: String! @join__field(graph: WORLD)
+      }
+    `;
+
+    const gateway = new ApolloGateway({
+      supergraphSdl,
+    });
+
+    expect(gateway.load()).resolves.toBeTruthy();
+  });
+
+  it('throws errors when using unsupported features for EXECUTION', () => {
+    const supergraphSdl = `#graphql
+      schema
+        @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/unsupported-feature/v0.1"
+          for: EXECUTION
+        ) {
+        query: Query
+      }
+
+      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
+
+      directive @join__type(
+        graph: join__Graph!
+        key: join__FieldSet
+      ) repeatable on OBJECT | INTERFACE
+
+      directive @join__owner(graph: join__Graph!) on OBJECT | INTERFACE
+
+      directive @join__graph(name: String!, url: String!) on ENUM_VALUE
+
+      directive @tag(
+        name: String!
+      ) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION
+
+      enum CacheControlScope {
+        PRIVATE
+        PUBLIC
+      }
+
+      enum core__Purpose {
+        """
+        \`EXECUTION\` features provide metadata necessary to for operation execution.
+        """
+        EXECUTION
+
+        """
+        \`SECURITY\` features provide metadata necessary to securely resolve fields.
+        """
+        SECURITY
+      }
+
+      scalar join__FieldSet
+
+      enum join__Graph {
+        WORLD @join__graph(name: "world", url: "https://world.api.com.invalid")
+      }
+
+      type Query {
+        hello: String! @join__field(graph: WORLD)
+      }
+    `;
+
+    const gateway = new ApolloGateway({
+      supergraphSdl,
+    });
+
+    expect(() => gateway.load()).rejects.toMatchInlineSnapshot(`
+      Array [
+        "feature https://specs.apollo.dev/unsupported-feature/v0.1 is for: EXECUTION but is unsupported",
+      ]
+    `);
+  });
+
+  it('throws errors when using unsupported features for SECURITY', async () => {
+    const supergraphSdl = `#graphql
+      schema
+        @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/unsupported-feature/v0.1"
+          for: SECURITY
+        ) {
+        query: Query
+      }
+
+      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
+
+      directive @join__type(
+        graph: join__Graph!
+        key: join__FieldSet
+      ) repeatable on OBJECT | INTERFACE
+
+      directive @join__owner(graph: join__Graph!) on OBJECT | INTERFACE
+
+      directive @join__graph(name: String!, url: String!) on ENUM_VALUE
+
+      directive @tag(
+        name: String!
+      ) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION
+
+      enum CacheControlScope {
+        PRIVATE
+        PUBLIC
+      }
+
+      enum core__Purpose {
+        """
+        \`EXECUTION\` features provide metadata necessary to for operation execution.
+        """
+        EXECUTION
+
+        """
+        \`SECURITY\` features provide metadata necessary to securely resolve fields.
+        """
+        SECURITY
+      }
+
+      scalar join__FieldSet
+
+      enum join__Graph {
+        WORLD @join__graph(name: "world", url: "https://world.api.com.invalid")
+      }
+
+      type Query {
+        hello: String! @join__field(graph: WORLD)
+      }
+    `;
+
+    const gateway = new ApolloGateway({
+      supergraphSdl,
+    });
+
+    expect(() => gateway.load()).rejects.toMatchInlineSnapshot(`
+      Array [
+        "feature https://specs.apollo.dev/unsupported-feature/v0.1 is for: SECURITY but is unsupported",
+      ]
+    `);
+  });
+});

package/src/datasources/LocalGraphQLDataSource.ts

@@ -1,4 +1,4 @@
-import { GraphQLRequestContext, GraphQLResponse } from 'apollo-server-types';
+import { GraphQLResponse } from 'apollo-server-types';
 import {
   GraphQLSchema,
   graphql,
@@ -6,12 +6,13 @@ import {
   DocumentNode,
   parse,
 } from 'graphql';
-import { GraphQLDataSource } from './types';
-import {
-  enablePluginsForSchemaResolvers,
-} from 'apollo-server-core/dist/utils/schemaInstrumentation';
+import { enablePluginsForSchemaResolvers } from 'apollo-server-core/dist/utils/schemaInstrumentation';
+import { GraphQLDataSource, GraphQLDataSourceProcessOptions } from './types';
 
-export class LocalGraphQLDataSource<TContext extends Record<string, any> = Record<string, any>> implements GraphQLDataSource<TContext> {
+export class LocalGraphQLDataSource<
+  TContext extends Record<string, any> = Record<string, any>,
+> implements GraphQLDataSource<TContext>
+{
   constructor(public readonly schema: GraphQLSchema) {
     enablePluginsForSchemaResolvers(schema);
   }
@@ -19,9 +20,7 @@ export class LocalGraphQLDataSource<TContext extends Record<string, any> = Recor
   async process({
     request,
     context,
-  }: Pick<GraphQLRequestContext<TContext>, 'request' | 'context'>): Promise<
-    GraphQLResponse
-  > {
+  }: GraphQLDataSourceProcessOptions<TContext>): Promise<GraphQLResponse> {
     return graphql({
       schema: this.schema,
       source: request.query!,
@@ -37,7 +36,7 @@ export class LocalGraphQLDataSource<TContext extends Record<string, any> = Recor
       source: `{ _service { sdl }}`,
     });
     if (result.errors) {
-      throw new Error(result.errors.map(error => error.message).join('\n\n'));
+      throw new Error(result.errors.map((error) => error.message).join('\n\n'));
     }
 
     const sdl = result.data && result.data._service && result.data._service.sdl;