Fred T-H avatar Fred T-H committed 4ef7716

Starting a wiki with the general doc

Comments (0)

Files changed (1)

-== Welcome ==
-
-Welcome to your wiki! This is the default page we've installed for your convenience. Go ahead and edit it.
-
-=== Wiki features ===
-
-This wiki uses the [[http://www.wikicreole.org/|Creole]] syntax, and is fully compatible with the 1.0 specification.
-
-The wiki itself is actually a hg repository, which means you can clone it, edit it locally/offline, add images or any other file type, and push it back to us. It will be live immediately.
-
-Go ahead and try:
-
-{{{
-$ hg clone http://bitbucket.org/ferd/chut/wiki/
-}}}
-
-Wiki pages are normal files, with the .wiki extension. You can edit them locally, as well as creating new ones.
-
-=== Syntax highlighting ===
-
-You can also highlight snippets of text, we use the excellent [[http://www.pygments.org/|Pygments]] library.
-
-Here's an example of some Python code:
-
-{{{
-#!python
-
-def wiki_rocks(text):
-	formatter = lambda t: "funky"+t
-	return formatter(text)
-}}}
-
-You can check out the source of this page to see how that's done, and make sure to bookmark [[http://pygments.org/docs/lexers/|the vast library of Pygment lexers]], we accept the 'short name' or the 'mimetype' of anything in there.
-
-Have fun!
+= Chut =
+
+Chut is an experimental core for a distributed chat system in Erlang. The system aims to support long-polling connections from many tabs in a browser, but could easily be adapted to a desktop client or anything really.
+
+== What's done ==
+The system is currently pretty minimal it includes the following:
+* User-to-user communication
+* Multiple clients for a single user is possible
+* Session timeouts
+* Distribution on multiple nodes
+* Basic web-server implementation
+* Ugly javascript long-polling client (bug-ridden)
+* General test suite
+
+=== How it works ===
+The first concept to understand is the idea of clients and users. A client is basically a connection from a socket, web server, browser tab, whatever. The user is a bunch of processes that represent a real world user. Clients connect to a user and can route messages through them for another user, which in turns routes them to that user's clients.
+
+{{http://imgur.com/RiGZ4.png|client-users}}
+
+Users are composed of a supervisor, a gen_fsm and a gen_event:
+
+==== Supervisor ====
+The supervisor adopts a one-for-all restart strategy for the FSM and event manager, making sure the user can't exist without them. The supervisor also acts as an entry point to the user hierarchy. The whole group can then be killed that way.
+
+==== gen_event ====
+The event manager is responsible for routing messages from user to user, and also from user to each of the clients. Each message sent from or to a given user must pass through the event manager. 
+
+The messages have the following format:
+{received, From, Message}: Another user sent you a message 
+{sent, To, Message}: Your user sent someone else a message
+
+Different event handlers attached to the event manager will be dealing with routing messages:
+
+* //usr_dispatch_handler//: Takes messages you send and routes them to another user. There is only one of these per user.
+* //usr_listen_handler//: Takes any kind of message received and transmits them to the client. the format of the message is altered to be {UserId, {received, From, Message}} or {UserId, {sent, To, Message}} so a given process can hold more than one client connection. There is one handler of this kind per client.
+
+These two handlers are enough to do all the message routing. Additional handlers could be added to do logging, message history, presence updates, etc.
+
+
+==== gen_fsm ====
+The finite state machine acts as a manager for state. It tracks the addition and deletion of //usr_listen_handler//s to the user. When there are no listeners left on the user, the state machine falls into a waiting state. If no handler is added within given time limit (determined by the supervisor), the FSM kills the supervisor, bringing down the client itself.
+
+This time delays allows a user with only 1 client in a browser to refresh pages and stay connected.
+
+The user as a whole can be illustrated that way:
+{{http://imgur.com/Tn9G3.png|user}}
+
+==== Addressing ====
+Each user is thus made of 3 processes individually registered with the global module. The names used are //UserId//, //{manager, UserId}// and //{monitor, UserId}// for the supervisor, event manager and the finite state machine, respectively.
+
+The global module was used over solutions like mnesia for reasons such as automatic monitoring of registered processes, the possibility to define procedures in case of netsplits when the network comes back up, a local lookup for names, etc. This system allows to have instant distribution over many nodes.
+
+==== Web Server and javascript implementation ====
+The current implementation is broken, to put it simply. The mochiweb server is botched-up copy/pasting and the javascript implementation is subject to stack overflows with listen requests and doesn't break up listen calls when submitting new messages, making it easy to hit a browser's limit. Moreover, the current listen implementation will not call the server back once an error occured.
+
+It is strongly suggested that the whole browser + javascript client part should be thrown into a garbage can to never be considered again. I really need to replace it with something better.
+
+== What's left to be done ==
+* A better web implementation for long-polling
+* Enabling conversation history for the last few messages 
+* Adding logging to messages sent and received
+* Notifying the user when someone he's talking to disconnects
+* Specifying functions to deal with netsplits and user registration
+* Add more unit tests
+* Benchmark the performances
+* And much more!
+
+=== How it's gonna be done ===
+The most important points to extend at the moment are the web implementation and conversation history.
+
+The web implementation will likely require to start the //web_server.erl// module from scratch and to restart the javascript part from scratch too. I don't really know how I'm going to proceed for the whole thing yet, so we'll see.
+
+As for the conversation history, it should be trivial to add a new event handler that will keep received and sent messages to its local state. A new message could be added of the form {From, {history, LastId}} where LastId might just be {now(), make_ref()}. The event handler catching this message can then reply to 'From' by sending the history needed.
+
+A similar procedure can be done for the logger. A simple event handler listening to every message sent and logging them on disk somewhere (or in a database) is also trivial to add.
+
+More unit tests should be one of the top priority also. So far, only a general common test suite exists, testing the general behavior of the chat users and client modules.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.