cp-remote v1.0.2

cp-remote   

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

• 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> ...

c8 results are available here.

Coveralls page is here.

API

Source: index.js

• run

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—