Skip to content

Getting started

Jump to bottom
Oğuz Eroğlu edited this page Dec 31, 2019 · 2 revisions

Getting started

Let's implement a simple example to understand how this all works.

In this example, we want to implement a simple client that sends 2 numbers to a server, the server adds these two numbers and sends the result back to the client.

Step 1) Installing the library

We start by installing the library for client and the server.

For the client, we simply go to the Rhubarb releases page and download the latest Rhubarb.min.js and RhubarbWorker.min.js files.

For the server, we run this command: npm install rhubarb-js to install the dependency.

Step 2) Defining protocols

Rhubarb is designed to define the protocols once in a JSON file, this file would later be used both by the server and the client. This helps getting rid of code duplications and long if's - else if's in the codebase.

We create a new file called protocol-definition.json.

We define our first protocol called addTwoNumbers. This protocol has two parameters val1 and val2. This is the message that is sent from client to server:

"addTwoNumbers": {
  "val1": "numerical",
  "val2": "numerical"
}

Rhubarb expects "numerical" or "char_N" as parameter type (where N is the max length of the character). "numerical" means that the parameter will have numerical values (integer, float etc.). "char_13" means the parameter will have a string value between [1-13] characters. Since we want to add two numbers in this example, we'll use numerical values.

We define our second protocol called additionResult. This is the message sent from server to the client, containing the addition of two numbers as a parameter:

"additionResult": {
  "val": "numerical"
}

To sum up, this is what the protocol-definition.json looks like:

{
  "addTwoNumbers": {
    "val1": "numerical",
    "val2": "numerical"
  },
  "additionResult": {
    "val": "numerical"
  }
}

Step 3) Implementing the client

We create a new HTML file and inside the <head> tag we import the Rhubarb library that we've downloaded from the releases page:

<head>
    <script src="./Rhubarb.min.js"></script>
</head>

Note: In this example Rhubarb.min.js and the client HTML page are located within the same folder.

Now we can initialize the Rhubarb library:

Rhubarb.init({
  protocolDefinitionPath: "./protocol-definition.json",
  workerPath: "./RhubarbWorker.min.js",
  serverAddress: "ws://localhost:8087",
  onReady: function(){
      // to be filled later
  },
  onError: function(err){
    alert(err);
  }
});

These are the mandatory parameters for the init method for a client. We simple pass the path to the protocol-definition.json that we just defined, we also pass the worker script path that we've downloaded from the releases page. The serverAddress parameter is the websocket address of the server that we'll implement in the next step. We also pass onReady and onError methods. onReady is executed when everything went well and Rhubarb is initialized. onError is executed when there's a problem initializing the Rhubarb library. In that case we can always alert or console.log the err parameter to see what went wrong.

Now it's time to send two numbers to the server. Inside the onReady method is a good place to do that:

Rhubarb.send("addTwoNumbers", {
  val1: 13,
  val2: 23
});

When called from a client, Rhubarb.send expects two parameters: The protocol name and the protocol parameters object. The protocol name is the same name we defined in the protocol-definition.json, the parameter names are also the same. As we already defined these parameters a numerical, we can pass numbers to them. In this example we pass 13 and 23 (the expected sum would be 36).

Then we need to wait for an additionResult message from the server. We can add this before or after send function:

Rhubarb.onReceived("additionResult", function(getter){
  alert(getter("val"));
});

Here, we tell Rhubarb that when an additionResult message is received, it should execute the callback function we pass. The callback functions are executed with a getter function. This getter function helps return the defined parameters. Since inside the protocol-definition file we have chosen val as the parameter name of the additionResult protocol, we call the getter function with val. We alert this value to see if the server has added 13 and 23 correctly.

To sum up, this is what the test.html looks like:

<html>
  <head>
      <script src="./Rhubarb.min.js"></script>
  </head>

  <body>
    <script>
      Rhubarb.init({
        protocolDefinitionPath: "./protocol-definition.json",
        workerPath: "./RhubarbWorker.min.js",
        serverAddress: "ws://localhost:8087",
        onReady: function(){
          Rhubarb.send("addTwoNumbers", {
            val1: 13,
            val2: 23
          });
          Rhubarb.onReceived("additionResult", function(getter){
            alert(getter("val"));
          });
        },
        onError: function(err){
          alert(err);
        }
      });
    </script>
  </body>
</html>

Step 4) Implementing the server

We start by creating a new file called server.js, this'll be a simple NodeJS server that runs Rhubarb.

We import Rhubarb using require:

var Rhubarb = require("rhubarb-js");

We then need to initialize Rhubarb for the server:

Rhubarb.init({
  protocolDefinitionPath: './protocol-definition.json',
  isServer: true,
  serverListenPort: 8087
});

When called from a server, Rhubarb.init expects only 3 parameters. The path to protocol-definition file, isServer parameter set to true and a serverListenPort parameter. For this example we'll run the server through port 8087.

Note that initializing Rhubarb for a server is blocking operation, so we don't need to pass onReady callback function.

We then tell Rhubarb to notice us when it receives a addTwoNumbers message from a client:

Rhubarb.onReceived("addTwoNumbers", function(getter, clientID){
  var val1 = getter("val1");
  var val2 = getter("val2");
  Rhubarb.send("additionResult", {
    val: val1 + val2
  }, clientID);
});

The callback function we pass to onReceived for a server has also a clientID parameter. The clientID represents the unique ID of a client within all the connected clients. Note that the send method also expects a clientID parameter for a server, in order to specify to which client we're sending this message to.

To sum up this is what the server looks like:

var Rhubarb = require("rhubarb-js");

Rhubarb.init({
  protocolDefinitionPath: './protocol-definition.json',
  isServer: true,
  serverListenPort: 8087
});

Rhubarb.onReceived("addTwoNumbers", function(getter, clientID){
  var val1 = getter("val1");
  var val2 = getter("val2");
  Rhubarb.send("additionResult", {
    val: val1 + val2
  }, clientID);
});

You can now run the server (node server.js), host the test.html from any HTTP server. When you go to the test.html page, you'd see the value 36 alerted.

Clone this wiki locally