doc: KTP protocol

docs/klish3.ru.md

@@ -269,6 +269,88 @@ stderr и отправляется обслуживающему серверу,
 объявлена фильтром, чтобы ее можно было использовать после знака "|".
 
 
+## Протокол KTP
+
+Протокол KTP (Klish Transfer Protocol) используется для взаимодействия клиента
+klish с обслуживающим
+сервером klishd. Основная задача - передача команд и пользовательского ввода
+от клиента - серверу, передача текстового вывода выполненной команды и статуса
+выполнения команды - в обратную сторону. Кроме этого в протоколе предусмотрены
+средства для получения клиентом от сервера вариантов автодополнения для
+незавершенных команд и подсказок для команд и параметров.
+
+Протокол KTP реализован средствами из библиотеки libfaux, которая упрощает
+создание специализированного сетевого протокола на базе шаблона обобщенного
+сетевого протокола. Протокол построен поверх потокового сокета. Сейчас в проекте
+klish используются UNIX-сокеты для взаимодействия клиента и сервера.
+
+Пакет протокола KTP состоит из заголовка фиксированной длины и набора
+"параметров". В специальном поле заголовка хранится количество параметров.
+Каждый параметр имеет свой небольшой заголовок, в котором указан тип параметра и
+его длина. Таким образом в начале KTP пакета расположен KTP заголовок, за ним
+заголовок первого параметра, данные первого параметра, заголовок второго
+параметра, данные второго параметра и т.д. Все поля в заголовках передаются с
+использованием сетевого (big-endian) порядка байт.
+
+KTP заголовок:
+
+|Размер, байт|Название поля                    |Значение поля|
+|------------|---------------------------------|-------------|
+|4           |Magic номер                      |0x4b545020   |
+|1           |Версия протокола (major)         |0x01         |
+|1           |Версия протокола (minor)         |0x00         |
+|2           |Код команды                      |             |
+|4           |Статус                           |             |
+|4           |Не используется                  |             |
+|4           |Количество параметров            |             |
+|4           |Длина всего пакета (с заголовком)|             |
+
+Коды команд:
+
+|Код|Название      |Направление|Описание                                       |
+|---|--------------|-----------|-----------------------------------------------|
+|'i'|STDIN         |->         |stdin пользовательский ввод (PARAM_LINE)       |
+|'o'|STDOUT        |<-         |stdout вывод команды (PARAM_LINE)              |
+|'e'|STDERR        |<-         |stderr вывод команды (PARAM_LINE)              |
+|'c'|CMD           |->         |Команда на выполнение (PARAM_LINE)             |
+|'C'|CMD_ACK       |<-         |Результат выполнения команды                   |
+|'v'|COMPLETION    |->         |Запрос на автодополнение (PARAM_LINE)          |
+|'V'|COMPLETION_ACK|<-         |Возможные дополнения (PARAM_PREFIX, PARAM_LINE)|
+|'h'|HELP          |->         |Запрос подсказки (PARAM_LINE)                  |
+|'H'|HELP_ACK      |<-         |Подсказка (PARAM_PREFIX, PARAM_LINE)           |
+|'n'|NOTIFICATION  |<-         |Асинхронное сообщение (PARAM_LINE)             |
+|'a'|AUTH          |->         |Запрос на аутентификацию                       |
+|'A'|AUTH_ACK      |<-         |Подтверждение аутентификации                   |
+|'I'|STDIN_CLOSE   |->         |stdin был закрыт                               |
+|'O'|STDOUT_CLOSE  |->         |stdout был закрыт                              |
+|'E'|STDERR_CLOSE  |->         |stderr был закрыт                              |
+
+Колонка "Направление" показывает в каком направлении передается команда. Стрелка
+вправо означает передачу от клиента к серверу, стрелка влево - от сервера
+клиенту. В колонке "Описание" в скобках приведены названия параметров, в которых
+передаются данные.
+
+Заголовок параметра:
+
+|Размер, байт|Название поля                         |
+|------------|--------------------------------------|
+|2           |Тип параметра                         |
+|2           |Не используется                       |
+|1           |Длина данных параметра (без заголовка)|
+
+Типы параметров:
+
+|Код|Название     |Направление|Описание                                     |
+|---|-------------|-----------|---------------------------------------------|
+|'L'|PARAM_LINE   |<->        |Строка. Многофункциональна                   |
+|'P'|PARAM_PREFIX |<-         |Строка. Для автодополнения и подсказки       |
+|'$'|PARAM_PROMPT |<-         |Строка. Пользовательское приглашение         |
+|'H'|PARAM_HOTKEY |<-         |Функциональная клавиша и ее значение         |
+|'W'|PARAM_WINCH  |<-         |Размеры пользовательского окна. При изменении|
+|'E'|PARAM_ERROR  |<-         |Строка. Сообщение об ошибке                  |
+|'R'|PARAM_RETCODE|<-         |Код возврата выполненной команды             |
+
+
 ## Структура XML конфигурации
 
 Основным способом описания klish команд на сегодняшний день являются XML файлы.