Remote child_process runner with message support
HTML JavaScript CSS Python Shell
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
coverage
diagrams
test
.gitignore
.travis.yml
Gruntfile.js
LICENCE
README.md
cp-remote.py
cp-remote.sh
index.js
pack.sh
package-lock.json
package.json
packed.js

README.md

cp-remote   Build Status Coverage Status NPM version

Node.js child_process done remotely, IPC channel intact!

Example:

var cp_remote = require('cp-remote');
var assert = require('assert');
var remote = cp_remote.run('host', '/path/on/host/to/sub.js', 'foo', { answer: 42 });
remote.on('message', function (msg)
{
    assert.deepEqual(msg, { foo: 'bar' });
});
remote.send({ hello: 'world' });

You might implement the remote script, sub.js, like this:

var assert = require('assert');
assert.equal(process.argv[2], 'foo')
assert.deepEqual(process.argv[3], { answer: 42 });
process.on('message', function (msg)
{
    assert.deepEqual(msg, { hello: 'world' });
    process.disconnect();
});
process.send({ foo: 'bar' });

The API is described here.

Pre-requisites

Client:

  • SSH client (e.g. OpenSSH), configured for password-less logon to the remote host (e.g. using a private key).
  • Node.js (of course)
  • Bash
  • socat

Remote host:

  • SSH server (e.g. OpenSSH)
  • Node.js (node command should be in the remote PATH of SSH sessions)
  • Python (it provides access to socketpair, Node does not)
  • socat

Installation

npm install cp-remote

Limitation

You can't pass handles to a remote child process like you can with local child processes.

How it works

How it works

  • cp-remote calls child_process.spawn to run a Bash script, cp-remote.sh. The IPC channel will be on $NODE_CHANNEL_FD.
  • cp-remote.sh runs socat, telling it to relay data between $NODE_CHANNEL_FD and an SSH connection to the remote host.
  • The SSH connection is told to start cp-remote.py on the remote host.
  • cp-remote.py calls socket.socketpair to create a pair of connected file descriptors (Unix domain sockets).
  • cp-remote.py starts socat, telling it to relay data between standard input (i.e. the SSH connection) and one of the connected file descriptors.
  • cp-remote.py sets NODE_CHANNEL_FD to the other connected file descriptor and starts node, telling it to run the module you specified.

Licence

MIT

Test

To test creating and communicating with remote child processes:

grunt test --remote=<host1> --remote=<host2> ...

You can specify as many remote hosts as you like. The test will try to create a remote child process on each host and then communicate with each one.

It assumes the cp-remote module is installed at the same path on each host.

Lint

grunt lint

Code Coverage

grunt coverage --remote=<host1> --remote=<host2> ...

Instanbul results are available here.

Coveralls page is here.

API

Source: index.js

run(host, module_path)

Run a Node.js module on a remote host and return a child_process.ChildProcess object for communication with it.

Parameters:

  • {String} host The name (or IP address) of the remote host to run the module on.
  • {String} module_path The path to the module on the remote host. Any arguments following module_path will be made available to the module in its process.argv (starting at the third element).

Return:

{child_process.ChildProcess} The ChildProcess object for the remote process. You can do the same things with this object as a local ChildProcess, except send it handles (i.e. the optional sendHandle parameter to child.send isn't supported).

Go: TOC

—generated by apidox