Fixes gh-2306 New field in binary iproto protocol

[pgulutzan]

@EvgenyMekhanik:
Issue #2306 and issue #2307 and issue #2309 and issue #2310 involve
similar things and only one file, dev_guide/internals/box_protocol.rst.
I believed it was best to handle them together, so this commit is for all.
I am not handling the issues related to net_box.
That is why there is no :ref: link when I mention conn:new_stream().

I like the word "multiplex" but did not use it because the section starts by saying
"request multiplexing, for example ability to issue multiple requests asynchronously via the same connection"
so it could look odd to say we're adding it now.

I did not need to rename IPROTO_PROMOTE or IPROTO_DEMOTE etc. because they are undocumented,
I only needed to rename IPROTO_CONFIRM and IPROTO_ROLLBACK.

I notice in tarantool/tarantool#5860
that one of the objectives is:
"Interactive transactions. Such a transaction doesn’t need to be sent in one request - begin, commit and tx statements are allowed to be sent and executed in different requests."
This would be wonderful and would certainly be worth mentioning -- if it worked.
But I'm still seeing ER_TRANSACTION_YIELD using stream: via net.box with different requests.
Is this unfinished? Or am I misinterpreting that description of the objective?

I have not assigned you as a reviewer, please assign youself if you think it is appropriate.

---

Resolves #2306, #2307, #2309, #2310

[EvgenyMekhanik]

To use transactions over iproto streams you should set 'memtx_use_mvcc_engine = true' on remote server or use vinyl engine.
Simple example of using iproto streams:

conn = net_box.connect("remote server address")
stream = conn:new_stream()
conn_space = conn.space."space_name"
stream_space = stream.space."space_name"
stream:begin()
stream_space :replace({1})
stream_space :select({}) -- [1]
conn_space:select({}) --[] empty transaction was not commited
-- On remote server select is also empty
stream:commit()
conn_space:select({}) -- [1]

More examples in test/box/net.box_iproto_transactions_over_streams.test.lua

[pgulutzan]

Okay, in my second commit, I mentioned the first, with approximately the words that you suggested.

[pgulutzan]

Yes, fixed.

[pgulutzan]

I see that my interleaving example was bad. I changed it so that it mentions only the requests, and avoided predicting what the server will do.

[NickVolynkin]

@EvgenyMekhanik is the new version correct? Can we merge & publish this PR?

[EvgenyMekhanik]

IPROTO_BEGIN used to start transaction, IRPOTO_COMMIT to commit transaction and IPROTO_ROLLBACK used to rollback transaction.
There are multiple ways to start transaction:

1. stream:begin()
2. stream:call('box.begin')
3. stream:eval('box.begin()')
4. stream:execute('START TRANSACTION') -- sql syntax
   There are multiple ways to commit transactions:
5. stream:commit()
6. stream:call('box.commit')
7. stream:eval('box.commit()')
8. stream:execute('COMMIT')
   There are multiple ways to rollback transactions:
9. stream:rollback()
10. stream:call('box.rollback')
11. stream:eval('box.rollback()')
12. stream:execute('ROLLBACK')

[pgulutzan]

Yes, but we won't need to mention all possibilities in the iproto description.

[EvgenyMekhanik]

Here I would write:
"Thus there are now multiple ways to do transactions with net_box:
stream:begin() and stream:commit() or stream:rollback()
which cause IPROTO_BEGIN and IPROTO_COMMIT or IPROTO_ROLLBACK with ..."

But it's up to you

[pgulutzan]

The current sentence has clauses delimited with semicolons
"with net_box and ....;"
"with box.begin() and ...;"
"with SQL and ...".
Changing the initial words to "with net_box:" would make
it appear that the whole sentence is about net_box, but
only the first clause is about net_box.
So I will leave this unchanged, but thanks for the suggestion.

[pgulutzan]

@EvgenyMekhanik, @NickVolynkin: After I did the first commit for this issue, Kseniia Antonova on October 21 with commit 9f10fa0 added a new section for the streams feature, https://www.tarantool.io/en/doc/latest/book/box/stream/#term-interactive-transaction Streams and interactive transactions. It is better than my too-short comments. So I added a :ref: to that section, which will be valid after this second commit is merged.

My comment at the start, about ER_TRANSACTION_YIELD, is solved -- as Evgeny Mekhanik explained, I must use vinyl or memtx/mvcc. But, assuming that others might make the same mistake that I made, I added a short phrase that indicates that is necessary.

Incidentally, when testing, I saw this message:
[ALSOFT] (EE) Failed to set real-time priority for thread: Operation not permitted (1)
I have not noticed this message before. But I assumed that it has nothing to do with streams, so I ignored it.

[patiencedaur]

Suggested change

	:ref:`IPROTO_FLAGS <box_protocol-flags>` + IPROTO_FLAG_COMMIT
	:ref:`IPROTO_FLAGS <box_protocol-flags>` and IPROTO_FLAG_COMMIT

@pgulutzan Just to be clear, does + mean "and" here?

[pgulutzan]

One could say "and", but I prefer "+" and have used it elsewhere in the section.

[NickVolynkin]

@pgulutzan the plus sign is reserved for the algebraic operation of addition and can be understood as such. We don't want to risk confusing our readers. Please use "and", "or", and other suitable words.

[pgulutzan]

@NickVolynkin: See my third commit, as ordered.

[patiencedaur]

Do you mean that byte 34 is IPROTO_BIND_COUNT and byte 00 is MP_UINT? Which one of them equals zero — only MP_UINT or both?

It is not clear how the equals sign works in this case, what parts are code and what are not. Same comment for strings 1663–64. Our translation team has trouble working with these expressions.

Our documentation guidelines provide some information on how to write about code, what is code and what is not.

[pgulutzan]

At the start we say IPROTO_BIND_COUNT is a value i.e. 34
and MP_UINT means unsigned integer i.e. MP_UINT is a type.
At the end we have an illustration:
34 IPROTO_BIND_COUNT
00 MP_INT = 0 = number of parameters to bind
33 IPROTO_BIND_METADATA
90 MP_ARRAY, size 0 = there are no parameters to bind
Incidentally on 2020-08-16 I wrote to E. Shebunyaeva suggesting I could
change occurrences of MP_INT to MP_UINT, but there was no decision.