Skip to content

Latest commit

 

History

History
151 lines (96 loc) · 3.63 KB

README.md

File metadata and controls

151 lines (96 loc) · 3.63 KB
Raw

node-walve

walve is a stream based WebSocket implementation for node.js.

const walve = require('walve');

walve.createServer(wsocket => {
  wsocket.on('incoming', incoming => {
    // handle readable incoming stream
  })
}).listen(server)

Examples

You can find working examples in the /opt directory of this project.

  • echo: echos messages back to the browser
  • sugar: extends Server with some api sugar
  • stream: streams file through websocket to document
  • cluster: streams file through websocket cluster (hot concurrency)

Furthermore there are currently two real world examples using walve. Feel free to add own projects:

  • nearby real time geolocation tracking with walve and google maps
  • messenger real time messenger with support for image streaming

Installation

The package is available on npm as walve.

npm install --save walve

Documentation

Server

new Server([options])

Creates a new Server instance. Valid options are for example url which can be used to have multiple websocket servers on one http server.

Event: "connect"

Emitted when a new WebSocket upgrade was established. Provides instance of Socket as argument.

Event: "error"

Emitted when an error occurs. For example on failed upgrade.

server.listen(http)

Listens on the "upgrade" event of the http instance.

Socket

Abstracts a single WebSocket connection.

new Socket(socket)

Creates a new duplex stream Socket which reads and writes from the underlaying TCP socket.

Event: "incoming"

wsocket.on('incoming', function(incoming) {
  incoming.pipe(process.stdout, { end: false });
});

Emitted when a WebSocket frame is received. First argument is a an instance of Incoming.

Event: "end"

Emitted when the TCP connection closes.

socket.end

wsocket.end();
// actually better:
var outgoing = new Outgoing({ opcode: 0x08 });
outgoing.pipe(socket);
outgoing.end();

Will completly close the TCP socket.

Incoming

Abstracts an incoming WebSocket frame.

new Incoming()

Creates a new instance of the Incoming transform stream. Which transforms incoming WebSocket frames to node buffers.

incoming.header

if (incoming.header.opcode === 0x01) {
    // handle data as unicode
}

Contains fin, opcode, length and so on. You will mainly be interested in header.opcode as the other values are more for internal use.

Event: "readable"

var message = '';

incoming.on('readable', function() {
  message += incoming.read().toString();
});

Emitted when there is payload to read from the frame.

Event: "end"

incoming.on('end', function() {
  // log prev buffered messages
  console.log(message);
});

Emitted when frame ends and data was consumed with incoming.read().

Outgoing

Abstracts an outgoing WebSocket frame.

new Outgoing([options])

Returns a new instance of Outgoing transform stream. As this is a transform and not a writable stream you must pipe outgoing to the websocket socket provided by the server "connect" event. Options can contain a header object. See below for more.

outgoing.header

outgoing.header.final = true;
outgoing.header.masked = false;
outgoing.header.opcode = 0x01;
outgoing.header.length = 0x0a;

outgoing.write('Hello World').pipe(wsocket, { end: false });

Sets the header information of an outgoing frame. You can omit final and opcode as they will use most common default values true and 0x01 (text frame).