docs, changelog

CHANGELOG.md

@@ -11,7 +11,7 @@ The version headers in this history reflect the versions of Apollo Server itself
 
 > The changes noted within this `vNEXT` section have not been released yet.  New PRs and commits which introduce changes should include an entry in this `vNEXT` section as part of their development.  With few exceptions, the format of the entry should follow convention (i.e., prefix with package name, use markdown `backtick formatting` for package names and code, suffix with a link to the change-set à la `[PR #YYY](https://link/pull/YYY)`, etc.).  When a release is being prepared, a new header will be (manually) created below and the appropriate changes within that release will be moved into the new section.
 
-- FIXME add changelog entry
+- Improve startup error handling by ensuring that your server has loaded its schema and executed its `serverWillStart` handlers successfully before starting an HTTP server. If you're using the `apollo-server` package, no code changes are necessary. If you're using an integration such as `apollo-server-express` that is not a "serverless framework", you can should insert [`await server.start()`](https://www.apollographql.com/docs/apollo-server/api/apollo-server/#start) between `server = new ApolloServer()` and `server.applyMiddleware`. (If you don't call `server.start()` yourself, your server will still work, but the previous behavior of starting a web server that may fail to load its schema still applies.) The serverless framework integrations (Lambda, Azure Functions, and Cloud Functions) do not support this functionality. The protected method `willStart` has been removed; `start` or the new protected method `ensureStarting` should fulfill the same purpose if you were using it. [PR #4981](https://github.com/apollographql/apollo-server/pull/4981)
 
 ## v2.21.2
 

docs/source/api/apollo-server.md

@@ -699,12 +699,26 @@ The full URL of the server's subscriptions endpoint.
 
 #### `start`
 
-`ApolloServer.start()` is an async method that tells your Apollo Server to do everything necessary to become ready to start serving traffic. FIXME finish this
+`ApolloServer.start()` is an async method that tells your Apollo Server to do everything necessary to prepare to serve traffic.
+
+You should not call this if you are using the `apollo-server` package; that package's [`listen`](#listen) method begins by starting the server for you.
+
+You should not call this if you are using `apollo-server-lambda`, `apollo-server-azure-functions`, or `apollo-server-cloud-functions`; these "serverless" framework integrations don't differentiate between "starting the server" and "serving a request".
+
+You *should* call this if you are using another integration package such as `apollo-server-express`. Specifically, you should call `await server.start()` *before* calling `server.applyMiddleware` and starting your HTTP server. This will allow you to react to Apollo Server startup failures by crashing your process rather than starting to serve traffic.
+
+Starting your server consists of two steps.
+
+First, if your server is a [federated gateway](https://www.apollographql.com/docs/federation/managed-federation/overview/), it loads its schema; if it cannot load the schema, `start()` throws.
+
+Second, all [plugin `serverWillStart` handlers](../integrations/plugins/#serverwillstart) are invoked in parallel; if any of these throw, `start()` throws.
+
+For backwards compatibility reasons, calling `await server.start()` is optional. If you don't call it yourself, your integration package will invoke it "in the background" when you call `server.applyMiddleware`, and any attempt to execute a GraphQL operation will wait until the server has started and fail if startup fails (with a redacted error message sent to the GraphQL client). We recommend calling it yourself, so that your web server doesn't start trying to serve traffic until the Apollo Server is capable of accepting it.
 #### `applyMiddleware`
 
 Connects Apollo Server to the HTTP framework of a Node.js middleware library, such as hapi or express.
 
-You call this method instead of [`listen`](#listen) if you're using an `apollo-server-{integration}` package.
+You call this method instead of [`listen`](#listen) if you're using an `apollo-server-{integration}` package. You are highly recommended to [`await server.start()`](#start) before calling this method.
 
 Takes an `options` object as a parameter. Supported fields of this object are described below.
 
@@ -715,19 +729,24 @@ const express = require('express');
 const { ApolloServer } = require('apollo-server-express');
 const { typeDefs, resolvers } = require('./schema');
 
-const server = new ApolloServer({
-  typeDefs,
-  resolvers,
-});
-// FIXME add start here, and generally fix top level awaits
+async function startApolloServer() {
+  const server = new ApolloServer({
+    typeDefs,
+    resolvers,
+  });
+  await server.start();
 
-const app = express();
+  const app = express();
 
-// Additional middleware can be mounted at this point to run before Apollo.
-app.use('*', jwtCheck, requireAuth, checkScope);
+  // Additional middleware can be mounted at this point to run before Apollo.
+  app.use('*', jwtCheck, requireAuth, checkScope);
 
-// Mount Apollo middleware here.
-server.applyMiddleware({ app, path: '/specialUrl' });
+  // Mount Apollo middleware here.
+  server.applyMiddleware({ app, path: '/specialUrl' });
+  await new Promise(resolve => app.listen({ port: 4000 }, resolve));
+  console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`);
+  return { server, app };
+}
 ```
 
 ##### Options