Client-server requests and responses
This section describes client requests, their arguments, and the values returned by the server.
Some requests are described on separate pages. Those are the requests related to:
- stream transactions
- asynchronous server-client notifications
- replication
- SQL – IPROTO_EXECUTE and IPROTO_PREPARE.
| Name | Code | Description |
|---|---|---|
| IPROTO_OK | 0x00 MP_UINT |
Successful response |
| IPROTO_CHUNK | 0x80 MP_UINT |
Out-of-band response |
| IPROTO_TYPE_ERROR | 0x8XXX MP_INT |
Error response |
| IPROTO_UNKNOWN | -1 MP_UINT |
An unknown request type |
| IPROTO_SELECT | 0x01 | Select request |
| IPROTO_INSERT | 0x02 | Insert request |
| IPROTO_REPLACE | 0x03 | Replace request |
| IPROTO_UPDATE | 0x04 | Update request |
| IPROTO_UPSERT | 0x09 | Upsert request |
| IPROTO_DELETE | 0x05 | Delete request |
| IPROTO_CALL | 0x0a | Function remote call (conn:call()) |
| IPROTO_AUTH | 0x07 | Authentication request |
| IPROTO_EVAL | 0x08 | Evaluate a Lua expression (conn:eval()) |
| IPROTO_NOP | 0x0c | Increment the LSN and do nothing else |
| IPROTO_PING | 0x40 | Ping (conn:ping()) |
| IPROTO_ID | 0x49 | Share iproto version and supported features |
Code: 0x00.
This request/response type is contained in the header and signifies success. Here is an example:
Code: 0x80.
If the response is out-of-band, due to use of box.session.push(), then IPROTO_REQUEST_TYPE is IPROTO_CHUNK instead of IPROTO_OK.
Code: 0x8XXX (see below).
Instead of IPROTO_OK, an error response header
has 0x8XXX for IPROTO_REQUEST_TYPE. XXX is the error code – a value in
src/box/errcode.h.
src/box/errcode.h also has some convenience macros which define hexadecimal
constants for return codes.
To learn more about error responses, check the section Request and response format.
Since 2.11.0.
Code: -1.
An unknown request type. The constant is used to override the handler of unknown IPROTO request types. Learn more: box.iproto.override() and box_iproto_override.
Code: 0x01.
См. space_object:select(). Тело сообщения представляет собой ассоциативный массив из 6 элементов.
Если ID спейса tspace = 512 и это пятое сообщение,
conn.space.tspace:select({0},{iterator='GT',offset=1,limit=2}) вызовет следующий пакет запроса:
Байт-коды сообщения IPROTO_SELECT рассмотрены в разделе Примеры
Code: 0x02.
См. space_object:insert(). Тело сообщения представляет собой ассоциативный массив из 2 элементов:
For example, if the request is
INSERT INTO table-name VALUES (1), (2), (3), then the response body
contains an IPROTO_SQL_INFO map with SQL_INFO_ROW_COUNT = 3.
SQL_INFO_ROW_COUNT can be 0 for statements that do not change rows,
but can be 1 for statements that create new objects.
Если ID спейса tspace = 512 и это пятое сообщение,
conn.space.tspace:insert{1, 'AAA'} вызовет следующие пакеты запроса и ответа:
The tutorial Understanding the binary protocol shows actual byte codes of the response to the IPROTO_INSERT message.
Code: 0x03.
См. space_object:replace(). Тело сообщения представляет собой ассоциативный массив из 2 элементов, как и в случае IPROTO_INSERT:
Code: 0x04.
Тело сообщения обычно представляет собой ассоциативный массив из 4 элементов:
If the operation specifies no values, then IPROTO_TUPLE is a 2-item array:
Normally field numbers start with 1.
If the operation specifies one value, then IPROTO_TUPLE is a 3-item array:
Otherwise IPROTO_TUPLE is a 5-item array:
Если ID спейса tspace = 512 и это пятое сообщение,
conn.space.tspace:update(999, {{'=', 2, 'B'}}) вызовет следующий пакет запроса:
The map item IPROTO_INDEX_BASE is optional.
The tutorial Understanding the binary protocol shows the actual byte codes of an IPROTO_UPDATE message.
Code: 0x09.
Тело сообщения обычно представляет собой ассоциативный массив из 4 элементов:
IPROTO_OPS is the array of operations. It is the same as the IPROTO_TUPLE of IPROTO_UPDATE.
IPROTO_TUPLE is an array of primary-key field values.
Code: 0x05.
См. space_object:delete(). Тело сообщения представляет собой ассоциативный массив из 3 элементов:
Code: 0x08.
See conn:eval().
Since the argument is a Lua expression, this is
Tarantool’s way to handle non-binary with the
binary protocol. Any request that does not have
its own code, for example box.space.space-name:drop(),
will be handled either with IPROTO_CALL
or IPROTO_EVAL.
The tt administrative utility
makes extensive use of eval.
The body is a 2-item map:
- For IPROTO_EVAL and IPROTO_CALL the response body will usually be an array but, since Lua requests can result in a wide variety of structures, bodies can have a wide variety of structures.
Примечание
For SQL-specific responses, the body is a bit different. Learn more about this type of packets.
Code: 0x0a.
See conn:call(). This is a remote stored-procedure call. Tarantool 1.6 and earlier made use of the IPROTO_CALL_16 request (code: 0x06). It is now deprecated and superseded by IPROTO_CALL.
The body is a 2-item map. The response will be a list of values, similar to the IPROTO_EVAL response. The return from conn:call is whatever the function returns.
Примечание
For SQL-specific responses, the body is a bit different. Learn more about this type of packets.
Code: 0x07.
For general information, see the Access control section in the administrator’s guide.
For more on how authentication is handled in the binary protocol, see the Authentication section of this document.
The client sends an authentication packet as an IPROTO_AUTH message:
IPROTO_USERNAME holds the user name. IPROTO_TUPLE must be an array of 2 fields: authentication mechanism and scramble, encrypted according to the specified mechanism.
The server instance responds to an authentication packet with a standard response with 0 tuples.
To see how Tarantool handles this, look at
net_box.c
function netbox_encode_auth.
Code: 0x0c.
Нет такого запроса на Lua, который бы соответствовал IPROTO_NOP. IPROTO_NOP приводит к увеличению LSN. Иногда константу можно использовать для обновления значения, когда старое и новое значения одинаковы, но LSN нужно увеличить, поскольку нужно зарегистрировать изменение данных. Тело сообщения пустое.
Code: 0x40.
См. conn:ping(). В теле сообщения будет пустой ассоциативный массив, потому что IPROTO_PING в заголовке содержит всю информацию, необходимую экземпляру сервера.
Code: 0x49.
Clients send this message to inform the server about the protocol version and features they support. Based on this information, the server can enable or disable certain features in interacting with these clients.
The body is a 2-item map:
The response body has the same structure as the request body. It informs the client about the protocol version, features supported by the server, and a protocol used to generate user authentication data.
IPROTO_ID requests can be processed without authentication.