spinner
Spawns child processes with dynamic port allocation and other goodies. Sort of like forever but with a few more features.
- Allocates ports dynamically and hands them over child processes via the
PORT
environment variable - Respawn processes that decided to go to bed
- Stateless API for a pretty stateful module (uses fsmjs).
- Monitor a file/directory and restart the child if changed
- If a child was not 'touched' for some time, automatically stop it
$ npm install spinner
myapp.js
var http = require('http');
console.log('[myapp] Started on port %s', process.env.port || 5000);
http.createServer(function(req, res) {
console.log('[myapp] %s %s', req.method, req.url);
res.end('hello, world');
}).listen(process.env.port || 5000);
This is a simple node.js HTTP server that binds to process.env.port
.
It emits some logs which will be piped into the server's stdio streams.
server.js
var http = require('http');
var spinner = require('spinner').createSpinner();
spinner.start('./myapp.js', function(err, socket) {
var req = http.request({ socketPath: socket });
req.on('response', function(res) {
console.log('[server] HTTP %d %s', res.statusCode, http.STATUS_CODES[res.statusCode]);
res.on('data', function(data) {
console.log('[server] DATA <' + data.toString() + '>');
});
res.on('end', function() {
spinner.stop('./myapp.js');
});
});
req.end();
});
The server creates a spinner and starts ./myapp.js
. The callback receives a socket
parameter
with the unix domain socket (or named pipe in Windows) path. Then, it uses node's http
module to
issue an HTTP request into this pipe.
Output:
$ node server.js
[myapp] Started on port /tmp/ed929e3c521e4004bb93c59a65c968b2
[myapp] GET /
[server] HTTP 200 OK
[server] DATA <hello, world>
API
createSpinner(globalOptions)
Returns a spinner. Within a spinner namespace, child processes are identified by name and only a single child can exists for every name.
This means that if I call spinner.start('foo')
twice, only a single child will be spawned. The second call will return the same port.
globalOptions
may contain any of the options passed along to
spinner.start()
(except name
and args
) and used as defaults options
for spinner.start
.
spinner.start(options, callback)
// Name of child. Basically a key used to identify the child process
name: 'foofoo',
// Program to execute (default is `process.execPath`, which is node.js)
command: process.execPath,
// Array of arguments to use for spawn
args: [ './myapp.js' ],
// Environment variables for spawned process
env: { myenv: '1234' },
// working directory to spawn the app (default null)
cwd: null,
// Logger to use (default is `console`)
logger: console,
// Timeout in seconds waiting for the process to bind to the
// allocated port (default is 30 seconds)
timeout: 30,
// Number of attempts to start the process. After this, spinner will not
// fail on every `start` request unless a `stop` is issued (default is 3).
attempts: 3,
// Timeout in seconds to wait for a child to stop before issuing a
// SIGKILL (default is 30 sec)
stopTimeout: 30,
// Path of file or directory to monitor for changes. When the monitor
// indicates a change, the child will be restarted. Default is null
// (no monitor). file must exist when the child is first started.
monitor: './lazykiller.js',
// Stream to pipe process stdout to (default is process.stdout). Use `null` to disable.
stdout: process.stdout,
// Stream to pipe process stderr to (default is process.stderr). Use `null` to disable.
stderr: process.stderr,
// Idle time: if `spinner.start` is not called for this process within this time,
// spinner will automatically stop the process. Use `-1` to disable (default is 30 minutes).
idleTimeSec: 30 * 60,
// Number of seconds allowed between unexpected restarts of a child process. If a restart
// happens within less time, the child will be become faulted.
restartTolerance: 60,
// Number of seconds child process is not restarted when it is faulted. If child process
// started again after this timeout expired, another attempt to spawn it will be made.
faultTimeout: 60
The argument callback
is function(err, port)
where port
is the port number allocated for this child process and set in it's PORT
environment variable (in node.js: process.env.PORT
). If the child could not be started or if it did not bind to the port in the alloted timeout
, err
will indicate that with an Error
object.
spinner.start(script, callback)
A short form for spinner.start()
where script
is used as the first argument to the node engine prescribed in process.execPath
and also used as the name of the child.
Monitor is also set to point to the script, so if it changes, the child will be
restarted (unless monitor
is set to null
in the global options).
spinner.stop(name, callback)
Stops the child keyed name
. callback
is function(err)
.
Spinner sends SIGTERM
and after stopTimeout
passes, sends SIGKILL
.
spinner.stopall(callback)
Stops all the child processes maintained by this spinner.
callback
is function(err)
spinner.get(name)
Returns information about a child process named name
. The information includes the options
used to start the child process and a state
property indicating the current state of the
child.
Possible states are:
- stopped - Child is stopped.
- starting - Child is being spawned and waiting for port to be bound to.
- started - Child is started.
- stopping - Child is being stopped.
- faulted - Child is faulted. That is, the alloted number of start requests failed.
- restart - Child is being restarted.
spinner.list()
Returns the list of child processes maintained by this spinner. The result is a hash
keyed by the child name and contains the details from spinner.get()
.
Event: 'started'
function(port) {}
Emitted after the child process has been started and bound to port
. This means it can
be accessed from now on via { host: 'localhost', port: port }
.
Event: 'stopped'
function() {}
Emitted after the child process has been stopped.
Event: 'restarted'
function(port) {}
Emitted after the child process has been restarted (either due to a file change or due to a crash).
Event: 'error'
function(e) {}
Emitted when an error occured while starting the child process.
License
MIT
Contributors
Originally forked from forked from nploy by George Stagas (@stagas), but since I had to work out the crazy state machine, not much code of nploy
let. Neverthess, it's an awesome lib.