Gateway support via new @apollo/server-gateway-interface package

.changeset/eleven-needles-collect.md

@@ -0,0 +1,6 @@
+---
+"@apollo/server-integration-testsuite": patch
+"@apollo/server": patch
+---
+
+Support Gateway. Remove executor constructor option.

docs/source/migration.mdx

@@ -359,7 +359,7 @@ If supporting older versions of TypeScript is important to you and you'd like to
 
 ### `@apollo/gateway`
 
-<!-- TODO(AS4): Fix before release -->
+<!-- TODO(AS4): Fix before release. This now works at runtime; TS builds may require a new release of Gateway, and we'll update the docs when that's ready. -->
 
 > ⚠️ Note: The alpha version of Apollo Server 4 does **not** work as an [Apollo Gateway](/federation/gateway). You can still use this alpha to serve [subgraphs](/federation/subgraphs), just not Gateways. We will fix this before the general release of Apollo Server 4.
 
@@ -741,6 +741,45 @@ new ApolloServer<MyContext>({
 });
 ```
 
+### `executor`
+
+In Apollo Server 3, there are two different ways to specify a replacement for `graphql-js`'s execution functionality. Both of them involve defining a function of the type `GraphQLExecutor`. One way is to specify that function directly as the `executor` constructor option. The other way involves using the `gateway` option.
+
+In Apollo Server 4, this redundancy has been removed: there is no longer an `executor` constructor option. (Additionally, the TypeScript `GraphQLExecutor` type has been renamed `GatewayExecutor` and moved to the `@apollo/server-gateway-interface` package.)
+
+If your Apollo Server 3 code defined an `executor` function and used it like this:
+
+<MultiCodeBlock>
+
+```ts
+new ApolloServer({
+ executor,
+ // ...
+});
+```
+
+</MultiCodeBlock>
+
+your Apollo Server code can use `gateway`, like so:
+
+<MultiCodeBlock>
+
+```ts
+new ApolloServer({
+ gateway: {
+ async load() {
+ return { executor };
+ },
+ onSchemaLoadOrUpdate() {
+ return () => {};
+ },
+ async stop() {},
+ },
+});
+```
+
+</MultiCodeBlock>
+
 
 ## Removed features
 
@@ -1326,14 +1365,18 @@ Apollo Server 4 more consistently handles errors thrown by multiple plugin hooks
 
 The `gateway` option to the `ApolloServer` constructor is designed to be used with the `ApolloGateway` class from the `@apollo/gateway` package. Apollo Server 4 changes the details of how Apollo Server interacts with this object. If you use a [supported version of `@apollo/gateway`](#apollo-gateway) as your server's `gateway`, these changes won't affect you. However, if you provide something _other_ than an `ApolloGateway` instance to this option, you might need to adjust your custom code.
 
-In Apollo Server 2, the TypeScript type used for the `gateway` constructor option is called `GraphQLService`. In Apollo Server 3, the TypeScript type changed to `GatewayInterface`, but the `apollo-server-core` package continued to export an identical `GraphQLService` type. Apollo Server 4 no longer exports the legacy `GraphQLService` type. Instead, use `GatewayInterface`.
+All the TypeScript types you need to define your `gateway` are now part of the `@apollo/server-gateway-interface` package rather than being exported from an Apollo Server package directly. Additionally, many of these types have been renamed.
 
-In Apollo Server 3, your `gateway` may define either `onSchemaChange` or the newer `onSchemaLoadOrUpdate`. In Apollo Server 4, your `gateway` must define `onSchemaLoadOrUpdate`.
+In Apollo Server 2, the TypeScript type used for the `gateway` constructor option is called `GraphQLService`. In Apollo Server 3, the TypeScript type changed to `GatewayInterface`, but the `apollo-server-core` package continued to export an identical `GraphQLService` type. Apollo Server 4 no longer exports the legacy `GraphQLService` type. Instead, use `GatewayInterface`, now exported from `@apollo/server-gateway-interface`.
 
-In Apollo Server 3, the `GatewayInterface.load` method returns `Promise<GraphQLServiceConfig>`, which contains a `schema` and an `executor`. Apollo Server 4 renames `GraphQLServiceConfig` to `GatewayLoadResult`, which now only has an `executor` field. You can use the `onSchemaLoadOrUpdate` hook if you want to receive the schema.
+In Apollo Server 3, your `gateway` may define either `onSchemaChange` or the newer `onSchemaLoadOrUpdate`. In Apollo Server 4, your `gateway` must define `onSchemaLoadOrUpdate`.
 
-In Apollo Server 3, `GatewayInterface.load` returned an object with an `executor` field with the TypeScript type `GraphQLExecutor`. The `executor` field returned the `GraphQLExecutionResult` type, a type defined by Apollo Server 3. In Apollo Server 4, the `GraphQLExecutor` type now returns the `ExecutionResult` type from `graphql-js`. These two types are essentially the same, except that in `ExecutionResult` the  `data` and `extensions` fields are now `Record<string, unknown>`, rather than `Record<string, any>`.
+In Apollo Server 3, the `GatewayInterface.load` method returns `Promise<GraphQLServiceConfig>`, which contains a `schema` and an `executor`. Apollo Server 4 renames `GraphQLServiceConfig` to `GatewayLoadResult` (exported from `@apollo/server-gateway-interface`), which now only has an `executor` field. You can use the `onSchemaLoadOrUpdate` hook if you want to receive the schema.
 
+Additionally, the following types have been renamed and are now exported from `@apollo/server-gateway-interface`:
+- `GraphQLExecutor` is now `GatewayExecutor`
+- `SchemaLoadOrUpdateCallback` is now `GatewaySchemaLoadOrUpdateCallback`
+- `Unsubscriber` is now `GatewayUnsubscriber`
 
 
 ## Changes to defaults

packages/integration-testsuite/src/apolloServerTests.ts

@@ -32,11 +32,7 @@ import {
 import type {
  ApolloServerOptions,
  ApolloServer,
- GatewayInterface,
- SchemaLoadOrUpdateCallback,
  BaseContext,
- GraphQLExecutor,
- GraphQLRequestContextExecutionDidStart,
  PluginDefinition,
 } from '@apollo/server';
 import fetch from 'node-fetch';
@@ -71,6 +67,12 @@ import {
  it,
 } from '@jest/globals';
 import type { Mock } from 'jest-mock';
+import type {
+ GatewayExecutor,
+ GatewayGraphQLRequestContext,
+ GatewayInterface,
+ GatewaySchemaLoadOrUpdateCallback,
+} from '@apollo/server-gateway-interface';
 
 const quietLogger = loglevel.getLogger('quiet');
 function mockLogger() {
@@ -122,18 +124,18 @@ const makeGatewayMock = ({
  optionsSpy = (_options) => {},
  unsubscribeSpy = () => {},
 }: {
- executor: GraphQLExecutor<BaseContext> | null;
+ executor: GatewayExecutor | null;
  schema: GraphQLSchema;
  optionsSpy?: (_options: any) => void;
  unsubscribeSpy?: () => void;
 }) => {
  const triggers = {
  // This gets updated later, when ApolloServer calls gateway.load().
- triggerSchemaChange: null as SchemaLoadOrUpdateCallback | null,
+ triggerSchemaChange: null as GatewaySchemaLoadOrUpdateCallback | null,
  };
 
- const listeners: SchemaLoadOrUpdateCallback[] = [];
- const mockedGateway: GatewayInterface<BaseContext> = {
+ const listeners: GatewaySchemaLoadOrUpdateCallback[] = [];
+ const mockedGateway: GatewayInterface = {
  load: async (options) => {
  optionsSpy(options);
  // Make sure it's async
@@ -459,7 +461,7 @@ export function defineIntegrationTestSuiteApolloServerTests(
  });
 
  it("accepts a gateway's schema and calls its executor", async () => {
- const executor = jest.fn<GraphQLExecutor<{}>>();
+ const executor = jest.fn<GatewayExecutor>();
  executor.mockReturnValue(
  Promise.resolve({ data: { testString: 'hi - but federated!' } }),
  );
@@ -482,7 +484,7 @@ export function defineIntegrationTestSuiteApolloServerTests(
  const loadError = new Error(
  'load error which should be be thrown by start',
  );
- const gateway: GatewayInterface<BaseContext> = {
+ const gateway: GatewayInterface = {
  async load() {
  throw loadError;
  },
@@ -2247,7 +2249,7 @@ export function defineIntegrationTestSuiteApolloServerTests(
  }),
  });
 
- const executor = (req: GraphQLRequestContextExecutionDidStart<any>) =>
+ const executor = (req: GatewayGraphQLRequestContext) =>
  (req.source as string).match(/1/)
  ? Promise.resolve({ data: { testString1: 'hello' } })
  : Promise.resolve({ data: { testString2: 'aloha' } });
@@ -2417,9 +2419,7 @@ export function defineIntegrationTestSuiteApolloServerTests(
  };
  });
 
- const executor = async (
- req: GraphQLRequestContextExecutionDidStart<any>,
- ) => {
+ const executor = async (req: GatewayGraphQLRequestContext) => {
  const source = req.source as string;
  const { startPromise, endPromise, i } = executorData[source];
  startPromise.resolve();

packages/integration-testsuite/tsconfig.json

@@ -8,5 +8,7 @@
  "outDir": "./dist"
  },
  "include": ["src/**/*"],
- "references": [{ "path": "../server" }]
+ "references": [
+ { "path": "../server" },
+ ],
 }

packages/server/package.json

@@ -90,6 +90,7 @@
  },
  "dependencies": {
  "@apollo/cache-control-types": "^1.0.2",
+ "@apollo/server-gateway-interface": "^1.0.0",
  "@apollo/usage-reporting-protobuf": "^4.0.0-alpha.1",
  "@apollo/utils.createhash": "^1.1.0",
  "@apollo/utils.fetcher": "^1.0.0",