The pixl-ipc module provides interprocess communication (IPC) using unix domain sockets to provide fast local communication between processes that avoids touching the network stack. It is built as a component of pixl-server, a lightweight framework for building node.js daemon applications.

• JSON messages over UNIX domain sockets
• Protocol is language agnostic
• PHP and Node.js client classes provided
• Node.js client now supports async/await

Usage

Creating a Simple Server

var PixlServer = require('pixl-server');

var server = new PixlServer({
		
		__name: 'MyIPCServer',
		__version: "0.1",
		
		config: {
				"log_dir": "/var/tmp",
				"log_filename": "my_ipc_test.log",
				"debug_level": 9,
				
				"IPCServer" : {
					"socket_path" : "/var/tmp/my_ipc_server.sock"
				}
		},
		
		components: [require('pixl-ipc')]
		
});

server.startup( function() {
		console.log("Main startup");
		
		server.IPCServer.addURIHandler(/^\/myapi\/test/, "IPCServer", function(request, callback) {
			callback({"hello":"thanks for your message"});
		});
} );

Making Request from a Client

The Node.js client supports callback style requests as well as async/await-style Promises. If a callback is omitted, the methods connect/send/close will return a promise.

const IPCClient = require('pixl-ipc/client');

var testClient = new IPCClient("/var/tmp/my_ipc_server.sock");
testClient.connect(function() {
	testClient.send('/myapi/test', {"welcome":42}, function(err, data) {
		console.log(err, data);
	});
	
	testClient.send('/ipcserver/test/echo', {"ping":"me"}, function(err, data) {
		console.log(err, data);
	});
});

// Or using async/await
async function run() {
	let asyncClient = new IPCClient("/var/tmp/my_ipc_server.sock");
	try {
			await asyncClient.connect();
			let result =  await asyncClient.send('/myapi/test', {"welcome":42});
			console.log(result);
			await.asyncClient.close();
	}
	catch (e) {
		console.log("Exception: " + e);
	}
}

run();

Server

Config

Name	Type	Description
socket_path	string	Path where the socket file will be created -- must be same in client
exit_timeout	integer	When shutting down and waiting for client connections to close, this will force an exit when the timeout is exceeded (default 2000ms)
socket_chmod	string	The CHMOD(2) permission of the socket file (default: '777')
log_stats_interval	string	The frequency to log various stats using pixl-server event intervals. (default: 'minute')

Methods

addURIHandler(uriPattern, name, callback)

Name	Type	Description
uriPattern	string or regex	Identifies the type of messages the handler should receive by matching the URI request pattern
name	string	The name to associate with the handler (for logging)
callback	function	The method to call when a message is received

This method registers callback handler to process incoming requests matching the specified URI pattern. When the handler is called it is passed the request object and response callback.

The request contains:

Name	Type	Description
uri	string	URI passed from client
data	json object	The data from the client
pid	integer	The process ID of the client (Not yet implemented)

myHandler(request, callback) {
	console.dir(request);
	callback({thanks: "a lot"});
}

getStats()

Returns various statistics about the IPC server.

Built-in Message Handlers

/ipcserver/test/echo

You can pass in any arbitrary object and the server will echo back the message in the response

/ipcserver/test/delay

Name	Type	Description
delay	integer	The time in milliseconds to delay before sending a response back

This sets a delay response to the caller and sends back {delay: N}.

Node.js Client

Methods

constructor(socket_path [,logger, options])

Name	Type	Description
socket_path	string	Path where the socket file will be created -- must be same in client
logger	PixlLogger	Instance of a PixlLogger object if you want logging (optional)
options	json object	Override settings such as request timeout

// options with current defaults, times are in milliseconds
{
	userAgent: "Node/IPCClient" + process.cwd(), // A string that identifies your application
	requestTimeout : 10*1000, // How long to wait before timing out the request
	autoReconnect: 1000, // Reconnect in N ms if the connection is broken or set to 0 to prevent automatic reconnect
	codeToErr: false, // When a result message contains a non-falsey (zero) "code" element use the message as the error in callback
	messageTransform: null, // Provide a function to transform the error or data result before sending to the callback (details below)
	logStatsInterval: null // Logs perf metrics of the JSON stream every logStatsInterval milliseconds
}

Creates the client object and overrides default options if provided.

For messageTransform you can provide a function that alters the error or data before it is sent to the messages callback handler. It will override the codeToErr option if provided. The function is passed the full message object and should return an array of [err, data]. Here's an example implementation (the code used to implement codeToErr):

function codeToErr(msg) {
	var err = null;
	if (msg.code) {
		err = msg;
	}
	else if (msg.data && msg.data.code) {
		err = msg.data;
	}	
	return [err, msg.data];
}

connect(callback)

Name	Type	Description
callback	function	The function to call once the client is connected to the server

Opens a socket connection to the server. Callback is invoked with an error object or null if there was no error.

send(uri, message, callback)

Name	Type	Description
uri	string	The server URI being requested
message	json object	The data to send to the IPC server
callback	function	When the server sends a response, this callback will be invoked with (err, data)

Sends an asynchronous JSON request to the IPC Server and gets the response back in the callback.

close(callback)

Name	Type	Description
callback	function	Called once the connection is closed (optional)

Closes the socket connection and clears any timers.

PHP Client

PixlIPCClient provides an API for sending socket messages to the IPC server. Unlike the Node client, it is a blocking, synchronous model.

Sample

require_once "PixlIPCClient.class.php";

$ipc = new PixlIPCClient("/tmp/node_ipc_server.sock");
$ipc->connect();
$msg = array("hello"=>"there");
$result = $ipc->send('/ipcserver/test/echo', $msg);
print($msg)

Methods

constructor(socket_path [, options])

Name	Type	Description
socket_path	string	Path where the socket file will be created -- must be same in client
options	hash array	Override settings such as request timeout

// options with current defaults, times are in milliseconds
array(
	'userAgent' => "PHP/PixlIPCClient" . getcwd(), // A string that identifies your application
	'requestTimeout' => 500, // How long to wait before timing out the request
	'connectTimeout' => 500 // How long to wait before timing out the connection
)

Creates the client object and overrides default options if provide.

connect()

Opens a socket connection to the server. Throws exception if there was an error.

send(uri, message)

Name	Type	Description
uri	string	The server URI being requested
message	hash array	The data to send to the IPC server

Sends a JSON request to the IPC Server and returns the response. Throws exception if there was an error.

Performance Notes

In testing on a local ancient laptop (2011 2.4 GHz Intel Core i7), performance is sub-millisecond for message sizes under about 20K and about twice as fast on a reasonable AWS EC2 Instance (m4.xlarge).

Msg Size	laptop (ms)	EC2 (ms)
1K	0.13	0.09
5K	0.19	0.094
10K	0.36	0.18
20K	0.64	0.316
100K	3.35	1.374