Вложенный модуль box.error

Подмодуль box.error можно использовать для работы с ошибками в приложении. Например, можно получить информацию о последней ошибке, возникшей в Tarantool, или вызывать пользовательские ошибки вручную.

Отличие вызова ошибки с помощью box.error от встроенной функции Lua error заключается в том, что при достижении ошибки клиентом её код сохраняется. В то же время ошибка Lua всегда передаётся клиенту как ER_PROC_LUA.

Создать объект ошибки можно с помощью функции box.error.new(). Созданный объект можно передать в box.error() для вызова ошибки. Также ошибку можно вызвать с помощью error_object:raise().

В примере ниже показано, как создать и вызвать ошибку с заданным кодом и причиной.

 
local custom_error = box.error.new({ code = 500,                                     reason = 'Internal server error' })box.error(custom_error)--[[---- error: Internal server error...--]]

Функция box.error.new() предоставляет различные перегрузки для создания объекта ошибки с разными параметрами. Эти перегрузки аналогичны перегрузкам box.error(), описанным в следующем разделе.

Чтобы вызвать ошибку, используйте функцию box.error(). Эта функция может принимать заданные параметры ошибки или объект ошибки, созданный с помощью box.error.new(). В обоих случаях с помощью box.error() можно вызвать следующие типы ошибок:

• Пользовательская ошибка с заданной причиной, кодом и типом.
• Предопределённая ошибка Tarantool.

Для вызова пользовательской ошибки доступны следующие перегрузки box.error():

• box.error({ reason = string[, code = number, type = string] }) принимает Lua-таблицу, содержащую причину, код и тип ошибки.

• box.error(type, reason[, args]) принимает тип ошибки, её причину и необязательные аргументы, передаваемые в строку причины.

В примере ниже box.error() принимает Lua-таблицу с заданным кодом ошибки и причиной:

 
box.error { code = 500,            reason = 'Custom server error' }--[[---- error: Custom server error...--]]

В следующем примере показано, как задать пользовательский тип ошибки:

 
box.error { code = 500,            reason = 'Internal server error',            type = 'CustomInternalError' }--[[---- error: Internal server error...--]]

Если указан пользовательский тип, он возвращается в атрибуте error_object.type. Если тип не указан, error_object.type возвращает один из встроенных типов ошибок, например ClientError или OutOfMemory.

В этом примере показано, как вызвать ошибку с типом и причиной, заданными в аргументах box.error():

 
box.error('CustomConnectionError', 'cannot connect to the given port')--[[---- error: cannot connect to the given port...--]]

Для составления причины ошибки также можно использовать строку форматирования:

 
box.error('CustomConnectionError', '%s cannot connect to the port %u', 'client', 8080)--[[---- error: client cannot connect to the port 8080...--]]

Перегрузка box.error(code[, ...]) вызывает предопределённую ошибку Tarantool, заданную её идентификатором. Код ошибки определяет формат сообщения и количество обязательных аргументов. В примере ниже для кода ошибки box.error.READONLY аргументы не передаются:

 
box.error(box.error.READONLY)--[[---- error: Can't modify data on a read-only instance...--]]

Для кода ошибки box.error.NO_SUCH_USER необходимо передать один аргумент:

 
box.error(box.error.NO_SUCH_USER, 'John')--[[---- error: User 'John' is not found...--]]

box.error.CREATE_SPACE требует два аргумента:

 
box.error(box.error.CREATE_SPACE, 'my_space', 'the space already exists')--[[---- error: 'Failed to create space ''my_space'': the space already exists'...--]]

Чтобы получить последнюю возникшую ошибку, вызовите box.error.last():

 
box.error.last()--[[---- error: Internal server error...--]]

Чтобы получить сведения об ошибке, вызовите error_object.unpack(). Сведения об ошибке могут включать код, тип, сообщение и трассировку.

 
box.error.last():unpack()--[[---- code: 500  base_type: CustomError  type: CustomInternalError  custom_type: CustomInternalError  message: Internal server error  trace:  - file: '[string "custom_error = box.error.new({ code = 500,..."]'    line: 1...--]]

Установить последнюю ошибку явно можно с помощью box.error.set():

 
-- Create two errors --local error1 = box.error.new({ code = 500, reason = 'Custom error 1' })local error2 = box.error.new({ code = 505, reason = 'Custom error 2' })-- Raise the first error --box.error(error1)--[[---- error: Custom error 1...--]]-- Get the last error --box.error.last()--[[---- Custom error 1...--]]-- Set the second error as the last error --box.error.set(error2)--[[---...--]]-- Get the last error --box.error.last()--[[---- Custom error 2...--]]

В error_object предусмотрен API для организации ошибок в списки. Чтобы задать и получить предыдущую ошибку, используйте метод error_object:set_prev() и атрибут error_object.prev.

 
local base_server_error = box.error.new({ code = 500,                                          reason = 'Base server error',                                          type = 'BaseServerError' })local storage_server_error = box.error.new({ code = 507,                                             reason = 'Not enough storage',                                             type = 'StorageServerError' })base_server_error:set_prev(storage_server_error)--[[---...--]]box.error(base_server_error)--[[---- error: Base server error...--]]box.error.last().prev:unpack()--[[---- code: 507  base_type: CustomError  type: StorageServerError  custom_type: StorageServerError  message: Not enough storage  trace:  - file: '[string "storage_server_error = box.error.new({ code =..."]'    line: 1...--]]

В списках ошибок циклы не допускаются:

 
storage_server_error:set_prev(base_server_error)--[[---- error: 'builtin/error.lua:120: Cycles are not allowed'...--]]

Установка предыдущей ошибки не удаляет её собственные предыдущие элементы:

 
-- e1 -> e2 -> e3 -> e4e1:set_prev(e2)e2:set_prev(e3)e3:set_prev(e4)e2:set_prev(e5)-- Now there are two lists: e1 -> e2 -> e5 and e3 -> e4

IPROTO также поддерживает многоуровневую диагностику. Подробнее см. в Расширения MessagePack – тип ERROR.

Чтобы очистить ошибки, вызовите box.error.clear().

 
box.error.clear()--[[---...--]]box.error.last()--[[---- null...--]]

Ниже приведён список функций box.error и связанных объектов.