An easy way to send JSON over TCP using sockets.
npm install json-socketJsonSocket is a very easy way to send JSON over a socket using either TCP or UNIX sockets. JsonSocket uses a decorator pattern
to expose extra methods and events on instances of net.Socket.
These methods and events makes it straightforward to send bidirectional JSON messages of any kind and size.
You can install JsonSocket using Node Package Manager (npm):
``
npm install json-socket
Or add it to your package.json file, like this:
`json`
{
...
"dependencies": {
"json-socket": "*"
}
...
}
And then run:
`
npm install
JsonSocket relies on Node.js' built-in net package. Everytime you have an instancenet.Socket
of you simply wrap in an instance of JsonSocket.
Here is a simple example where a client can connect to the server and send two numbers (a and b) that the server multiplies
and sends back the result.
#### Server
`javascript
var net = require('net'),
JsonSocket = require('json-socket');
var port = 9838;
var server = net.createServer();
server.listen(port);
server.on('connection', function(socket) { //This is a standard net.Socket
socket = new JsonSocket(socket); //Now we've decorated the net.Socket to be a JsonSocket
socket.on('message', function(message) {
var result = message.a + message.b;
socket.sendEndMessage({result: result});
});
});
`
`javascript
var net = require('net'),
JsonSocket = require('json-socket');
var port = 9838; //The same port that the server is listening on
var host = '127.0.0.1';
var socket = new JsonSocket(new net.Socket()); //Decorate a standard net.Socket with JsonSocket
socket.connect(port, host);
socket.on('connect', function() { //Don't send until we're connected
socket.sendMessage({a: 5, b: 7});
socket.on('message', function(message) {
console.log('The result is: '+message.result);
});
});
`
---------------------------------------
Here is an example of a server that can stream square numbers. A client can connect and send a start command which shouldbeginAt
also include a value, i.e. which number should be squared first. Then the server streams a square every second,stop
until the client sends a command.
#### Server
`javascript
var net = require('net'),
JsonSocket = require('json-socket');
var port = 9838;
var server = net.createServer();
server.listen(port);
server.on('connection', function(socket) {
socket = new JsonSocket(socket);
var n;
var isRunning = false;
var streatTimeout;
socket.on('message', function(message) {
if (message.command == 'start') {
if (!isRunning) {
n = message.beginAt || 1;
isRunning = true;
streamInterval = setInterval(function() {
socket.sendMessage(n * n);
n++;
}, 1000);
}
} else if (message.command == 'stop') {
if (isRunning) {
isRunning = false;
clearInterval(streamInterval);
}
}
});
});
`
`javascript
var net = require('net'),
JsonSocket = require('json-socket');
var port = 9838; //The same port that the server is listening on
var host = '127.0.0.1';
var socket = new JsonSocket(new net.Socket()); //Decorate a standard net.Socket with JsonSocket
socket.connect(port, host);
socket.on('connect', function() { //Don't send until we're connected
socket.sendMessage({command: 'start', beginAt: 10});
socket.on('message', function(square) {
console.log(square);
if (square > 200) {
socket.sendMessage({command: 'stop'});
}
});
});
`
Will output:
`
100
121
144
169
196
225
---------------------------------------
JsonSocket has two helper methods that are useful if you just need to send a single message and you don't need the socket
to stay open.
The second method is JsonSocket.sendSingleMessage. It sends a single message and closes the connection instantly.
Use this if you need to send a server a message, but you don't need any response.
`javascript
var JsonSocket = require('json-socket');
JsonSocket.sendSingleMessage(port, host, {type: 'ping'}, function(err) {
if (err) {
//Something went wrong
throw err;
}
console.log('Pinged '+host+' on port '+port);
});
``
The second method is JsonSocket.sendSingleMessageAndReceive. It sends a single message, waits for a single response
message from the server and closes the connection right after.
Use this if you need to send a server a message, and get a response, but you don't need the connection to stay open.
`javascript
var JsonSocket = require('json-socket');
JsonSocket.sendSingleMessageAndReceive(port, host, {type: 'ping'}, function(err, message) {
if (err) {
//Something went wrong
throw err;
}
console.log('Server said: '+message.type); //E.g. pong
});
``
The messages can be any Javascript object that can be converted to JSON:
- Strings
- Numbers
- Booleans
- Objects
- Arrays
- Anything!
Since JsonSocket is a decorator of net.Socket, it supports all methods that net.Socket supports.
Besides that the following methods and events are also available on JsonSocket instances.
Sends a single message anc close the connection instantly.
__Arguments__
- port - Port to send the message to.
- most - Host to send the message to.
- message - The message to send.
- callback(err) - Will be called when the message has been sent.
---------------------------------------
Sends a single message to host:port, waits for a response message, and closes the connection right after.callback
As soon as the response message is received the function is invoked (if given) with the response message
as the second argument.
__Arguments__
- port - Port to send the message to.
- most - Host to send the message to.
- message - The message to send.
- callback(err, message) - Will be called when the response message has been received. The response message is given as the second argument.
---------------------------------------
Sends a JSON a message over the socket.
__Arguments__
- message - The message to send.
- callback(err) - Will be called after the message has been sent.
---------------------------------------
Same as socket.sendMessage, except that the socket is closed right after the message has been sent using net.end().
No more messages can be sent from either the server or client through this socket.
---------------------------------------
Convenience method for sending an error as a message.
__Arguments__
- err - An Error object that should be formatted as a message.
- callback(err) - Will be called after the message has been sent.
__Example__
`javascript`
socket.sendError(new Error('Something went wrong!');
Will send a message of this JSON format:
`json`
{
"success": false,
"error": "Something went wrong"
}
---------------------------------------
Same as socket.sendError, except that the socket is closed right after the message has been sent using net.end().
No more messages can be sent from either the server or client through this socket.
---------------------------------------
Returns true if either the server or the client has closed the connection. Returns false otherwise.
---------------------------------------
- message - the message received from the other side.
Emitted when a complete message has been received.
The JsonSocket protocol works by JSON.stringify'ing the message and prefixing it with a content length and a content length delimiter (#).
Example:
`javascript`
socket.sendMessage({
type: "ping"
});
Will send a message that looks like this:
`
15#{"type":"ping"}
This mechanism ensures that messages that are chunked will be parsed correctly.
##Todo
- socket.request() method, and request` event. Makes it easier to send multiple requests with callbacks.