Skip to content


Subversion checkout URL

You can clone with
Download ZIP
tag: v0.3.0
Fetching contributors…

Cannot retrieve contributors at this time

112 lines (86 sloc) 3.665 kb


An elegant way to define lightweight protocols on-top of TCP/TLS sockets in node.js


Installing npm (node package manager)

  curl | sh

Installing nssocket

  [sudo] npm install nssocket


Working within node.js it is very easy to write lightweight network protocols that communicate over TCP or TLS. The definition of such protocols often requires repeated (and tedious) parsing of individual TCP/TLS packets into a message header and some JSON body.

With nssocket this tedious bookkeeping work is done automatically for you in two ways:

  1. Leverages wildcard and namespaced events from EventEmitter2
  2. Automatically serializes messages passed to .send() and deserializes messages from data events.
  3. Automatically wraps TCP connections with TLS using a known workaround


Messages in nssocket are serialized JSON arrays of the following form:

  ["namespace": "to": "event", { "this": is, "the": payload }]

Although this is not as optimal as other message formats (pure binary, msgpack) most of your applications are probably IO-bound, and not by the computation time needed for serialization / deserialization. When working with NsSocket instances, all events are namespaced under data to avoid collision with other events.


So get on with it right? SHOW ME SOME CODE!

Simple Example

  var nssocket = require('nssocket');

  // Create an `nssocket` TCP server
  var server = nssocket.createServer(function (socket) {
    // Here `socket` will be an instance of `nssocket.NsSocket`.
    socket.send(['you', 'there']);['iam', 'here'], function (data) {
      // Good! The socket speaks our language 
      // (i.e. simple 'you::there', 'iam::here' protocol)
      // { iam: true, indeedHere: true }

  // Tell the server to listen on port `6785` and then connect to it
  // using another NsSocket instance.

  var outbound = new nssocket.NsSocket();['you', 'there'], function () {
    outbound.send(['iam', 'here'], { iam: true, indeedHere: true });



socket.send(event, data)

Writes data to the socket with the specified event, on the receiving end it will look like: JSON.stringify([event, data]).

socket.on(event, callback)

Equivalent to the underlying .addListener() or .on() function on the underlying socket except that it will permit all EventEmitter2 wildcards and namespaces., callback)

Helper function for performing shorthand listeners namespaced under the data event. For example:

  // These two statements are equivalent
  someSocket.on(['data', 'some', 'event'], function (data) { });['some', 'event'], function (data) { });


Closes the current socket, emits close event, possibly also error


Remove all listeners, destroys socket, clears buffer. It is recommended that you use socket.end().


All tests are written with vows and should be run through npm:

  $ npm test

Author: Nodejitsu

Contributors: Paolo Fragomeni, Charlie Robbins, Jameson Lee

Jump to Line
Something went wrong with that request. Please try again.