Mesh

Getting Started

First thing you have to do is edit the app.yaml in your root directory to include tailbone/mesh

includes:
  - tailbone/mesh

Next we will need to configure what type of mesh network we want to form, the most stable and most asked for is websockets. To enable this you will need to modify the appengine_config.py. If it is not already in you root folder, copy the template appengine_config_template.py from the tailbone subdirectory into the root.

Here we will enable the mesh settings:

tailboneMesh_ENABLE_WEBSOCKET = True
# tailboneMesh_ENABLE_TURN = False
# tailboneMesh_ROOM_EXPIRATION = 86400  # one day in seconds
# tailboneMesh_PORT = 8889
# tailboneMesh_ENABLE_generate_room_name = define_your_own_python_function

Now when we start the dev server using tailbone serve we will also need to start the websocket server, using node tailbone/tailbone/mesh/websocket.js. This may throw an error saying that ws is not installed to install it run npm install ws. This installs the websocket module for node.

We should be able to run our local server now, try running the mesh tests by pointing your browser to http://localhost:8080/test/mesh.

The associated javascript library works with the mesh backend, here is a short tutorial on how it works.

First include <script src="/tailbone.js"></script>. This will include any javascript that the tailbone library needs based on the modules you have imported.

Now the following code should work, note every the mesh, mesh.peers, and an individual peer (in peers or mesh.self) all have the same api of bind("eventname", functioncallback), unbind("eventname", optional_function), and trigger("eventname", arg1, arg2, argn).

Check out the QUnit test for some usage examples: https://github.com/dataarts/tailbone/blob/master/tailbone/test/mesh.html

tailbone.Mesh.options.useWebRTC = false; // makes it not try and upgrade to experimental WebRTC connection
var mesh1 = new tailbone.Mesh();
var mesh2;
mesh1.bind('connect', function() {
  mesh2 = new tailbone.Mesh(mesh1.id);
  console.log(mesh1.peers); // this should be a list of peers
  console.log(mesh1.self); // this should be my node
  mesh1.trigger("something_to_everybody", "arg1", "arge2");  // triggers an event on self + peers
  mesh1.peers.trigger("something_to_all_but_me", "arg1"); // trigger to just peers
  mesh1.self.trigger("somthing for me"); // trigger for just me
  mesh1.peers[0].trigger("something_for_peer1"); // just send to peer 1
});

mesh1.bind('enter', function(newguy) {
  console.log("the new node is", newguy, "and can now be found in", mesh1.peers);
});

mesh1.bind("disconnect", function(justleft) {
  console.log(justleft, "has been disconnected from", mesh1.peers);
});

Setup for deployment

Ok so there is a little extra step you have to do for deployment at the moment. First you have to set up your application from http://cloud.google.com/console, and you have to enable billing. This is what makes it possible to use the compute engine api from you app engine application. Also, for the time being you will need to go into the cloud console and under compute engine enable the following default firewall. "tcp:8888,88889" this enables websocket access and a server to report the stats of the machine for load balancing.

After that just run tailbone deploy master or whatever your version is and go to /api/mesh. The first time you run this it will provide an error because it hasn't set up a compute engine instance. Give it a few minutes and keep an eye on cloud.google.com/console and refresh later. It should now show up with a shiny websocket url and you are good to go.

How does it work?

So what is happening is that you make request /api/mesh/{roomname}. If you don't specify a room name it makes one for you. Then it looks to see if that room is already associated with the ip of a compute engine instance if it is it sends you there to join your room, otherwise it creates one. It uses the task queue api provided by app engine to regularly check the status and the usage statistics of all of the compute engine instances or to see if one goes down. It regularly calculates the load of the instances and if more or less instances are needed it shuts them down or adds more. The room creation is specific to mesh, if you just need a loadbalanced set of instances doing the same thing check out tailbone/customce where you can define your own startup script in appengine_config.py and run some different arbitrary code like a video encoder with ffmpeg for example.

Enjoy!