api: extra information for iproto errors

Since Tarantool 2.4.1, iproto error responses contain extra info with
backtrace. After this patch, DatabaseError would contain `extra_info`
property, if it was provided.

1. https://www.tarantool.io/en/doc/latest/dev_guide/internals/box_protocol/#responses-for-errors

Part of #323

Author: DifferentialOrange

Diff for: CHANGELOG.md

@@ -136,6 +136,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Support iproto feature discovery (#206).
 - Backport ConnectionPool support for Python 3.6 (#232).
+- Support extra information for iproto errors (#232).
 
 ### Changed
 - Bump msgpack requirement to 1.0.4 (PR #223).

Diff for: doc/api/submodule-types.rst

@@ -0,0 +1,4 @@
+module :py:mod:`tarantool.types`
+================================
+
+.. automodule:: tarantool.types

Diff for: doc/index.rst

@@ -43,6 +43,7 @@ API Reference
    api/submodule-response.rst
    api/submodule-schema.rst
    api/submodule-space.rst
+   api/submodule-types.rst
    api/submodule-utils.rst
 
 .. Indices and tables

Diff for: tarantool/const.py

@@ -27,7 +27,7 @@
 IPROTO_OPS = 0x28
 #
 IPROTO_DATA = 0x30
-IPROTO_ERROR = 0x31
+IPROTO_ERROR_24 = 0x31
 #
 IPROTO_METADATA = 0x32
 IPROTO_SQL_TEXT = 0x40
@@ -36,6 +36,8 @@
 IPROTO_SQL_INFO_ROW_COUNT = 0x00
 IPROTO_SQL_INFO_AUTOINCREMENT_IDS = 0x01
 #
+IPROTO_ERROR = 0x52
+#
 IPROTO_VERSION = 0x54
 IPROTO_FEATURES = 0x55
 

Diff for: tarantool/error.py

@@ -41,10 +41,17 @@ class DatabaseError(Error):
     Exception raised for errors that are related to the database.
     """
 
-    def __init__(self, *args):
+    def __init__(self, *args, extra_info=None):
         """
         :param args: ``(code, message)`` or ``(message,)``.
         :type args: :obj:`tuple`
+
+        :param extra_info: Additional `box.error`_ information
+            with backtrace.
+        :type extra_info: :class:`~tarantool.types.BoxError` or
+            :obj:`None`, optional
+
+        .. _box.error: https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_error/error/
         """
 
         super().__init__(*args)
@@ -59,6 +66,8 @@ def __init__(self, *args):
             self.code = 0
             self.message = ''
 
+        self.extra_info = extra_info
+
 
 class DataError(DatabaseError):
     """
@@ -235,7 +244,7 @@ class NetworkError(DatabaseError):
     Error related to network.
     """
 
-    def __init__(self, orig_exception=None, *args):
+    def __init__(self, orig_exception=None, *args, **kwargs):
         """
         :param orig_exception: Exception to wrap.
         :type orig_exception: optional
@@ -256,7 +265,7 @@ def __init__(self, orig_exception=None, *args):
                 super(NetworkError, self).__init__(
                     orig_exception.errno, self.message)
             else:
-                super(NetworkError, self).__init__(orig_exception, *args)
+                super(NetworkError, self).__init__(orig_exception, *args, **kwargs)
 
 
 class NetworkWarning(UserWarning):

Diff for: tarantool/response.py

@@ -11,6 +11,7 @@
 from tarantool.const import (
     IPROTO_REQUEST_TYPE,
     IPROTO_DATA,
+    IPROTO_ERROR_24,
     IPROTO_ERROR,
     IPROTO_SYNC,
     IPROTO_SCHEMA_ID,
@@ -21,6 +22,7 @@
     IPROTO_VERSION,
     IPROTO_FEATURES,
 )
+from tarantool.types import decode_box_error
 from tarantool.error import (
     DatabaseError,
     InterfaceError,
@@ -117,14 +119,22 @@ def __init__(self, conn, response):
             #     self.append(self._data)
         else:
             # Separate return_code and completion_code
-            self._return_message = self._body.get(IPROTO_ERROR, "")
+            self._return_message = self._body.get(IPROTO_ERROR_24, "")
             self._return_code = self._code & (REQUEST_TYPE_ERROR - 1)
+
+            self._return_error = None
+            return_error_map = self._body.get(IPROTO_ERROR)
+            if return_error_map is not None:
+                self._return_error = decode_box_error(return_error_map)
+
             self._data = []
             if self._return_code == 109:
                 raise SchemaReloadException(self._return_message,
                                             self._schema_version)
             if self.conn.error:
-                raise DatabaseError(self._return_code, self._return_message)
+                raise DatabaseError(self._return_code,
+                                    self._return_message,
+                                    extra_info=self._return_error)
 
     def __getitem__(self, idx):
         if self._data is None:

Diff for: tarantool/types.py

@@ -0,0 +1,102 @@
+"""
+Additional Tarantool type definitions.
+"""
+
+import typing
+from dataclasses import dataclass
+
+@dataclass
+class BoxErrorStackUnit():
+    """
+    Type representing Tarantool `box.error`_ single MP_ERROR_STACK
+    object.
+
+    .. _box.error: https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_error/error/
+    """
+
+    type: str
+    """
+    Type that implies source, for example ``"ClientError"``.
+    """
+
+    file: str
+    """
+    Source code file where error was caught.
+    """
+
+    line: int
+    """
+    Line number in source code file.
+    """
+
+    message: str
+    """
+    Text of reason.
+    """
+
+    errno: int
+    """
+    Ordinal number of the error.
+    """
+
+    errcode: int
+    """
+    Number of the error as defined in ``errcode.h``.
+    """
+
+    fields: typing.Optional[dict] = None
+    """
+    Additional fields depending on error type. For example, if
+    :attr:`~tarantool.types.BoxErrorStackComponent.type`
+    is ``"AccessDeniedError"``, then it will include ``"object_type"``,
+    ``"object_name"``, ``"access_type"``.
+    """
+
+@dataclass
+class BoxError():
+    """
+    Type representing Tarantool `box.error`_ object.
+
+    .. _box.error: https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_error/error/
+    """
+
+    stack: list
+    """
+    Array of :class:`~tarantool.types.BoxErrorStackUnit` objects.
+    """
+
+MP_ERROR_STACK = 0x00
+MP_ERROR_TYPE = 0x00
+MP_ERROR_FILE = 0x01
+MP_ERROR_LINE = 0x02
+MP_ERROR_MESSAGE = 0x03
+MP_ERROR_ERRNO = 0x04
+MP_ERROR_ERRCODE = 0x05
+MP_ERROR_FIELDS = 0x06
+
+def decode_box_error(mp_map):
+    """
+    Decode MessagePack map received from Tarantool to `box.error`_
+    object representation.
+
+    :param mp_map: Error MessagePack map received from Tarantool.
+    :type mp_map: :obj:`dict`
+
+    :rtype: :class:`~tarantool.types.BoxError`
+    """
+
+    encoded_stack = mp_map.get(MP_ERROR_STACK, [])
+    stack = []
+
+    for item in encoded_stack:
+        stack.append(BoxErrorStackUnit(
+            item.get(MP_ERROR_TYPE),
+            item.get(MP_ERROR_FILE),
+            item.get(MP_ERROR_LINE),
+            item.get(MP_ERROR_MESSAGE),
+            item.get(MP_ERROR_ERRNO),
+            item.get(MP_ERROR_ERRCODE),
+            item.get(MP_ERROR_FIELDS),
+        ))
+
+    return BoxError(stack)

Diff for: test/suites/lib/skip.py

@@ -154,3 +154,14 @@ def skip_or_run_datetime_test(func):
 
     return skip_or_run_test_pcall_require(func, 'datetime',
                                       'does not support datetime type')
+
+def skip_or_run_error_extra_info_test(func):
+    """Decorator to skip or run tests related to extra error info
+    provided over iproto depending on the tarantool version.
+
+    Tarantool provides extra error info only since 2.4.1 version.
+    See https://github.com/tarantool/tarantool/issues/4398
+    """
+
+    return skip_or_run_test_tarantool(func, '2.4.1',
+                                      'does not provide extra error info')

Diff for: test/suites/test_dml.py

@@ -1,8 +1,10 @@
 import sys
 import unittest
 import tarantool
+from tarantool.error import DatabaseError
 
 from .lib.tarantool_server import TarantoolServer
+from .lib.skip import skip_or_run_error_extra_info_test
 
 class TestSuite_Request(unittest.TestCase):
     @classmethod
@@ -309,6 +311,24 @@ def test_13_unix_socket_connect(self):
         self.sock_con = tarantool.connect(self.sock_srv.host, self.sock_srv.args['primary'])
         self.assertEqual(self.sock_con.ping(notime=True), "Success")
 
+    @skip_or_run_error_extra_info_test
+    def test_14_extra_error_info(self):
+        try:
+            self.con.eval("not a Lua code")
+        except DatabaseError as exc:
+            self.assertEqual(len(exc.extra_info.stack), 1)
+            info = exc.extra_info.stack[0]
+            self.assertEqual(info.type, 'LuajitError')
+            self.assertRegex(
+                info.file,
+                r'/__w/sdk/sdk/tarantool-(?:\d+\.\d+)/tarantool/src/box/lua/call\.c')
+            self.assertTrue(info.line > 0)
+            self.assertEqual(info.errno, 0)
+            self.assertEqual(info.errcode, 32)
+            self.assertEqual(info.fields, None)
+        else:
+            self.fail('Expected error')
+
     @classmethod
     def tearDownClass(self):
         self.con.close()