Welcome to Pidman 👋

A rock solid process orchestration library for Node

🏠 Homepage

About

Pidman is a library designed to make external processes management an easy task.

It avoids the typical callback hell where you get into when using native API while at the same time enhances the default language functionality by allowing you to create groups of processes, monitor their activity and gives you the option to manage their statuses at any given time, whether there is data flowing, an error occurs or whenever the process closes or exits. If the later, you'll be provided with all the required information and metadata to help you react accordingly.

Grouping a serie of external commands or programs is useful when they depend on each other. Obviously, you can run an individual process if you don't need to manage a group.

Goal

The goal of Pidman is to provide the most reliable process management tool without entering into dark territories. It has to remain simple to use and be easy to setup. In a matter of seconds, you should be able to orchestrate a series of programs or external commands while ensuring you won't loose their traces.

Persistence

Pidman stores your groups and processes' metadata using Connectors. Currently, there is a single connector called MemoryConnector which can be persisted locally. You'll be always in sync with the processes that run over Pidman.

There are plans to add more connectors (NoSQL, MySQL, etc). Contributors are welcome.

Logging

Pidman offers a vast set of logging targets to keep you informed. Thanks to the use of Winston transports, the output of this library can be redirected to either console, Slack, MongoDB, Sentry, New Relic, a file, a stream and dozens of other popular destinations.

Just include the preferred one when initializing the Pidman instance:

const SlackHook = require("winston-slack-webhook-transport");

const pm = new Pidman({
  logger: {
    transport: new SlackHook({
      webhookUrl: "https://hooks.slack.com/services/xxx/xxx/xxx",
    }),
  },
});

Thread Behavior

Pidman run processes in forked mode. This means, your program's event loop won't be locked. This is a pseudo-thread mechanism that allows running commands and programs on the background while you keep listening for any event that might arise during execution of these commands.

Daemons and Background Processes

If you run a command that spawns itself as a background process or daemon, Pidman will not be able to kill it properly. This is because the program will detach itself from its parent hence the new daemonized/background process will run unattached from the main Node's process running your code.

Prerequisites

• npm >=5.8.0
• node >=9.3.0

Install

npm i pidman

or

yarn add pidman

Typescript Setup

If you use Typescript, don't forget to target ES2015 or higher in your tsconfig.json:

  "compilerOptions": {
    ...
    "target": ["ES2015"],
    ...
  }

API / Documentation

There is a detailed API Documentation.

Usage

For a quick hands-on usage explanation, check out the basic demo and read the comments in there.

First, instantiate the main Pidman's class:

import { Pidman } from "pidman";

const pm = new Pidman();

You can optionally provide a PidmanOptions to the Pidman constructor. An example would be specifying a logging transport.

Group

Let's start adding a PidmanGroup which will contain one or more PidmanProcess.

A group simplifies the management of multiple commands and programs which relate to each other within a specific domain or context in your application. For example, if you need to run some maintenance commands when a user removes a document or triggers some action, then you can have a group do this job.

A PidmanGroup accepts a GroupOptions as unique argument on construction. The meaning of these options are explained here. You can choose to initialize the processes using the processes array in the options or by later using the addProcess method:

import { Pidman, PidmanGroup } from "pidman";

const pm = new Pidman();
const group = new PidmanGroup();

group.addProcess({
  path: "/home/someuser",
  command: "rm -rf ./docs",
});

pm.addProcessGroup(group);

pm.run();

The only required property is command, otherwise nothing runs. You can see a description of the different options here. You can optionally identify this group using a unique id string or let Pidman choose a random one.

Process

A PidmanProcess can be run inside a group or isolated. Although, you can join a process to any group whenever you need to. It's a flexible mechanism.

import { someEvent } from './events';
import { Pidman, PidmanGroup, PidmanProcess } from "pidman";

const pm = new Pidman();
const group = new PidmanGroup();

group.addProcess({
  path: "/home/someuser",
  command: "rm -rf ./docs",
});

pm.addProcessGroup(group);

const lockProcess = new PidmanProcess({
  user: "www",
  group: "www",
  path: "/var/www",
  command: "touch",
  arguments: ["lock"],
});

group.addProcess(lockProcess);

someEvent.on('doit', () => {
  group.run();
});

pm.run();

Monitor Groups and Process

You can choose to monitor special events coming from a group's children processes or individually on each process. The callback signatures are detailed here:

const group = new PidmanGroup({
  monitor: {
    onData: (data) => {
      // data.output is the process' stdout and stderr
      console.log(data.output)
    },
    onClose: (event) => {
      if (event.exitCode && event.exitCode !== 0) {
        console.error('ouch! something is wrong: ');
        console.error(event.process.output);
      } else {
        console.info(`process ${event.process.options.id} closed at ${event.time}`);
      }
    }
  }
});

Kill 'Em All

By providing (or not) a valid program termination signal, you can choose to kill all processes in a group at once or individually:

const killed = await group.kill();

or

const killed = await lockProcess.kill('SIGKILL');

Author

👤 Nicolas Iglesias

• Website: https://pidman.qalfy.com
• Github: @webpolis

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page.

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2020 Nicolas Iglesias.
This project is MIT licensed.