Skip to content

iproto: Incorrect document structure and ToC #2526

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
Tracked by #2646
veod32 opened this issue Dec 29, 2021 · 1 comment · Fixed by #3151
Closed
Tracked by #2646

iproto: Incorrect document structure and ToC #2526

veod32 opened this issue Dec 29, 2021 · 1 comment · Fixed by #3151
Assignees
@patiencedaur
Labels
iproto Related to the iproto protocol rewrite [nature] Revise existing text for structure/phrasing/terms server [area] Task relates to Tarantool's server (core) functionality

Comments

@veod32
Copy link
Collaborator

veod32 commented Dec 29, 2021 •
edited by patiencedaur
Loading

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).
@veod32 veod32 added server [area] Task relates to Tarantool's server (core) functionality iproto Related to the iproto protocol rewrite [nature] Revise existing text for structure/phrasing/terms labels Dec 29, 2021
@veod32 veod32 modified the milestones: error, iproto Dec 29, 2021
@patiencedaur patiencedaur mentioned this issue Feb 1, 2022
Open
26 tasks
@patiencedaur patiencedaur removed this from the iproto milestone Feb 1, 2022
@patiencedaur patiencedaur changed the title [3pt] iproto: Incorrect document structure and ToC iproto: Incorrect document structure and ToC Aug 16, 2022
@patiencedaur patiencedaur added 8sp and removed 3sp labels Aug 16, 2022
@patiencedaur patiencedaur self-assigned this Sep 14, 2022
@patiencedaur patiencedaur mentioned this issue Sep 16, 2022
Merged
@patiencedaur
Copy link
Contributor

Binary protocol doc structure-2.pdf

@patiencedaur patiencedaur mentioned this issue Oct 4, 2022
Closed
10 tasks
@veod32 veod32 added 3sp and removed 8sp labels Oct 12, 2022
patiencedaur added a commit that referenced this issue Nov 3, 2022
@patiencedaur @xuniq @sergepetrenko
Rewrite iproto protocol description (#3151)
179adca 
Resolves #1662
Resolves #2422
Resolves #2442
Resolves #2467
Resolves #2526
Part of #2416

* Split the Binary protocol page into several sections
* Move examples to How-to
* Correct the description of the greeting
  Resolves #2467
* Elaborate on IPROTO_OPS and the different uses of IPROTO_TUPLE
* Provide missing info on keys
* Clarify Replication items in terms of whether they are a request,
  response, map, key, etc. Groom the structure accordingly
* Add PROMOTE and DEMOTE descriptions
* Bring all SQL-related info into one document
* Clarify that IPROTO_REQUEST_TYPE is used in requests and responses alike
* Improve formatting
* Add tables for uniformity
* Add UML diagram illustrations in the SVG format

Co-authored-by: Kseniia Antonova <[email protected]>
Co-authored-by: Serge Petrenko <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@patiencedaur patiencedaur

Labels
iproto Related to the iproto protocol rewrite [nature] Revise existing text for structure/phrasing/terms server [area] Task relates to Tarantool's server (core) functionality
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Rewrite iproto protocol description tarantool/doc
2 participants
@patiencedaur @veod32