.

Current State

The nightly build of Firebase now supports;

• Comet-style HTTP support.

• WebSocket HTTP support.

The support for HTTP traffic is disabled by default but can currently be enabled and directed to a port by setting the following in cluster.props

node.client.enable-http-server=true

And the following in server.props

web-client-bind-address=0.0.0.0\:8080

The Firebase protocol will be converted to JSON when using the HTTP support to better support JavaScript development. WebSockets are fairly straight forward, the client can send JSON messages and the server will push JSON messages to the client. However, regular HTTP is a bit more tricky: GET is used to poll and POST to send messages, but you need to have a HTTP-session (JSESSIONID). This means that if the first request from the server is a GET then the server will return immediately with a “Set-Cookie” header instead of a poll.

WebSockets and HTTP are served on the same port but under the following paths:

/http
/socket

NOTE: The implementation is still in flux and the information given above may very well change as we get closer to a proper release.

Usage Example

On to the fun stuff! Here I will show you an example of how it works in practice and how would you implement a simple login using nothing but JavaScript HTML5 and WebSocket.

Opening a WebSocket to Firebase is very simple, all you have to do is point it towards the right URL and port.

var socket = new WebSocket("ws://localhost:8080/socket");

Note the ws:// protocol which specifies WebSocket for the communication.

To send a login request we just call socket.send(…) with the JSON equivalent of the LoginRequestPacket as specified in the Firebase protocol. Note that in the current JSON implementation of the Firebase protocol you need to add classId to specify the type and then place the payload in a data-field.

socket.send('{"classId":10,"user":"Foo","password":"123","operatorId":"1"}');

Password needs to be, as always in the default mock login handler, integers.

The socket object has different callbacks, to listen for incoming messages we implement onMessage and check for login responses. To get the message payload, i.e. Firebase messages, we must access the data field.

socket.onmessage = function(msg){
    var loginResponse = jQuery.parseJSON(msg)[0];
    if (loginResponse.classId == 11) {
       alert("Login "+loginResponse.data.status);
    }
};

Those are the basics of the WebSockets communication. I have deployed a more complete source code for trying logins here - http://www.robotsociety.com/jslogin/login.html . You will need a local Firebase running on the default port of 8080 to try it out. To see the full source code you can browse the source files for the example directly here: http://www.robotsociety.com/jslogin/

The Problem
Internally Firebase replicates events and state to minimize the risk of data loss, however, there is one instance where this is particular hard, and that is between the clients and the server. And here’s why:

Because Firebase is not one-to-one when mapping incoming events to players, but rather one-to-many we have chosen to not extend the transaction boundaries to the clients themselves as this would be extremely costly.

This means that if a client looses its TCP connection unexpectedly, there may be messages lost. This might come about from several scenarios, for example:

• A client role node in the Firebase cluster crashes. This will normally disconnect all players from the node, and upon reconnection they will be load balanced to another server.
• The client application crashes. When opened again, the client will reconnect to the Firebase cluster.
• A glitch in the routing between the client and the server disconnects the client.

In any of the cases we’ll look at today, the client will be able to realize it has lost the connection and reconnect.

Preconditions
The only thing that is really necessary to start handling reconnects gracefully is for the client to recognise it is reconnecting. If it is handled in-process this should be trivial, and when a client starts it may look to a cookie or a saved state to see if it was closed correctly, ie. a “dirty state” flag.

Also, you need to mark crucial events with ID:s and optionally a flag which can tell you if an event is “resent” (more on this below), and also make sure such events have corresponding answers from the server. Remember that Firebase is an asynchronous system, so you’ll send a critical event, then some time later, you will get an answer, hence the importance of an event ID.

And what events are “critical”? It’s up to you really, but probably those that can significantly alter the outcome of the game. The events that you really don’t want to get lost. But the key word is “significantly”, you probably don’t want to enforce a call/response-pattern on all events in all games. In gambling most events such as bet, call, fold etc are significant, whereas in a social shooter perhaps very few are.

Idempotency to the Rescue
In event processing idempotency is usually meant as the ability to resend events without changing the initial outcome more than once. In an idempotent system, if event X is sent ten times, only the first received will be executed upon, the rest will be ignored. For Firebase this means that the client should be able to send a critical event several times and the server will simply respond as if the event is executed if it is already acted upon.

Let’s break it down:

• The client must keep a back log of sent “critical” events which it has yet to receive answers to. So for each critical event it will save an ID in a map together with the entire event, and for each response to a critical event the ID will be removed from the map. If the client is not awaiting any response the map will be empty.
• When a reconnection occur, the client should check if the above map is empty, if not any event therein may theoretically have been dropped. Each event in the map should be resent, optionally with a flag detailing that this is indeed a resent event.
• The server should keep a map of ID to response objects for a reasonable amount of time, or be able to calculate a response without changing the internal state. So if it receives an event which it has already executed upon, it should recalculate the response, or fetch the response from a map.

Example: Load Test
The load test we’re using internally is very simple: Each client sends a sequence of integers and the server simply echoes the integers right back. So the client may send “5″ and will wait for the server to send “5″ back. It then waits for X milliseconds before increasing the sequence to “6″ and repeat. This simple game allows us not only to determine the exact load at any given time (ie. events per second) but also verify that Firebase honours its FIFO behaviour.

So the client will keep a queue of integers it expects the server to respond to, and it also has an integer sequence to create new events from. The queue of integers acts as the client side map: if it is empty there’s no response outstanding. On reconnect the client checks the queue and resends any integers found in it. The server simply echoes the integers back to the client, but also checks that the sequence is intact (again checking FIFO ordering) except for the case of reconnects when the sequence is allowed to jump back a few steps.

Finally
Hopefully this should have straightened out a few questions. Keeping strict idempotency in any system is tricky, but it will give you a very robust platform, and paired off with Firebase will be damn near bullet-proof!

The new version is available on the Firebase download page.

• We loaded 40 000 poker players on a 3 node cluster of cheap so called “pizza boxes”.
• Going from 1 to 2 nodes increased throughput with 50%, and from 2 to 3 with an additional 60%.

Read the above one more time: 40 000 players on a cluster that today would cost you less than €1500 is astounding! Granted, there no external integrations involved here, but still I think you’ll agree that it is pretty neat.

So, you want to write a multi-player game? And perhaps you’re considering Cubeia Firebase as your platform? Then we’ll take a good look at what you actually need to know, and need to do to get going. We’re going to keep it short, and then expand on the different items in later posts.

Client Language
You need a game client, and should decide what language or platform you’ll be using. If you want to deploy it to the web, perhaps flex would be suitable. If you want a heavier client, you should probably go for C++ or Java. For the rest of these posts we’ll assume you went the Flex / Flash track, but Firebase supports Flex and Flash, Java, C++ and C# so it is really your choice!

The Firebase Protocol
The client API of your choice comes with ready made command objects for a number of actions that are taken care of by Firebase, and that you don’t have to do yourself! They are taken care of by the platform, and include:

• login / logout
• join / leave game
• watch / unwatch game
• query / subscribe lobby
• send action to game / service
• etc…

In most cases, the Firebase commands are request / response. You will, for example, send a “login” command to the Firebase servers, and then wait for an answer which will be either a “yes” or a “no” (we’ll discuss Firebase and authentication / login later). The “send action to game” is how you communicate with your game, which is running inside Firebase, and for more on that, see below.

Your Protocol
The Firebase protocol takes care of many “generic” actions for you, but you will need to have a protocol specific to your game.These are the actions your players can make, such as:

• fire weapon
• move
• place bet
• do the macarena
• etc…

the actions you actually need will be apparent when you start writing your game, but at this point you should figure out what form the commands will take. Firebase will treat your own commands as binary data, that is to say, you can use any format you want. Many will use XML or JSON which are widely supported in all languages. For larger projects though, we’d recommend you to look at protocol generation schemes such as Google’s Protobuf as it scales better and nicely separates your protocol from your code which is something that becomes important as the game grows in size. You can even use the protocol generation used by Firebase, called Styx; This generator takes a specification in XML and produces serialization factories and command objects in a variety of languages.

Server Language
The server code is the heart of your game. This is where most decisions will take place, where you keep track of the players, send notifications and much more. Normally all Firebase games are written in Java, but you can also write your server code in a number of script languages such as JavaScript or Ruby which is brilliant if you quickly want to prototype a game. Be aware though that the script languages are a bit slower, so if high performance is a must for you, you’ll have to go the Java route.

Building Server Code
How you build your client code is very much up to you and what IDE you’re using. But for the server side code we strongly recommend use Apache Maven for building, simply because there’s some neat plugins and tools already built for you to simplify your life. It is still your choice though and you can use anything from Ant to batch scripts.

Database
You probably want to store results and data somewhere. Firebase will not impose any choice on you and you’re free to use whatever data storage you like best. Firebase contains build in support for most relations databases, such as MySQL or Oracle, via JDBC and JPA, but you can equally well use column databases or simple text files, the choice is entirely up to you!

Ready. Set. Go!
So download what you need. If you went with the Flex/Java route you will need a Java SDK installed together with Apache Maven. Strictly speaking you don’t need an IDE, you could use a simple text editor, but normally you will want to install IDE:s such as Eclipse before going on. And with that done you should be ready to dive in head first in the traditional “hello world” tutorial on our wiki. Or if your feeling brave, the “quickstart extreme – not for the faint hearted“!

Next installment will look closer at the server game itself, its components and functions. Stay tuned!

Firebase is a “game agnostic multi-player server”, but that might not be entirely easy to parse. So let’s go backwards: If you want to write a multi-player game, what are the big components you need to worry about before it is done? You need a game client obviously, then a game server, a protocol between the two, and probably a database to store data in. Firebase is here to help you with 2 of those 4 components.

And how, exactly?

• Your game client, which can be written in almost any language you want, utilizes a Firebase Client API to send and receive messages from the game server. This way you don’t have to worry about the protocol for each game or player, or addressing in general: Firebase will handle that for you.
• You don’t have to write a game server, you can use Firebase itself as a server, and all you have to do is to write the game. That is to say, you write the code that decides what to do when, for example, player “adam” sends a “bet” action. In other words, the logic and not the server.

Let’s look at the last bit again. A game server is a complicated beast, it should handle multi-threading, networking, be possible to extend easily, be fast as hell, and hopefully also be fairly simple to work with. And you can certainly write it all yourself, but why bother when Firebase will do it for you? If you write a game in Firebase, you can concentrate on what really matters: the game, not the crud surrounding it. Needless to say, you’ll be finished much faster that way!

You can write your game client in any language supported by the Firebase Client API. At the moment this means C/C++, C#, Flash/Flex and Java, but Objective-C is on the way. For the server side game your a bit more restricted and your main choice should be Java, but we’re also supporting a number of script languages such as JavaScript, Ruby or Groovy.

With me still? Fine, next we’ll look at what you actually need to do, a kind of head-first crash course if you like. Stay tuned!

The source code is available under an AGPL license and there’s even a small demo to download. Even though it is early days still and the poker is not yet an “official” Cubeia product, you can hit the forums at our community site to ask questions. See you there!