Initial commit

source/_static/style.css

@@ -0,0 +1,28 @@
+@import url(http://fonts.googleapis.com/css?family=Roboto+Condensed&subset=cyrillic,latin);
+
+body {
+    background: #ebe8e1!important;
+}
+
+h1, h2, h3, h4, h5, h6, legend {
+    font-family: "Roboto Condensed", "Roboto Slab", sans-serif;
+    font-weight: normal;
+}
+
+.wy-side-nav-search,
+.wy-nav-top {
+    background-color: #207E5C;
+}
+
+.wy-menu-vertical a:active {
+    background-color: #1A6449;
+}
+
+.wy-nav-side {
+    background-color: #232323;
+}
+
+.wy-table-responsive table td,
+.wy-table-responsive table th {
+    white-space: normal;
+}

source/_templates/layout.html

@@ -0,0 +1,5 @@
+{# layout.html #}
+{# Import the theme's layout. #}
+{% extends "!layout.html" %}
+
+{% set css_files = css_files + ['_static/style.css'] %}

source/conf.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# Ely.by docs documentation build configuration file, created by
+# sphinx-quickstart on Sun Feb  1 22:04:01 2015.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+import sphinx_rtd_theme
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'Документация Ely.by'
+copyright = '2015, ErickSkrauch'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'ru'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'monokai'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = '_static/favicon.ico'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Elybydocsdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  ('index', 'Elybydocs.tex', 'Ely.by docs Documentation',
+   'ErickSkrauch', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'elybydocs', 'Ely.by docs Documentation',
+     ['ErickSkrauch'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'Elybydocs', 'Ely.by docs Documentation',
+   'ErickSkrauch', 'Elybydocs', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False

source/index.rst

@@ -0,0 +1,23 @@
+.. Ely.by docs documentation master file, created by
+   sphinx-quickstart on Sun Feb  1 22:04:01 2015.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Добро пожаловать в документацию Ely.by!
+=======================================
+
+В этой документации вы найдёте информацию о публичных сервисах проекта Ely.by, ознакомившись с которой вы сможете самостоятельно
+реализовать свои программные продукты для совместной работы с сервисом Ely.by.
+
+Вы можете свободно улучшать и вносить предложения по изменениям в документацию в репозитории документации.
+
+Содержание:
+~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 2
+
+   skin-system
+   minecraft-auth
+   oauth
+

source/minecraft-auth.rst

@@ -0,0 +1,304 @@
+Авторизация для Minecraft
+-------------------------
+
+Здесь приведена информация по авторизации для лаунчеров и серверов Minecraft через сервис авторизации Ely.by.
+
+Протокол авторизации реализован максимально похожим на `оригинальный протокол авторизации Mojang <http://wiki.vg/Authentication>`_,
+но тем не менее эта документация описывает все доступные функции конкретно сервиса авторизации Ely.by.
+
+Общие положения
+===============
+
+* Все запросы должны выполняться на URL **http://minecraft.ely.by**.
+
+* При успешном запросе, сервер вернёт ответ со статусом 200. Любой другой код свидетельствует об ошибке.
+
+* Сервер всегда отвечает JSON данными, кроме случаев системных ошибок. Учитывайте это для отображения пользователю правильного
+  сообщения об ошибке.
+
+* В случае предусмотренной ошибки, вы получилите следующие данные:
+
+  .. code-block:: javascript
+
+     {
+         "error": "Краткое описание ошибки",
+         "errorMessage": "Более длинное описание ошибки на английском языке, пригодное для отображения пользователю."
+     }
+
+Предусмотренные ошибки
+~~~~~~~~~~~~~~~~~~~~~~
+
+В отличие от оригинального протокола, на Ely применяется меньший зоопарк ошибок
+
+.. list-table::
+   :widths: 20 50 30
+   :header-rows: 1
+
+   * - Ошибка (error)
+     - Причина
+     - Решение
+   * - Not Found
+     - Вы выполнили запрос на неизвестный URL или отправили POST запрос туда, где ожидался GET.
+     - Внимательно прочитайте документацию по запросу, который вы выполняете.
+   * - IllegalArgumentException
+     - Вы передали неполный список данных для выполнения запроса.
+     - Внимательно перепроверьте что вы шлёте в запросе и что указано в документации.
+   * - ForbiddenOperationException
+     - Пользователь ввёл/разработчик передал неверные значения.
+     - Необходимо вывести пользователю уведомление о неправильно введённых данных.
+
+Авторизация в лаунчере
+======================
+
+В этом разделе описана авторизация для лаунчера или любой другой настольной программы, которой необходимо получить
+accessToken для игрового клиента Minecraft. Важно понимать, что этот accessToken не имеет ничего общего с accessToken,
+получаемым при oAuth авторизации - это два абсолютно разных ключа.
+
+Все запросы выполняются на подуровень /auth POST запросом.
+
+.. function:: /auth/authenticate
+
+   Непосредственная авторизация пользователя, используя его логин (ник или e-mail) и пароль.
+
+   Входные параметры:
+
+   :username: Никнейм пользователя или его e-mail (более предпочтительно).
+
+   :password: Пароль пользователя.
+
+   :clientToken: Уникальный токен лаунчера пользователя.
+
+   Успешный ответ:
+
+   .. code-block:: javascript
+
+      {
+          'accessToken': "Длинная_строка_содержащая_access_token",
+          'clientToken': "Переданный_в_запросе_client_token",
+          'availableProfiles': {}, /* См. ниже */
+          'selectedProfile': {
+              'id': "Длинная_строка_с_uuid_пользователя",
+              'name': "Текущий_nickname_пользователя",
+              'legacy': false
+          }
+      }
+
+   **availableProfiles** содержит в себе массив с одним элементом, таким же, как и selectedProfile. Добавлено только для
+   соответствия оригинальному протоколу и на деле не используется самими Mojang.
+
+   Касательно параметра **legacy** в selectedProfile в оригинальном протоколе явно не даны пояснения на счёт этого
+   параметра, но сказано, что обычно он в false. Возможно, он как-то используется официальным лаунчером.
+
+.. function:: /auth/refresh
+
+   Обновляет валидный accessToken. Этот запрос позволяет не хранить на клиенте его пароль, а оперировать только сохранённым
+   значением accessToken для практически бесконечной возможности проходить авторизацию.
+
+   Входные параметры:
+
+   :accessToken: Уникальный ключ, полученый после авторизации.
+
+   :clientToken: Уникальный идентификатор клиента, относительно которого получен accessToken.
+
+   .. note:: В оригинальном протоколе так же передаётся значение selectedProfile, но на деле от него мало что зависит и
+             для идентификации пользователя достаточно только этих двух параметров. Наш сервер не обидится, увидив его -
+             он просто его проигнорирует.
+
+   В случае получения какой-либо предусмотренной ошибки, следует заново запросить пароль пользователя и произвести
+   обычную авторизацию.
+
+   Успешный ответ:
+
+   .. code-block:: javascript
+
+      {
+          'accessToken': "Новая_длинная_строка_ содержащая_access_token",
+          'clientToken': "Переданный_в_запросе_client_token",
+          'selectedProfile': {
+              'id': "Длинная_строка_с_uuid_пользователя",
+              'name': "Текущий_nickname_пользователя",
+              'legacy': false
+          }
+      }
+
+.. function:: /auth/validate
+
+   Этот запрос позволяет проверить валиден ли указанный accessToken или нет. Этот запрос не обновляет токен и его время
+   жизни, а только позволяет удостовериться, что он ещё действительный.
+
+   Входные параметры:
+
+   :accessToken: Уникальный ключ, полученый после авторизации.
+
+   Успешным ответом будет являться любой результат, не содержащий в себе поля **error**. В `оригинальной документации
+   <http://wiki.vg/Authentication#Validate>`_ не сказано, что в итоге должен вернуть этот запрос, так что ориентируйтесь
+   на поле **error** в теле ответа.
+
+.. function:: /auth/signout
+
+   Не реализовано.
+
+.. function:: /auth/invalidate
+
+   Не реализовано.
+
+Авторизация на сервере
+======================
+
+Эти запросы выполняются непосредственно клиентом и сервером при помощи внутреннего кода или библиотеки authlib
+(начиная с версии 1.7.2). Они актуальны только в том случае, если вы уже произвели авторизацию и запустили игру с валидным
+accessToken. Вам остаётся только заменить пути внутри игры/библиотеки на привидённые ниже пути.
+
+Поскольку непосредственно изменить что-либо в работе authlib или игры вы не можете, здесь не приводятся передаваемые значения
+и ответы сервера. При необходимости вы сможете найти эту информацию самостоятельно в интернете.
+
+Через authlib
+~~~~~~~~~~~~~
+
+.. important:: Эта часть документации описывает запросы, выполняемые через authlib в версии игры 1.7.2+. Для более старых
+               версий смотрите раздел ниже.
+
+Все запросы из этой категории выполняются на подуровень /session. Перед каждым из запросов указан тип отправляемого запроса.
+
+.. function:: POST /session/join
+
+   Запрос на этот URL производится клиентом в момент подключения к серверу с online-mode=true.
+
+.. function:: GET /session/hasJoined
+
+   Запрос на этот URL выполняет сервер с online-mode=true после того, как клиент, пытающийся к нему подключится, успешно
+   выполнит join запрос.
+
+   .. attention:: Внутри тела ответа есть параметр **properties**, который, в свою очередь, содержит поле **value** с
+                  закодированной в ней base64 строкой. В оригинальной системе авторизации данные зашифрованы с помощью
+                  приватного ключа и расшифровывались на клиенте с помощью публичного.
+
+                  Ely, в свою очередь, **не выполняет шифрацию вовсе**, поэтому вам необходимо отключить проверку подписи в
+                  библиотеке authlib. В противном случае текстуры всегда будут признаваться невалидными.
+
+Для старых версий
+~~~~~~~~~~~~~~~~~
+
+.. important:: Эта часть документации описывает запросы, выполняемые более старыми версиями Minecraft, когда не применялась
+               библиотека authlib. Это все версии, младше версии 1.7.2.
+
+Все запросы из этой категории выполняются на подуровень /session/legacy. Перед каждым из запросов указан тип отправляемого запроса.
+
+Принцип обработки этих запросов такой же, как и для authlib, отличие только во входных параметрах и возвращаемых значения.
+
+.. function:: GET /session/legacy/join
+
+   Запрос на этот URL производится клиентом в момент подключения к серверу с online-mode=true.
+
+.. function:: GET /session/legacy/hasJoined
+
+   Запрос на этот URL выполняет сервер с online-mode=true после того, как клиент, пытающийся к нему подключится, успешно
+   выполнит join запрос.
+
+Важно не потерять GET параметр **?user=** в конце обоих запросов, чтобы получились следующие URL:
+``http://minecraft.ely.by/session/legacy/hasJoined?user=``.
+
+Одиночная игра
+==============
+
+По сути, одиночная игра - это локальный сервер, созданный для одного игрока. По крайней мере это так, начиная с версии 1.6,
+в которой и был представлен механизм локальных серверов.
+
+Тем не менее, описанный ниже запрос актуален только для Minecraft 1.7.6+, когда для загрузки скинов стала использоваться
+так же authlib.
+
+.. function:: GET /session/profile/{uuid}
+
+   Запрос на этот URL выполняется клиентом в одиночной игре на локальном сервере (созданном посредством самой игры).
+   В URL передаётся UUID пользователя, с которым был запущен клиент, а в ответ получается информация о текстурах игрока.
+
+Готовые библиотеки authlib
+==========================
+
+Поскольку самостоятельная реализация связана с трудностями поиска исходников, подключения зависимостей и в конце-концов с
+процессом компиляции, ниже приведён список пропатченых библиотек со всеми необходимыми изменениями адресов, отключённой
+проверкой подписи и встроенной системой скинов для серверов с online-mode=false. Вы можете использовать их "как есть".
+
+* Minecraft 1.8 - :download:`authlib 1.5.17 <_static/minecraft-auth/authlib/authlib-1.5.17.jar>`
+
+* Minecraft 1.7.10 - :download:`authlib 1.5.16 <_static/minecraft-auth/authlib/authlib-1.5.16.jar>`
+
+* Minecraft 1.7.9 - :download:`authlib 1.5.13 <_static/minecraft-auth/authlib/authlib-1.5.13.jar>`
+
+В более ранних версиях система скинов находилась внутри клиента, так что библиотеки ниже обеспечивают только авторизацию.
+
+* Minecraft 1.7.5 - :download:`authlib 1.3.1 <_static/minecraft-auth/authlib/authlib-1.3.1.jar>`
+
+* Minecraft 1.7.2 - :download:`authlib 1.3 <_static/minecraft-auth/authlib/authlib-1.3.jar>`
+
+.. hint:: На самом деле вам нужен только файл ``YggdrasilMinecraftSessionService.class``. Но здесь приведены готовые
+          библиотеки, чтобы вам не нужно было его искать и самостоятельно изменять.
+
+Для использования библиотеки вам необходимо заменить оригинальную, располагающуюся по пути /libraries/com/mojang/authlib/
+согласно её имени или же положить в другое место и просто при запуске игры подключить её, вместо оригинальной.
+
+Установка authlib на сервер
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Кроме этого библиотеку необходимо установить и на сервер. Для этого вам понадобится файл сервера с расширением .jar.
+Щёлкните на нём правой кнопкой мыши, выберите вариант "Открыть с помощью..." и выберите удобный архиватор (скорее всего WinRar).
+Затем проделайте те же действия с authlib такой же версии, что и ваш сервер.
+
+Перед вами будет 2 окна: одно с файлами authlib, другое с файлами сервера. Вам необходимо перетащить **только папку "com"**
+из authlib на сервер и подтвердить замену.
+
+.. figure:: _static/minecraft-auth/authlib-install.png
+   :align: center
+   :alt: Процесс перетягивания: что куда.
+
+После этих действий вы можете закрыть оба окна и в настройках сервера включить online-mode=true, авторизация через Ely.by
+установлена и работает!
+
+Установка на версии ниже 1.7.2
+==============================
+
+Для более старых версий существует достаточно большое многообразие различных случаев, раскрыть которые в этой документации
+не представляется возможным. Вся установка заключается в замене определённых строк в определённых классах через
+InClassTranslator.
+
+На форуме RuBukkit есть отличный пост, в котором собрана вся нужна информация по именам классов на различных версиях
+Minecraft. Переписывать его сюда не имеет смысла, так что просто перейдите на его страницу и найдите нужную версию.
+
+|rubukkit_link|.
+
+.. |rubukkit_link| raw:: html
+
+   <a href="http://www.rubukkit.org/threads/spisok-klassov-i-klientov-dlja-mcp.25108/#post-303710" target="_blank">RuBukkit -
+   Список классов и клиентов для MCP</a>
+
+Пример установки
+~~~~~~~~~~~~~~~~
+
+Предположим, что вы хотите установить авторизацию на сервер версии 1.5.2.
+
+Сначала вы переходите по вышепривидённой ссылке, выбираете нужную версию (1.5.2) и видите список классов:
+
+* **bdk.class** - путь до joinserver
+
+* **jg.class** - путь до checkserver
+
+Затем вы должны взять .jar файл клиента и открыть его любым архиватором. После чего вам необходимо найти файл **bdk.class**.
+Для этого удобно воспользоваться поиском.
+
+После того, как вы нашли файл, его нужно извлечь из архива - просто перетащите его оттуда в удобную для вас дирикторию.
+
+Дальше запустите InClassTranslator и в нём откройте этот класс. Слева будет список найденных в файле строк, которые вы
+можете изменить. Нужно заменить только строку, отвечающую за запрос на подключение к серверу:
+
+.. figure:: _static/minecraft-auth/installing_by_inclasstranslator.png
+   :align: center
+   :alt: Процесс перетягивания: что куда.
+
+После этого вам нужно положить изменённый .class обратно в .jar файл игры.
+
+Ту же самую операцию вам необходимо провести и с сервером, только заменить ссылку на hasJoined.
+
+-----------------------
+
+После этих действий вам нужно в настройках включить online-mode=true и сервер станет пускать на себя только тех игроков,
+которые будут авторизованы через Ely.by.

source/oauth.rst

@@ -0,0 +1,285 @@
+oAuth авторизация
+-----------------
+
+На этой странице вы найдёте информацию о подключении oAuth авторизации для вашего сайта через сервис Ely.by.
+Это такой же способ авторизации, как и вход через Вконтакте, Twitter, Google, Facebook и другие.
+Вкупе с использованием нашей системы скинов на своём сервере это позволит увеличить количество игроков на сервере и на сайте сервера.
+
+Добавление приложения
+=====================
+
+Для начала вам необходимо создать новое приложение. Вы можете это сделать на `Странице добавления приложения <http://ely.by/auth/add>`_.
+Внимательно отнеситесь к заполняемым полям - они будут влиять на внешний вид страницы авторизации.
+
+Описание:
+~~~~~~~~~
+
+:Название: Задаёт имя приложения, отображаемое на странице авторизации и в списке ваших приложений. **Обязательное поле**.
+
+:Описание: Отображается под назаванием приложения и позволяет пользователю убедится в том, что он авторизуется именно на желаемом ресурсе.
+
+:Адрес сайта: Позволяет задать обратную ссылку на ваш сайт.
+
+:Изображение: Ссылка на логотип или нечто иное, идентифицирующее ваш проект. Это поле не обязательно, но является крайне желательным для заполнения.
+
+Параметры авторизации:
+~~~~~~~~~~~~~~~~~~~~~~
+
+:Тип ответа: Задаёт дальнейшие действия сервиса oAuth авторизации после выполнения пользователем авторизации. 
+             На данным момент поддерживается только вариант "Получить код авторизации", что является форматом ответа для авторизации на сайтах.
+
+:Перенаправление: URL адрес, на который будет переадресован пользователь с данными, согласно выбранному *типу ответа*,
+                  после авторизации. **Обязательное поле**.
+
+Разрешения:
+~~~~~~~~~~~
+
+.. note:: Поскольку API для работы с Ely.by ещё не создано, вместе с получением токена доступа (access_token) вы получите и данные о пользователе.
+
+.. list-table:: Список доступных разрешений
+   :widths: 15 85
+   :header-rows: 1
+
+   * - Разрешение
+     - Описание
+   * - E-mail адрес
+     - Регистрационный e-mail адрес пользователя, подтверждённый им при регистрации.
+
+Инициализация авторизации
+=========================
+
+После того, как вы добавите приложение, получите ссылку на инициализацию авторизации и разместите её в любом удобном месте, например так:
+
+.. code-block:: html
+   
+   <a href="<ваша_ссылка>">Войти через Ely.by</a>
+
+По нажатию на ссылку, `если всё в порядке </oauth.html#auth-start>`_, пользователь попадёт на нашу страницу авторизации, где будут представлены данные вашего приложения,
+указанные при его регистрации.
+
+После успешного завершения процедуры авторизации, пользователь будет перенаправлен на страницу **перенаправления после авторизации** (redirect_uri).
+
+Если пользователь откажется от авторизации, то вы можете обработать и это, согласно `следующему разделу </oauth.html#auth-finish>`_.
+
+Данные придут в следующем формате:
+
+.. code-block:: html
+
+   <redirect_uri>?code=<код_авторизации>
+   
+Например это может выглядеть так:
+
+.. code-block:: http
+
+   http://someresource.by/oauth/ely.php?code=dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ
+
+Где:
+
+.. list-table::
+   :widths: 15 85
+   :header-rows: 0
+
+   * - redirect_uri
+     - http://someresource.by/oauth/ely.php
+   * - код_авторизации
+     - dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ
+
+Обмен кода на ключ
+==================
+
+После получения кода авторизации, вам необходимо обменять его на ключ авторизации (access_key). Для этого вам необходимо выполнить POST запрос на url:
+
+.. code-block:: http
+
+   http://oauth.ely.by/access-token
+
+И передать туда параметры **client_id**, **client_secret**, **redirect_uri** и **grant_type**. Значения этих параметров
+вы можете найти на странице с информацией о вашем приложении.
+
+Пример реализации запроса на PHP:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+
+   <?php
+   // В этой переменной будут храниться ваши параметры oAuth
+   $oauth_params = array(
+       'client_id' => 'BdBrINDm3CMXhrb6gaAeWqquyZmP2VUS9CLDU50M', // Публичный ключ
+       'client_secret' => 'Pk4uCtZw5WVlSUpvteJuTZkVqHXZ6aNtTaLPXa7X', // Секретный ключ
+       'redirect_uri' => 'http://someresource.by/oauth/some.php', // Редирект после авторизации
+       'grant_type' => 'authorization_code' // Просто нужно по протоколу. Не меняйте это значение
+   );
+   
+   // Выполняем код ниже только если пришёл код авторизации
+   if (!is_null($_GET['code'])) {
+       $oauth_params['code'] = $_GET['code'];
+   
+       $curl = curl_init();
+       curl_setopt($curl, CURLOPT_URL, 'http://oauth.ely.by/access-token');
+       curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
+       curl_setopt($curl, CURLOPT_POST, true);
+       curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($oauth_params));
+       $out = json_decode(curl_exec($curl));
+       curl_close($curl);
+   }
+
+Пояснение по коду:
+
+* Сначала мы объявляем переменную $oauth_params, в которую заносим значения, полученные после регистрации приложения.
+
+* Затем проверяем, пришёл ли код. Если кода нет, то, вероятно, пользователь отклонил запрошенные права. Подробнее об ошибках.
+
+* Инициализируем Curl для отправки запроса на форму обмена кода на токен: http://oauth.ely.by/access-token.
+
+* Запрос должен быть выполнен как POST и в него должны быть переданы 5 параметров: client_id, client_secret, redirect_uri, grant_type и code.
+  Имена полей должны быть именно такими, порядок не важен.
+
+* Выполняем запрос, получаем строку ответа от Ely и сразу же декодируем JSON строку.
+
+-------------------
+
+Таким образом в переменной **$out** будет находиться информация об авторизации.
+
+Ответ от сервера
+================
+
+В случае успешного запроса, в теле ответа будет находиться результат обмена кода авторизации на токен доступа.
+Данные являются простым JSON объектом и могут быть прочитаны в большинстве языков программирования без привлечения сторонних библиотек.
+
+Ознакомьтесь со списком возможных ошибкок в `следующем разделе </oauth.html#access-token>`_.
+
+-------------------
+
+После парсинга JSON строки вы получите следующие данные:
+
+.. code-block:: javascript
+
+   {
+       "access_token": "4qlktsEiwgspKEAotazem0APA99Ee7E6jNryVBrZ", /* Токен доступа */
+       "token_type": "Bearer",
+       "expires": 1407528497, /* Unix-timestamp истечения токена доступа */
+       "expires_in": 86400, /* Количество секунд, на которое выдан токен */
+       "user_data": {
+           "id": "1", /* Уникальный id пользователя */
+           "nickname": "ErickSkrauch", /* Текущий ник пользователя */
+           "profileUrl": "http://ely.by/erickskrauch", /* Ссылка на профиль */
+           "email": "erickskrauch@ely.by", /* Вы получите E-mail только если вы запросили право на доступ */
+           "skin": { /* Ссылки на различные изображения скина пользователя */
+               "faceUrl": "http://ely.by/minecraft/skin_buffer/faces/1c659e89546ae0cbf16965619053e31d.png",
+               "renderUrl": "http://ely.by/minecraft/skin_buffer/skins/1c659e89546ae0cbf16965619053e31d.png",
+               "skinUrl": "http://ely.by/minecraft/skins/1c659e89546ae0cbf16965619053e31d.png"
+           }
+       }
+   }
+
+На этом процедура авторизации закончена. Дальнейшая обработка данных зависит от потребностей вашего приложения.
+Вы можете выдать пользователю форму для довведения дополнительных данных или сразу произвести его регистрацию
+в своей системе и дальнейшую авторизацию.
+
+Возможные ошибки
+================
+
+Так или инчае, но реализовать oAuth авторизацию с первого раза получается далеко не у всех. Самым важным является правильно
+понять причину и исправить её. Ниже приведены стандартные и предусмотренные сообщения, которые вы можете получить в случае
+неправильной передачи данных на сервер или нестандартных действий пользователя.
+
+Тем не менее, если вы получили ошибку, неописанную в этой документации, пожалуйста, сообщите мне о ней в
+`форму обратной связи <http://ely.by/site/contact>`_.
+
+.. _auth-start:
+
+Ошибки при инициализации авторизации
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. _auth-start-fields:
+
+Поля
+""""
+
+Ошибка с текстом:
+
+.. code-block:: text
+
+   The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "redirect_uri" parameter.
+
+Означает то, что вы забыли передать в параметрах то или иное значение.
+Необходимое значение указано во 2 предложении.
+Чтобы решить эту проблему вам нужно просто добавить поле и его значение в передаваемые параметры.
+
+Клиент
+""""""
+
+Если же вы встретили следующую проблему:
+
+.. code-block:: text
+
+   Client authentication failed.
+
+Это означает, что переданные параметры не соответствуют ни одному зарегистрированному приложению.
+Проверьте ваши значения code и redirect_uri, а лучше используйте уже сгенерированную ссылку на странице информации о приложении.
+
+.. _auth-finish:
+
+Ошибки во время завершения авторизации
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+После того, как пользователь пройдёт авторизацию на Ely, ему будет предоставлен список разрешений, касающихся вашего приложения.
+Если пользователь разрешит доступ, то всё пройдёт как описано в документации выше, но если же он нажмёт на кнопку "Отказать",
+то он будет перенаправлен на ваш redirect_uri, но с другими GET параметрами:
+
+.. code-block:: http
+
+   http://someresource.by/oauth/some.php?error=access_denied&error_message=The+resource+owner+or+authorization+server+denied+the+request.
+
+То есть в вашем обработчике по пути redirect_uri вам необходимо обработать состояние, когда нет параметра code, но есть error
+и вывести пользователю какое-либо сообщение о том, что пользователь не дал доступа к своим данным - вы не дадите доступа к своему сервису :_:
+
+.. _access-token:
+
+Ошибки во время обмена токенов
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Поскольку обмен кода на токен доступа происходит через отправку POST запроса, данные передаются обратно в формате JSON.
+Поэтому опознать сообщение об ошибке можно по наличию поля **error** в ответе от сервера.
+
+В случае возникновения ошибки вы получите 2 поля:
+
+.. code-block:: javascript
+
+   {
+       "error": "invalid_request",
+       "error_description": "bla bla bla bla"
+   }
+
+В поле **error** находится системное описание ошибки, оно указано в скобках у разделов ниже. В поле **error_description**
+находится описание ошибки на английском языке. Содержание достаточно для самостоятельного решения проблемы, но в случае непонятности
+той или иной ошибки, внизу привидён список возможных ошибок с пояснениями на русском языке.
+
+Поля (invalid_request)
+""""""""""""""""""""""
+
+Смотрите "Ошибки при инициализации авторизации - :ref:`auth-start-fields`".
+
+Неподдерживаемый Grant (unsupported_grant_type)
+"""""""""""""""""""""""""""""""""""""""""""""""
+
+Если вы встретили эту ошибку, то это значит, что вы попытались произвести авторизацию по неизвестному для нашего oAuth сервера типу Grant.
+На данный момент Ely поддерживает только grant **authorization_code**, поэтому использование любого другого значения привидёт к этой ошибке.
+
+Клиент (invalid_client)
+"""""""""""""""""""""""
+
+Эта ошибка возникает в случае, когда трио значений **client_id**, **client_secret** и **redirect_uri** не совпали
+ни с одним из зарегистрированных приложений. Перепроверьте ваши значения.
+
+Ошибка доступа (invalid_grant)
+""""""""""""""""""""""""""""""
+
+Эта ошибка встречается в том случае, если переданный **code** не соответствует вашим **client_id** и **redirect_uri**.
+Возможно, вы неправильно обработали полученные данные или на нашем сервере были сброшены коды авторизации по каким-либо техническим причинам (маловероятно).
+
+Неизвестная ошибка (undefined_error)
+""""""""""""""""""""""""""""""""""""
+
+Код на сервере никогда не будет идеален и может случится так, что виноват буду я, а не вы. Если вы стабильно получаете эту ошибку,
+то, пожалуйста, сообщите мне об этом в `форму обратной связи <http://ely.by/site/contact>`_, чтобы я мог оперативно всё исправить.

source/skin-system.rst

@@ -0,0 +1,163 @@
+Система скинов
+--------------
+
+На этой странице вы найдёте информацию о самостоятельной реализации системы скинов на базе сервиса Ely.by.
+
+Система скинов Ely.by, в отличие от других, не заменяет, а дополняет официальную, тем самым игроки с лицензией не теряют
+свои скины, а игроки без лицензии смогут установить себе скин и видеть скины других игроков.
+
+Кроме того, в основных принципах сервиса лежит соответствие официальной системе скинов: нет плащей, нет ушек, нет HD-скинов.
+Это означает, что на вашем сервере не будут бегать разноцветные пугала с вырвиглазными скинами.
+
+URL-адреса запросов
+===================
+
+Система скинов располагается по URL **http://skinsystem.ely.by**. На сервере доступно 3 основных обработчика:
+
+.. function:: /skins/{nickname}.png
+
+   Этот URL отвечает за загрузку скинов. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить.
+
+.. function:: /cloaks/{nickname}.png
+
+   Этот URL отвечает за загрузку плащей. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить.
+
+   Хотя Ely.by не поддерживает пользовательскую загрузку плащей, мы оставляем за собой право устанавливать дополнительные,
+   относительно официальной системы скинов, плащи. В любом случае, мы будет пользоваться теми же принципами, что и Mojang -
+   плащи только за великие заслуги.
+
+.. function:: /textures/{nickname}
+
+   По этому URL вы можете получить текстуры для указанного в запросе **nickname**. Результатом является JSON строка, с
+   meta-информацией о скине следующего формата:
+
+   .. code-block:: javascript
+
+      {
+          'SKIN': {
+              'url': 'http://example.com/skin.png',
+              'hash': 'uniquehashofskin',
+              'metadata': {
+                  'model': 'default' /* default или slim, в зависимости от формата скина */
+              }
+          },
+          'CAPE': {
+              'url': '',
+              'hash': ''
+          }
+      }
+
+   *В абсолютном большинстве случаев, содержание CAPE будет именно таким, как показано выше.*
+
+.. note:: Ник не чувствителен к регистру и внутри обработчика в любом случае приводится к нижнему регистру.
+
+Кроме того, для всех запросов необходимо в GET параметрах передать следующие значения:
+
+:version: Версия протокола, по которому идёт запрос на скины. На данный момент таковым является 2 протокол, т.е. вам
+          нужно всегда указывать version=2.
+
+:minecraft_version: Версия Minecraft, с которой идёт запрос. Этот параметр можно не передавать в том случае, если вы
+                    передаёте параметр authlib_version.
+
+:authlib_version: Версия authlib, с которой выполняется запрос. Этот параметр актуален для версий Minecraft 1.7.6+, когда
+                  для загрузки скинов стала использоваться отдельная библиотека, а не реализация внутри игры.
+
+                  Параметр может быть передан вместо параметра **minecraft_version**.
+
+Если в запросе не будет параметра **version** и **minecraft_version** или **authlib_version**, сервер ответит 400
+ошибкой и скин не будет загружен.
+
+Примеры запросов
+~~~~~~~~~~~~~~~~
+
+.. code-block:: http
+
+   http://skinsystem.ely.by/skins/erickskrauch.png?version=2&minecraft_version=1.7.2
+
+Получает скин игрока **erickskrauch** с версии Minecraft 1.7.2.
+
+.. code-block:: http
+
+   http://skinsystem.ely.by/cloaks/notch?version=2&minecraft_version=1.6.4
+
+Получает плащ игрока **notch** с версии Minecraft 1.6.4. Обратите внимание, что расширение ".png" не передано.
+
+.. code-block:: http
+
+   http://skinsystem.ely.by/textures/EnoTiK?version=2&authlib_version=1.5.17
+
+Получает текстуры игрока **EnoTiK** с версии authlib 1.5.17 (версия Minecraft 1.8).
+
+Вспомогательные адреса запросов
+===============================
+
+Кроме того, во 2 версии протокола системы скинов определены несколько специальных URL, которые проксируют трафик внутрь
+основных запросов, перечисленных выше.
+
+Ник как GET параметр
+~~~~~~~~~~~~~~~~~~~~
+
+Эти URL, в отличие от основных запросов, позволяют передать ник игрока в качестве одного из GET параметров. Такие запросы
+полезены для версии Minecraft 1.5.2 и ниже, когда внутри кода игры не использовалась подстановка %s для ника, а производилась
+простая конкатенация строк. Таким образом можно передать все необходимые GET параметры, указав ник последним.
+
+.. function:: /skins/?name={nickname}.png
+
+   Тот же запрос на скин. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить.
+
+.. function:: /cloaks/?name={nickname}.png
+
+   Тот же запрос на плащ. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить.
+
+Примеры запросов:
+"""""""""""""""""
+
+.. code-block:: http
+
+   http://skinsystem.ely.by/skins/?version=2&minecraft_version=1.5.2&name=erickskrauch.png
+
+Получает скин игрока **erickskrauch** с версии Minecraft 1.5.2.
+
+.. code-block:: http
+
+   http://skinsystem.ely.by/cloaks/?version=2&minecraft_version=1.4.7&name=notch
+
+Получает плащ игрока **notch** с версии Minecraft 1.4.7. Обратите внимание, что расширение ".png" не передано.
+
+Старый формат запроса
+~~~~~~~~~~~~~~~~~~~~~
+
+В 1 версии протокола системы скинов применялся другой способ загрузки скинов. Все запросы шли по URL
+**http://ely.by/minecraft.php** и все данные передавались через GET параметры.
+
+На данный момент любой запрос, выполненный на вышеуказанный URL приведёт к 301 редиректу на
+**http://skinsystem.ely.by/minecraft.php**, где запрос будет проксирован на основные запросы.
+
+Этот запрос является fallback роутом, применяемым для обратной совместимости с 1 версией и не рекомендуется для
+использования в новых проектах. Тем не менее, он должен быть описан, так как применятся и будет достаточно долго применяться
+в связи с долгосрочным переходом на 2 версию протокола системы скинов.
+
+1 версия системы скинов (deprecated)
+====================================
+
+.. warning:: Информация в этом разделе является устаревшей и приведена здесь только ради создания иллюзии крутого развития
+             проекта. В любом случае вы **не должны** использовать этот протокол, т.к. в один момент он окончательно перестанет
+             работать.
+
+На старте проекта применялся URL для загрузки скинов **http://ely.by/minecraft.php**, в который через GET параметры
+передавались данные. Сейчас этот URL является устаревшим и планомерно выводится из обращения в пользу 2 версии протокола.
+
+.. function:: /minecraft.php
+
+   Параметры, передаваемые в этот запрос:
+
+   :name: Имя игрока без учёта регистра и без расширения **.png**.
+
+   :type: Тип запрашиваемых данных. Возможные значения: skin и cloack. Изначально была допущена ошибка, из-за которой
+          запрос на плащи шёл с значением cloack, вместо cloak. Увы, это так и останется в истории проекта.
+
+   :mine_ver: Версия Minecraft. Точки в версии должны были быть заменены на прочерки, т.е. 1.7.2 должно было быть передано
+              как 1_7_2. Хотя могло работать и с точками :)
+
+   :ver: Версия протокола. Обычно передавалось значение 1_0_0, которое, в принципе, ни на что не влияло, но тем не менее
+         передавалось. Сейчас применяется для идентификации запроса, проксируемого с 1 версии во 2.