API Reference: Drain HTTP server plugin

Using the plugin

In the examples below, we use top-level await calls to start our server asynchronously. Check out our Getting Started guide to see how we configured our project to support this.

This article documents the options for the ApolloServerPluginDrainHttpServer plugin, which you can import from @apollo/server/plugin/drainHttpServer.

This plugin is designed for use with expressMiddleware and other framework integrations built on top of Node http.Servers. We highly recommend using this plugin to ensure your server shuts down gracefully.

You do not need to use this plugin with the startStandaloneServer function; it automatically handles server draining.

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 package. Here's a basic example of how to use it with Express:

index.ts

1
import { ApolloServer } from '@apollo/server';
2
import { expressMiddleware } from '@apollo/server/express4';
3
import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
4
import express from 'express';
5
import http from 'http';
6
import cors from 'cors';
7
import { json } from 'body-parser';
8
import { typeDefs, resolvers } from './schema';
9

10
interface MyContext {
11
  token?: String;
12
}
13

14
const app = express();
15
// Our httpServer handles incoming requests to our Express app.
16
// Below, we tell Apollo Server to "drain" this httpServer,
17
// enabling our servers to shut down gracefully.
18
const httpServer = http.createServer(app);
19

20
const server = new ApolloServer<MyContext>({
21
  typeDefs,
22
  resolvers,
23
  plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
24
});
25
await server.start();
26

27
app.use(
28
  '/graphql',
29
  cors<cors.CorsRequest>(),
30
  json(),
31
  expressMiddleware(server, {
32
    context: async ({ req }) => ({ token: req.headers.token }),
33
  }),
34
);
35

36
await new Promise<void>((resolve) => httpServer.listen({ port: 4000 }, resolve));
37

38
console.log(`🚀 Server ready at http://localhost:4000/graphql`);

index.js

1
import { ApolloServer } from '@apollo/server';
2
import { expressMiddleware } from '@apollo/server/express4';
3
import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
4
import express from 'express';
5
import http from 'http';
6
import cors from 'cors';
7
import { json } from 'body-parser';
8
import { typeDefs, resolvers } from './schema';
9

10
const app = express();
11
// Our httpServer handles incoming requests to our Express app.
12
// Below, we tell Apollo Server to "drain" this httpServer,
13
// enabling our servers to shut down gracefully.
14
const httpServer = http.createServer(app);
15

16
const server = new ApolloServer({
17
  typeDefs,
18
  resolvers,
19
  plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
20
});
21
await server.start();
22

23
app.use(
24
  '/graphql',
25
  cors(),
26
  json(),
27
  expressMiddleware(server, {
28
    context: async ({ req }) => ({ token: req.headers.token }),
29
  }),
30
);
31

32
await new Promise((resolve) => httpServer.listen({ port: 4000 }, resolve));
33

34
console.log(`🚀 Server ready at http://localhost:4000/graphql`);

Options

Name / Type	Description
`httpServer` `http.Server`	The server to drain; required.
`stopGracePeriodMillis` `number`	How long to wait before forcefully closing non-idle connections. Defaults to `10_000` (ten seconds).

Inline trace

Cache control

API Reference: Drain HTTP server plugin

Using the plugin

Options

`httpServer`

`stopGracePeriodMillis`