ws-rpc: lightweight RPC support for the ws WebSocket server

Server

Install dependencies:

npm install express
npm install ws
npm install ws-rpc
npm install ws-flash-client
npm install policyfile

Complete example with Express, ws, and the Flash client shim support:

Notes:

• args stands for multiple arguments, e.g. arg1, arg2, arg3
• messages with callbacks can only be used when messaging a single client

var prod = process.env.NODE_ENV === 'production';
var app = require('express').createServer();
var wss = new (require('ws').Server)({ server: app });
var wsrpc = require('ws-rpc').extend(wss);
var wsflash = require('ws-flash-client');
require('policyfile').createServer().listen(prod ? 843 : 10843, app);

app.configure(function() {
	// configure other stuff like express globals, jade, stylus, etc.
	// ...
	
	// configure the ws-rpc middleware:
	app.use(wsrpc.middleware(express));
	
	// configure the ws-flash-client middleware:
	app.use(wsflash.middleware(express));
	
	// static file handling must come afterwards:
	app.use(express.static(pub));
	
	// bind node to a port
	app.listen(prod ? 80 : 1234);
});

// create/get a named room (channel)
var myRoom = wss.room('myRoom');

// handle a new client connection
wss.on('connect', function(client) {

	// add client to a room
	myRoom.add(client);
	
	// message the client
	client.message('some message', args);
	
	// message the client with callback
	client.message('some message', args, function(err, args) {
		if(err)
			// ...
	});
	
	//client.on(... <-- not here, see below
});

// handle message from a client without a callback
wss.on('some message', function(client, args) {

	// ...
});

// handle message from a client with a callback
wss.on('some message', function(client, args, cb) {

	// ...
	
	// call the callback (should use node convention but not mandatory)
	cb(null, 'ok');
});

// handle client disconnection
wss.on('disconnect', function(client) {

	//myRoom.remove(client); <- not necessary, this is done automatically

	// example: broadcast to all client's rooms
	for(id in client.rooms)
		client.rooms[id].message('some message', args);
});

// message all clients connected to the server
wss.message('some message', args);

// message all clients in a room
myRoom.message('some message', args);

// and don't forget this if you don't want your Node to crash on an error:
// if the error comes from a client, the client is passed as second parameter
wss.on('error', function(e, client) {
	console.log(client ? 'client' : 'server', e);
});

Binary messages are not handled by the RPC extension, so you can handle them separately using the classic ws API.

Also, if you want to intercept the raw string messages and do your own handling in some cases, you can leave out the require('ws-rpc').extend(wss); line above, and do the following:

wss.on('connection', function(client) { // notice: "connection" vs "connect"
	client.on('message', function(data, flags) {
		if(is_my_message(data)) {
			// handle the raw message here
			// ...
			// notify the RPC extension that this message was already handled
			flags.handled = true;
		}
		// otherwise the message will be handled as RPC
	});
});

// only setup the RPC extension after the above
require('ws-rpc').extend(wss);

Browser

In your HTML page (JADE syntax shown):

!!! 5
html
	head
		meta(http-equiv='X-UA-Compatible', content='IE=Edge,chrome=1')
		//if lt IE 8
			script(src='http://cdnjs.cloudflare.com/ajax/libs/json2/20110223/json2.min.js')
		script(src='http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js')
		script(src='/ws-rpc-client.min.js')
		script(src='/ws-flash.min.js')
		script(src='/myclientcode.js')
	body
		#msg

Complete example with the Flash client shim support (for full usage and options please see ws-flash-client):

$(function() {

	$.wsFlashClientInit({}, function(err) {
		if(err)
			return log('no websocket support');

		// create the client (will use WebSocket object on the background)
		// param1: url
		// param2 (optional): protocols, see http://dev.w3.org/html5/websockets/#websocket
		// param3 (optional): connection timeout in ms (default 4s), set to -1 to disable automatic reconnecting
		// param4 (optional): reconnection wait timeout (default 1s)
		var ws = new WebSocketRPC('ws://' + window.location.host + '/');
		
		// handle a message from the server
		ws.on('some message', function(args) {
			
			// ...
		});

		// handle a message from the server with a callback
		ws.on('some message', function(args, cb) {

			// ...
			
			cb(null, 'hello from client');
			
			// or, in the case of an error:
			
			cb(new Error('some problem'));
		});
		
		// message the server
		ws.message('some message', args);
		
		// message the server with a callback
		ws.message('some message', args, function(err, args) {
			if(err)
				// ...
		});
		
		// disconnect from the server
		// param1 (optional): disable automatic reconnection
		ws.disconnect(true);

		// connected event
		ws.on('open', function(world) {
			log('connected');
			
			// access the WebSocket if needed:
			//ws.socket ... <- will be null when disconnected, and then a new one created
		});

		// disconnected event
		ws.on('close', function(world) {
			log('disconnected');
		});
		
		// error event
		ws.on('error', function(e) {
			log(e.stack || e);
		});
	});

	// just an example
	function log(s) {
		var m = $('#msg');
		m.text(m.text()  + '\n' + s);
	}
});

Usage without ws-flash-client:

var ws = new WebSocketRPC('ws://' + window.location.host + '/');

// ..and the same operations as above..

License

New BSD License.