Saturday, October 6, 2012

Android + Erlang for Great Good: Cowboy Setup and Account Route

Please read Android + Erlang for Great Good: An Introduction if you haven't already done so.

Now that I've selected my webserver and defined my client its time to get started.  Since I don't know much about Erlang, Java or Android development I decided to start with a problem I'm VERY familiar with, all that standard account & authentication goop that you somehow have to rewrite every time you change languages, platforms etc.

Since my client is on an Android, we already have an authenticated user, we just need to somehow confirm their identity.  Fortunately the big players in the web have finally pretty much centered on the Oauth2 protocol to handle this problem.  What I need to do is pretty simple, get a token of some sort from the validating authority (in this case the players phone) and send that token + the players email address to my server.  My server can then validate the token via a call to a google server and return one of the following:
  • Invalid token: return 401 and note the oauth2 authority.
  • Token expired: return 401 and note the oauth2 authority.
  • Valid token, user does not exist: return 404.
  • Valid token, valid user: return 200 & json payload containing account details.

On the server side it looks like the account handler will need to become a standard REST + json resource, supporting GET, PUT and DELETE operations.  This post will walk through initial server setup and setup the route to /account.

Create a directory for this application and then copy the rebar script from basho into the new directory.  Next we'll want to create an application skeleton using ./rebar create-app appid=my_game.  This creates a very minimal app skeleton for you.

Now lets get cowboy integrated into our application.  For this we'll need to create a rebar.config file and put the following into it:

{deps, [
  {jiffy, ".*", {git, "git://github.com/davisp/jiffy.git", {branch, "master"}}},
  {cowboy, "0.6.1", {git, "git://github.com/extend/cowboy.git", {tag, "0.6.1"}}}
]}.
The jiffy dependency will come in handy later on when we need to encode/decode json.

./rebar get-deps will download these dependencies and ./rebar compile will compile them and your application code. We'll want to do this now to be sure we didn't make any mistakes thus far.

Now its time to define our application start point. When you start erlang with the -s file_name syntax erlang looks for a start/0 function within that file and executes it. We'll use the my_game_app.erl for this as well as the standard supervisor start/2, stop/1 functionality. Within start we'll need to start cowboy and my_game. The complete function is:
start() ->
  reloader:start(), %Makes debugging simple...
  ok = application:start(cowboy),
  ok = ssl:start(),
  ok = inets:start(),  
  ok = application:start(my_game).
inets and ssl are required when actually validating the auth token with google so we'll need to start both of them when our application is started as well.

Reloader is a very useful code snippet from the guys at Basho that allows for hot code upgrades within your running server.  This is particularly useful for debugging.  Simply add the erl file located here to your /src directory and going forward almost all code changes will be reloaded automatically whenever you ./rebar compile the app.  As far as I can tell, only changes to start/0 are not automatically reloaded as that particular method does not utilize the standard erlang supervisor pattern.

By default cowboy does nothing, so next we have to tell it about our end point.  This will simply be /account/email@address.com.  To set this up we need to edit the start/2 method. Putting it inside the start/2 method will allow us to upgrade the routes within the running server later on if needed. One more item to note is that cowboy uses binary strings so make sure you place << >> around your strings or the patterns will not match properly. The complete start/2 method looks like this:
start(_StartType, _StartArgs) ->
 Dispatch = [
  {'_', [
   {[<<"account">>, email], account_handler, []}
  ]}
 ],
 {ok, _} = cowboy:start_listener(http, 100,
   cowboy_tcp_transport, [{port, 8080}],
   cowboy_http_protocol, [{dispatch, Dispatch}]
  ),
 my_game_sup:start_link().

Finally lets setup our start.sh script to automate starting the server.  You can't actually run the server yet as the account_handler referenced by the dispatch does not yet exist, but you can start it up and get your first taste of error messages from the cowboy server.

Our start.sh is extremely simple and contains only the following line:
erl -pa ebin deps/*/ebin -boot start_sasl -s my_game_app

 Stay tuned for the actual account_handler implementation.

Android + Erlang for Great Good: An Introduction

I've recently begun working on a multiplayer Android game that will communicate with an erlang server.   The erlang server will contain at least 2 endpoints, a REST account manger and a Websocket which will push erlang server events from the server engine and receive all player commands.

My experience in both erlang and android development is extremely limited, essentially I've read (some of) the manual and written a few lines of demo/tutorial code in each.

I began by looking for a proper web server for erlang.  I reviewed the following:

  1. Webmachine.  Great implementation of a RESTful server, layered on mochiweb.  Their RESTful diagram is a great resource for people wanting to understand REST better.  No built in support for Websockets as of yet.
  2. ChicagoBoss.  Very new, looks extremely interesting.  An MVC framework for erlang, it utilizes Django style templates which are actually compiled into erlang bytecode for speed.  Recommend reviewing it if you want to write a standard MVC application or a RESTful webserver for a client side MVC framework.  Supports Websockets via Cowboy. 
  3. Cowboy.  A brand new http server in erlang.  Cowboy is technically more of a tcp/ip connector pool/manager with out of the box support for http, https, REST, and Websockets. 
After doing a POC of a websocket implementation in ChicagoBoss I realized that most of what I needed was in Cowboy and ChicagoBoss, while cool, didn't really add all that much to the equation. It's a great framework for an MVC application, but doesn't really fit my use cases.

One item I lost when I removed ChicagoBoss was the transparent encoding/decoding of json that make RESTful interfaces in ChicagoBoss so simple.  After a bit more searching I found jiffy which appeared to suit my needs.  It transforms json objects into erlang proplists.  Additionally its written in C and utilizes binary strings for improved performance.

On the Android side I looked into using phonegap or appcellerator or just an HTML 5 webapp, and I decided that I wanted to actually learn to code on the Android platform.  So the client will be Java targeting Froyo (API 8).

Before continuing you'll want to get Erlang installed and working on your system.  For Ubuntu I recommend this gist.  You'll also want to familiarize yourself with rebar, the build system for erlang.

Erlang server source code at brocksamson/my_game

Newer posts: