iproto: Incorrect document structure and ToC

[veod32]

Product: Tarantool
Since: latest
Audience/target: developers
Root document: https://www.tarantool.io/en/doc/latest/dev_guide/internals/box_protocol/
SME: @ sergepetrenko

Details

In the Index section :

• The list of requests doesn't match the number and the order of document sections describing these requests.
• Some internal links in the list are incorrect: starting from IPROTO_JOIN till IPROTO_RREGISTER, they all have the same anchor #box-protocol-join

@ locker says:

Я думаю, что нужны следующие секции:

1. Формат запроса и ответа. Общие положения: используем msgpack, размер запроса передается перед самим запросам, для сопоставления запрос-ответ используем sync number, что такое header/body и т.д. Здесь же можно дать описание и типы ключей header-а запроса.
2. Все типы ключей, используемых для передачи аргументов, с их типами и кратким описанием (например, IPROTO_SPACE_ID - идентификато таблицы, unsigned integer).
3. Секцию со всеми возможными пользовательскими запросами с описанием, что делает, какие аргументы принимает, что возвращает.
4. PUB/SUB - отдельно - тут особый протокол, нужно описать отдельно. Можно ссылку сюда дать из IPROTO_WATCH, IPROTO_UNWATCH из секции с пользовательскими запросами.
5. Стримы. Описать в чем смысл стримов. Дать ссылку сюда из IPROTO_STREAM_ID из секции с типами ключей кргументов.
6. Репликация. Описать кратко все внутренние запросы используемые репликацией. Пользователи (разработчики коннекторов) это читать не будут, поэтому лучше в отдельной секции.
   Про SQL и вызов функций писать не вижу особого смысла - это лучше добавить в описание запроса (IPROTO_CALL, IPROTO_EXECUTE).

[patiencedaur]

Binary protocol doc structure-2.pdf