ws-rpc

lightweight RPC support for the ws WebSocket server

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

Install dependencies:

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

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(errargs) {
        if(err)
            // ... 
    });
    
    //client.on(... <-- not here, see below 
});
 
// handle message from a client without a callback 
wss.on('some message', function(clientargs) {
 
    // ... 
});
 
// handle message from a client with a callback 
wss.on('some message', function(clientargscb) {
 
    // ... 
    
    // 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(eclient) {
    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(dataflags) {
        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);

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(argscb) {
 
            // ... 
            
            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(errargs) {
            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.. 
 

New BSD License.