pi

pixl-ipc

IPC Server using Unix Sockets and the pixl-server framework

Showing:

Popularity

Downloads/wk

1

GitHub Stars

2

Maintenance

Last Commit

7mos ago

Contributors

2

Package

Dependencies

6

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

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

NameTypeDescription
socket_pathstringPath where the socket file will be created -- must be same in client
exit_timeoutintegerWhen shutting down and waiting for client connections to close, this will force an exit when the timeout is exceeded (default 2000ms)
socket_chmodstringThe CHMOD(2) permission of the socket file (default: '777')
log_stats_intervalstringThe frequency to log various stats using pixl-server event intervals. (default: 'minute')

Methods

addURIHandler(uriPattern, name, callback)

NameTypeDescription
uriPatternstring or regexIdentifies the type of messages the handler should receive by matching the URI request pattern
namestringThe name to associate with the handler (for logging)
callbackfunctionThe 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

NameTypeDescription
delayintegerThe 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])

NameTypeDescription
socket_pathstringPath where the socket file will be created -- must be same in client
loggerPixlLoggerInstance of a PixlLogger object if you want logging (optional)
optionsjson objectOverride 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)

NameTypeDescription
callbackfunctionThe 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)

NameTypeDescription
uristringThe server URI being requested
messagejson objectThe data to send to the IPC server
callbackfunctionWhen 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)

NameTypeDescription
callbackfunctionCalled 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])

NameTypeDescription
socket_pathstringPath where the socket file will be created -- must be same in client
optionshash arrayOverride 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)

NameTypeDescription
uristringThe server URI being requested
messagehash arrayThe 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 Sizelaptop (ms)EC2 (ms)
1K0.130.09
5K0.190.094
10K0.360.18
20K0.640.316
100K3.351.374

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial