API Reference: Drain HTTP server plugin

Using the plugin

This API reference documents the ApolloServerPluginDrainHttpServer plugin.

This plugin is designed for use with apollo-server-express and other framework-specific packages which are built on top of Node http.Servers. It is highly recommended that you use this plugin with packages like apollo-server-express if you want your server to shut down gracefully.

You do not need to explicitly use this plugin with the batteries-included apollo-server package: that package automatically uses this plugin internally.

When you use this plugin, Apollo Server will drain your HTTP server when you call the stop() method (which is also called for you when the SIGTERM and SIGINT signals are received, unless disabled with the stopOnTerminationSignals constructor option). Specifically, it will:

• Stop listening for new connections
• Close idle connections (i.e., connections with no current HTTP request)
• Close active connections whenever they become idle
• Wait for all connections to be closed
• After a grace period, if any connections remain active, forcefully close them.

This plugin is exported from the apollo-server-core package. It is tested with apollo-server-express, apollo-server-koa, and apollo-server-fastify. (If you're using Hapi, you should instead use the ApolloServerPluginStopHapiServer plugin exported from the apollo-server-hapi package.)

Here's a basic example of how to use it with Express. See the framework integrations docs for examples of how to use it with other frameworks.

1
const express = require('express');
2
const { ApolloServer } = require('apollo-server-express');
3
const { ApolloServerPluginDrainHttpServer, ApolloServerPluginLandingPageLocalDefault } = require('apollo-server-core');
4
const { typeDefs, resolvers } = require('./schema');
5
const http = require('http');
6

7
async function startApolloServer() {
8
  const app = express();
9
  // Our httpServer handles incoming requests to our Express app.
10
  // Below, we tell Apollo Server to "drain" this httpServer,
11
  // enabling our servers to shut down gracefully.
12
  const httpServer = http.createServer(app);
13
  const server = new ApolloServer({
14
    typeDefs,
15
    resolvers,
16
    csrfPrevention: true,
17
    cache: 'bounded',
18
    plugins: [ApolloServerPluginDrainHttpServer({ httpServer }), ApolloServerPluginLandingPageLocalDefault({ embed: true })],
19
  });
20

21
  await server.start();
22

23
  // Mount Apollo middleware here.
24
  server.applyMiddleware({ app });
25
  await new Promise<void>((resolve) => httpServer.listen({ port: 4000 }, resolve));
26
  console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`);
27
  return { server, app };
28
}

1
const express = require('express');
2
const { ApolloServer } = require('apollo-server-express');
3
const { ApolloServerPluginDrainHttpServer, ApolloServerPluginLandingPageLocalDefault } = require('apollo-server-core');
4
const { typeDefs, resolvers } = require('./schema');
5
const http = require('http');
6

7
async function startApolloServer() {
8
  const app = express();
9
  // Our httpServer handles incoming requests to our Express app.
10
  // Below, we tell Apollo Server to "drain" this httpServer,
11
  // enabling our servers to shut down gracefully.
12
  const httpServer = http.createServer(app);
13
  const server = new ApolloServer({
14
    typeDefs,
15
    resolvers,
16
    csrfPrevention: true,
17
    cache: 'bounded',
18
    plugins: [ApolloServerPluginDrainHttpServer({ httpServer }), ApolloServerPluginLandingPageLocalDefault({ embed: true })],
19
  });
20

21
  await server.start();
22

23
  // Mount Apollo middleware here.
24
  server.applyMiddleware({ app });
25
  await new Promise((resolve) => httpServer.listen({ port: 4000 }, resolve));
26
  console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`);
27
  return { server, app };
28
}

Options