Make the plugin (and gateway) API almost entirely async (#5295)

Before this PR, some plugin methods were sync, some were async, and some
returned ValueOrPromise (ie, could be sync or async). This led to a lack
of functionality for the never-async methods, confusing inconsistency,
and generally vagueness as to what types things are.

It's 2021: making a function async is as simple as adding the word
`async` and maybe wrapping a return type in `Promise<>`. This PR
simplifies matters by making almost every plugin and gateway method
always async.

The one exception is `willResolveField`, which is called far more than
any other plugin method. We already know that schema instrumentation has
unfortunate performance overhead so adding to it by adding more Promises
to every field doesn't seem like a good idea for now. We reserve the
write to change `willResolveField` to a `PromiseOrValue` sometimes-async
method later.

(Note that in practice, we usually either `await` or call `Promise.all`
on the return values from plugins rather than directly calling `.then`,
so if you're not using TypeScript you can probably get away with writing
sync methods; and if you are using TypeScript the compiler will quickly
show you where you're missing your `async`s.)

Specifically, this PR:
- Makes the following formerly-`ValueOrPromise` methods into async
  methods: `serverWillStart`, `serverWillStop`, `didResolveSource`,
  `didResolveOperation`, `didEncounterErrors`, `responseForOperation`,
  `willSendResponse`
- Makes the following formerly-sync methods into async methods:
  `requestDidStart`, `renderLandingPage`, `parsingDidStart` and its stop
  hook, `validationDidStart` and its stop hook, `executionDidStart`,
  `executionDidEnd`
- `executionWillStart` can no longer longer return an end hook as a
  function; `executionWillEnd` must be returned in an object (which was
  one of two options before)
- Changes the methods on `Dispatcher` so that there's only one "sync"
  method (for `willResolveField`) and the other methods aren't explicitly
  named with `Async`
- Simplifies the `GraphQLService` interface (used for `@apollo/gateway`)
  to require the `stop` method to exist, to require `executor` to be
  async, and to note that we always pass `apollo` to `load`. (All recent
  versions of `@apollo/gateway` satisfy this.) Also require the
  `GraphQLExecutor` function type to be async.

This also avoids the use of `ValueOrPromise<void>`, a somewhat confusing
type that means "either a Promise or a return value we shouldn't look
at" though we do still have `Promise<X|void>` types.

Note that we allow `options` and `context` functions to still have
`ValueOrPromise` semantics.

Fixes #4103. Fixes #4999. Incorporates work by @lucasconstantino from
#4050 and #4051.

Author: glasser

docs/source/api/plugin/usage-reporting.md

@@ -113,7 +113,7 @@ The only properties of the reported error you can modify are its `message` and i
 
 Specify this asynchronous function to configure which requests are included in usage reports sent to Apollo Studio. For example, you can omit requests that execute a particular operation or requests that include a particular HTTP header.
 
-This function is called for each received request. It takes a [`GraphQLRequestContext`](https://github.com/apollographql/apollo-server/blob/main/packages/apollo-server-types/src/index.ts#L115-L150) object and must return a `Promise<Boolean>` that indicates whether to include the request. It's called either after the operation is successfully resolved (via [the `didResolveOperation` event](https://www.apollographql.com/docs/apollo-server/integrations/plugins/#didresolveoperation)), or after it generates an error (via [the `didEncounterErrors` event](https://www.apollographql.com/docs/apollo-server/integrations/plugins/#didencountererrors)).
+This function is called for each received request. It takes a [`GraphQLRequestContext`](https://github.com/apollographql/apollo-server/blob/main/packages/apollo-server-types/src/index.ts#L115-L150) object and must return a `Promise<Boolean>` that indicates whether to include the request. It's called either after the operation is successfully resolved (via [the `didResolveOperation` event](https://www.apollographql.com/docs/apollo-server/integrations/plugins/#didresolveoperation)), or when sending the final error response if the operation was not successfully resolved (via [the `willSendResponse` event](https://www.apollographql.com/docs/apollo-server/integrations/plugins/#willsendresponse)).
 
 By default, all requests are included in usage reports.
 

docs/source/integrations/plugins.md

@@ -19,7 +19,7 @@ events. Here's a basic plugin that responds to the `serverWillStart` event:
 
 ```js:title=index.js
 const myPlugin = {
-  serverWillStart() {
+  async serverWillStart() {
     console.log('Server starting up!');
   },
 };
@@ -32,7 +32,7 @@ you can export it as a separate module:
 
 ```js:title=myplugin.js
 module.exports = {
-  serverWillStart() {
+  async serverWillStart() {
     console.log('Server starting up!');
   },
 };
@@ -44,7 +44,7 @@ To create a plugin that accepts options, create a function that accepts an
 ```js:title=myplugin.js
 module.exports = (options) => {
   return {
-    serverWillStart() {
+    async serverWillStart() {
       console.log(options.logMessage);
     },
   };
@@ -57,7 +57,9 @@ module.exports = (options) => {
 A plugin specifies exactly which [events](#apollo-server-event-reference)
 it responds to by implementing functions that correspond to those events.
 The plugin in the examples above responds to the `serverWillStart` event, which
-fires when Apollo Server is preparing to start up.
+fires when Apollo Server is preparing to start up. Almost all plugin events
+are `async` functions (ie, functions that return `Promise`s); the one exception
+is [`willResolveField`](#willresolvefield).
 
 A plugin can respond to any combination of supported events.
 
@@ -79,7 +81,7 @@ lifecycle:
 
 ```js
 const myPlugin = {
-  requestDidStart() {
+  async requestDidStart() {
     console.log('Request started!');
   },
 };
@@ -92,19 +94,17 @@ just like you respond to `serverWillStart`, but you _also_ use this function
 
 ```js
 const myPlugin = {
-  requestDidStart(requestContext) {
+  asyn crequestDidStart(requestContext) {
     console.log('Request started!');
 
     return {
-
-      parsingDidStart(requestContext) {
+      async parsingDidStart(requestContext) {
         console.log('Parsing started!');
       },
 
-      validationDidStart(requestContext) {
+      async validationDidStart(requestContext) {
         console.log('Validation started!');
       }
-
     }
   },
 };
@@ -150,42 +150,47 @@ that is invoked after the corresponding lifecycle phase _ends_:
 
 * [`parsingDidStart`](#parsingdidstart)
 * [`validationDidStart`](#validationdidstart)
-* [`executionDidStart`](#executiondidstart) (this handler can alternatively return an _object_ containing an `executionDidEnd` function)
 * [`willResolveField`](#willresolvefield)
 
+([`executionDidStart`](#executiondidstart) returns an _object_ containing an `executionDidEnd` function instead of just a function as an end handler; that's because the returned object can also contain `willResolveField`.)
+
+Just like the event handers themselves, these end hooks are async functions (except for the end hook for `willResolveField`).
+
 These **end hooks** are passed any errors that occurred during the
 execution of that lifecycle phase. For example, the following plugin logs
 any errors that occur during any of the above lifecycle events:
 
 ```js
 const myPlugin = {
-  requestDidStart() {
+  async requestDidStart() {
     return {
-      parsingDidStart() {
-        return (err) => {
+      async parsingDidStart() {
+        return async (err) => {
           if (err) {
             console.error(err);
           }
         }
       },
-      validationDidStart() {
+      async validationDidStart() {
         // This end hook is unique in that it can receive an array of errors,
         // which will contain every validation error that occurred.
-        return (errs) => {
+        return async (errs) => {
           if (errs) {
             errs.forEach(err => console.error(err));
           }
         }
       },
-      executionDidStart() {
-        return (err) => {
-          if (err) {
-            console.error(err);
+      async executionDidStart() {
+        return {
+          async executionDidEnd(err) {
+            if (err) {
+              console.error(err);
+            }
           }
-        }
-      }
-    }
-  }
+        };
+      },
+    };
+  },
 }
 ```
 
@@ -230,7 +235,7 @@ const server = new ApolloServer({
 
     /* This plugin is defined in-line. */
     {
-      serverWillStart() {
+      async serverWillStart() {
         console.log('Server starting up!');
       },
     }
@@ -252,8 +257,7 @@ Request lifecycle events are associated with a specific request. You define resp
 
 ### `serverWillStart`
 
-The `serverWillStart` event fires when Apollo Server is preparing to start serving GraphQL requests. If you respond to this event with an `async` function (or if the function returns a `Promise`), the server doesn't start until the asynchronous operation completes. If the `Promise` is _rejected_, startup _fails_ (**unless you're using [Express middleware](/integrations/middleware/)**). This helps you make sure all
-of your server's dependencies are available before attempting to begin serving requests.
+The `serverWillStart` event fires when Apollo Server is preparing to start serving GraphQL requests. The server doesn't start until this asynchronous method completes. If it throws (ie, if the `Promise` it returns is _rejected_), startup _fails_ and your server will not serve GraphQL operations. This helps you make sure all of your server's dependencies are available before attempting to begin serving requests. (Specifically, this is fired from the `listen()` method in `apollo-server`, from the `start()` method for a framework integration like `apollo-server-express`, and during the first request for a serverless integration like `apollo-server-lambda`.)
 
 #### Example
 
@@ -263,7 +267,7 @@ const server = new ApolloServer({
 
   plugins: [
     {
-      serverWillStart() {
+      async serverWillStart() {
         console.log('Server starting!');
       }
     }
@@ -285,10 +289,10 @@ const server = new ApolloServer({
 
   plugins: [
     {
-      serverWillStart() {
+      async serverWillStart() {
         const interval = setInterval(doSomethingPeriodically, 1000);
         return {
-          serverWillStop() {
+          async serverWillStop() {
             clearInterval(interval);
           }
         }
@@ -311,9 +315,9 @@ const server = new ApolloServer({
 
   plugins: [
     {
-      serverWillStart() {
+      async serverWillStart() {
         return {
-          renderLandingPage() {
+          async renderLandingPage() {
             return { html: `<html><body>Welcome to your server!</body></html>` };
           }
         }
@@ -334,7 +338,7 @@ requestDidStart?(
     GraphQLRequestContext<TContext>,
     'request' | 'context' | 'logger'
   >
-): GraphQLRequestListener<TContext> | void;
+): Promise<GraphQLRequestListener<TContext> | void>;
 ```
 
 This function can optionally return an object that includes functions for responding
@@ -346,16 +350,14 @@ const server = new ApolloServer({
 
   plugins: [
     {
-      requestDidStart(requestContext) {
-
-        /* Within this returned object, define functions that respond
-           to request-specific lifecycle events. */
+      async requestDidStart(requestContext) {
+        // Within this returned object, define functions that respond
+        // to request-specific lifecycle events.
         return {
-
-          /* The `parsingDidStart` request lifecycle event fires
-             when parsing begins. The event is scoped within an
-             associated `requestDidStart` server lifecycle event. */
-          parsingDidStart(requestContext) {
+          // The `parsingDidStart` request lifecycle event fires
+          // when parsing begins. The event is scoped within an
+          // associated `requestDidStart` server lifecycle event.
+          async parsingDidStart(requestContext) {
             console.log('Parsing started!')
           },
         }
@@ -386,7 +388,7 @@ didResolveSource?(
   requestContext: WithRequired<
     GraphQLRequestContext<TContext>, 'source' | 'logger'>,
   >,
-): ValueOrPromise<void>;
+): Promise<void>;
 ```
 
 ### `parsingDidStart`
@@ -405,7 +407,7 @@ parsingDidStart?(
     GraphQLRequestContext<TContext>,
     'metrics' | 'source' | 'logger'
   >,
-): (err?: Error) => void | void;
+): Promise<void | (err?: Error) => Promise<void>>;
 ```
 
 ### `validationDidStart`
@@ -425,7 +427,7 @@ validationDidStart?(
     GraphQLRequestContext<TContext>,
     'metrics' | 'source' | 'document' | 'logger'
   >,
-): (err?: ReadonlyArray<Error>) => void | void;
+): Promise<void | (err?: ReadonlyArray<Error>) => Promise<void>>;
 ```
 
 ### `didResolveOperation`
@@ -444,7 +446,7 @@ didResolveOperation?(
     GraphQLRequestContext<TContext>,
     'metrics' | 'source' | 'document' | 'operationName' | 'operation' | 'logger'
   >,
-): ValueOrPromise<void>;
+): Promise<void>;
 ```
 
 ### `responseForOperation`
@@ -460,7 +462,7 @@ responseForOperation?(
     GraphQLRequestContext<TContext>,
     'metrics' | 'source' | 'document' | 'operationName' | 'operation' | 'logger'
   >,
-): ValueOrPromise<GraphQLResponse | null>;
+): Promise<GraphQLResponse | null>;
 ```
 
 ### `executionDidStart`
@@ -474,10 +476,10 @@ executionDidStart?(
     GraphQLRequestContext<TContext>,
     'metrics' | 'source' | 'document' | 'operationName' | 'operation' | 'logger'
   >,
-): (err?: Error) => void | void;
+): Promise<GraphQLRequestExecutionListener | void>;
 ```
 
-`executionDidStart` may return an ["end hook"](#end-hooks) function. Alternatively, it may return an object with one or both of the methods `executionDidEnd` and `willResolveField`.  `executionDidEnd` is treated identically to an end hook: it is called after execution with any errors that occurred. `willResolveField` is documented in the next section.
+`executionDidStart` may return an object with one or both of the methods `executionDidEnd` and `willResolveField`.  `executionDidEnd` is treated like an end hook: it is called after execution with any errors that occurred. `willResolveField` is documented in the next section. (In Apollo Server 2, `executionDidStart` could return also return an end hook directly.)
 
 ### `willResolveField`
 
@@ -487,6 +489,8 @@ You provide your `willResolveField` handler in the object returned by your [`exe
 
 Your `willResolveField` handler can optionally return an ["end hook"](#end-hooks) function that's invoked with the resolver's result (or the error that it throws). The end hook is called when your resolver has _fully_ resolved (e.g., if the resolver returns a Promise, the hook is called with the Promise's eventual resolved result).
 
+`willResolveField` and its end hook are the only synchronous plugin APIs (ie, they do not return `Promise`s).
+
 #### Example
 
 ```js
@@ -495,9 +499,9 @@ const server = new ApolloServer({
 
   plugins: [
     {
-      requestDidStart(initialRequestContext) {
+      async requestDidStart(initialRequestContext) {
         return {
-          executionDidStart(executionRequestContext) {
+          async executionDidStart(executionRequestContext) {
             return {
               willResolveField({source, args, context, info}) {
                 const start = process.hrtime.bigint();
@@ -531,7 +535,7 @@ didEncounterErrors?(
     GraphQLRequestContext<TContext>,
     'metrics' | 'source' | 'errors' | 'logger'
   >,
-): ValueOrPromise<void>;
+): Promise<void>;
 ```
 
 ### `willSendResponse`
@@ -546,5 +550,5 @@ willSendResponse?(
     GraphQLRequestContext<TContext>,
     'metrics' | 'response' | 'logger'
   >,
-): ValueOrPromise<void>;
+): Promise<void>;
 ```

docs/source/monitoring/metrics.md

@@ -92,23 +92,21 @@ For a list of available lifecycle events and their descriptions, see [Plugins](.
 
 ```js
 const myPlugin = {
-
   // Fires whenever a GraphQL request is received from a client.
-  requestDidStart(requestContext) {
+  async requestDidStart(requestContext) {
     console.log('Request started! Query:\n' +
       requestContext.request.query);
 
     return {
-
       // Fires whenever Apollo Server will parse a GraphQL
       // request to create its associated document AST.
-      parsingDidStart(requestContext) {
+      async parsingDidStart(requestContext) {
         console.log('Parsing started!');
       },
 
       // Fires whenever Apollo Server will validate a
       // request's document AST against your GraphQL schema.
-      validationDidStart(requestContext) {
+      async validationDidStart(requestContext) {
         console.log('Validation started!');
       },
 

packages/apollo-server-core/src/ApolloServer.ts

@@ -448,9 +448,8 @@ export class ApolloServerBase {
       if (taggedServerListenersWithRenderLandingPage.length > 1) {
         throw Error('Only one plugin can implement renderLandingPage.');
       } else if (taggedServerListenersWithRenderLandingPage.length) {
-        this.landingPage =
-          taggedServerListenersWithRenderLandingPage[0].serverListener
-            .renderLandingPage!();
+        this.landingPage = await taggedServerListenersWithRenderLandingPage[0]
+          .serverListener.renderLandingPage!();
       } else {
         this.landingPage = null;
       }

packages/apollo-server-core/src/__tests__/logger.test.ts

@@ -23,7 +23,7 @@ async function triggerLogMessage(loggerToUse: Logger) {
     logger: loggerToUse,
     plugins: [
       {
-        requestDidStart({ logger }) {
+        async requestDidStart({ logger }) {
           logger.debug(KNOWN_DEBUG_MESSAGE);
         },
       },