Overview

In the last part, we implemented the first version of our chat server. Now that the framework is down, we can start adding some more features. You can find the source for this tutorial here

In this part, we will add the following features:

• Rate Limiting for Messages
• Admin Login
• Kick/Ban users
• Limiting connections per host

Rate Limiting

This feature will *help* in stopping people from spamming the chat room. It isn’t very complex, but it will give you the idea of what rate limiting can do. The algorithm for rate limiting is very simple, if a user sends too many messages in a certain interval, stop them from sending. At the top of chat_room.erl I’ve added the following:

-define(RATE_MSG_INTERVAL, 3).
-define(RATE_MSG_COUNT, 10).

I’ve just randomly chosen these values for now, and it means if you try to send more than 10 messages in 3 seconds, you will be rate limited. The check for rate limiting will go in the chat_message function:

handle_cast({chat_message, {Sess, Msg}}, State) when is_list(Msg) and(length(Msg) > 0) ->
    case get_session(Sess, State) of
        {error, not_found} -> {noreply, State};
        {ok, #client_state{nick=Nick,id=ID} = C} ->
            CleanMsg = chat_util:unicode_clean(lists:sublist(Msg, 256)),
            {NewC, NewState} = update_client(C, State),
            case handle_command(NewC, CleanMsg, NewState) of
                {ok, S1} -> {noreply, S1};
                _ ->
                    case should_rate_limit(NewC, NewState) of
                        {yes, {_, S2}} ->
                            send_system_msg(NewC, "You are sending messages to fast. Please wait a few seconds and try again."),
                            {noreply, S2};
                        {no, {RateClient, S2}} ->
                            chat_postoffice:broadcast_mail({msg, {chat_msg, {Nick, CleanMsg}}}, [ID]),
                            chat_postoffice:send_mail(ID, {msg, {sent_chat_msg, {Nick, CleanMsg}}}),
                            {_, S3} = update_client(RateClient#client_state{last_msg=now()}, S2),
                            {noreply, S3}
                    end
            end
    end;

We’ve just added a check that calls should_rate_limit and based on what it returns, the user is rate limited(and we notify them), or they are not, and the message can be sent. Also, you may notice the handle_command function, we will discuss this in a little.

To implement rate limiting, I’ve updated our client’s state with last_msg and msg_count:

-record(client_state, {
id, nick, host,last_action,admin=false,last_msg=never,msg_count=0
}).

Finally, the implementation of should_rate_limit. This function implements our simple algorithm.

should_rate_limit(#client_state{last_msg=never} = C, State) -> 
    NewState = update_client(C#client_state{last_msg=now(),msg_count=1}, State),
    {no, NewState};
should_rate_limit(#client_state{last_msg=LastMsg,msg_count=Count} = C, State) ->
	RateSecs = calendar:datetime_to_gregorian_seconds(calendar:now_to_datetime(now())) - calendar:datetime_to_gregorian_seconds(calendar:now_to_datetime(LastMsg)),
	case {RateSecs =< ?RATE_MSG_INTERVAL, (Count + 1) > ?RATE_MSG_COUNT} of
	    {true, true} -> {yes, update_client(C#client_state{msg_count=Count}, State)};
	    {false, _} -> {no, update_client(C#client_state{msg_count=0}, State)};
	    _ -> {no, update_client(C#client_state{msg_count=Count+1}, State)}
	end;
should_rate_limit(_, State) -> {no, State}.

Admin Control

This feature allows the administrator exercise some control over the chat server, with features such as kicking/banning users. The admin features are only protected by a password. We define the admin password as so:

-define(ADMIN_PASSWORD, "demopass").

It is probably a good idea to change this password if you are running it on a public server.

I have updated the client state to contain another field, called admin. When a user joins, this value defaults to false. To become an admin, (and to change a client’s state to admin=true), the user must authenticate. To handle authentication, and various other commands, we will use an IRC style /command param1 param2 param3..paramN. If you want to add spaces for a parameter, surround it with quotes.

You probably noticed in the previous section that we added a handle_command check in the chat message function. This will allow us to parse and handle any possible commands. It looks like the following:

handle_command(Client, Msg, State) ->
    case re:run(Msg, "^/([A-Za-z0-9]+) ?(.+){0,1}", [{capture, all_but_first, list}]) of
        {match, [Cmd]} -> process_command(Cmd, [], Client, State);
        {match, [Cmd, ParamStr]} -> process_command(Cmd, get_params(ParamStr), Client, State);
        _ -> {error, no_command}
    end.

It takes a chat message, and tries to parse out a command. If it is valid, we then process the command further. process_command takes the command (value after the slash), and a list of parameters (along with the client state, and server state). Using Erlang’s pattern matching, we can easily handle any command we want by just matching the string. For now, process_command handles two commands, /help, and /auth.

process_command("help", _, Client, State) ->
    send_system_msg(Client, "Commands: (/auth password)"),
    {ok, State};
 
% Generic admin handler.
process_command("admin", Args, #client_state{admin=true} = Client, State) -> process_admin_command(Args, Client, State);
 
% Authenticate an administrator    
process_command("auth", [?ADMIN_PASSWORD], Client, State) -> 
    send_system_msg(Client, "You are now authenticated as an administrator. Type /admin help for commands."),
    case Client#client_state.admin of
        false -> chat_postoffice:broadcast_mail({msg, {admin_logged_in, Client#client_state.nick}}, []);
        _ -> ok
    end,
    {_, NewState} = update_client(Client#client_state{admin=true}, State),
    {ok, NewState}; 
process_command("auth", _, Client, State) -> send_system_msg(Client, "Invalid adminstrator password."), {ok, State};  
 
% Unknown command. 
process_command(_, _, Client, State) -> 
    send_system_msg(Client, "Invalid command or format."),
    {ok, State}.

/help just prints out help. All users can access this command. The auth command is what will give us administrator access. Using pattern matching, we can check to see if the correct password was entered. If it was, we update the client state and notify all the other users that this user has became an admin.

Once a user is authenticated, the Generic Admin Handler function will match, and the process_admin_command function will be called.

Admin Commands

Now that the user is logged in, we want to add some admin functionality. In this tutorial, we add the following commands:

• /admin logout
• /admin help
• /admin kick user reason
• /admin ban user reason seconds
• /admin unban host
• /admin info user
• /admin bans

Kicking a user

To kick a user, the admin will specify a user, and a reason. The code is:

% Kick a user
process_admin_command(["kick", User, Reason], #client_state{id=MySess} = Client, State) ->
    case get_user_by_nick(User, State) of
        {error, not_found} -> send_system_msg(Client, "Unable to kick: user not found.");
        {ok, #client_state{id=Sess} = C} when Sess /= MySess -> 
            send_system_msg(C, "You have been kicked from the chat room. Reason: " ++ Reason),
            chat_room:leave(Sess, "kicked: " ++ Reason);
        _ -> send_system_msg(Client, "Sorry, you can't kick yourself!")
    end,
    {ok, State};

First, we lookup the user. If the user exists, we *make* them leave the chat room, and specify the reason. That’s it.

Banning a user

This is a little more complicated, as we want to persist the ban between server restarts. To do this, we use a DETS table, which is basically ETS(Erlang’s in memory database), persisted to disk. Erlang stores the database in a file. We use the file name “bans.dets”. The table is created/opened in our chat_room init function:

init(_Args) -> 
	process_flag(trap_exit, true),
	{ok, BansTable} = dets:open_file("bans.dets", []),
	_ConnTable = ets:new(conns, [named_table]),
	timer:apply_after(?CHECK_IDLE_TIME, ?MODULE, find_idle_clients, []),
	{ok, #state{bans_table=BansTable}}.

Each item in the bans_table will be defined by the following record:

-record(user_ban, {
host,last_nick,reason,until
}).

Okay, now for the fun part. First, let’s see the function to ban a user:

% Ban a user
process_admin_command(["ban", User, Reason, Seconds], #client_state{id=MySess} = Client, State) ->
    case {get_user_by_nick(User, State), string:to_integer(Seconds)} of
        {_, {error, _}} -> send_system_msg(Client, "Unable to ban: invalid time specified.");
        {{error, not_found}, _} -> send_system_msg(Client, "Unable to ban: user not found.");
        {{ok, #client_state{id=Sess,host=Host} = C}, {Secs, _}} when Sess /= MySess -> 
            {Mega, S, Micro} = now(),
            BanTime = {Mega, S + Secs, Micro},
            BanTimeStr = httpd_util:rfc1123_date(calendar:now_to_local_time(BanTime)),
            send_system_msg(C, "You have been banned from the chat room until " ++ BanTimeStr ++ ". Reason: " ++ Reason),
            chat_room:leave(Sess, "banned: " ++ Reason),
            dets:insert(State#state.bans_table, #user_ban{host=Host,last_nick=User,reason=Reason,until=BanTime});
        _ -> send_system_msg(Client, "Sorry, you can't ban yourself!")
    end,
    {ok, State};

This function looks up the user, and if the user exists, we let them know that they have been banned(and disconnect them) and store an item in the DETS table describing the ban.

Now that the user has been disconnected, we need to make sure they can’t login until the ban is up. This check is implemented in our join function.

handle_call({join, {Nick, Host}}, _From, #state{clients=Clients} = State) when is_list(Nick) ->
    case {is_banned(Host,State), can_connect(Host), validate_nick(Nick, State)} of
        {{yes, Until}, _, _} -> {reply, {error, {banned, Until}}, State};
		{_, no, _} -> {reply, {error, too_many_conns}, State};
		{_, _, {error, Reason}} -> {reply, {error, Reason}, State};
        {_, {yes, NumConns}, {ok, ValidNick}} ->
            Session = get_unique_session(State),
            case chat_postoffice:create_mailbox(Session) of
                ok -> 
					update_host_conns(Host, NumConns + 1),
                    chat_postoffice:broadcast_mail({msg, {user_joined_room, ValidNick}}, [Session]),
                    Client = #client_state{id=Session,nick=ValidNick,host=Host,last_action=now()},
                    {reply, {ok, Session}, State#state{clients=[Client | Clients]}};
                {error, _} -> {reply, {error, not_available}, State}
            end
    end;

We have updated this function to call the function, is_banned, which determines if a user is indeed banned. If they are, we return an error, and the message is displayed to the user.

The ban function simply looks up a host/ip address in the bans table, and determines if it is still active.

is_banned(Host, #state{bans_table=Table}) ->
    Now = now(),
    case qlc:e(qlc:q([Ban || Ban <- dets:table(Table), Ban#user_ban.host == Host])) of
        [] -> no;
        [#user_ban{until=Until} | _] when Until >= Now -> {yes, Until};
        _ -> no
    end.

Connection Limiting

Finally, we’ve added a simple check in the join function, called can_connect, which checks to see if a user has the maximum connections allowed open. This is defined as:

% Max connections per host
-define(MAX_CONNECTIONS, 3).

The number of connections for a host is stored in an ETS table. We don’t need to persist this because if the server crashes, all connections will be gone anyway.

When a user joins, we update the connections table.

% Updates a host in connections ETS table
update_host_conns(Host, Conns) -> ets:insert(conns, {Host, Conns}).

When a user leaves, we update the connections table.

host_disconnected(Host) ->
	case ets:lookup(conns, Host) of
		[] -> ok;
		[{_, Num}] when is_integer(Num) -> ets:insert(conns, {Host, Num - 1});
		_ -> ets:insert(conns, {Host, 0})
	end.

Conclusion

Now we have a more functional server, but it still needs lots of work(that’s for you to decide). The source is available here. Try it out locally, by doing:

wget http://tech9computers.com/erl_chat-0.2.tar.gz
tar -xvzf erl_chat-0.2.tar.gz
cd erl_chat-0.2
make erl_chat

Then visit http://localhost:8000 to try it out

If anyone has any comments/suggestions/requests please let me know, I’d be happy to get some feedback on this. And also, you can try a demo here, although don’t think that demopass will get you admin control .

Getting into the code

In the previous part, I introduced the chat system and how it should work. Now we are going to write the chat_postoffice, chat_mailbox, chat_room, and chat_web modules. Before you read download the source for this tutorial here. and dedicate about 20 minutes to read through this tutorial, because it’s kind of long (sorry).

Setting up the project

When you look at the source, take a look at the structure of the files and folders. There is a makefile to help you build and run the project. To run the server, just do the following:

$ cd erl_chat
$ make erl_chat

This will compile all the code, and start the OTP application. The web server runs on port 8000.

The Mailbox Process

Before we set up the post office, let’s define how a mailbox will work. First, it will run in its own process and keep a list of messages. Essentially it is just a loop, that accepts the following messages:

• {mail, {msg, Data}}
• {mail, {add_listener, {MsgID, Pid}}}
• {mail, {remove_listener, Pid}}
• {mail, {get_msg_id, Pid}}
• quit

To create a mailbox, the post office will spawn a process and then the chat_mailbox:start function is called. The start function sets the initial state and then puts the process into hibernation.

start

start(ID) ->
    proc_lib:hibernate(?MODULE, loop, [#state{id=ID}]).

The following are the record definitions for the mailbox:

-record(message, {
id,data
}).
 
-record(state, {
id,cur_id=0,listeners=[],messages=[]
}).

NOTE: What is proc_lib:hibernate

This function helps keep the memory footprint much lower for a process. It is very useful when a process only does action when it receives a message. It discards the call stack and garbage collects for the process.

Now let’s write the loop function for our mailbox. It just receives a message for our process and does something with it. Here is the entire loop function.

loop

loop(#state{id=ID,cur_id=CurID,messages=Msgs,listeners=Listeners} = State) ->
    receive
        {mail, {add_listener, {_MsgID, _Pid} = Listener}} ->
            NewState = notify_listeners(State#state{listeners=[Listener | Listeners]}),
            proc_lib:hibernate(?MODULE, loop, [NewState]);
        {mail, {remove_listener, Pid}} ->
            NewListeners = lists:filter(fun({_Id, P}) -> P /= Pid end, Listeners),
            proc_lib:hibernate(?MODULE, loop, [State#state{listeners=NewListeners}]);
        {mail, {get_msg_id, Pid}} ->
            Pid ! {cur_msg_id, CurID},
            proc_lib:hibernate(?MODULE, loop, [State]);
        {mail, {msg, Data}} ->
            Msg = #message{id=CurID,data=Data},
            NewState = notify_listeners(State#state{messages=[Msg | Msgs],cur_id=CurID+1}),
            proc_lib:hibernate(?MODULE, loop, [NewState]);
        quit -> ok;
        _ -> proc_lib:hibernate(?MODULE, loop, [State])
    end.

Okay, let’s break down everything in that loop.

add_listener

When a new listener is added, the first thing we do is call notify_listeners, which will try to update the newly added listener(and any others) with any messages that have a higher/or equal message ID. Well go over notify listeners in a little.

remove_listener

This just goes through the list of listeners, if one matches the given Pid, remove it.

get_msg_id

This just returns the highest message ID (so the client knows what the latest message ID is).

msg

This adds a message to the mailbox. notify_listeners is also called to try and update anyone interested.

quit

Tells the mailbox to quit (and the process will exit).

Notifying listeners

Finally, our mailbox needs a notify_listener function. This will go through each listener and then check to see if any messages are available, and if so, send them to the Pid. If a listener is notified, it is removed also.

notify_listeners

notify_listeners(#state{listeners=Listeners,messages=Msgs,cur_id=CurID} = State) ->
    NewListeners = lists:filter(fun({MsgID, Pid}) ->
        case MsgID >= CurID of
            true -> true;
            _ ->
                % Select messages that are greater than or equal to the requested ID
                case lists:filter(fun(#message{id=ID}) -> ID >= MsgID end, Msgs) of
                    [] -> true; % no messages were found for this listener, keep it in the list
                    M -> Pid ! lists:map(fun(#message{data=Data,id=MID}) -> {MID, Data} end, M), false % remove it
                end
        end
    end, Listeners),
    State#state{listeners=NewListeners}.

Okay, that does it for our mailbox, now let’s work on the post office, which will communicate with our mailbox.

Creating the Post Office

Now it’s time to implement the post office. Without really focusing on the chat room aspects now, the post office should work somewhat like it does in real life. Ours will do the following:

• Create/Delete mailboxes.
• Send message to a mailbox by a unique ID (aka address).
• Send message to all mailboxes (junk mail, broadcast).

Our chat_postoffice module uses the gen_server behavior so a lot of the code in the module is related to that. First let’s define the state of our postoffice server. It is very simple and just contains a list of mailboxes.

-record(state, {
mailboxes=[]
}).

Each item in the mailboxes list will be a tuple:

{Id,Pid}

Where Id is the mailbox ID, and Pid is the process ID for the mailbox. You can see in our init function that our server starts with no mailboxes(empty list).

Our create_mailbox function is defined below. First we check to see if the mailbox already exists, if not, we add it to our list and spawn off a mailbox process (we will go into the chat_mailbox module in a little bit).

create_mailbox

handle_call({create_mailbox, ID}, _From, #state{mailboxes=MBoxes} = State) ->
    case get_mailbox(ID, State) of
        {ok, _} -> {reply, {error, already_exists}, State};
        {error, notfound} ->
            Pid = spawn_link(chat_mailbox, start, [ID]),
            NewBox = {ID, Pid},
            {reply, ok, State#state{mailboxes=[NewBox | MBoxes]}}
    end;

And here is our method for deleting a mailbox. It removes the mailbox from the list and sends a message to the mailbox process to quit.

delete_mailbox

handle_cast({delete_mailbox, ID}, #state{mailboxes=MBoxes} = State) ->
    NewBoxes = lists:filter(fun({Id, Pid}) ->
        case Id /= ID of
            false -> 
                % tell the mailbox process to quit
                Pid ! quit, false;
            _ -> true
        end
    end, MBoxes),
    {noreply, State#state{mailboxes=NewBoxes}};

Now we want to create methods for sending and broadcasting mail.

To send mail, we look up the mailbox ID, and send the process a message. Note: Delivery is not guaranteed, if the mailbox process dies then it will never receive the message. In another post we will make it more fault tolerant, but for now, I wouldn’t worry about the mailbox process dying.

send_mail

handle_cast({send_mail, {ID, Msg}}, State) ->
    case get_mailbox(ID, State) of
        {ok, {_Id, Pid}} -> Pid ! {mail, Msg};
        _ -> ok
    end,
    {noreply, State};

And finally, let’s make our broadcast function. It takes a message and a list of ID’s not to send to.

broadcast_mail

handle_cast({broadcast_mail, {Msg, Except}}, #state{mailboxes=MBoxes} = State) when is_list(Except) ->
    [Pid ! {mail, Msg} || {Id, Pid} <- MBoxes, lists:member(Id, Except) == false],
    {noreply, State};

chat_room server

This server contains the core logic of our chat room. This includes maintaining all connected users, and functions to allow a user to join or leave the chat room, get list of online users, and send/receive messages(and events).

The state of the chat_room server is defined below. At the most basic level, it is just going to contain a list of all the users in the chat room. The client state is also defined below.

-record(state, {
clients=[]
}).
 
-record(client_state, {
id, nick, host,last_action
}).

The chat_room server will have the following functions:

• join
• leave
• wait/wait_finish
• chat_message
• get_users
• get_msg_id
• find_idle_clients

Let’s start by writing the join function. This will first check to make sure that a nickname is valid(alphanumeric, no longer than 16 characters) and available. If everything is okay, we will create a mailbox for the user, notify all other users that a user has joined, and return a unique session to the caller. If an error occurs, it is returned to the caller as well.

join

handle_call({join, {Nick, Host}}, _From, #state{clients=Clients} = State) when is_list(Nick) ->
    case validate_nick(Nick, State) of
        {error, Reason} -> {reply, {error, Reason}, State};
        {ok, ValidNick} ->
            Session = get_unique_session(State),
            case chat_postoffice:create_mailbox(Session) of
                ok -> 
                    chat_postoffice:broadcast_mail({msg, {user_joined_room, ValidNick}}, [Session]),
                    Client = #client_state{id=Session,nick=ValidNick,host=Host,last_action=now()},
                    {reply, {ok, Session}, State#state{clients=[Client | Clients]}};
                {error, _} -> {reply, {error, not_available}, State}
            end
    end;

The leave function is used to log out of the chat room. It will remove the user, and notify the others that that user has left. In the next part, we will implement a timeout so that if a user hasn’t done anything in a specified time, he will be removed.

leave

handle_cast({leave, {Sess, Reason}}, #state{clients=Clients} = State) when is_list(Reason) ->
    case get_session(Sess, State) of
        {error, not_found} -> {noreply, State};
        {ok, Client} ->
            chat_postoffice:delete_mailbox(Client#client_state.id),
            CleanReason =  chat_util:unicode_clean(lists:sublist(Reason, 32)),
            chat_postoffice:broadcast_mail({msg, {user_left_room, {Client#client_state.nick, CleanReason}}}, [Client#client_state.id]),
            OtherClients = lists:filter(fun(#client_state{id=ID}) -> ID /= Client#client_state.id end, Clients),
            {noreply, State#state{clients=OtherClients}}
    end;

Chat message will broadcast a message to the chat room.

chat_message

handle_cast({chat_message, {Sess, Msg}}, State) when is_list(Msg) ->
    case get_session(Sess, State) of
        {error, not_found} -> {noreply, State};
        {ok, #client_state{nick=Nick,id=ID} = C} ->
            CleanMsg = chat_util:unicode_clean(lists:sublist(Msg, 256)),
            chat_postoffice:broadcast_mail({msg, {chat_msg, {Nick, CleanMsg}}}, [ID]),
            chat_postoffice:send_mail(ID, {msg, {sent_chat_msg, {Nick, CleanMsg}}}),
            NewState = update_client(C, State),
            {noreply, NewState}
    end;

Finally, we have ,wait, wait_finish, and get_users.

The wait function will add a listener to the user’s mailbox.

wait

handle_cast({wait, {Sess, MsgID, Pid}}, State) when is_integer(MsgID) ->
    case get_session(Sess, State) of
        {error, not_found} -> Pid ! {error, bad_session}, {noreply, State};
        {ok, C} ->
            NewState = update_client(C, State), 
            chat_postoffice:send_mail(Sess, {add_listener, {MsgID, Pid}}), {noreply, NewState}
    end;

wait_finish removes the listener from a mailbox.

wait_finish

handle_cast({wait_finish, {Sess, Pid}}, State) ->
    case get_session(Sess, State) of
        {error, not_found} -> {noreply, State};
        {ok, _} -> chat_postoffice:send_mail(Sess, {remove_listener, Pid}), {noreply, State}
    end;

The get_users function just returns a list with the nickname of every user.

get_users

handle_call({get_users, Sess}, _From, State) ->
    case get_session(Sess, State) of
        {error, not_found} -> {reply, {error, not_found}, State};
        {ok, C} -> 
            NewState = update_client(C, State),
            {reply, {ok, lists:map(fun(#client_state{nick=Nick}) -> Nick end, State#state.clients)}, NewState}
    end;

That does it for the chat_room server. If you look through the code you will also see a find_idle_clients function, which runs on a timer to see if any clients have left the browser and timed out.

Finally, the web front-end

There are two pages that the end user will see. The login page, where they can choose a nickname, and the chat page. There are two templates that we will be using, called index.html, the login page, and chat.html, the chat screen. The rest of the interaction between the web browser and the server will take place with AJAX.

First, let’s make it so a user can join the chat room. Take a look at the chat_web module and you will see a section called Request Handlers. These are functions that are called when a request comes in. We can look at the path to decide what to do.

At the bottom of our request handlers, we have one that will just try to serve a file from our docroot directory. This is where we will store our javascript and any other static files.

handle_request(Req, Path) ->
	Req:serve_file(string:sub_string(Path, 2), "docroot", []).

Also, I’ve included some helper functions in chat_util for loading templates with ErlyDTL. You can use the Django template language in your templates, and then render them with any variables you want. We don’t use this that much.

Login

Our login page, which is at the path /, is rendered like so:

handle_request(Req, "/") -> html_ok(Req, chat_util:get_template("index", []));

You can take a look at the template, it basically does a simple HTTP post to the path, /login/.

Our login handler just calls chat_room:join to attempt to join the chat room. If an error occurs, it is passed into the login template and returned to the user. If all is good, we set a cookie with the user’s chat session ID.

login

handle_request(Req, "/login/") ->
    Post = Req:parse_post(),
	case chat_room:join(chat_util:get_parameter("nick", Post), Req:get(peer)) of
	    {ok, SessID} -> 
	        SessCookie = mochiweb_cookies:cookie("chat_sess", SessID, [{path, "/"}]),
	        Req:respond({302, [SessCookie, {"Location", "/chat/"}], <<>>});
		{error, not_available} -> html_ok(Req, chat_util:get_template("index", [{error, "The nickname is not available."}]));
	    _ -> html_ok(Req, chat_util:get_template("index", [{error, "The nickname must be alphanumeric and not blank."}]))
	end;

The main chat interface

Once the user is redirected to the /chat/ path and has a session cookie set, the AJAX will take over. I don’t want to go too much into the javascript, but it mainly does the following:

• Get’s the current message ID and validates the session.
• Get’s the list of online users.
• Waits for any messages to come in from the server.

Start client is called to get the message ID. If successful, it gets the online users.

startClient

function startClient() {
	addSystemMsg("Establishing connection to chat service...");
	new Ajax.Request('/chat/start/',
	  {
	    method:'get',
	    onSuccess: function(transport){
			var response = transport.responseText.evalJSON();
 
			if(response.status == "ok") {
				msgID = response.response;
				addSystemMsg("Connected to chat service.");
				getOnlineUsers();
			}
			else if(response.status == "error" && response.response == "bad_session") addSystemMsg("Unable to locate your session. Please <a href=\"/\">login</a> again.");
	    },
	    onFailure: function(){ addSystemMsg("The chat service is not responding at this time.") }
	  });
}

After the message ID and the online users are retrieved, the client enters the message loop. After a message is received, it is processed by handleServiceMsg, which basically looks at the JSON object and decides what to do(user joined, chat message, etc,.).

getServiceMsg

function getServiceMsg() {
	new Ajax.Request('/chat/wait/?msg_id=' + msgID,
	  {
	    method:'get',
	    onSuccess: function(transport){
	        if(transport.responseText == "") {
	            setTimeout('getServiceMsg();', 10000);
	        }
	        else {
	            addSystemMsg(transport.responseText);
	            var response = transport.responseText.evalJSON();
	            if(handleServiceMsg(response) == true) {
		  	        getServiceMsg();
		        }
	        }
	    },
	    onFailure: function(){ 
	        setTimeout('getServiceMsg();', 10000) }
	  });
}

getServiceMsg talks to the following handler, which just adds a listener for our session, and waits for a message.

handle_request(Req, "/chat/wait/") ->
    MsgID = chat_util:get_parameter_int("msg_id", Req:parse_qs()),
    chat_room:wait(get_session(Req), MsgID, self()),
    timer:apply_after(?COMET_TIMEOUT, ?MODULE, timeout_wait, [self()]),
    proc_lib:hibernate(?MODULE, wait, [Req]);

If there are no messages after a certain time(?COMET_TIMEOUT), a timeout message is sent and the client is told to reconnect.

When the user wants to send a message, an AJAX post is performed to the path /chat/send_msg/. The following is the handler for sending a chat message. It’s pretty simple.

handle_request(Req, "/chat/send_msg/") ->
    chat_room:chat_message(get_session(Req), chat_util:get_parameter("msg", Req:parse_post())),
    json_respond(json_client_ok(<<"">>), Req);

Conclusion

Well, that’s it for now. You can download the source and try it out yourself. The server runs on port 8000. (http://localhost:8000).

In the next part, I will discuss some more advanced features, such as rate limiting, limiting connections for a host, admin control, more fault tolerance(using ETS/DETS) for storing messages, and more. While you are waiting, come chat: chat.tech9computers.com

Comet is a technique to stream data, or “push” events to the web browser, instead of making the client poll the server every few seconds. This lets the client receive near real-time updates. If you want to read more about Comet, check out the article on Wikipedia, more specifically, the section about Ajax with long polling, as this is what our server will implement.

I chose web based chat because it is a great “hello world” for learning how Comet works, and I really enjoy programming chat related stuff (see my very old implementation of GameRanger)

Chat Architecture

Before we get into any code, we have to talk about how the overall chat system works. Here are a few specifications.

• Erlang is going to handle all server-side tasks.
• Mochiweb will be used to serve the browsers.
• There will be only one (global) chat room.
• When a user sends a message, all others in the room will see it.

Okay, that should do it for now. That is the very basic outline of what the chat system needs to do. Now let’s talk about the server.

Server Overview

The server will use Erlang’s OTP feature to make sure that all of our services remain running and are monitored.

We are going to have the following logical services managed by OTP:

• chat_room
• chat_postoffice
• chat_web

The other modules are:

• chat_mailbox – handles mailbox processing
• chat_util – helper functions for the application
• chat_sup – supervisor
• chat_server – the chat_server application

chat_room

This module will be used to maintain the state of our chat room, and allow us to implement any “chat_room” logic, such as join/leave, sending messages, etc,.

chat_postoffice

This module is very important, it will hold all the mailboxes for each user in the chat room. Whenever we want to notify a user of something, we will send a message to the “post office”. The post office will then relay the message to an individual user’s mailbox. After the message has arrived in a user’s mailbox, the mailbox may notify our web server, and the web server can notify the client’s web browser. (I know, that’s a lot handle, but don’t worry, it will be explained).

chat_web

Finally, the chat_web module is what the web browsers will be talking to, this is the front-end of the chat system. The web module will handle the basic tasks, such as joining the chat room, sending messages, and of course, receiving messages.

Implementing chat_mailbox

In Part 2, we will implement the chat_mailbox module for our chat server. (Source code will be included).