linelink

linelink

Minimalist IPC/RPC protocol with message framing over any duplex stream. For example:

• UNIX domain socket communication
• Process-to-process IPC
• Reliable message chunking over streams

Features

✅ Simple protocol: [length in hex] [JSON payload]
✅ Symmetric client/server capabilities
✅ Also supports unidirectional messages/events
✅ Works with any duplex stream (TCP, UNIX, etc.)
✅ Promise-based API
✅ Zero dependencies
✅ Just 143 lines of code (cloc src)
✅ Multiple asyncronous messages can be "on air" at the same time.

Installation

npm install linelink

Usage

Server

import { createServer } from 'net';
import { LineLink } from 'linelink';

const server = createServer(socket => {
  const link = new LineLink(socket);
  
  link.register('ping', () => 'pong');
  link.register('add', (a, b) => a + b);
  link.on('myevent', (msg) => console.log(`received event: msg`));
}).listen('/tmp/app.sock');

Client

import { connect } from 'net';
import { LineLink } from 'linelink';

const link = new LineLink(connect('/tmp/app.sock'));
const sum = await link.call('add', 2, 3); // 5
const pong = await link.call('ping'); // 'pong'
link.send('myevent', 'hello');

Protocol Specification

A message "line" is structured like this.

HHH JsonSerializedPayload
^  ^^
│  │└─ Payload
│  └── Space (0x20)
└───── Hexadecimal value of the length of the payload, not padded.

The JSON payload from client to server is in the form

{
	method: [name of the "function" to call]
	id: an incrementing number (per connection) to match server requests
	args: the arguments specified by callee (JSON serialized)
}

The JSON payload from server to client:

{
	id: negative number matching the client's request.
	result: JSON serialized server reply
}

or { id: matching the request id error: error message string. }

Both sides can send payload with an id of 0 to send unidirectional events.

License

MIT