Submodule box.iproto
Since 2.11.0.
The box.iproto submodule provides the ability to work with the network subsystem of Tarantool.
It allows you to extend the IPROTO functionality from Lua.
With this submodule, you can:
- parse unknown IPROTO request types
- send arbitrary IPROTO packets
- override the behavior of the existing and unknown request types in the binary protocol
The submodule exports all IPROTO constants and features to Lua.
IPROTO constants in the box.iproto namespace are written in uppercase letters without the IPROTO_ prefix.
The constants are divided into several groups:
- key. Example: IPROTO_SYNC.
- request type. Example: IPROTO_OK.
- flag. Example: IPROTO_COMMIT.
- ballot key. Example: IPROTO_FLAG_COMMIT.
- metadata key. Example: IPROTO_FIELD_IS_NULLABLE.
- RAFT key. Example: IPROTO_TERM.
Each group is located in the corresponding subnamespace without the prefix. For example:
box.iproto.key.SYNC = 0x01
-- ...
box.iproto.type.SELECT = 1
-- ...
box.iproto.flag.COMMIT = 1
-- ...
box.iproto.ballot_key.VCLOCK = 2
-- ...
box.iproto.metadata_key.IS_NULLABLE = 3
-- ...
box.iproto.raft_key.TERM = 0
-- ...
The submodule exports:
- the current IPROTO protocol version (box.iproto.protocol_version)
- the set of IPROTO protocol features supported by the server (box.iproto.protocol_features)
- IPROTO protocol features with the corresponding code (box.iproto.feature)
Example
The example converts the feature names from box.iproto.protocol_features set into codes:
-- Features supported by the server
box.iproto.protocol_features = {
streams = true,
transactions = true,
error_extension = true,
watchers = true,
pagination = true,
}
-- Convert the feature names into codes
features = {}
for name in pairs(box.iproto.protocol_features) do
table.insert(features, box.iproto.feature[name])
end
return features -- [0, 1, 2, 3, 4]
Every IPROTO request has a static handler. That is, before version 2.11.0, any unknown request raised an error. Since 2.11.0, a new request type is introduced – IPROTO_UNKNOWN. This type is used to override the handlers of the unknown IPROTO request types. For details, see box.iproto.override() and box_iproto_override functions.
The table lists all available functions and data of the submodule:
| Name | Use |
|---|---|
| box.iproto.key | Request keys |
| box.iproto.type | Request types |
| box.iproto.flag | Flags from the IPROTO_FLAGS key |
| box.iproto.ballot_key | Keys from the IPROTO_BALLOT requests |
| box.iproto.metadata_key | Keys nested in the IPROTO_METADATA key |
| box.iproto.raft | Keys from the IPROTO_RAFT_ requests |
| box.iproto.protocol_version | The current IPROTO protocol version |
| box.iproto.protocol_features | The set of supported IPROTO protocol features |
| box.iproto.feature | IPROTO protocol features |
| box.iproto.override() | Set a new IPROTO request handler callback for the given request type |
| box.iproto.send() | Send an IPROTO packet over the session’s socket |