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

Diff for: 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

Diff for: 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']

Diff for: 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,]

Diff for: 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)

Diff for: tarantool/msgpack_ext/packer.py

@@ -8,17 +8,20 @@
 from uuid import UUID
 from msgpack import ExtType
 
+from tarantool.types import BoxError
 from tarantool.msgpack_ext.types.datetime import Datetime
 from tarantool.msgpack_ext.types.interval import Interval
 
 import tarantool.msgpack_ext.decimal as ext_decimal
 import tarantool.msgpack_ext.uuid as ext_uuid
+import tarantool.msgpack_ext.error as ext_error
 import tarantool.msgpack_ext.datetime as ext_datetime
 import tarantool.msgpack_ext.interval as ext_interval
 
 encoders = [
     {'type': Decimal,  'ext': ext_decimal },
     {'type': UUID,     'ext': ext_uuid    },
+    {'type': BoxError, 'ext': ext_error   },
     {'type': Datetime, 'ext': ext_datetime},
     {'type': Interval, 'ext': ext_interval},
 ]
@@ -29,7 +32,8 @@ def default(obj):
 
     :param obj: Object to encode.
     :type obj: :class:`decimal.Decimal` or :class:`uuid.UUID` or
-        :class:`tarantool.Datetime` or :class:`tarantool.Interval`
+         or :class:`tarantool.BoxError` or :class:`tarantool.Datetime`
+         or :class:`tarantool.Interval`
 
     :return: Encoded value.
     :rtype: :class:`msgpack.ExtType`

Diff for: tarantool/msgpack_ext/unpacker.py

@@ -6,12 +6,14 @@
 
 import tarantool.msgpack_ext.decimal as ext_decimal
 import tarantool.msgpack_ext.uuid as ext_uuid
+import tarantool.msgpack_ext.error as ext_error
 import tarantool.msgpack_ext.datetime as ext_datetime
 import tarantool.msgpack_ext.interval as ext_interval
 
 decoders = {
     ext_decimal.EXT_ID : ext_decimal.decode ,
     ext_uuid.EXT_ID    : ext_uuid.decode    ,
+    ext_error.EXT_ID   : ext_error.decode   ,
     ext_datetime.EXT_ID: ext_datetime.decode,
     ext_interval.EXT_ID: ext_interval.decode,
 }
@@ -28,7 +30,8 @@ def ext_hook(code, data):
 
     :return: Decoded value.
     :rtype: :class:`decimal.Decimal` or :class:`uuid.UUID` or
-        :class:`tarantool.Datetime` or :class:`tarantool.Interval`
+         or :class:`tarantool.BoxError` or :class:`tarantool.Datetime`
+         or :class:`tarantool.Interval`
 
     :raise: :exc:`NotImplementedError`
     """

Diff for: 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}

Diff for: 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()

Diff for: 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')