https://github.com/itteco/graceful-cluster
Gracefully restart node.js http cluster with zero downtime. Shutdown server without active inbound connections reset.
https://github.com/itteco/graceful-cluster
Last synced: 12 months ago
JSON representation
Gracefully restart node.js http cluster with zero downtime. Shutdown server without active inbound connections reset.
- Host: GitHub
- URL: https://github.com/itteco/graceful-cluster
- Owner: itteco
- License: mit
- Created: 2016-07-25T17:00:06.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2019-09-11T21:45:58.000Z (almost 7 years ago)
- Last Synced: 2025-06-22T00:59:25.793Z (12 months ago)
- Language: JavaScript
- Size: 15.6 KB
- Stars: 22
- Watchers: 4
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Graceful cluster
Install:
npm install graceful-cluster
## How to use
### 1. Enable graceful server shutdown
This patch will prevent active connections reset when server receives `SIGKILL` or `SIGTERM`. Idle (keep-alive) inbound connections without active requests will be destroyed.
Example 'server.js':
```js
// Example server with 'express'.
var express = require('express');
var app = express();
var listener = app.listen(8000);
var GracefulServer = require('graceful-cluster').GracefulServer;
var gracefulServer = new GracefulServer({
server: listener,
shutdownTimeout: 10 * 1000, // 10 sec.
});
```
GracefulServer options description:
| option | info
| ------------------------ | ---
|`log` | function, custom log function, `console.log` used by default.
|`server` | required, http server instance.
|`shutdownTimeout` | ms, force worker shutdown on `SIGTERM` timeout. Defaults to 5000ms.
Also you can initiate graceful shutdown when needed:
```js
gracefulServer.shutdown();
```
### 2. Use simplified cluster initialization
This cluster wrapper will send `SIGTERM` signal to workers and wait till they finished all requests.
Also it can gracefully restart all workers one by one with zero cluster downtime on some conditions:
1. Worker memory used.
2. Worker time online.
3. Your custom condition: just call `GracefulCluster.gracefullyRestartCurrentWorker()` to restart current worker in `serverFunction`.
4. On `SIGUSR2` signal to cluster process.
Example 'cluster.js':
```js
var GracefulCluster = require('graceful-cluster').GracefulCluster;
process.title = ''; // Note, process title must be near filename (cluster.js) length, longer title truncated.
GracefulCluster.start({
shutdownTimeout: 10 * 1000, // 10 sec.
restartOnTimeout: 5 * 3600 * 1000, // 5 hours.
restartOnMemory: 150 * 1024 * 1024, // 150 MB.
serverFunction: function() {
require('./server'); // Your 'server.js' code module with server logic.
}
});
```
GracefulCluster options description:
| option | info
| ------------------------ | ---
| `disableGraceful` | disable graceful shutdown for faster debug.
| `exitFunction` | optional, function that is called when the master needs to exit. The default function exits with exit code 0.
| `log` | function, custom log function, `console.log` used by default.
| `restartOnMemory` | bytes, optional. restart worker on memory usage.
| `restartOnTimeout` | ms, optional. restart worker by timer.
| `serverFunction` | **required**, function with worker logic.
| `shutdownTimeout` | ms, optional. force worker shutdown on `SIGTERM` timeout. Defaults to 5000ms.
| `workersCount` | workers count, if not specified `os.cpus().length` will be used.
### Gracefully restart cluster
Graceful restart performed by `USR2` signal:
```sh
pkill -USR2
```
or
```sh
kill -s SIGUSR2
```
This method is also good if your app is launched with [forever](https://github.com/foreverjs/forever):
```sh
forever start cluster.js
```
### Using with PM2
If you prefer [PM2](https://github.com/Unitech/pm2) you should use 'server.js' patch only. This will force PM2 to wait until active connections are closed when using:
```sh
pm2 reload
```
With PM2 graceful reload don`t forget to set important process parameters:
- `"instances": 0` - use cluster with multiple instances, so one instance will still work when another is reloaded.
- `"kill_timeout": 5000` - wait more time to allow active connections finish their responses.