Examples

Client Examples

The Javascript Client API is intentionally very simple. The rubris library acts as a form of plugin to the EngineIO library as we can see below.

The examples below illustrate the basic mechanisms.

Starting and Configuring

$(function() {

  // create rubris instance
  var rubris = new Rubris({});

  // create the EngineIO instance 
  var socket = eio.Socket({ path : uri.path , port: uri.port, 
      protocol: "ws", host: uri.host });
  
  // set the binary type
  socket.binaryType = 'arraybuffer';
            
  
  socket.once('open', function(){
      // set the controlling socket on the rubris object
      rubris.setSocket(socket)

      // on open retrieve the available channels
      rubris.initChannels();
  });
      

  // hook Rubris into EngineIOto process message responses
  socket.on('message', function(data){
      rubris.parseMessage(data);
  });

}

The basic set up for a rubris instance is shown above. The 2 lines we are interested in are rubrsi.setSocket(socket) and the rubris.parseMessage(data). The former enables rubris to initialise itself and the latter hooks rubris’ message parsing into the message callback.

If you want to intercept and preprocess the messages this is the place to wrap the rubris message parsing in your own function.

Receiving Messages

Registering for Message response callbacks

  // process channels
  socket.on('channels', function(data){
    processChannels(data);
  });
  
  // proces RPC responses
  socket.on('rpc', function(data){
    processRPC(data);
  });
  
  // process subscribe responses
  socket.on('subscribeResponse', function(data){
    processSubscribeResponse(data);
  });

  // process push messages
  socket.on('push', function(data){
    processPush(data);
  });

  // process conversation response
  socket.on('conversation', function(data){
    processConversation(data);
  });

Parsing the messages

All The messages are of the same envelope format and parsing is relatively simple:

Text formats

function processRPC(message){   
    $('#messageId').text( (++rpcCount)+" "+ message.id+ ': time'+ (
        (new Date).getTime()-message.timestamp)+" "+ 
          rubris.getPayloadAsText(message.payload))
    
  }

Here we see a simple RPC callback that uses the message.id and the message.timestamp. The rubris.getPayloadAsText() function is a convenience function that uses the native textDecoder to process the payload into a string (if the browser has no nativeDecoder then a shim is used).

The basics of the text decode is shown below:

/*
   Return payload as text for callees do not need to have their own text decoder
*/

function getAsText(payload, textDecoder) {

      if (payload) {
          if (payload.type === prot.payload.dataview) {
              return decodeText(payload.data.buffer.slice(payload.start, payload.end),
                  textDecoder, payload.type)
          } else if (payload.type === prot.payload.uint8) {
              return decodeText(payload.data.subarray(payload.start, payload.end),
                  textDecoder, payload.type)
          } else if (payload.type === prot.payload.text) {
              return payload.data;
          }
      }
    return '';
}}

You are free to use your own decode method if you want. It is just a helper.

We can see that if we want to pass JSON or a text protocol like FIX we just need to decode the array back to a String format.

Binary data

For a binary type payload you can see that yu pretty much have direct access to the underlying array to process the bytes directly.

function processPush(message){
    $('#'+message.channel+"_"+message.topic+"_price").html( 
      (message.payload.data.getFloat64(message.payload.start, 
        rubris.protocol.littleEndian)).toFixed(5))
  }

Further information on handling Message types is on the Client Docs

Sending Messages

Sending messages is straightforward. The library provides constructor methods for each message type. e.g.

Subscribe Messages

var messageId;

$("#news-btn").click(function(event){
  var chan = ["EMEA News"];
  var channelId = rubris.channels["news"].id;
  messageId = wrap32BitUnsigned(messageId++) ; 
  socket.send(rubris.subscribeMessage(chan,[] , channelId, messageid));        
});

The above is a simple subscribe to the topicEMEA News on the news channel. The subscribeMessage function takes care of constructing the envelope and structure. The socket.send() function does the actual POST of the data. The empty array as the second argument is the unsubscribe array. You can pass up to a total of 2048 topics in total in both arrays.

RPC Messages

$("#rpc-btn").click(function(event){
  var val = $('#message').val();    
  messageId = wrap32BitUnsigned(messageId++)
  socket.send(rubris.rpcMessage(val, rubris.channels['myChannel'].id, messageid));
});

Similarly, the RPC send is also pretty simple. The difference is that there is no array. Instead the channelId is the definer of the namepsace on the server.

The other message types follow the same pattern.