Document Lua helpers for encoding/decoding IPROTO packets

Product: Tarantool
Since: 3.0
Root document:
https://www.tarantool.io/en/doc/latest/reference/reference_lua/box/box_iproto
https://www.tarantool.io/en/doc/latest/dev_guide/internals/box_protocol/
SME: @ locker

Details

The following new constants and functions were added to the box.iproto
namespace:

• GREETING_SIZE: Size of a Tarantool greeting message

• GREETING_PROTOCOL_LEN_MAX: Max length of a protocol string that can
  be encoded in a Tarantool greeting message.

• GREETING_SALT_LEN_MAX: Max length of a salt string that can be
  encoded in a Tarantool greeting message.

• box.iproto.encode_greeting({version = x, uuid = x, salt = x}):
  Encodes a Tarantool greeting message. Takes a table. Returns a
  string. Raises on error. The protocol is set to "Binary" (IPROTO).

• box.iproto.decode_greeting(string): Decodes a Tarantool greeting
  message. Takes a string. Returns a table with the following fields:
  protocol, version, uuid, salt. Raises on error. The input
  string must be exactly GREETING_SIZE bytes long.

• box.iproto.encode_packet(header[, body]): Encodes an IPROTO packet.
  Takes a packet header and optionally a body given as a table or a
  string. A table argument will be encoded in MsgPack. A string
  argument will be copied as is (it's supposed to contain valid MsgPack
  but it isn't enforced). Returns a string. Raises on error.

• box.iproto.decode_packet(string[, pos]): Decodes an IPROTO packet.
  Takes a string containing one or more encoded IPROTO packets and
  optionally a position in the string to start decoding from. If the
  position is omitted, the function will start decoding from the
  beginning of the string. On success returns the decoded packet
  header, body, and the position in the string where decoding stopped.
  Both header and body are returned as msgpack.object. The body may
  be absent (set to nil). If the input is truncated, returns nil and
  the min number of bytes required to decode the packet. On failure,
  raises an error.

For examples, see test/app-luatest/iproto_encoder_test.lua.

Requested by @locker in https://github.com/tarantool/tarantool/commit/22580990e7c029d255fd3705cdc86b81ce97dd14.

Start with the box.iproto reference page and the box protocol internals page linked in the issue, then compare the APIs with test/app-luatest/iproto_encoder_test.lua. Document the listed constants and greeting and packet encoding/decoding functions, including arguments, return values, errors, and truncation behavior; done means the reference covers all listed additions with useful examples.