Protobuf module

[TarantoolBot]

Related dev. issue(s): tarantool/tarantool#9844

Product: Tarantool
Since: 3.2
Root document: a new page in https://www.tarantool.io/en/doc/latest/reference/reference_lua/
SME: @ Col-Waltz

Details

Introducing protobuf encoder. All the Protocol Buffers wire types
are supported except group start/end, which are deprecated in proto3.
To encode data you need to create a protocol according to which
data will be encoded.

The two main components of the protocol are messages and enums.
To create them .message and .enum functions are used

Each message consists of name of the message and fields.
Each field has a name, a type and an id. Id must be unique
for all fields in one message. For example this is a message with
six fields:

protobuf.message('KeyValue', {
    key = {'bytes', 1},
    create_revision = {'int64', 2},
    mod_revision = {'int64', 3},
    version = {'int64', 4},
    value = {'bytes', 5},
    lease = {'int64', 6),
})

This implementation supports recursive definition for fields in
message. Depth of recursion is defined by input data because all
fields are optional by default. Example of recursive message:

protobuf.message('Node', {
    number = {'int64', 1},
    data = {'bytes', 2},
    next_node = {'Node', 3},
})

Each enum type consists of name of type and values.
Values must have a zero value to be set as default as in example:

protobuf.enum('EventType', {
    ['PUT'] = 0,
    ['DELETE'] = 1,
})

To create a protocol .protocol function is used. This function
supports forward declared types and nested messages so the tuple
can be set according to example:

schema = protobuf.protocol({
    protobuf.message(<...>),
    protobuf.message(<...>),
    protobuf.enum(<...>),
    protobuf.enum(<...>),
})

Output protocol can then be used for encoding entered data by the
method named encode. This method converts input data
according to chosen message definition from
protobuf protocol into protobuf wireformat. All fields in message
definition are optional so if some input data is missing
it simply will not be encoded. Input data can be
submitted using luatypes or using cdata (for example
entering int64) according to the example.

result = schema:encode(‘KeyValue’,
    {
        key = 'protocol',
        version = 2,
        lease = 5,
    }
)

Output result will be a binary string encoded according to the
protobuf standard and can be transmitted to another user.
Requested by @ Col-Waltz in tarantool/tarantool@f83fded.