tcp-emitter v1.1.1

TCP Emitter Server

TCP Emitter Server is a net.Server object that acts as an Event Emitter router for different processes. These processes (known as TCP Emitter clients) can be implemented in any language and interact with TCP Emitter server via the TCP Protocol.

Installation

npm install --save tcp-emitter

API

require('tcp-emitter')(options)

Delimiter

Delimiter used to seperate payloads in a single TCP request. Apart from making it possible for TCP Emitter clients to combine multiple payloads in a single TCP request, this was mainly implemented due to the use of Nagle's algorithm in NodeJS net module. When sending data through TCP while using net module in seperate .write() invocations, it will try to combine the messages together and send them in a single TCP request. For this reason when sending a payload (even when a TCP message consist of one payload), it should end with the specified delimiter.

Nagle's algorithm in NodeJS

// Sending a message from the client side.
clientSocket.write('hello')
clientSocket.write('world')

// Receiving the message from the server side.
serverSocket.on('data', console.log) // => 'helloworld'

Verify Client

Function used to verify whether a connection should be allowed or denied. When omitted, all connections are allowed. When specified a connection will be allowed if it returns true. When this function requires async processing it should return a Promise resolved with true to allow a connection or any other value but true to deny it.

Synchronous Verify Client.

const verifyClient = socket => allowed.indexOf(socket.address().address) !== -1
require('tcpEmitter')(verifyClient).listen({ host: 'localhost', port: 8080 })

Asynchronous Verify Client

const verifyClient = socket => {
  return makeRequest('GET', '/allowed').then(allowed => {
    return allowed.indexOf(socket.address().address) !== -1
  })
}

require('tcpEmitter')(verifyClient).listen({ host: 'localhost', port: 8080 })

Events

The following table contains the events emitted by TCP Emitter server

TCP Emitter Clients

As specified in the introduction, these can be implemented in any language as long as they follow the TCP Emitter Payload spec. A TCP Emitter client can do the following three different interactions with the TCP Emitter server:

Examples assume that '@@@' delimiter is used. For more info about why delimiter is used please refer to this section.

Payload Spec

Subscribe

Example

{"type": "subscribe", "event": "event-name"}@@@

Unsubscribe

Example

{"type": "unsubscribe", "event": "event-name"}@@@

Broadcast

When a TCP Emitter client broadcasts to an event which itself is subscribed to, it won't be notified by TCP Emitter server.

Example

{"type": "broadcast", "event": "event-name", "args": [1, "text", true, {"name": "luca"}]}@@@

Multi-Payload TCP Request

As mentioned in the delimiter section, TCP Emitter clients can send multiple payloads in a single TCP Request. The following is an example of a TCP Request message containing multiple payloads.

{"type": "subscribe", "event": "new-user"}@@@{"type": "unsubscribe", "event": "new-admin"}@@@{"type": "broadcast", "event": "access-change", "args": ["user"]}@@@

Example

TCP Emitter server configured with a delimiter set to !!!

require('tcp-emitter')({
  delimiter: '!!!'
}).listen({ host: 'localhost', port: 8080 })

Note in this example TCP Emitter clients are implemented in JavaScript, however as mentioned in the introduction these can be implemented in any language.

TCP Emitter client 1.

const clientOne = require('net').createConnection({
  host: 'localhost',
  port: 8080
}, () => {
  clientOne.on('data', console.log)
  
  clientOne.setEncoding('utf-8')

  clientOne.write(JSON.stringify({
    type: 'subscribe',
    event: 'got-episode'
  }) + '!!!')
})

TCP Emitter client 2.

const clientTwo = require('net').createConnection({
  host: 'localhost',
  port: 8080
}, () => {
  clientTwo.on('data', console.log)
  
  clientTwo.setEncoding('utf-8')

  clientTwo.write(JSON.stringify({
    type: 'subscribe',
    event: 'got-episode'
  }) + '!!!')
})

When TCP Emitter 1 broadcasts to got-episode event:

clientOne.write(JSON.stringify({
  type: 'broadcast',
  event: 'got-episode',
  args: ['S7E5 - Eastwatch']
}) + '!!!')

TCP Emitter 2 'data' listener will be invoked with the following string:

'{"event":"got-episode","args":["S7E5 - Eastwatch"]}!!!'

Tests

npm install
npm test

Generate Documentation

npm install
npm run docs

License

ISC