Skip to content

Latest commit

 

History

History
287 lines (185 loc) · 9.46 KB

README.md

File metadata and controls

287 lines (185 loc) · 9.46 KB
Raw

daemon-control

Build Status Code Climate Test Coverage Donate

NPM version bitHound Dependencies bitHound Dev Dependencies

This package offers an easy and quick to use tool to manage the control script for a daemon as well a lot of ways to deeply configure control script behaviour for each step.

Usage

var dc = require('daemon-control');

function daemon(daemonized) {
}

dc(daemon, 'daemon.pid');
$ node daemon.js {start|stop|restart|status|nodaemon|help[|reload]} [...]

A complete example can be found in sources @github.

Installation

With npm:

 $ npm install --save daemon-control

API

require('daemon-control');

Returns DaemonControl constructor.

Class: DaemonControl

Extends events.EventEmitter. It manages the steps to control the daemon.

Events

Note: Events are emitted only on control scrip.

Event: 'error'

  • err: {Error Object} the error.

Emitted when an error occurr.

[new] DaemonControl(daemon, filename[, options])

Returns a new DaemonControl object to control the daemon, parses command line arguments and tries to act as requested by command line.

daemon(daemonized) {Function}

  • daemonized: {Boolean} true if lunched as a daemon or false if launched with nodaemon command line option.

The daemon entry point.

filename {String}

The path of the pidfile.

options {Object}

  • cwd: {String} (default: process.cwd()) Proxied to child_process.spawn.
  • detached: {Boolean} (default: true) Proxied to child_process.spawn.
  • env: {Object} (default: process.env) Proxied to child_process.spawn.
  • hooks: {Object} (default: null) Defines hooks for each step of control script.
  • reload: {Boolean} (default: false) Specifies if reload command is enabled or not.
  • timeout: {Integer} (default: 5) Specifies SIGKILL timeout.
  • stdio: {Array|String} (default: 'ignore') Proxied to child_process.spawn.

If any other option is present, it is proxied to [child_process.spawn] (https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options).

hooks:

If not specified control script acts with its default behaviour. Can be used to customized one or more steps. Each hook is a Function which accept a done Function as first parameter which must be called at the end of the customized hook.

Functions done accept a Boolean verbose parameter as first parameter, if set to true default messages are printed to console, otherwise the hook can print custom messages to console and call done with verbose parameter set to false.

reload:

If true the reload command line parameter will be enabled. This means the deamon must be aware it can receive a SIGHUP.

timeout:

The timeout (in seconds) before sending SIGKILL to daemon, if SIGTERM is not enough to stop it.

Hooks

syntax(done)

  • done(verbose): {Function}

Called when there is syntax error in command line.

help(done)

  • done(verbose): {Function}

Called when help is requested from command line.

argv(done, command, argv)

  • done(command, argv): {Function} This is the special case where done Function does not accept a verbose parameter.
  • command {String}: The command.
  • argv {Array}: The rest of arguments in command line.

Called to parse command line. By default done is called with command and argv passed to this hook.

When command line is parsed, done must be called with the command in input (or null if a syntax error is detected) and the argv that will be passed to daemon command line.

status(done, pid)

  • done(verbose, pid): {Function}
  • pid: {Integer} the pid of the deamon or null if daemon is not running.

Called when a status check is performed. Can be used to perform deeper checks on daemon to discover if it is running correctly. If accordingly to these checks the daemon is not running, done must be called with pid parameter set to null, otherwise with the value passed to the hook.

term(done)

  • done(verbose): {Function}

Called before sending SIGTERM to daemon. This hook is not called if daemon is not running.

kill(done)

  • done(verbose): {Function}

Called before sending SIGKILL to daemon. This hook is not called if SIGTERM was enough to stop the daemon.

stop(done)

  • done(verbose): {Function}

Called after daemon is stopped.

starting(done, options)

Called before daemon launch attempt. This is the latest occasion to customize the options Object (if this is required) before passing it to done Function.

start(done, child)

Called after daemon launch attempt. This is called reguardless if daemon was started correctly or not in order to give access to the ChildProcess Object.

running(done, pid)

  • done(verbose): {Function}
  • pid: {Integer} the pid of the deamon.

Called when start is requested from command line and the daemon is already running.

reload(done, pid)

  • done(verbose): {Function}
  • pid: {Integer} the pid of the deamon or null if daemon is not running.

Called before sending SIGHUP to daemon. If Pid is null this hook has just to print an error message to console.

wait(done)

  • done(verbose): {Function}

Called once per second while waiting for deamon to exit after a SIGTERM have been sent to it. Usefull to customize the output to console of one dot per second.

Command line parameters

$ node daemon.js {start|stop|restart|status|nodaemon|help[|reload]} [...]

The first parameter is consumed by control script, from second one to last one (if present) they are passed to the daemon.

status

The package checks for the pidfile, if it exists its content is read and if it is an Integer the package checks for process with that pid; if this process exists the daemon is running.

start

A status check is performet, if the daemon is not running the pakage tries to lauch it.

stop

A status check is performed, if the daemon is running the pakage tries to stop it.

restart

A status check is performed, if the daemon is running the pakage tries to stop it. Once this process is completed, the package tries to launch the daemon.

help

The help message is printed to console.

reload

A status check is performed, if the daemon is running the pakage sends it a SIGHUP. If reload option was false when constructor was called, this command is not enabled and it cause a syntax error.

nodaemon

The Function daemon is launched without running a daemon. Usefull during application development.

Compatibility

This package is written following Node.js 4.2 specifications always taking care about backward compatibility. The package it tested under several Node.js versions.

Note: required Node.js 0.11.

Note: tested only under UNIX.

Licence

MIT Licence

Bugs

Do not hesitate to report any bug or inconsistency @github.

ChangeLog

  • 2017-02-07 - v0.1.5
    • Updated dependencies
  • 2016-12-27 - v0.1.4
    • Updated dependencies
  • 2015-11-02 - v0.1.3
    • Added daemonized paramenter to daemon Function.
  • 2015-11-01 - v0.1.2
    • Added nodaemon command.
  • 2015-10-24 - v0.1.1
    • Added complete example.
    • Added argv hook.
    • Fixed syntax hook.
    • Fixed restart command.
  • 2015-10-23 - v0.1.0
    • First stable release
  • 2015-10-18 - v0.0.2
    • Design pattern refactory
  • 2015-10-15 - v0.0.1
    • Embryonal stage