View source for Node Chat/Docs

'''TODO: CONVERT THIS!!! This is copy/pasted from the Wikia docs & I just removed any private info... still need to update all of the paths, etc. to be for the new project.''

== Where is the code ==
* Front-end: https://github.com/Wikia/app/tree/dev/extensions/wikia/Chat2
* Back-end: https://github.com/SeanColombo/chat

== What is the chat's datastore? ==
The chat uses redis for a datastore. Currently, none of the data stored in redis DB is critical. Therefore it is not needed to provide replication or backup.

==How I can change debugging level?==
You can you add commend line option loglevel=INFO and just start server with it. Or edit this file (/chat/server_config.js line 57), Possible levels of debugging: CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG. After you changed file you need to restart server. IDEA: it would be nice to keep debugging level in txt file. The file would be read every 1min by nodejs. So we wouldn't need to restart server when we want to change debugging level.

==How to restart server==
"sudo killall node" Server will be started automatically by runit process or supervisor if it was started using either of those.

==I don't see any problem in log but chat is broken where else to look==
You can try to use [http://en.wikipedia.org/wiki/Ngrep ngrep ]. Example of ngrep usage:
  sudo ngrep -d any port 80

==What are the responsibilities of the Web-site stack==
PHP stack's responsibilities: rendering of the chat.php page, server and instance selection and authorization. All messages and status exchange is handled by node.js server.

==Where are the chat configurations==
Chat is special case where configuration need to be shared between the web-app stack and the Chat server. In order to solve this problem we store configuration in a JSON file. JSON format is easy to ready by PHP and JaveScript. Github location of an example config file: https://github.com/SeanColombo/chat/ChatConfig_EXAMPLE.json

==How do Chat and the main website exchange information and is it safe==
The site and Chat provides to each other API methods. In order to prevent users from injecting unwanted data to Chat or MediaWiki We use ChatCommunicationToken for signing requests. Each installation of the chat server needs to have its own ChatCommunicationToken.
https://github.com/SeanColombo/chat/ChatConfig_EXAMPLE.json#L2

==How does authorization work==
[[file:Chat_author.png| thumb| 250px]]
* User accesses chat.php
* The site gets all needed user information and store them in object(user info object)
* The site generates KEY and stores "user info object" in memcached under the KEY
* The page is rendered with KEY(wgChatKey) as one of the JS vars.
* Client Java Script accesses node.js server with KEY.
* Node.js sends the query to the site with KEY through API protected with ChatCommunicationToken.
* If the KEY is correct media wiki answers with JSON containing "user object".
* Now node.js server knows if user is authorized to connect and what his privileges are.
==What is the network protocol between node.js and browser==
For message transportation we use popular lib [http://socket.io/ socket.io] The     
library implements wrappers for 5 different underline technology: websocket, flashsocket, htmlfile, xhr-polling, jsonp-pollin. However for compatibility and simplification reasons we pick only one format: xhr-polling. You can find more information about this transportation technique http://en.wikipedia.org/wiki/Comet_(programming) search for: XMLHttpRequest long polling.

== Can I test chat in my local development environment ==
Yes, simply follow the [[Node Chat/Docs/Dev Setup|Dev Setup Instructions]].

== Chat-Bot ==
If you need a chat-bot to help you test some things, Wikia user Sactage made a ruby chat and put it on github: https://github.com/sactage/chatbot-rb

==How do emoticons work==
Emoticons are added during message rendering. Any wiki can define there own emoticons by editing mediawiki:emoticons article. Default icons are defined in: https://github.com/Wikia/app/blob/dev/extensions/wikia/Chat2/ChatDefaultEmoticons.i18n.php
'''TODO: This needs to be ported to perhaps be not-mediawiki-specific anymore, but in a way that allows the Wikia instance to continue to work as-is.'''

= Scaling =
== Failover ==
One way to allow for high-availability is to have a second stack (on a second machine) and failover to that second computer automatically.

[[File:Chat_infrastructure_simple_view.png|thumb|150px]] In case of failure of active stack, traffic can be switched to other stack.

==Why there are many instances of node.js on chat machines==
[[File:Chat_top_processes.png|thumb|150px]] One of the limitation of [http://nodejs.org/ node.js] is that its single threaded which means that we can't use the full power of modern multi core servers. In order to use the full advantage of multi-core CPUs we run more than one instance on each machine.

==How the load is split between instances of node.js==
We use a simple modulo operation, <code>instance_id = chat_room_id % number_of_instances</code>.  The chat_room_id could be based on some listing you have, or it could be the id for a subdomain of your site, depending on how you use the system.