Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Remote child_process runner with message support
JavaScript Python Shell
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

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.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 (only version 1.7.x is supported at the current time)

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 (only version 1.7.x is supported at the current time)

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

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

Something went wrong with that request. Please try again.