:dash: turbo-ws

A blazing fast low-level WebSocket server based on turbo-net.

Features

• Supports thousands of concurrent connections with minimal CPU and RAM impact.
• Binary and text frames are supported. That means you can directly send Node's Buffers or Strings if you prefer.
• Built with reliability in mind.

Getting Started

Install turbo-ws using npm:

npm install --save @hugmanrique/turbo-ws

Or via yarn:

yarn add @hugmanrique/turbo-ws

The minimum supported Node version is v8.10.0.

Let's get started by creating a WebSocket server:

import Server from '@hugmanrique/turbo-ws';

const server = new Server();
const port = 80;

Then, add a 'connection' listener. The callback will contain a Connection and a Request object:

server.on('connection', (connection, req) => {
  const userAgent = req.getHeader('User-Agent');

  console.log(`Using ${userAgent} browser`);
  connection.send('Hello world!');
});

Finally call the #listen(port) method and run your Node app:

server.listen(port).then(() => {
  console.log(`Listening on *:${port}`);
});

Methods

connection.send(data)

Sends data to the client. Depending on the type of the passed object, it will send the data in one or multiple frames:

• Strings get sent directly in one frame.
• Objects get converted to strings through JSON.stringify.
• Node's Buffers get sent as binary data and may be sent in multiple frames.

connection.ping([payload])

Sends a ping frame that may contain a payload. The client must send a Pong frame with the same payload in response. Check the connection.on('pong') method for more details.

connection.close([callback])

Closes the connection.

server.broadcast(data)

Sends data to all the clients. Follows the same logic as connection.send(data)

server.getConnections()

Get an unordered array containing the current active connections.

server.close()

Closes the server. Returns a Promise that will get completed when all the connections are closed.

Events

Both the Server and the Connection are EventEmitters, so you can listen to these events:

server.on('connection', connection)

Emitted when a new connection is established. The callback arguments are connection, request, where the first is a turbo-net Connection and the later is a turbo-http Request object. Check out their docs to see what fields and methods are available.

server.on('close')

Emitted when the server has terminated all the WebSocket connections and it is going to die.

connection.on('text', string)

Emitted when the client sends some text data.

connection.on('binary', binaryStream)

Emitted when the client sends some buffered binary data. Returns a BinaryStream, which is a wrapper for Node's stream.Readable. You can then add listeners to the stream:

const writable = fs.createWriteStream('file.txt');

connection.on('binary', stream => {
  stream.pipe(writable);

  stream.on('end', () => {
    console.log('Saved client logs to disk!');
  });
});

connection.on('ping')

Emitted when the server received a Ping frame from the client.

connection.on('pong')

Emitted when the server received a Pong frame from the client.

connection.on('close')

Emitted when a connection is fully closed. No other events will be emitted after.

License

MIT © Hugo Manrique