About

An event-driven IPC implementation for NodeJS using unix file sockets

Docs | Source | Releases | NPM

Table of Contents

About (you are here)

Usage

Advanced Usage

API

Quick Start

Want to get up and running quickly? This is for you.

Install

npm install --save @crussell52/socket-ipc

A Simple Example

Client:

const {Client} = require('@crussell52/socket-ipc');
const client = new Client({socketFile: '/tmp/myApp.sock'});

// Say hello as soon as we connect to the server with a simple message
// that give it our name.
client.on('connect', () => client.send('hello', {name: 'crussell52'}));

// Connect. It will auto-retry if the connection fails and auto-reconnect if the connection drops.
client.connect();

Server:

const {Server} = require('@crussell52/socket-ipc');
const server = new Server({socketFile: '/tmp/myApp.sock'});

// Listen for errors so they don't bubble up and kill the app.
server.on('error', err => console.error('IPC Server Error!', err));

// Log all messages. Topics are completely up to the sender!
server.on('message', (message, topic) => console.log(topic, message));

// Say hello back to anybody that sends a message with the "hello" topic. 
server.on('message.hello', (message, clientId) => server.send('hello', `Hello, ${message.name}!`, clientId));

// Start listening for connections.
server.listen();

// Always clean up when you are ready to shut down your app to clean up socket files. If the app
// closes unexpectedly, the server will try to "reclaim" the socket file on the next start.
function shutdown() {
    server.close();
}

More Examples

Check out the /examples directory in the source for more code samples. (Make sure you set the SOCKET_FILE constant at the top of the example files before you run them!)

Limitations

Let’s get this out of the way early…

Requires:

Transport Support:

Unsupported Features:

Love the project, but you need it to do something it doesn’t? Open up a feature request!

Alternate solutions

node-ipc ZeroMQ

Why this one?

When I needed to solve this problem, most of what I found was tied to some extra external dependency or platform (electron, redis, etc). The node-ipc lib caught my eye for a time, but I wasn’t in love with the interface and it was published under a non-standard (and sometimes considered “satirical”) license.

So this package was born. Here are the goals of this project: