wsapi

ws + websocket-stream + multiplex + dnode


Why

Doing RPC and file uploads / downloads over http is not so much fun. This library lets you effortlessly serve up APIs (over websockets) that feel local. You get auto-reconnect, heartbeat keepalive and multiplexed binary streaming for free. It Just Works!

How

server.js
`` javascript
var http = require('http');
var ecstatic = require('ecstatic');
var wsapi = require('wsapi');

var statics = ecstatic(__dirname + '/share', { cache: 'no-cache' });

var server = http.createServer(function(req, res) {
console.log(req.url);
statics(req, res, function() {
req.url = '/';
statics(req, res);
});
});

wsapi({
server: server,
methods: require('./api'),
});

server.listen('8080', '::', function(err) {
console.log('server listening on ' + port);
});
`

api.js
` javascript
module.exports = function(muxer) {
return {

// simple function
hello: function(cb) {
cb(null, 'oh hai');
},

// stream
startListening: function(cb) {
var number = 0;
var stream = muxer.createStream();
var interval = setInterval(function() {
stream.write('event: ' + number++);
}, 2000);
stream.on('finish', function() {
clearInterval(interval);
});
cb(null, stream.meta);
},

};
};
`

client.js
` javascript
var wsapi = require('wsapi');
var api = wsapi();

api.on('connect', function() {

// basic function
api.methods.hello(function(err, res) {
console.log(res);
});

// stream
api.methods.startListening(function(err, id) {
api.on('stream', function(stream) {
if (stream.meta === id) {
stream.on('data', function(data) {
console.log(data.toString());
});
}
});
});

});
`

Install


npm install wsapi

Test

node test

Example

` bash
cd wsapi
npm install
node example
`

Require

#### var wsapi = require('wsapi')
In a browser this returns the client constructor - in other places, the server constructor.

Server constructor

#### var server = wsapi(opts)
Where opts _must_ contain:
* Anything needed by ws (generally an http server object or a port)
* A methods object to be passed to dnode, or a function (that accepts a multiplex instance as an argument) which returns a methods object

Server instance methods

#### server.close()
Close the server and disconnect all clients.

Client constructor

#### var api = wsapi([opts])
Where opts can contain:
* protocol string; "ws" or "wss", defaults to "ws"
* host string; defaults to "localhost"
* port string; defaults to 80
* timeout milliseconds; defaults to 5000
* reconnectInterval milliseconds; defaults to 2500
* heartbeatInterval milliseconds; defaults to 50000 (50 seconds)

Client instance methods

#### api.connect()
Generally you shouldn't need to call this directly since it is invoked automatically by the constructor and auto-reconnect logic.
#### api.disconnect()
Disconnect from the server if connected.
#### api.createStream([id])
Open a binary duplex stream to the server - if id is omitted, a random one will be generated.

Client instance properties

#### api.methods
An object, your api methods will be available on this object after connecting.
#### api.connecting
Boolean.
#### api.connected
Boolean.

Client events

#### api.emit('connect')
Emitted when a client successfully connects to a server.
#### api.emit('disconnect')
Emitted when the connection to a server is lost.
#### api.emit('stream', stream)
Emitted when a new stream has been opened by the server.
#### api.emit('error', err)`
Generally emitted when connection attempts fail and when a method call times out.

Releases

The latest stable release is published to npm.
* 2.1.0
* Disconnect client on error.
* 2.0.0
* Rewrite to support binary streaming by switching from mux-demux to multiplex.
* 1.x
* First pass.

License

Copyright © 2014 Jesse Tane

This work is free. You can redistribute it and/or modify it under the
terms of the WTFPL.

No Warranty. The Software is provided "as is" without warranty of any kind, either express or implied, including without limitation any implied warranties of condition, uninterrupted use, merchantability, fitness for a particular purpose, or non-infringement.