Skip to content
Snippets Groups Projects
  • Col-Waltz's avatar
    f83fded7
    Introduce protobuf encoder · f83fded7
    Col-Waltz authored
    Introducing lua protobuf encoder.
    Encoder can create a new protocol and encode data according to it.
    As a result a binary string is returned that can be transported
    by wire or decoded back by another protobuf decoder.
    The future versions will add support protocol creation from .proto
    files and decode method for encoded data.
    
    Part of #9844
    
    @TarantoolBot document
    Title: Protobuf module
    Product: Tarantool
    Root document: -
    
    Protobuf encoder API
    
    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:
    
    ```lua
    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:
    
    ```lua
    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:
    
    ```lua
    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:
    
    ```lua
    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.
    
    ```lua
    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.
    f83fded7
    History
    Introduce protobuf encoder
    Col-Waltz authored
    Introducing lua protobuf encoder.
    Encoder can create a new protocol and encode data according to it.
    As a result a binary string is returned that can be transported
    by wire or decoded back by another protobuf decoder.
    The future versions will add support protocol creation from .proto
    files and decode method for encoded data.
    
    Part of #9844
    
    @TarantoolBot document
    Title: Protobuf module
    Product: Tarantool
    Root document: -
    
    Protobuf encoder API
    
    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:
    
    ```lua
    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:
    
    ```lua
    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:
    
    ```lua
    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:
    
    ```lua
    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.
    
    ```lua
    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.