msgpack: support error extension type

Tarantool supports error extension type since version 2.4.1 [1].
This patch introduced the support of Tarantool error extension type in
msgpack decoders and encoders.

Tarantool error extension type objects are decoded to
`tarantool.BoxError` type. `tarantool.BoxError` may be encoded to
Tarantool error extension type objects.

Error extension type internals are the same as errors extra information:
the only difference is that extra information is encoded as a separate
error dictionary field and error extension type objects is encoded as
MessagePack extension type objects.

The only way to receive an error extension type object from Tarantool is
to receive an explicitly built `box.error` object: either from
`return box.error.new(...)` or a tuple with it. All errors raised within
Tarantool (including those raised with `box.error(...)`) are encoded
based on the same rules as simple errors due to backward compatibility.

It is possible to create error extension type objects with Python code,
but it not likely to be really useful since most of their fields is
computed on error initialization on server side (even for custom error
types):

```
tarantool.BoxError([
    tarantool.BoxErrorStackUnit(
        type='ClientError',
        file='[string "                     local err = box.error.ne..."]',
        line=1,
        message='Unknown error',
        errno=0,
        errcode=0,
    )
])
```

1. tarantool/tarantool#4398

Part of #232

Author: DifferentialOrange

doc/dev-guide.rst

@@ -83,6 +83,8 @@ they are represented with in-built and custom types:
     +-----------------------------+----+-------------+----+-----------------------------+
     | :obj:`uuid.UUID`            | -> | `UUID`_     | -> | :obj:`uuid.UUID`            |
     +-----------------------------+----+-------------+----+-----------------------------+
+    | :class:`tarantool.BoxError` | -> | `ERROR`_    | -> | :class:`tarantool.BoxError` |
+    +-----------------------------+----+-------------+----+-----------------------------+
     | :class:`tarantool.Datetime` | -> | `DATETIME`_ | -> | :class:`tarantool.Datetime` |
     +-----------------------------+----+-------------+----+-----------------------------+
     | :class:`tarantool.Interval` | -> | `INTERVAL`_ | -> | :class:`tarantool.Interval` |
@@ -109,5 +111,6 @@ and iterate through it as with any other serializable object.
 .. _extension types: https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/
 .. _DECIMAL: https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/#the-decimal-type
 .. _UUID: https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/#the-uuid-type
+.. _ERROR: https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/#the-error-type
 .. _DATETIME: https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/#the-datetime-type
 .. _INTERVAL: https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/#the-interval-type

tarantool/__init__.py

@@ -42,6 +42,8 @@
 
 from tarantool.connection_pool import ConnectionPool, Mode
 
+from tarantool.types import BoxError, BoxErrorStackUnit
+
 __version__ = "0.9.0"
 
 
@@ -136,4 +138,4 @@ def connectmesh(addrs=({'host': 'localhost', 'port': 3301},), user=None,
 __all__ = ['connect', 'Connection', 'connectmesh', 'MeshConnection', 'Schema',
            'Error', 'DatabaseError', 'NetworkError', 'NetworkWarning',
            'SchemaError', 'dbapi', 'Datetime', 'Interval', 'IntervalAdjust',
-           'ConnectionPool', 'Mode']
+           'ConnectionPool', 'Mode', 'BoxError', 'BoxErrorStackUnit']

tarantool/const.py

@@ -129,4 +129,4 @@
 # Tarantool 2.10 protocol version is 3
 CONNECTOR_IPROTO_VERSION = 3
 # List of connector-supported features
-CONNECTOR_FEATURES = []
+CONNECTOR_FEATURES = [IPROTO_FEATURE_ERROR_EXTENSION,]

tarantool/msgpack_ext/error.py

@@ -0,0 +1,47 @@
+"""
+Tarantool `error`_ extension type support module.
+
+Refer to :mod:`~tarantool.msgpack_ext.types.error`.
+
+.. _error: https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/#the-error-type
+"""
+
+import msgpack
+
+from tarantool.types import (
+    encode_box_error,
+    decode_box_error,
+)
+
+EXT_ID = 3
+"""
+`error`_ type id.
+"""
+
+def encode(obj):
+    """
+    Encode an error object.
+
+    :param obj: Error to encode.
+    :type obj: :class:`tarantool.BoxError`
+
+    :return: Encoded error.
+    :rtype: :obj:`bytes`
+    """
+
+    err_map = encode_box_error(obj)
+    return msgpack.packb(err_map)
+
+def decode(data):
+    """
+    Decode an error object.
+
+    :param obj: Error to decode.
+    :type obj: :obj:`bytes`
+
+    :return: Decoded error.
+    :rtype: :class:`tarantool.BoxError`
+    """
+
+    err_map = msgpack.unpackb(data, strict_map_key=False)
+    return decode_box_error(err_map)

tarantool/types.py

@@ -47,7 +47,7 @@ class BoxErrorStackUnit():
     fields: typing.Optional[dict] = None
     """
     Additional fields depending on error type. For example, if
-    :attr:`~tarantool.types.BoxErrorStackComponent.type`
+    :attr:`~tarantool.BoxErrorStackComponent.type`
     is ``"AccessDeniedError"``, then it will include ``"object_type"``,
     ``"object_name"``, ``"access_type"``.
     """
@@ -62,7 +62,7 @@ class BoxError():
 
     stack: list
     """
-    Array of :class:`~tarantool.types.BoxErrorStackUnit` objects.
+    Array of :class:`~tarantool.BoxErrorStackUnit` objects.
     """
 
 MP_ERROR_STACK = 0x00
@@ -102,3 +102,33 @@ def decode_box_error(err_map):
         ))
 
     return BoxError(stack)
+
+def encode_box_error(err):
+    """
+    Encode Python `box.error`_ representation to MessagePack map.
+
+    :param err: Error to encode
+    :type err: :obj:`tarantool.BoxError`
+
+    :rtype: :obj:`dict`
+
+    :raises: :exc:`KeyError`
+    """
+
+    stack = []
+    for item in err.stack:
+        dict_item = {
+            MP_ERROR_TYPE: item.type,
+            MP_ERROR_FILE: item.file,
+            MP_ERROR_LINE: item.line,
+            MP_ERROR_MESSAGE: item.message,
+            MP_ERROR_ERRNO: item.errno,
+            MP_ERROR_ERRCODE: item.errcode,
+        }
+
+        if item.fields is not None: # omitted if empty
+            dict_item[MP_ERROR_FIELDS] = item.fields
+
+        stack.append(dict_item)
+
+    return {MP_ERROR_STACK: stack}

test/suites/__init__.py

@@ -19,14 +19,15 @@
 from .test_uuid import TestSuite_UUID
 from .test_datetime import TestSuite_Datetime
 from .test_interval import TestSuite_Interval
+from .test_error_ext import TestSuite_ErrorExt
 
 test_cases = (TestSuite_Schema_UnicodeConnection,
               TestSuite_Schema_BinaryConnection,
               TestSuite_Request, TestSuite_Protocol, TestSuite_Reconnect,
               TestSuite_Mesh, TestSuite_Execute, TestSuite_DBAPI,
               TestSuite_Encoding, TestSuite_Pool, TestSuite_Ssl,
               TestSuite_Decimal, TestSuite_UUID, TestSuite_Datetime,
-              TestSuite_Interval)
+              TestSuite_Interval, TestSuite_ErrorExt,)
 
 def load_tests(loader, tests, pattern):
     suite = unittest.TestSuite()

test/suites/lib/skip.py

@@ -165,3 +165,14 @@ def skip_or_run_error_extra_info_test(func):
 
     return skip_or_run_test_tarantool(func, '2.4.1',
                                       'does not provide extra error info')
+
+def skip_or_run_error_ext_type_test(func):
+    """Decorator to skip or run tests related to error extension
+    type depending on the tarantool version.
+
+    Tarantool supports error extension type 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 support error extension type')