Nascent Political Miscreant

    json-socket
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/json-socket package

    0.3.0 • Public • Published

    JsonSocket Build Status

    JsonSocket 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.

    Installation

    You can install JsonSocket using Node Package Manager (npm):

    npm install json-socket
    

    Or add it to your package.json file, like this:

    {
        ...
        "dependencies": {
            "json-socket": "*"
        }
        ...
    }

    And then run:

    npm install
    

    Usage

    JsonSocket relies on Node.js' built-in net package. Everytime you have an instance of net.Socket you simply wrap in an instance of JsonSocket.

    Simple client/server example

    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

    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});
        });
    });

    Client

    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);
        });
    });

    Streaming example

    Here is an example of a server that can stream square numbers. A client can connect and send a start command which should also include a beginAt value, i.e. which number should be squared first. Then the server streams a square every second, until the client sends a stop command.

    Server

    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++;
                    }, 1000);
                }
            } else if (message.command == 'stop') {
                if (isRunning) {
                    isRunning = false;
                    clearInterval(streamInterval);
                }
            }
        });
    });

    Client

    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
    

    Sending a single message

    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.

    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.

    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
    });

    Message formats

    The messages can be any Javascript object that can be converted to JSON:

    • Strings
    • Numbers
    • Booleans
    • Objects
    • Arrays
    • Anything!

    Extra methods exposed on JsonSocket instances

    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.

    JsonSocket.sendSingleMessage(port, host, message, callback)

    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.

    JsonSocket.sendSingleMessageAndReceive(port, host, message, callback)

    Sends a single message to host:port, waits for a response message, and closes the connection right after. As soon as the response message is received the callback 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.

    socket.sendMessage(message, callback)

    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.

    socket.sendEndMessage(message, callback)

    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.


    socket.sendError(err, callback)

    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

    socket.sendError(new Error('Something went wrong!');

    Will send a message of this JSON format:

    {
        "success": false,
        "error": "Something went wrong"
    }

    socket.sendEndError(err, callback)

    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.


    socket.isClosed()

    Returns true if either the server or the client has closed the connection. Returns false otherwise.


    Event: 'message'

    • message - the message received from the other side.

    Emitted when a complete message has been received.

    How the protocol works

    The JsonSocket protocol works by JSON.stringify'ing the message and prefixing it with a content length and a content length delimiter (#).

    Example:

    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.

    Keywords

    none

    Install

    npm i json-socket

    DownloadsWeekly Downloads

    195,148

    Version

    0.3.0

    License

    none

    Last publish

    Collaborators

    • samuelbolduc
    • sebastianseilund