Load Balancing Tutorial

In FastX 3, load balancing is accomplished by writing a custom javascript function that will return the proper server id of the server that you wish to execute the action on.  In most cases, the amount of custom code will be minimal so while javascript knowledge is preferred, a person with some basic scripting knowledge should be able to modify some of these examples to fit the need.

The load balancing function

Here is the basic structure of the load balancing function to return the local serverId.

function  (input) {
  return input.local.serverId;
}

All functions will begin with the line which declares the function.

function  (input) {

The load balancing function takes one parameter input which is a JSON object of all the data needed to make a decision

The next line returns the serverId of the system that is executing this function.  This function MUST return a serverId in order for load balancing to succeed.

return input.local.serverId;

Finally, the last line is the closing bracket of the function

}

The input object

The input object has all the information needed to choose which server to execute the function on.  This is what the inout object looks like

{
  "action": "STRING", //the action that will be executed,  "user/login" || "session/start"
  "user": { //user data object
    "login": "STRING", //the login name of the user
    "serverId": "STRING", //the serverId of the user (if action = "session/start")
  },
  "local": { //local server object
    "serverId": "STRING", //the serverId of the system executing the function
  },
  "servers": [ server_object1, server_object2, ..., server_objectN], 
  //array of server objects
}

The server object

Each server object has the following parameters

{
  serverId: "STRING", //server's id
  urls: ["https://192.168.1.100:3300"], //array of the server's urls
  hostname: "STRING", //server's hostname
  sessions: INT, //number of sessions currently running on this server
  uptime: INT, //uptime of the server
  loadavg: [ INT, INT, INT ], //load average of the server (1, 5, 15 minutes)
  totalmem: INT,  //total memory in bytes
  freemem: INT, //free memory in bytes
  sudo: BOOLEAN, //is FastX sudo user enabled?  This allows starting sessions on START
  create: [ "login", "start"], //actions that are enabled on this server
  static: { // user defined static data },
  metrics: {// user defined metrics },
}

A more complex example

A typical use case of the load balancing function is to filter out servers not matching the criteria, then sorting the results, and getting the serverId with the lowest/highest value.  A typical function would look like this

function (input) {
   let myArray = input.servers
   .filter (c => c.static.group === "G1") //get all servers in the G1 group
   .sort ((a, b) => a.freemem > b.freemem); //sort based on the amount of memory available
  return myArray [0].serverId; //return the serverId of the first server in the array
}

Javascript has many built in array manipulation functions available to it. Array.prototype.filter and Array.prototype.sort can be chained together to easily get the serverId you need

Per user criteria

Since we have some user data available, why don’t we use it to return different servers based on who is trying to start the session

function (input) {
   if (["admin1","admin2", "admin3"].indexOf (input.user.login) >= 0) {
       //if your username is admin[1,2,3], connect locally
       return input.local.serverId;
   }
   if (input.user.login === "blacklisted_guy") {
      return; // if you do not return a serverId, you cannot log in
   }
   //else, connect to the one with the most memory
   let myArray = input.servers
   .filter (c => c.static.group === "G1") //get all servers in the G1 group
   .sort ((a, b) => a.freemem > b.freemem); //sort based on the amount of memory available
  return myArray [0].serverId; //return the serverId of the first server in the array
}

Conclusion

Javascript is a simple, easy to use language with lots of built in functions available.  The input object should give you all you need to create a complex function that can return the proper serverId so that you can create user defined load balancing scenarios based on your own criteria.

If you have any questions or need further assistance, please contact StarNet Support