Document Lua helpers for encoding/decoding IPROTO packets

[TarantoolBot]

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 tarantool/tarantool@2258099.