https://github.com/thesephi/gracefulize
A lightweight server-side Node.js module that helps properly exit a Node.js process hosting a native Node.js HTTP server
https://github.com/thesephi/gracefulize
handle-resource helper-tool server-side
Last synced: 8 months ago
JSON representation
A lightweight server-side Node.js module that helps properly exit a Node.js process hosting a native Node.js HTTP server
- Host: GitHub
- URL: https://github.com/thesephi/gracefulize
- Owner: Thesephi
- License: mit
- Created: 2020-02-24T00:24:20.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2020-07-27T07:35:15.000Z (almost 6 years ago)
- Last Synced: 2025-10-03T01:32:33.592Z (8 months ago)
- Topics: handle-resource, helper-tool, server-side
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/gracefulize
- Size: 4.88 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# gracefulize
# Why
A Node.js HTTP server object, once listening on a handle (e.g. a port number),
is expected to take that "handle resource" for itself until it is closed.
Except when it doesn't.
Say you have a Node.js HTTP server in your `server.js` file, then start it, then
stop it with `Ctrl + C`, that HTTP server can be killed together with the
host process (the `server.js` process itself), but sometimes it doesn't cleanly
release the aforementioned "handle resource". In my experience, most times it
does, but it's plain annoying when it doesn't, e.g. when the resource is a unix-
socket.
While there are "scientific" explanations for all this (when it does, and when
not), they are beyond the scope of this document, the purpose of which is to
explain why this module exists & how it should be used.
What this helper module does is to ensure when the main Node.js process terminates,
(e.g. on `SIGINT`), it first politely asks the Node.js HTTP server to peacefully
shutdown, then it waits until the Node.js HTTP server has properly done so before
allowing the main Node.js process to finally terminate.
However, if the Node.js HTTP server fails to cooperate politely (e.g. it hangs
trying to serve some unresponsive client, or deal with a cyclic I/O operation -
you name it), then the main Node.js process can still be "coldly" terminated by
sending subsequent `SIGINT` signals to it.
Hopefully this module provides an acceptable middle ground to properly exit a Node.js
process parenting a Node.js HTTP server. If you find a use case where this module
is inappropriate, please raise an issue so we could improve this documentation
accordingly.
# How
If you already have done something like this before:
```javascript
let express = require('express');
let myServer = express.listen(3000, () => {
console.log('server started at port 3000');
});
```
Then you only need to add 1 additional line now:
```javascript
let express = require('express');
let myServer = express.listen(3000, () => {
console.log('server started at port 3000');
});
// the following line is new
require('gracefulize')(myServer);
```
Please note that the above example uses `ExpressJS`, but it is essentially the
same for `Koa` or any other `Node.js`-based HTTP server.
# Do I need this?
- If you have _never_ implemented anything to ensure a graceful shutdown of your
Node.js HTTP server for your server app before, then yes
- Otherwise, probably not