Merge pull request #22 from CppComet/alfa

Added .md docs

Author: VictorTrapenok

docs/wiki-md/comet/authentication.md

@@ -0,0 +1,100 @@
+
+# Авторизация пользователей
+
+Помимо каналов где каждый кто знает имя канала может подписаться на него, есть возможность авторизации пользователей на комет сервере и отправки личных сообщений пользователям по их идентификаторам. Авторизация пользователя происходит в 2 этапа. Первый этап это отправка идентификатора пользователя в вашей системе и случайного хеша в комет сервер.
+
+
+```
+
+mysql> INSERT INTO users_auth (id, hash )VALUES (1, 'auth_hash1');
+
+```
+
+  * Здесь строка auth_hash1 - это текстовый ключ авторизации. Вы его сами генерируете на своём сервере и отправляете сначала в комет по средствам insert запроса в таблицу users_auth, а затем передаёте в JavaScript для авторизации конкретного пользователя на комет сервере.
+  * Числовой_Идентификатор_пользователя - Это id пользователя на вашем сайте, любое целое положительное число не более чем из 9 цифр. 
+
+
+```
+
+// На втором этапе эти сведения (идентификатор пользователя и хеш) надо передать в JavaScript Api
+$(document).ready(function()
+{
+    CometServer().start({dev_id:15, user_key:"auth_hash1", user_id:"Числовой_Идентификатор_пользователя" })
+});
+
+```
+
+И теперь пользователь будет авторизован на комет сервере.
+
+# Отправка сообщений для авторизованных пользователей
+
+При отправке сообщений авторизованным пользователям по их идентификатору ([insert запрос в таблицу users_messages](/docs/wiki-md/comet/cometql.md)) сообщения доставляются пользователю на все устройства (До 16 устройств) на которых он прошёл авторизацию в данный момент. Это очень удобно в том случаи если человек зашёл на ваш сайт и авторизовался на нём более чем с одного устройства (к примеру телефон и компьютер или просто в двух разных браузерах сидит одновременно).
+
+Если человек в данный момент ofline то сообщение помещается в очередь сообщений и будет доставлено когда человек появится online.
+
+Основное назначение очереди сообщений это доставка сообщений после кратковременного перехода человека в ofline. Например в тех случаях когда человек обновляет страницу сайта на которой было открыто соединение он уходит в ofline примерно на 1 секунду.
+
+
+
+# Подписка на получение личных сообщений
+Для того чтобы получать личные сообщения. Надо подписаться на них. Подписка на сообщения с именем события "event1" от сервера доставленные в соответствии с данными авторизации (то есть по id пользователя) осуществляется следующим образом.
+
+```
+CometServer().subscription("msg.event1", function(e){ console.log(e)})
+```
+
+
+Канал msg относиться к [списку каналов с особыми свойствами](/docs/wiki-md/comet/javascript_api/pipe-types.md) 
+
+# Определение статуса авторизации
+
+Что бы определится авторизовались мы на комет сервере или нет есть несколько специальных функций
+
+Функция isAuthorized вернёт текущее значение состояния авторизации. Бывает три значения в ответе.
+
+  * undefined - статус ещё не определён, на пример не было подключения или оно в процессе.
+  * true - авторизованы
+  * false - не авторизованны
+
+
+```
+
+cometApi.isAuthorized()
+
+```
+
+
+Функция onAuthSuccess служит для подписки на оповещения о том моменте кода статус поменялся с любого на "авторизован"
+
+```
+
+cometApi.onAuthSuccess(function()
+{
+     alert("Авторизовались успешно")
+})
+
+```
+
+
+Функция onAuthFalill служит для подписки на оповещения о том моменте кода статус поменялся с любого на "не авторизован"
+
+```
+
+cometApi.onAuthFalill(function()
+{
+     alert("Не авторизовались")
+})
+
+```
+
+
+# Онлайн демо отправки личных сообщений
+
+[Код примера](https://github.com/CppComet/auth-example) [online demo on github](https://cppcomet.github.io/auth-example/index.html) [Смотреть на codepen.io](https://codepen.io/Levhav/pen/XaWLra)
+
+Откройте пример в двух или более браузерах, Скопируйте ваш `USER_ID` из одного окна и вставьте его в другое окно. В поле с подписью ` Identificator of user who must will receive the message` введите текст сообщения и нажмите отправить. Вы увидите что сообщение придёт только в то окно у которого задан то же USER_ID который вы и указали при отправке.
+
+<html>
+See the Pen <a href='https://codepen.io/Levhav/pen/XaWLra/'>CppComet auth chat example</a> by Trapenok Victor (<a href='https://codepen.io/Levhav'>@Levhav</a>) on <a href='https://codepen.io'>CodePen</a>.
+
+</html>

docs/wiki-md/comet/building-from-source.md

@@ -0,0 +1,215 @@
+
+# Установка
+
+Рекомендуемые ОС ubuntu, debian, centos
+
+```
+
+apt-get update
+apt-get install cmake make cpp gcc libssl-dev g++ nginx libmysqlclient-dev mysql-server mysql-client flex mailutils uuid-dev 
+
+```
+
+
+# Собираем из исходных кодов
+
+```
+
+git clone https://github.com/Levhav/comet-server
+cd comet-server
+cmake .
+make
+
+```
+
+
+# Настройки
+
+CppComet использует базу данных mysql для хранения данных пользователей для авторизации на сервере. И хранения времени, когда пользователь был в сети. И для хранения временных данных, таких как не доставленные сообщения и другие данные.
+
+  * Создайте базу в mysql на основе файла [db.sql](https://github.com/Levhav/comet-server/blob/master/db.sql)
+  * В файле [comet.ini](https://github.com/CppComet/comet-server/blob/master/comet.ini) укажите реквизиты для доступа к бд в секции [db]
+
+```
+
+[db]
+host = localhost
+user = root
+password = root
+name = comet_db
+port = 3305
+
+```
+
+Укажите пароль для доступа к api комет сервера
+
+```
+
+[main] 
+; пароль для доступа к api комет сервера
+password = 0000000000000000000000000000000000000000000000000000000000000000
+
+```
+
+Остальные настройки из файла [comet.ini](https://github.com/CppComet/comet-server/blob/master/comet.ini) можно не менять.
+
+
+___
+Весь перечень настроек в статье [Настройка файла comet.ini](/docs/wiki-md/comet/ini-file.md) 
+___
+
+  
+# Запуск
+Запуск в консольном режиме
+
+```
+
+./cpp_comet
+
+```
+
+Запуск в режиме демона
+
+```
+
+systemctl start comet.service
+
+```
+
+
+# Добавление в автозагрузку
+
+
+
+```
+cp ./comet.service /etc/systemd/system
+systemctl daemon-reload
+systemctl enable comet.service
+```
+
+# Настройка nginx в качестве реверс прокси
+
+Для того чтоб настроить работу комет сервера на одной машине с другим сервером. Или просто иметь возможность работы не только по http но и по https надо настроить реверс прокси.
+
+Ниже приведён пример конфигурации nginx для проксирования трафика до комет сервера с /comet-server на комет сервер запущенный на порту 82 и всего остального трафика на веб сервер запущенном на порту 8080
+
+```
+
+server {
+	listen 0.0.0.0:80;   
+	server_name comet-server.com;
+ 
+	location / {
+		proxy_pass http://127.0.0.1:8080;
+		proxy_set_header Host $host;
+		proxy_set_header X-Real-IP $remote_addr;
+		proxy_set_header X-Forwarded-For $remote_addr;
+		proxy_connect_timeout 120;
+		proxy_send_timeout 120;
+		proxy_read_timeout 180;
+	}
+
+	keepalive_disable none;
+	lingering_close always;
+	send_timeout 3600s;
+
+	location /comet-server {
+        proxy_pass http://127.0.0.1:82;
+        
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header Host $http_host;
+        proxy_set_header X-NginX-Proxy true;
+        
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        
+        proxy_redirect off;
+        keepalive_timeout 900;
+        proxy_read_timeout 900;
+	} 
+}
+
+# HTTPS server
+
+
+server {
+	listen 0.0.0.0:443;  
+	server_name comet-server.com;
+
+	ssl on;
+	ssl_certificate /etc/letsencrypt/live/comet-server.com/fullchain.pem;
+	ssl_certificate_key /etc/letsencrypt/live/comet-server.com/privkey.pem;
+	 
+	ssl_session_timeout 70m;
+
+	ssl_protocols SSLv3 TLSv1;
+	ssl_ciphers ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv3:+EXP;
+	ssl_prefer_server_ciphers on;
+
+	keepalive_disable none;
+	lingering_close always;
+	send_timeout 3600s;
+ 
+	location / {
+		proxy_pass http://127.0.0.1:8080;
+		proxy_set_header Host $host;
+		proxy_set_header X-Real-IP $remote_addr;
+		proxy_set_header X-Forwarded-For $remote_addr;
+		proxy_connect_timeout 120;
+		proxy_send_timeout 120;
+		proxy_read_timeout 180;
+		 
+	}
+	 
+	location /comet-server {
+        proxy_pass http://127.0.0.1:82;
+        
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header Host $http_host;
+        proxy_set_header X-NginX-Proxy true;
+        
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        
+        proxy_redirect off; 
+        keepalive_timeout 900;
+        proxy_read_timeout 900;
+	}
+}
+
+```
+
+
+# Возможные проблемы после установки
+ 
+Обратите внимание на то какие значения параметра port указаны в секциях [ws] и [cometql] именно на этих  портах комет сервер будет ожидать входящие подключения.
+
+В шаблоне comet.ini поставляемом в репозитории параметр port  для подключений из JavaScrip api выставлен в 8087
+Это значит что подключатся надо так:
+
+```
+cometApi.start({user_id:1, user_key:"userHash", node:"example.ru:8087"})
+```
+
+
+Параметр port  для подключений из CometQL выставлен в 3300
+Это значит что подключатся надо так:
+
+```
+$link = mysqli_connect("example.ru", "root", "", "CometQL_v1", 3300);
+```
+
+
+Так же обратите внимание на то что надо указывать имя базы данных CometQL_v1, оно символизирует версию апи и вероятно потом выйдет версия CometQL_v2 и можно будет при подключении выбирать версию для работы.
+
+
+
+
+
+
+
+