pot-js

Process management module

Table of Contents

• pot-js
  • Table of Contents
  • Motivation
  • Features
  • Installing
  • CLI Reference
  • Node.js module API Reference
    • exec([options]) - Options
    • Connection
    • Operators
    • Schemas
    • Commands
    • createCli(pkg, commands)
  • License

Motivation

forever and pm2 are great third-party process management tools, but they are not module friendly. Saying if you are writing a CLI service tool, you may need to built-in a process management module for handling process monitor, run as a daemon, stop, scale, reload, and then you could just focus on developing your service logic. So I created this module.

Features

• Automatically restart process if it crashes. Like forever
• Able to scale or reload instances with zero down time. Like pm2
• Provides both CLI and Node.js module API
• Supports isolated workspaces
• User friendly interactive CLI
• Easy to extend
• Built-in powerful logger system

Installing

$ npm install pot-js

For global CLI command, please add -g option

$ npm install -g pot-js

CLI Reference

pot <command> [options]

Commands:
  pot start [entry]             Spawn and monitor a process
  pot restart [name]            Restart a process
  pot restartall                Restart all processes
  pot reload [name]             Reload a process
  pot reloadall                 Reload all processes
  pot stop [name]               Stop a process
  pot stopall                   Stop all processes
  pot scale [name] [instances]  Scale up/down a process
  pot list                      List processes                     [aliases: ls]
  pot log [name] [category]     Show log
  pot show [name]               Show process information
  pot flush [name]              Remove log files
  pot flushall                  Remove all log files

Options:
  --version   Show version number                                      [boolean]
  -h, --help  Show help                                                [boolean]

Node.js module API Reference

exec([options])

Spawn and monitor a process.

Options

• args (String|String[]): List of string arguments. Defaults to [].
• baseDir (String): The base directory for resolving modules or directories. Defaults to the current working directory.
• cluster (Boolean): Enforce using cluster mode. If not set, it will automatically set to true when spawning a Node.js related process.
• config (String): Path to the config file. Defaults to .potrc.
• cwd (String): Current working directory. Defaults to process.cwd().
• daemon (Boolean): Run as a daemon. Defaults to false.
• entry (String): Entry script path. Defaults to ./index.js.
• env (Object): Environment variables object. Defaults to process.env.
• events (Object): Defining scripts by event hooks. Like scripts in package.json. Here are available event hooks:
  • spawn: New child process has been spawned
  • start: The monitor has started
  • stop: The monitor has fully stopped and the process is killed
  • crash: The monitor has crashed (too many restarts or spawn error)
  • sleep: The monitor is sleeping
  • exit: Child process has exited
  • stdout: Child process stdout has emitted data
  • stderr: Child process stderr has emitted data
  • warn: Child process has emitted an error
• execArgs (String|String[]): Execution arguments. Defaults to [].
• execPath (String): Execution Path. Defaults to process.execPath, which returns the absolute pathname of the executable that started the Node.js process. i.e. /usr/local/bin/node.
• force (Boolean): Enforce restart even if the process is exists. Defaults to false.
• inspect (Boolean|String|Object): Enable node inspector. Require Node.js >= v6.3.0. Defaults to false.
• instances (Number): Cluster instances. Defaults to 1.
• logLevel (String|Object): Log level. See pot-logger for detail. Here are available levels:
  • ALL
  • TRACE
  • DEBUG (default in development mode)
  • INFO (default in production mode)
  • WARN
  • ERROR
  • FATAL
  • OFF
• logsDir (String): Log files directory. In daemon mode, log messages will write to some .log files.
• maxRestarts (Number): How many restarts are allowed within 60s.
• monitorProcessTitle (String): Monitor process title. Defaults to "node".
• name (String): Process monitor name. Should be unique. Defaults to the basename of baseDir.
• production (Boolean): Production mode. Short hand for setting NODE_ENV="production" env. Defaults to true.
• watch (Boolean|Object): Enable watch mode. Defaults to false. Here are available props for object config:
  • enable (Boolean): Enable watch. Defaults to true.
  • dirs (String|String[]): Defining watching directories.
  • ignoreDotFiles (Boolean): Ignore watching .* files. Defaults to true.
  • ignoreNodeModulesDir (Boolean): Ignore watching node_modules directory. Defaults to true.
• workspace (String): Workspace.

Connection

API to communicate with monitors

(TODO)

• Connection.getNames(options)
• Connection.getByName(name, options)
• Connection.getState(name, options)
• Connection.getAllInstances(options)
• Connection.flushOffline()
• connection#getState(instanceId)
• connection#restart()
• connection#reload(options)
• connection#scale(number)
• connection#flush()
• connection#disconnect()
• connection#requestStopServer(options)

Operators

Command lines interface helper functions

(TODO)

• Operators.start(options)
• Operators.restart(options)
• Operators.restartAll(options)
• Operators.reload(options)
• Operators.reloadAll(options)
• Operators.stop(options)
• Operators.stopAll(options)
• Operators.scale(options)
• Operators.list(options)
• Operators.show(options)
• Operators.log(options)
• Operators.flush(options)
• Operators.flushAll(options)

Schemas

Config and CLI json schemas

(TODO)

Commands

pot-js commands descriptor. Useful to extend or modify command via createCli()

A command may contain these props:

• command (String): A string representing the command. eg: stop [name]
• description (String): Command description
• schema (Object): The JSON schema of options and positional arguments
• operator (Function): The operator function of the command

(TODO)

createCli(pkg, commands)

A helper function to create CLI, built on top of yargs

(TODO)

License

MIT