Skip to content

Commit 7126c93

Browse files
committed
doc: add examples and notes to http server.close et al
Add examples to `http` server.close, server.closeAllConnections, server.closeIdleConnections. Also add notes about usage for both server.close*Connections libraries.
1 parent b68e5e7 commit 7126c93

File tree

1 file changed

+78
-1
lines changed

1 file changed

+78
-1
lines changed

doc/api/http.md

Lines changed: 78 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1494,13 +1494,59 @@ connected to this server which are not sending a request or waiting for
14941494
a response.
14951495
See [`net.Server.close()`][].
14961496

1497+
```js
1498+
const http = require('node:http');
1499+
1500+
const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
1501+
res.writeHead(200, { 'Content-Type': 'application/json' });
1502+
res.end(JSON.stringify({
1503+
data: 'Hello World!',
1504+
}));
1505+
});
1506+
1507+
server.listen(8000);
1508+
// Close the server after 10 seconds
1509+
setTimeout(() => {
1510+
server.close(() => {
1511+
console.log('server on port 8000 closed successfully');
1512+
});
1513+
}, 10000);
1514+
```
1515+
14971516
### `server.closeAllConnections()`
14981517

14991518
<!-- YAML
15001519
added: v18.2.0
15011520
-->
15021521

1503-
Closes all connections connected to this server.
1522+
Closes all connections connected to this server, including active connections
1523+
connected to this server which are sending a request or waiting for a response.
1524+
1525+
> This is a forceful way of closing all connections and should be used with
1526+
> caution. Whenever using this in conjunction with `server.close`, calling this
1527+
> _after_ `server.close` is recommended as to avoid race conditions where new
1528+
> connections are created between a call to this and a call to `server.close`.
1529+
1530+
```js
1531+
const http = require('node:http');
1532+
1533+
const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
1534+
res.writeHead(200, { 'Content-Type': 'application/json' });
1535+
res.end(JSON.stringify({
1536+
data: 'Hello World!',
1537+
}));
1538+
});
1539+
1540+
server.listen(8000);
1541+
// Close the server after 10 seconds
1542+
setTimeout(() => {
1543+
server.close(() => {
1544+
console.log('server on port 8000 closed successfully');
1545+
});
1546+
// Closes all connections, ensuring the server closes successfully
1547+
server.closeAllConnections();
1548+
}, 10000);
1549+
```
15041550

15051551
### `server.closeIdleConnections()`
15061552

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

1560+
> Starting with Node.js 19.0.0, there's no need for calling this method in
1561+
> conjunction with `server.close` to reap `keep-alive` connections. Using it
1562+
> won't cause any harm though, and it can be useful to ensure backwards
1563+
> compatibility for libraries and applications that need to support versions
1564+
> older than 19.0.0. Whenever using this in conjunction with `server.close`,
1565+
> calling this _after_ `server.close` is recommended as to avoid race
1566+
> conditions where new connections are created between a call to this and a
1567+
> call to `server.close`.
1568+
1569+
```js
1570+
const http = require('node:http');
1571+
1572+
const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
1573+
res.writeHead(200, { 'Content-Type': 'application/json' });
1574+
res.end(JSON.stringify({
1575+
data: 'Hello World!',
1576+
}));
1577+
});
1578+
1579+
server.listen(8000);
1580+
// Close the server after 10 seconds
1581+
setTimeout(() => {
1582+
server.close(() => {
1583+
console.log('server on port 8000 closed successfully');
1584+
});
1585+
// Closes idle connections, such as keep-alive connections. Server will close
1586+
// once remaining active connections are terminated
1587+
server.closeIdleConnections();
1588+
}, 10000);
1589+
```
1590+
15141591
### `server.headersTimeout`
15151592

15161593
<!-- YAML

0 commit comments

Comments
 (0)