Nestable Processes Mutate
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


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


    0.0.6 - Upon disconnection, client now errors (cleans) all pending (client-initiated) callbacks.


    For increased reliability, it is suggested to use the WebSocket protocol over encrypted connections only. Some proxy servers handle the unencrypted form of the protocol in a way which prevents it from operation. This is being addressed by "masking" in newer versions of the protocol, however too many older versions are already in the wild. See the second code example on this page on how to configure HTTPS support in your Node.


    Install dependencies:

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

    Example with Express, ws, and the Flash client shim support (see below for HTTPS):


    • 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 ws = require('ws-rpc').extend(require('ws'));
    var wss = new ws.Server({ server: app });
    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: 
        // configure the ws-flash-client middleware: 
        // static file handling must come afterwards: 
        // bind node to a port 
        app.listen(prod ? 80 : 1234);
    // create/get a named room (channel) 
    var myRoom ='myRoom');
    // handle a new client connection 
    wss.on('connect', function(client) {
        // add client to a room 
        // message the client 
        client.message('some message', args);
        // message the client with callback 
        client.message('some message', args, function(err, args) {
                // ... 
        // Note: 
        // you can hook your listener actions on every client separately, but if you  
        // have the same handler for every client, you should consider doing it the way 
        // below*, as with large number of clients, that will save you a lot of resources. 
        // handle message from a client without a callback 
        client.on('some message', function(args) {
            // ... 
        // handle message from a client with a callback 
        client.on('some message', function(args, cb) {
            // ... 
            // call the callback (should use node convention but not mandatory) 
            cb(null, 'ok');
    // *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.

    The above example, but with HTTP + HTTPS support

    For completeness, here's a guide on how to get a free 90-day SSL certificate:

    1. Make a subdirectory in your project folder, e.g.: mkdir https

    2. Create a text file in that directory, e.g.:, with the following contents (C= is the ISO 3166-1 Alpha-2 code of your country)

      [ req ] distinguished_name=req_distinguished_name prompt=no

      [ req_distinguished_name ] C=US ST=State or County or Shire L=City O=Company Name

    3. Execute the following commands (the second command is to remove password from your secret-key file):

      openssl genrsa -des3 -out 2048 openssl rsa -in -out rm openssl req -new -config -key -out

    4. Use the CSR file to request a certificate from a recognized issuer. (You can get a free 90-day free certificate from here. I'm not affiliated in any way with that site, but it worked for me. UPDATE: these certificates display a warning on Firefox: "Error code: sec_error_unknown_issuer".)

    5. After verification through your domain's contact email address, you will obtain a CRT file from the issuer. Place it along with the KEY file you generated above in the https directory.

    Then configure your server as follows:

    var prod = process.env.NODE_ENV === 'production';
    var app = require('express').createServer();
    var ws = require('ws-rpc').extend(require('ws'));
    var wsflash = require('ws-flash-client');
    require('policyfile').createServer().listen(prod ? 843 : 10843, app);
    var httpsOptions = {
        key: fs.readFileSync('https/'),
        cert: fs.readFileSync('https/')
    var httpServer = http.createServer(app.handle.bind(app)).listen(port);
    var httpsServer = https.createServer(httpsOptions, app.handle.bind(app))
    var wss = new ws.Server({ server: new ws.ServerHub([ httpServer, httpsServer ]) });
    app.configure(function() {
        // continue as in the above example 
        // ... 


    In your HTML page (JADE syntax shown):

    !!! 5
    		meta(http-equiv='X-UA-Compatible', content='IE=Edge,chrome=1')
    		//if lt IE 8

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

    $(function() {
        $.wsFlashClientInit({}, function(err) {
                return log('no websocket support');
            var WebSocketRPC = InitWebSocketRPC(WebSocket);
            // create the client (will use WebSocket object on the background) 
            // param1: url 
            // param2 (optional): protocols, see 
            // param3 (optional): connection timeout in ms (default 4s), use -1 to disable auto-reconnect 
            // param4 (optional): reconnection wait timeout in ms (default 1s) 
            var ws = new WebSocketRPC('ws://' + + '/');
            // 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) {
                    // ... 
            // disconnect from the server 
            // param1 (optional): disable automatic reconnection 
            // connected event 
            ws.on('open', function() {
                // access the WebSocket if needed: 
                //ws.socket ... <- will be null when disconnected, and then a new one created 
            // disconnected event 
            ws.on('close', function() {
            // 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 WebSocketRPC = InitWebSocketRPC(WebSocket);
    var ws = new WebSocketRPC('ws://' + + '/');
    // ..and the same operations as above.. 

    Using the WebSocket client from Node.js

    var ws = require('ws-rpc').extend(require('ws'));
    var wsc = new ws.RPCWebSocket('ws://');
    wsc.on('message 1', function(arg1, arg2, cb) {
        log('message 1: ' + arg1 + '' + arg2);
        cb(null, 'message1 response from client', 'arg2');
    // etc. 


    Find the example app here, or installed in node_modules/ws-rpc/example.

    cd example
    npm install
    node testws

    Then load http://localhost:1144/ in your browsers, and/or open another console and

    cd example
    node testws-server-client

    Tested with

    ├─┬ express@2.5.8 
    │ ├─┬ connect@1.8.5 
    │ │ └── formidable@1.0.9 
    │ ├── mime@1.2.4 
    │ ├── mkdirp@0.3.0 
    │ └── qs@0.4.2 
    ├─┬ jade@0.20.3 
    │ ├── commander@0.5.2 
    │ └── mkdirp@0.3.0 
    ├── nib@0.3.2 
    ├── policyfile@0.0.5 
    ├─┬ stylus@0.24.0 
    │ ├── cssom@0.2.2 
    │ ├── debug@0.5.0 
    │ ├── growl@1.4.1 
    │ └── mkdirp@0.3.0 
    ├─┬ ws@0.4.7 
    │ ├── commander@0.5.0 
    │ └── options@0.0.2 
    ├── ws-flash-client@0.0.2
    └── ws-rpc@0.0.2

    Tested on

    • Google Chrome 17 Mac, 16, 17 Win
    • Firefox 7 Mac, 10 Win
    • Internet Explorer 6, 7, 8, 9 on Win XP and Win 7 (Flash)
    • Safari 5.1 Win, 5 Mac
    • Opera 9.8 Win (Flash)
    • Chrome Beta on Android 4.0, Galaxy Nexus
    • Mobile Safari on iOS 5.0.1, iPhone 3GS


    New BSD License.




    npm i ws-rpc

    Downloadsweekly downloads







    last publish


    • avatar