child-service

Start services as child-process, wait until they are ready and stop them.

Installation

npm install child-service

Usage

Let's assume, we have a service that does not detach, but it is not ready immediately after start. We want to start this service call some endpoints and stop it again (for example in tests). Assume that our service is implemented in service.js (for portability, we use a Node.js program in this example, but I actually wrote this tool for use with chisel.

We can now do the following.

const { ChildService } = require("child-service");
const got = require("got");

// We call nodejs in this example, but in reality, it
// is probably some binary executable.
const childService = new ChildService({
  command: process.execPath, // you can also use a promise here
  args: ["service.js"], // you can also use a promise here
  readyRegex: /Listening on port 3000/,
  spawnOptions: {
    cwd: __dirname
  }
});

(async function () {
  await childService.start();
  console.log("Started!");

  const response = await got("http://127.0.0.1:3000");
  console.log(response.body);

  await childService.stop();
  console.log("Stopped!");
})();

This will start the service, wait until the stdout matches pattern, then call an endpoint and stop it again. The output of this program is:

Started!
hello

Stopped!

The package also makes sure that processes are stopped when the parent-process dies unexpectedly. It takes into account quitting by process.exit() as well as SIGTERM, SIGINT and SIGKILL.

API reference

ChildService

The class for starting and stopping services.

Kind: global class
Access: public

• ChildService
  • new ChildService(userOptions)
  • .start() ⇒ Promise.<void>
  • .stop() ⇒ Promise.<void>

new ChildService(userOptions)

Create a new child-service

Param	Type	Description
userOptions	object	parameters
userOptions.command	string | Promise.<string>	the command to execute
[userOptions.args]	Array.<string> | Promise.<Array.<string>>	arguments to the command
[userOptions.readyRegex]	RegExp	process is assumed to be ready, when this regex matches the output.
[userOptions.outputLimit]	number	only look for readyRegex in the first "outputLimit" number of bytes of the output.
[userOptions.spawnOptions]	object	options to pass to child_process.spawn
[userOptions.timeoutAfterSignal]	number	(default: 1000) how long (in milliseconds) to wait after stopping the child with SIGTERM, before using SIGKILL and after that before giving up.
[userOptions.listenOnStderr]	boolean	(default: false) whether to wait for "readyRegex" on stderr of the child-process instead of stdout

childService.start() ⇒ Promise.<void>

Starts the service.

Kind: instance method of ChildService
Returns: Promise.<void> - resolves when the "readyRegex" has been found.

childService.stop() ⇒ Promise.<void>

Stop the service.

Kind: instance method of ChildService
Returns: Promise.<void> - resolves, when the executable has exited.

License

child-service is published under the MIT-license.

See LICENSE.md for details.

Release-Notes

For release notes, see CHANGELOG.md

Contributing guidelines

See CONTRIBUTING.md.