diff --git a/doc/code_snippets/test/errors/error_list_test.lua b/doc/code_snippets/test/errors/error_list_test.lua new file mode 100644 index 0000000000..474561d26a --- /dev/null +++ b/doc/code_snippets/test/errors/error_list_test.lua @@ -0,0 +1,47 @@ +local status, err = pcall(function() + -- snippet_start + 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 + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'BaseServerError') + luatest.assert_equals(err:unpack().message, 'Base server error') + luatest.assert_equals(err.prev:unpack().type, 'StorageServerError') + luatest.assert_equals(err.prev:unpack().message, 'Not enough storage') +end diff --git a/doc/code_snippets/test/errors/raise_error_array_custom_type_args_test.lua b/doc/code_snippets/test/errors/raise_error_array_custom_type_args_test.lua new file mode 100644 index 0000000000..dbed30cde4 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_error_array_custom_type_args_test.lua @@ -0,0 +1,18 @@ +local status, err = pcall(function() + -- snippet_start + box.error('CustomConnectionError', '%s cannot connect to the port %u', 'client', 8080) + --[[ + --- + - error: client cannot connect to the port 8080 + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'CustomConnectionError') + luatest.assert_equals(err:unpack().message, 'client cannot connect to the port 8080') +end diff --git a/doc/code_snippets/test/errors/raise_error_array_custom_type_test.lua b/doc/code_snippets/test/errors/raise_error_array_custom_type_test.lua new file mode 100644 index 0000000000..8723a60b30 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_error_array_custom_type_test.lua @@ -0,0 +1,18 @@ +local status, err = pcall(function() + -- snippet_start + box.error('CustomConnectionError', 'cannot connect to the given port') + --[[ + --- + - error: cannot connect to the given port + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'CustomConnectionError') + luatest.assert_equals(err:unpack().message, 'cannot connect to the given port') +end diff --git a/doc/code_snippets/test/errors/raise_error_table_custom_type_test.lua b/doc/code_snippets/test/errors/raise_error_table_custom_type_test.lua new file mode 100644 index 0000000000..d8a9181433 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_error_table_custom_type_test.lua @@ -0,0 +1,20 @@ +local status, err = pcall(function() + -- snippet_start + box.error { code = 500, + reason = 'Internal server error', + type = 'CustomInternalError' } + --[[ + --- + - error: Internal server error + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'CustomInternalError') + luatest.assert_equals(err:unpack().message, 'Internal server error') +end diff --git a/doc/code_snippets/test/errors/raise_error_table_test.lua b/doc/code_snippets/test/errors/raise_error_table_test.lua new file mode 100644 index 0000000000..64d2cd10c3 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_error_table_test.lua @@ -0,0 +1,17 @@ +local status, err = pcall(function() + -- snippet_start + box.error { code = 500, reason = 'Custom server error' } + --[[ + --- + - error: Custom server error + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().message, 'Custom server error') +end diff --git a/doc/code_snippets/test/errors/raise_new_error_array_custom_type_test.lua b/doc/code_snippets/test/errors/raise_new_error_array_custom_type_test.lua new file mode 100644 index 0000000000..2f2646e6a6 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_new_error_array_custom_type_test.lua @@ -0,0 +1,18 @@ +local status, err = pcall(function() + local custom_error = box.error.new('CustomInternalError', 'Internal server error') + + box.error(custom_error) + --[[ + --- + - error: Internal server error + ... + --]] +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'CustomInternalError') + luatest.assert_equals(err:unpack().message, 'Internal server error') +end diff --git a/doc/code_snippets/test/errors/raise_new_error_table_custom_type_test.lua b/doc/code_snippets/test/errors/raise_new_error_table_custom_type_test.lua new file mode 100644 index 0000000000..a323b5c979 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_new_error_table_custom_type_test.lua @@ -0,0 +1,20 @@ +local status, err = pcall(function() + local custom_error = box.error.new({ code = 500, + reason = 'Internal server error', + type = 'CustomInternalError' }) + + box.error(custom_error) + --[[ + --- + - error: Internal server error + ... + --]] +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'CustomInternalError') + luatest.assert_equals(err:unpack().message, 'Internal server error') +end diff --git a/doc/code_snippets/test/errors/raise_new_error_table_test.lua b/doc/code_snippets/test/errors/raise_new_error_table_test.lua new file mode 100644 index 0000000000..7ffb02b8bb --- /dev/null +++ b/doc/code_snippets/test/errors/raise_new_error_table_test.lua @@ -0,0 +1,19 @@ +local status, err = pcall(function() + local custom_error = box.error.new({ code = 500, + reason = 'Internal server error' }) + + box.error(custom_error) + --[[ + --- + - error: Internal server error + ... + --]] +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'ClientError') + luatest.assert_equals(err:unpack().message, 'Internal server error') +end diff --git a/doc/code_snippets/test/errors/raise_new_tarantool_error_multiple_arg_test.lua b/doc/code_snippets/test/errors/raise_new_tarantool_error_multiple_arg_test.lua new file mode 100644 index 0000000000..a056312f61 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_new_tarantool_error_multiple_arg_test.lua @@ -0,0 +1,17 @@ +local status, err = pcall(function() + local custom_error = box.error.new(box.error.CREATE_SPACE, 'my_space', 'the space already exists') + + box.error(custom_error) + --[[ + --- + - error: 'Failed to create space ''my_space'': the space already exists' + ... + --]] +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_tarantool_error_is_raised = function() + luatest.assert_equals(err:unpack().message, "Failed to create space 'my_space': the space already exists") +end diff --git a/doc/code_snippets/test/errors/raise_new_tarantool_error_one_arg_test.lua b/doc/code_snippets/test/errors/raise_new_tarantool_error_one_arg_test.lua new file mode 100644 index 0000000000..2b03e75e87 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_new_tarantool_error_one_arg_test.lua @@ -0,0 +1,17 @@ +local status, err = pcall(function() + local custom_error = box.error.new(box.error.NO_SUCH_USER, 'John') + + box.error(custom_error) + --[[ + --- + - error: User 'John' is not found + ... + --]] +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_tarantool_error_is_raised = function() + luatest.assert_equals(err:unpack().message, "User 'John' is not found") +end diff --git a/doc/code_snippets/test/errors/raise_tarantool_error_multiple_arg_test.lua b/doc/code_snippets/test/errors/raise_tarantool_error_multiple_arg_test.lua new file mode 100644 index 0000000000..fd04684337 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_tarantool_error_multiple_arg_test.lua @@ -0,0 +1,17 @@ +local status, err = pcall(function() + -- snippet_start + box.error(box.error.CREATE_SPACE, 'my_space', 'the space already exists') + --[[ + --- + - error: 'Failed to create space ''my_space'': the space already exists' + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_tarantool_error_is_raised = function() + luatest.assert_equals(err:unpack().message, "Failed to create space 'my_space': the space already exists") +end diff --git a/doc/code_snippets/test/errors/raise_tarantool_error_no_arg_test.lua b/doc/code_snippets/test/errors/raise_tarantool_error_no_arg_test.lua new file mode 100644 index 0000000000..4c1cfd6324 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_tarantool_error_no_arg_test.lua @@ -0,0 +1,17 @@ +local status, err = pcall(function() + -- snippet_start + box.error(box.error.READONLY) + --[[ + --- + - error: Can't modify data on a read-only instance + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_tarantool_error_is_raised = function() + luatest.assert_equals(err:unpack().message, "Can't modify data on a read-only instance") +end diff --git a/doc/code_snippets/test/errors/raise_tarantool_error_one_arg_test.lua b/doc/code_snippets/test/errors/raise_tarantool_error_one_arg_test.lua new file mode 100644 index 0000000000..6bb3d769bc --- /dev/null +++ b/doc/code_snippets/test/errors/raise_tarantool_error_one_arg_test.lua @@ -0,0 +1,17 @@ +local status, err = pcall(function() + -- snippet_start + box.error(box.error.NO_SUCH_USER, 'John') + --[[ + --- + - error: User 'John' is not found + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_tarantool_error_is_raised = function() + luatest.assert_equals(err:unpack().message, "User 'John' is not found") +end diff --git a/doc/code_snippets/test/errors/set_error_test.lua b/doc/code_snippets/test/errors/set_error_test.lua new file mode 100644 index 0000000000..1b341a72ef --- /dev/null +++ b/doc/code_snippets/test/errors/set_error_test.lua @@ -0,0 +1,45 @@ +local status, err = pcall(function() + -- snippet_start + -- 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 + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().message, 'Custom error 1') +end diff --git a/doc/code_snippets/test/errors/unpack_clear_error_test.lua b/doc/code_snippets/test/errors/unpack_clear_error_test.lua new file mode 100644 index 0000000000..06e0c2ae7c --- /dev/null +++ b/doc/code_snippets/test/errors/unpack_clear_error_test.lua @@ -0,0 +1,63 @@ +local status, err = pcall(function() + -- Create an error: start + local custom_error = box.error.new({ code = 500, + reason = 'Internal server error', + type = 'CustomInternalError' }) + -- Create an error: end + + -- Raise the error: start + box.error(custom_error) + --[[ + --- + - error: Internal server error + ... + --]] + -- Raise the error: end + + -- Get the last error: start + box.error.last() + --[[ + --- + - error: Internal server error + ... + --]] + -- Get the last error: end + + -- Get error details: start + 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 + ... + --]] + -- Get error details: end + + -- Clear the errors: start + box.error.clear() + --[[ + --- + ... + --]] + box.error.last() + --[[ + --- + - null + ... + --]] + -- Clear the errors: end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'CustomInternalError') + luatest.assert_equals(err:unpack().message, 'Internal server error') +end diff --git a/doc/reference/reference_lua/box_error.rst b/doc/reference/reference_lua/box_error.rst index 131662de84..1e7b5f9272 100644 --- a/doc/reference/reference_lua/box_error.rst +++ b/doc/reference/reference_lua/box_error.rst @@ -1,14 +1,205 @@ -------------------------------------------------------------------------------- - Submodule box.error -------------------------------------------------------------------------------- +.. _box-error-submodule: -The ``box.error`` function is for raising an error. The difference between this -function and Lua's built-in `error `_ function +Submodule box.error +=================== + +The ``box.error`` submodule can be used to work with errors in your application. +The difference between raising a error using ``box.error`` +and a Lua's built-in `error `_ function is that when the error reaches the client, its error code is preserved. In contrast, a Lua error would always be presented to the client as :errcode:`ER_PROC_LUA`. -Below is a list of all ``box.error`` functions. + +.. _box_error_create_error: + +(Optional) Create an error +-------------------------- + +Call :ref:`box.error.new() `. + +.. _box_error_raise_error: + +Raise an error +-------------- +Call :ref:`box.error() `. +For :ref:`new errors `, you can also call ``error.raise``. + +* Custom error (reason, type, format string). +* Tarantool predefined error. + + +.. _box_error_raise_custom_error: + +Custom error +~~~~~~~~~~~~ + +``box.error()`` accepts two sets of arguments: + +* error code, reason, and type: ``box.error({code = num, reason = string[, type = string]})`` +* error type, reason, and optional arguments: ``box.error(type, reason[, args])`` + +.. NOTE:: + + The same overloads are available for :ref:`box.error.new() `. + + +.. _box_error_raise_custom_table_error: + +box.error({ code = number[, ...]}) +********************************** + + +Code + reason: + +.. literalinclude:: /code_snippets/test/errors/raise_error_table_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +Custom type: + +.. literalinclude:: /code_snippets/test/errors/raise_error_table_custom_type_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +.. _box_error_raise_custom_array_error: + +box.error(type, reason[, ...]) +****************************** + +Custom type + reason: + +.. literalinclude:: /code_snippets/test/errors/raise_error_array_custom_type_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +Custom type + reason + arguments: + +.. literalinclude:: /code_snippets/test/errors/raise_error_array_custom_type_args_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + + + +.. _box_error_raise_tarantool_error: + +Tarantool error +~~~~~~~~~~~~~~~ + +``box.error(code,[ args]) (zero, one, two, and more)`` + +code determines the format of the error message + +no arguments: + +.. literalinclude:: /code_snippets/test/errors/raise_tarantool_error_no_arg_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + + + +array Tarantool (code + arg): + +.. literalinclude:: /code_snippets/test/errors/raise_tarantool_error_one_arg_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +array Tarantool (code + multiple args): + +.. literalinclude:: /code_snippets/test/errors/raise_tarantool_error_multiple_arg_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + + + + +.. _box_error_get_last_error: + +Get the last error +------------------ + +Call :ref:`box.error.last() `: + +.. literalinclude:: /code_snippets/test/errors/unpack_clear_error_test.lua + :language: lua + :start-after: Get the last error: start + :end-before: Get the last error: end + :dedent: + +.. _box_error_get_error_details: + +Get error details +----------------- + +Call ``unpack`` to get an error details: code, type, message, trace. + +.. literalinclude:: /code_snippets/test/errors/unpack_clear_error_test.lua + :language: lua + :start-after: Get error details: start + :end-before: Get error details: end + :dedent: + +.. _box_error_set_last_error: + +Set the last error +------------------ + +Call :ref:`box.error.set() `: + +.. literalinclude:: /code_snippets/test/errors/set_error_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +.. _box_error_error_lists: + +Error lists +----------- + +:ref:`set_prev `, :ref:`prev `: + +.. literalinclude:: /code_snippets/test/errors/error_list_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +.. _box_error_clear_errors: + +Clear errors +------------ + +Call :ref:`box.error.clear() `: + +.. literalinclude:: /code_snippets/test/errors/unpack_clear_error_test.lua + :language: lua + :start-after: Clear the errors: start + :end-before: Clear the errors: end + :dedent: + + + +.. _box-error-submodule-api-reference: + +API Reference +------------- + +Below is a list of ``box.error`` functions and related objects. .. container:: table diff --git a/doc/reference/reference_lua/box_error/error.rst b/doc/reference/reference_lua/box_error/error.rst index 904e19c6d7..4be1c0e14d 100644 --- a/doc/reference/reference_lua/box_error/error.rst +++ b/doc/reference/reference_lua/box_error/error.rst @@ -21,7 +21,7 @@ box.error() Throw an error. This method emulates a request error, with text based on one of the pre-defined Tarantool errors defined in the file `errcode.h - `_ in + `_ in the source tree. Lua constants which correspond to those Tarantool errors are defined as members of ``box.error``, for example ``box.error.NO_SUCH_USER == 45``. diff --git a/doc/reference/reference_lua/checks.rst b/doc/reference/reference_lua/checks.rst index 20f4f4d5d3..cff7877566 100644 --- a/doc/reference/reference_lua/checks.rst +++ b/doc/reference/reference_lua/checks.rst @@ -1,4 +1,4 @@ -.. checks-module: +.. _checks-module: Module checks ============= diff --git a/doc/reference/reference_lua/errcodes.rst b/doc/reference/reference_lua/errcodes.rst index f92654ab01..7a80388107 100644 --- a/doc/reference/reference_lua/errcodes.rst +++ b/doc/reference/reference_lua/errcodes.rst @@ -9,7 +9,7 @@ more descriptive than error codes, are not present in server responses. The actu message may contain a filename, a detailed reason or operating system error code. All such messages, however, are logged in the error log. Below are general descriptions of some popular codes. A complete list of errors can be found in file -`errcode.h `_ in the source tree. +`errcode.h `_ in the source tree. .. container:: table diff --git a/locale/ru/LC_MESSAGES/reference/reference_lua/box_error/error.po b/locale/ru/LC_MESSAGES/reference/reference_lua/box_error/error.po index 451734e671..bb69170e82 100644 --- a/locale/ru/LC_MESSAGES/reference/reference_lua/box_error/error.po +++ b/locale/ru/LC_MESSAGES/reference/reference_lua/box_error/error.po @@ -29,14 +29,14 @@ msgstr "(целое число) числовой код ошибки, задае msgid "" "Throw an error. This method emulates a request error, with text based on one" " of the pre-defined Tarantool errors defined in the file `errcode.h " -"`_ in the" +"`_ in the" " source tree. Lua constants which correspond to those Tarantool errors are " "defined as members of ``box.error``, for example ``box.error.NO_SUCH_USER ==" " 45``." msgstr "" "Выдача ошибки. Моделирование ошибки запроса с текстом на основе одной из " "ошибок Tarantool, заданных в файле `errcode.h " -"`_ в " +"`_ в " "исходном дереве. Lua-постоянные, которые соответствуют этим ошибкам в " "Tarantool, определяются как элементы ``box.error``, например " "``box.error.NO_SUCH_USER == 45``."