Запросы и ответы клиент-сервер

В этом разделе описаны клиентские запросы, их аргументы и значения, возвращаемые сервером.

Некоторые запросы описаны на отдельных страницах. Это запросы, связанные с:

• потоковыми транзакциями
• асинхронными уведомлениями сервер-клиент
• репликацией
• SQL – IPROTO_EXECUTE и IPROTO_PREPARE.

Код: 0x00.

Этот тип запроса/ответа содержится в заголовке и означает успешное выполнение. Пример:

Код: 0x80.

Если ответ является внеполосным из-за использования box.session.push(), то IPROTO_REQUEST_TYPE принимает значение IPROTO_CHUNK вместо IPROTO_OK.

Код: 0x8XXX (см. ниже).

Вместо IPROTO_OK заголовок ответа с ошибкой содержит 0x8XXX в IPROTO_REQUEST_TYPE. XXX – код ошибки, значение из src/box/errcode.h. В src/box/errcode.h также определены вспомогательные макросы, задающие шестнадцатеричные константы для кодов возврата.

Подробнее об ответах с ошибками см. в разделе Формат запросов и ответов.

Начиная с версии 2.11.0.

Код: -1.

Неизвестный тип запроса. Константа используется для переопределения обработчика неизвестных типов IPROTO-запросов. Подробнее: box.iproto.override() и box_iproto_override.

Код: 0x01.

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

Если ID tspace равен 512 и это пятое сообщение, {conn}.``space.tspace:select({0},{iterator='GT',offset=1,limit=2}) приведёт к следующему пакету запроса:

В примерах можно найти фактические байтовые коды сообщения IPROTO_SELECT.

Код: 0x02.

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

Например, если запрос – INSERT INTO {table-name} VALUES (1), (2), (3), то тело ответа содержит карту IPROTO_SQL_INFO с SQL_INFO_ROW_COUNT = 3. SQL_INFO_ROW_COUNT может быть равно 0 для операторов, не изменяющих строки, но может быть равно 1 для операторов, создающих новые объекты.

Если ID tspace равен 512 и это пятое сообщение, {conn}.``space.tspace:insert{1, 'AAA'} приведёт к следующим пакетам запроса и ответа:

В руководстве Понимание бинарного протокола показаны фактические байтовые коды ответа на сообщение IPROTO_INSERT.

Код: 0x03.

См. space_object:replace(). Тело представляет собой карту из 2 элементов, как и для IPROTO_INSERT:

Код: 0x04.

См. space_object:update().

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

Если операция не задаёт значений, то IPROTO_TUPLE представляет собой массив из 2 элементов:

Обычно номера полей начинаются с 1.

Если операция задаёт одно значение, то IPROTO_TUPLE представляет собой массив из 3 элементов:

В остальных случаях IPROTO_TUPLE представляет собой массив из 5 элементов:

Если ID tspace равен 512 и это пятое сообщение, {conn}.``space.tspace:update(999, {{'=', 2, 'B'}}) приведёт к следующему пакету запроса:

Элемент карты IPROTO_INDEX_BASE является необязательным.

В руководстве Понимание бинарного протокола показаны фактические байтовые коды сообщения IPROTO_UPDATE.

Код: 0x09.

См. space_object:upsert().

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

IPROTO_OPS – массив операций. Он аналогичен IPROTO_TUPLE для IPROTO_UPDATE.

IPROTO_TUPLE – массив значений полей первичного ключа.

Код: 0x05.

См. space_object:delete(). Тело представляет собой карту из 3 элементов:

Код: 0x08.

См. conn:eval(). Поскольку аргументом является Lua-выражение, таким образом Tarantool обрабатывает небинарные запросы через бинарный протокол. Любой запрос, не имеющий собственного кода, например box.space.{space-name}:drop(), будет обработан либо через IPROTO_CALL, либо через IPROTO_EVAL.

Административная утилита tt активно использует eval.

Тело представляет собой карту из 2 элементов:

• Для IPROTO_EVAL и IPROTO_CALL тело ответа обычно представляет собой массив, но поскольку Lua-запросы могут возвращать самые разные структуры, тела ответов также могут иметь самые разные структуры.

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

Код: 0x0a.

См. conn:call(). Это удалённый вызов хранимой процедуры. В /release/1.6 и более ранних версиях использовался запрос IPROTO_CALL_16 (код: 0x06). Сейчас он устарел и заменён на IPROTO_CALL.

Тело представляет собой карту из 2 элементов. Ответ будет списком значений, аналогичным ответу IPROTO_EVAL. Возвращаемое значение conn:call – это то, что возвращает функция.

Код: 0x07.

Общие сведения см. в разделе Пользователи руководства администратора.

Подробнее о том, как аутентификация работает в бинарном протоколе, см. в разделе Аутентификация этого документа.

Клиент отправляет пакет аутентификации как сообщение IPROTO_AUTH:

IPROTO_USERNAME содержит имя пользователя. IPROTO_TUPLE должен быть массивом из 2 полей: механизм аутентификации и шифр (scramble), зашифрованный в соответствии с указанным механизмом.

Экземпляр сервера отвечает на пакет аутентификации стандартным ответом с 0 кортежей.

То, как Tarantool это обрабатывает, см. в net_box.c, функция netbox_encode_auth.

Код: 0x0c.

Не существует Lua-запроса, полностью эквивалентного IPROTO_NOP. Он приводит к увеличению LSN. Может использоваться для обновлений, в которых старые и новые значения совпадают, но LSN необходимо увеличить, так как изменение данных должно быть зафиксировано. Тело: отсутствует.

Начиная с версии 3.3.0.

Код: 0x11 Тело представляет собой карту из 2 элементов:

Код: 0x40.

См. conn:ping(). Тело будет пустой картой, так как IPROTO_PING в заголовке содержит всю информацию, необходимую экземпляру сервера.

Код: 0x49.

Клиенты отправляют это сообщение, чтобы сообщить серверу о версии протокола и поддерживаемых возможностях. На основе этой информации сервер может включать или отключать определённые возможности при взаимодействии с этими клиентами.

Тело представляет собой карту из 2 элементов:

Тело ответа имеет ту же структуру, что и тело запроса. Оно сообщает клиенту о версии протокола, возможностях, поддерживаемых сервером, и протоколе, используемом для генерации данных аутентификации пользователя.

Запросы IPROTO_ID могут обрабатываться без аутентификации.