Skip to content

Commit

Permalink
doc: add examples and notes to http server.close et al
Browse files Browse the repository at this point in the history
Add examples to `http` server.close, server.closeAllConnections,
server.closeIdleConnections. Also add notes about usage for both
server.close*Connections libraries.
  • Loading branch information
mmarchini committed Aug 10, 2023
1 parent b68e5e7 commit 7126c93
Showing 1 changed file with 78 additions and 1 deletion.
79 changes: 78 additions & 1 deletion doc/api/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -1494,13 +1494,59 @@ connected to this server which are not sending a request or waiting for
a response.
See [`net.Server.close()`][].

```js
const http = require('node:http');

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({
data: 'Hello World!',
}));
});

server.listen(8000);
// Close the server after 10 seconds
setTimeout(() => {
server.close(() => {
console.log('server on port 8000 closed successfully');
});
}, 10000);
```

### `server.closeAllConnections()`

<!-- YAML
added: v18.2.0
-->

Closes all connections connected to this server.
Closes all connections connected to this server, including active connections
connected to this server which are sending a request or waiting for a response.

> This is a forceful way of closing all connections and should be used with
> caution. Whenever using this in conjunction with `server.close`, calling this
> _after_ `server.close` is recommended as to avoid race conditions where new
> connections are created between a call to this and a call to `server.close`.
```js
const http = require('node:http');

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({
data: 'Hello World!',
}));
});

server.listen(8000);
// Close the server after 10 seconds
setTimeout(() => {
server.close(() => {
console.log('server on port 8000 closed successfully');
});
// Closes all connections, ensuring the server closes successfully
server.closeAllConnections();
}, 10000);
```

### `server.closeIdleConnections()`

Expand All @@ -1511,6 +1557,37 @@ added: v18.2.0
Closes all connections connected to this server which are not sending a request
or waiting for a response.

> Starting with Node.js 19.0.0, there's no need for calling this method in
> conjunction with `server.close` to reap `keep-alive` connections. Using it
> won't cause any harm though, and it can be useful to ensure backwards
> compatibility for libraries and applications that need to support versions
> older than 19.0.0. Whenever using this in conjunction with `server.close`,
> calling this _after_ `server.close` is recommended as to avoid race
> conditions where new connections are created between a call to this and a
> call to `server.close`.
```js
const http = require('node:http');

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({
data: 'Hello World!',
}));
});

server.listen(8000);
// Close the server after 10 seconds
setTimeout(() => {
server.close(() => {
console.log('server on port 8000 closed successfully');
});
// Closes idle connections, such as keep-alive connections. Server will close
// once remaining active connections are terminated
server.closeIdleConnections();
}, 10000);
```

### `server.headersTimeout`

<!-- YAML
Expand Down

0 comments on commit 7126c93

Please sign in to comment.