Client-server requests and responses | Tarantool
Документация на русском языке
поддерживается сообществом

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:

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_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:

Example of IPROTO_OK usageSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT

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.

Code: 0x01.

См. space_object:select(). Тело сообщения представляет собой ассоциативный массив из 6 элементов.

IPROTO_SELECTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_SELECTIPROTO_SYNCMP_UINTBodyIPROTO_SPACE_IDMP_UINTIPROTO_INDEX_IDMP_UINTIPROTO_LIMITMP_UINTIPROTO_OFFSETMP_UINTIPROTO_ITERATORMP_UINTIPROTO_KEYMP_ARRAYResponse to IPROTO_SELECTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT

Если ID спейса „tspace“ = 512 и это пятое сообщение,
conn.space.tspace:select({0},{iterator='GT',offset=1,limit=2}) вызовет:

IPROTO_SELECTexample requestSize21HeaderIPROTO_REQUEST_TYPEIPROTO_SELECTIPROTO_SYNC5BodyIPROTO_SPACE_ID512IPROTO_INDEX_ID0IPROTO_ITERATOR6IPROTO_OFFSET1IPROTO_LIMIT2IPROTO_KEY[1]

Байт-коды сообщения IPROTO_SELECT рассмотрены в разделе Примеры

Code: 0x02.

См. space_object:insert(). Тело сообщения представляет собой ассоциативный массив из 2 элементов:

IPROTO_INSERTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_INSERTIPROTO_SYNCMP_UINTBodyIPROTO_SPACE_IDMP_UINTIPROTO_TUPLEMP_ARRAYResponse to IPROTO_INSERTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_ARRAY of tuples

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.

If the id of „tspace“ is 512 and this is the fifth message,
conn.space.tspace:insert{1, 'AAA'} will produce the following request and response packets:

IPROTO_INSERTexample requestSize17HeaderIPROTO_REQUEST_TYPEIPROTO_INSERTIPROTO_SYNC5BodyIPROTO_SPACE_ID512IPROTO_TUPLE[1, 'AAA']IPROTO_INSERTexample responseSize36HeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNC5IPROTO_SCHEMA_VERSION100BodyIPROTO_DATA[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:

IPROTO_REPLACESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_REPLACEIPROTO_SYNCMP_UINTBodyIPROTO_SPACE_IDMP_UINTIPROTO_TUPLEMP_ARRAY of field valuesResponse to IPROTO_REPLACESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT

Code: 0x04.

См. space_object:update().

Тело сообщения обычно представляет собой ассоциативный массив из 4 элементов:

IPROTO_UPDATESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_UPDATEIPROTO_SYNCMP_UINTBodyIPROTO_SPACE_IDMP_UINTIPROTO_INDEX_IDMP_UINTIPROTO_KEYMP_ARRAY of index keysIPROTO_TUPLEMP_ARRAY of update opsResponse to IPROTO_UPDATESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT

If the operation specifies no values, then IPROTO_TUPLE is a 2-item array:

BodyIPROTO_TUPLEOperatorMP_STR: '#'Field numberMP_INT

Normally field numbers start with 1.

If the operation specifies one value, then IPROTO_TUPLE is a 3-item array:

BodyIPROTO_TUPLEOperatorMP_STR: '+', '-', '^', '|', '!', or '='Field numberMP_INTValueMP_OBJECT

Otherwise IPROTO_TUPLE is a 5-item array:

BodyIPROTO_TUPLEOperatorMP_STR: ':'Field numberMP_INTPositionMP_INTOffsetMP_INTValueMP_STR

Если ID спейса „tspace“ = 512 и это пятое сообщение, br| conn.space.tspace:update(999, {{'=', 2, 'B'}}) вызовет:

IPROTO_UPDATEexample requestSize32HeaderIPROTO_REQUEST_TYPEIPROTO_UPDATEIPROTO_SYNC5BodyIPROTO_SPACE_ID512IPROTO_INDEX_ID0IPROTO_INDEX_BASE1IPROTO_TUPLE['=',2,'B']IPROTO_KEY[999]

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.

См. space_object:upsert().

Тело сообщения обычно представляет собой ассоциативный массив из 4 элементов:

IPROTO_UPSERTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_UPSERTIPROTO_SYNCMP_UINTBodyIPROTO_SPACE_IDMP_UINTIPROTO_INDEX_BASEMP_UINTIPROTO_OPSMP_ARRAYIPROTO_TUPLEMP_ARRAYResponse to IPROTO_UPSERTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT

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 элементов:

IPROTO_DELETESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_DELETEIPROTO_SYNCMP_UINTBodyIPROTO_SPACE_IDMP_UINTIPROTO_INDEX_IDMP_UINTIPROTO_KEYMP_ARRAY of key valuesResponse to IPROTO_DELETESizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT

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 tarantoolctl administrative utility makes extensive use of eval.

The body is a 2-item map:

IPROTO_EVALSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_EVALIPROTO_SYNCMP_UINTBodyIPROTO_EXPRMP_STRIPROTO_TUPLEMP_ARRAY of argumentsResponse to IPROTO_EVALSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT
  • 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.

Если это пятое сообщение, conn:eval('return 5;') приведет к следующему:

IPROTO_EVALexample requestSize24HeaderIPROTO_REQUEST_TYPEIPROTO_EVALIPROTO_SYNCMP_UINTBodyIPROTO_EXPR'return 5;'IPROTO_TUPLE[]

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.

IPROTO_CALLSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_CALLIPROTO_SYNCMP_UINTBodyIPROTO_FUNCTION_NAMEMP_STRIPROTO_TUPLEMP_ARRAY of argumentsResponse to IPROTO_CALLSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_OBJECT

Примечание

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_AUTHSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_AUTHIPROTO_SYNCMP_UINTBodyIPROTO_USER_NAMEMP_STRIPROTO_TUPLEMP_ARRAYAuthentication mechanism,scramble

IPROTO_USERNAME holds the user name. IPROTO_TUPLE must be an array of 2 fields: authentication mechanism («chap-sha1» is the only supported mechanism right now) 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 в заголовке содержит всю информацию, необходимую экземпляру сервера.

IPROTO_PINGSize5HeaderIPROTO_REQUEST_TYPEIPROTO_PINGIPROTO_SYNCMP_UINTBodyMP_MAP, emptyResponse to IPROTO_PINGSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTIPROTO_SCHEMA_VERSIONMP_UINTBodyIPROTO_DATAMP_MAP, empty

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:

IPROTO_IDSizeMP_INTHeaderIPROTO_REQUEST_TYPEIPROTO_IDIPROTO_SYNCMP_UINTBodyIPROTO_VERSIONMP_UINTIPROTO_FEATURESMP_ARRAY of MP_UINT items

The response body has the same structure as the request body. It informs the client about the protocol version and features that the server supports.

IPROTO_ID requests can be processed without authentication.

Нашли ответ на свой вопрос?
Обратная связь