msgpack: support error extension type

Tarantool supports error extension type since version 2.4.1 [1],
encoding was introduced in Tarantool 2.10.0 [2]. 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
2. tarantool/tarantool#6433

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
+
 __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',]

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/datetime.py

@@ -13,7 +13,7 @@
 `datetime`_ type id.
 """
 
-def encode(obj):
+def encode(obj, _):
     """
     Encode a datetime object.
 
@@ -28,7 +28,7 @@ def encode(obj):
 
     return obj.msgpack_encode()
 
-def decode(data):
+def decode(data, _):
     """
     Decode a datetime object.
 

tarantool/msgpack_ext/decimal.py

@@ -225,7 +225,7 @@ def strip_decimal_str(str_repr, scale, first_digit_ind):
     # Do not strips zeroes before the decimal point
     return str_repr
 
-def encode(obj):
+def encode(obj, _):
     """
     Encode a decimal object.
 
@@ -335,7 +335,7 @@ def add_str_digit(digit, digits_reverted, scale):
 
     digits_reverted.append(str(digit))
 
-def decode(data):
+def decode(data, _):
     """
     Decode a decimal object.
 

tarantool/msgpack_ext/error.py

@@ -0,0 +1,52 @@
+"""
+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
+"""
+
+from tarantool.types import (
+    encode_box_error,
+    decode_box_error,
+)
+
+EXT_ID = 3
+"""
+`error`_ type id.
+"""
+
+def encode(obj, packer):
+    """
+    Encode an error object.
+
+    :param obj: Error to encode.
+    :type obj: :class:`tarantool.BoxError`
+
+    :param packer: msgpack packer to encode error dictionary.
+    :type packer: :class:`msgpack.Packer`
+
+    :return: Encoded error.
+    :rtype: :obj:`bytes`
+    """
+
+    err_map = encode_box_error(obj)
+    return packer.pack(err_map)
+
+def decode(data, unpacker):
+    """
+    Decode an error object.
+
+    :param obj: Error to decode.
+    :type obj: :obj:`bytes`
+
+    :param unpacker: msgpack unpacker to decode error dictionary.
+    :type unpacker: :class:`msgpack.Unpacker`
+
+    :return: Decoded error.
+    :rtype: :class:`tarantool.BoxError`
+    """
+
+    unpacker.feed(data)
+    err_map = unpacker.unpack()
+    return decode_box_error(err_map)

tarantool/msgpack_ext/interval.py

@@ -13,7 +13,7 @@
 `datetime.interval`_ type id.
 """
 
-def encode(obj):
+def encode(obj, _):
     """
     Encode an interval object.
 
@@ -28,7 +28,7 @@ def encode(obj):
 
     return obj.msgpack_encode()
 
-def decode(data):
+def decode(data, _):
     """
     Decode an interval object.
 

tarantool/msgpack_ext/packer.py

@@ -8,28 +8,36 @@
 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},
 ]
 
-def default(obj):
+def default(obj, packer=None):
     """
     :class:`msgpack.Packer` encoder.
 
     :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`
+
+    :param packer: msgpack packer to work with common types
+        (like dictionary in extended error payload)
+    :type packer: :class:`msgpack.Packer`, optional
 
     :return: Encoded value.
     :rtype: :class:`msgpack.ExtType`
@@ -39,5 +47,5 @@ def default(obj):
 
     for encoder in encoders:
         if isinstance(obj, encoder['type']):
-            return ExtType(encoder['ext'].EXT_ID, encoder['ext'].encode(obj))
+            return ExtType(encoder['ext'].EXT_ID, encoder['ext'].encode(obj, packer))
     raise TypeError("Unknown type: %r" % (obj,))

tarantool/msgpack_ext/unpacker.py

@@ -6,17 +6,19 @@
 
 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,
 }
 
-def ext_hook(code, data):
+def ext_hook(code, data, unpacker=None):
     """
     :class:`msgpack.Unpacker` decoder.
 
@@ -26,13 +28,18 @@ def ext_hook(code, data):
     :param data: MessagePack extension type data.
     :type data: :obj:`bytes`
 
+    :param unpacker: msgpack unpacker to work with common types
+        (like dictionary in extended error payload)
+    :type unpacker: :class:`msgpack.Unpacker`, optional
+
     :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`
     """
 
     if code in decoders:
-        return decoders[code](data)
+        return decoders[code](data, unpacker)
     raise NotImplementedError("Unknown msgpack extension type code %d" % (code,))

tarantool/msgpack_ext/uuid.py

@@ -20,7 +20,7 @@
 `uuid`_ type id.
 """
 
-def encode(obj):
+def encode(obj, _):
     """
     Encode an UUID object.
 
@@ -33,7 +33,7 @@ def encode(obj):
 
     return obj.bytes
 
-def decode(data):
+def decode(data, _):
     """
     Decode an UUID object.