feat userver/proto-structs: tests and fixes

* Stabilize the serialization API for Well-known types
* Introduce an extendable discovery system for Well-known types
   * Suppose that a proto struct uses `foo::bar::Something` for a field type, which is NOT a Protobuf type
   * Then `<userver/proto-structs/io/foo/bar/something.hpp>` should bring in the type definition (usually by including the proper header)
   * Then `<userver/proto-structs/io/foo/bar/something_conv.hpp>` should bring in proto-structs serialization for the type
   * Serialization discovery was inspired by userver chaotic and postgres
* Implement serialization for all main Well-known types: integers, strings, optional, vector, maps, `utils::Box`,
* Implement the collection of path to the current Protobuf node in case of a convertion error
* Add diverse conversion tests for various hand-written proto structs

Relates: <https://nda.ya.ru/t/cgDVoMPU7JV5ar>
commit_hash:a51e1837061bf5fbdbaed98cc987f03c68f4a5d1

Author: pananton

.mapping.json

@@ -18,43 +18,40 @@ namespace proto_structs {
 /// @brief Wrapper for `google.protobuf.Any` which provides interface to access stored message as compatible struct
 class Any final {
 public:
+    using ProtobufMessage = ::google::protobuf::Any;
+
     /// @brief Creates empty `Any`.
     Any() noexcept = default;
 
     /// @brief Creates wrapper initializing its underlying storage with @a proto_any
     Any(google::protobuf::Any proto_any) : storage_(std::move(proto_any)) {}
 
     /// @brief Creates `Any` holding @a obj
-    /// @tparam TStruct struct with defined compatability
-    /// @throws ConversionError if @a obj can't be converted to its compatible protobuf message
+    /// @tparam TStruct proto struct type
+    /// @throws WriteError if conversion of @a obj to its compatible message has failed
     /// @throws AnyPackError if compatible protobuf message can not be packed to `google.protobuf.Any`
-    /// @note This overload only works for structs for which compatability is defined using
-    ///       @ref proto_structs::CompatibleMessageTrait
     template <typename TStruct>
-    requires traits::CompatibleStruct<std::remove_cvref_t<TStruct>>
+    requires(!std::is_same_v<std::remove_cvref_t<TStruct>, ::google::protobuf::Any>) &&
+            (!std::is_same_v<std::remove_cvref_t<TStruct>, Any>) && traits::ProtoStruct<std::remove_cvref_t<TStruct>>
     Any(TStruct&& obj) {
         Pack(std::forward<TStruct>(obj));
     }
 
     /// @brief Packs @a obj in `Any`
-    /// @tparam TStruct struct with defined compatability
-    /// @throws ConversionError if @a obj can't be converted to its compatible protobuf message
+    /// @tparam TStruct proto struct type
+    /// @throws WriteError if conversion of @a obj to its compatible message has failed
     /// @throws AnyPackError if compatible protobuf message can not be packed to `google.protobuf.Any`
-    /// @note This overload only works for structs for which compatability is defined using
-    ///       @ref proto_structs::CompatibleMessageTrait
-    /// @note Method caches @a obj and later calls to @ref Get will not trigger unpacking
     template <typename TStruct>
-    requires traits::CompatibleStruct<std::remove_cvref_t<TStruct>>
+    requires(!std::is_same_v<std::remove_cvref_t<TStruct>, ::google::protobuf::Any>) &&
+            (!std::is_same_v<std::remove_cvref_t<TStruct>, Any>) && traits::ProtoStruct<std::remove_cvref_t<TStruct>>
     Any& operator=(TStruct&& obj) {
         Pack(std::forward<TStruct>(obj));
         return *this;
     }
 
     /// @brief Returns `true` if `Any` contains `TStruct`
-    /// @tparam TStruct struct with defined compatability
-    /// @note This method only works for structs for which compatability is defined using
-    ///       @ref proto_structs::CompatibleMessageTrait
-    template <traits::CompatibleStruct TStruct>
+    /// @tparam TStruct proto struct type
+    template <traits::ProtoStruct TStruct>
     bool Is() const noexcept {
         using Message = traits::CompatibleMessageType<TStruct>;
         return storage_.Is<Message>();
@@ -68,12 +65,10 @@ class Any final {
     }
 
     /// @brief Unpacks `Any` to `TStruct` struct
-    /// @tparam TStruct struct with defined compatability
+    /// @tparam TStruct proto struct type
     /// @throws AnyUnpackError if underlying `google.protobuf.Any` does not contain message compatible to `TStruct`
-    /// @throws ConversionError if struct can be converted from its compatible message
-    /// @note This method only works for structs for which compatability is defined using
-    ///       @ref proto_structs::CompatibleMessageTrait
-    template <traits::CompatibleStruct TStruct>
+    /// @throws ReadError if conversion of unpacked protobuf message to proto struct has failed
+    template <traits::ProtoStruct TStruct>
     TStruct Unpack() {
         using Message = traits::CompatibleMessageType<TStruct>;
         return MessageToStruct<TStruct>(Unpack<Message>());
@@ -94,25 +89,22 @@ class Any final {
     }
 
     /// @brief Packs @a obj to `Any`
-    /// @tparam TStruct struct with defined compatability
-    /// @throws ConversionError if @a obj can't be converted to its compatible protobuf message
-    /// @throws AnyPackError if packing of compatible protobuf message to `google.protobuf.Any` had failed
-    /// @note This method only works for structs for which compatability is defined using
-    ///       @ref proto_structs::CompatibleMessageTrait
-    /// @note Method caches @a obj and later calls to @ref Get will not trigger unpacking
+    /// @tparam TStruct proto struct type
+    /// @throws WriteError if conversion of @a obj to its compatible message has failed
+    /// @throws AnyPackError if packing of compatible protobuf message to `google.protobuf.Any` has failed
     template <typename TStruct>
-    requires traits::CompatibleStruct<std::remove_cvref_t<TStruct>>
+    requires traits::ProtoStruct<std::remove_cvref_t<TStruct>>
     void Pack(TStruct&& obj) {
         using Message = traits::CompatibleMessageType<std::remove_cvref_t<TStruct>>;
         Pack<Message>(StructToMessage(std::forward<TStruct>(obj)));
     }
 
     /// @brief Packs @a message to underlying `google.protobuf.Any`
     /// @tparam TMessage protobuf message type
-    /// @throws AnyPackError if packing of protobuf message to `google.protobuf.Any` had failed
+    /// @throws AnyPackError if packing of protobuf message to `google.protobuf.Any` has failed
     template <traits::ProtoMessage TMessage>
     void Pack(const TMessage& message) {
-        if (!storage_.PackFrom(&message)) {
+        if (!storage_.PackFrom(message)) {
             throw AnyUnpackError(TMessage::descriptor()->full_name());
         }
     }
@@ -121,7 +113,7 @@ class Any final {
     const ::google::protobuf::Any& GetProtobufAny() const& noexcept { return storage_; }
 
     /// @brief Returns underlying `google.protobuf.Any`
-    ::google::protobuf::Any GetProtobufAny() && noexcept { return std::move(storage_); }
+    ::google::protobuf::Any&& GetProtobufAny() && noexcept { return std::move(storage_); }
 
 private:
     ::google::protobuf::Any storage_;

libraries/proto-structs/include/userver/proto-structs/any.hpp

@@ -2,91 +2,95 @@
 
 /// @file userver/proto-structs/convert.hpp
 /// @brief Functions for protobuf message to/from struct conversion
+///
+/// Conversion functions rely on user-defined functions with the following signatures:
+/// 1. `StructType ReadProtoStruct(proto_structs::io::ReadContext&,
+///                                proto_structs::io::To<StructType>,
+///                                const MessageType&)`
+///
+/// 2. `void WriteProtoStruct(proto_structs::io::WriteContext&,
+///                           const StructType&,
+///                           MessageType&)`
+///
+/// This functions should be foundable by ADL lookup (just place them in the namespace where `StructType` is defined).
+///
+/// It is recommended to define `WriteProtoStruct` function as template with a `StructType` parameter and use universal
+/// reference `StructType&&` as a second parameter to enable perfect forwarding for conversions.
 
 #include <type_traits>
 #include <utility>
 
-#include <userver/proto-structs/exceptions.hpp>
-#include <userver/proto-structs/impl/context.hpp>
+#include <userver/proto-structs/io/context.hpp>
 #include <userver/proto-structs/type_mapping.hpp>
-#include <userver/utils/assert.hpp>
 
 USERVER_NAMESPACE_BEGIN
 
 namespace proto_structs {
 
-/// @brief Converts protobuf message @a msg to struct @a obj
+/// @brief Converts protobuf message @a msg to proto struct @a obj
 /// @tparam TMessage protobuf message type
-/// @tparam TStruct struct type
-/// @throws ConversionError if conversion failed (in that case `obj` is not modified)
-/// @note If function throws an exception, @a obj is not modified
-///
-/// Function calls `ReadStruct(obj, msg)` under the hood which should be foundable by argument-dependent lookup.
+/// @tparam TStruct proto struct type
+/// @throws ReadError if conversion has failed
+/// @warning If function throws an exception, @a obj is left in a valid but unspecified state
 template <traits::ProtoMessage TMessage, traits::ProtoStruct TStruct>
 void MessageToStruct(const TMessage& msg, TStruct& obj) {
-    impl::ReadContext ctx;
-    obj = ReadStruct(ctx, To<std::remove_cv_t<TStruct>>{}, msg);
-    UINVARIANT(!ctx.HasError(), "Read context contains error that should have been thrown");
+    io::ReadContext ctx(*msg.GetDescriptor());
+
+    try {
+        obj = ReadProtoStruct(ctx, io::To<std::remove_cv_t<TStruct>>{}, msg);
+    } catch (const ReadError&) {
+        // simply re-throw proper errors
+        throw;
+    } catch (const std::exception& e) {
+        // some user-defined `ReadProtoStruct` threw an exception instead of adding an error to context,
+        // adding it manually an re-throwing as a proper exception type
+        ctx.AddError(e.what());
+    }
 }
 
-/// @brief Converts protobuf message @a msg to specified structure type
-/// @tparam TStruct struct type
+/// @brief Converts protobuf message @a msg to specified proto struct type
+/// @tparam TStruct proto struct type
 /// @tparam TMessage protobuf message type
-/// @throws ConversionError if conversion failed
-///
-/// Function calls `ReadStruct(obj, msg)` under the hood which should be foundable by argument-dependent lookup.
+/// @throws ReadError if conversion has failed
 template <traits::ProtoStruct TStruct, traits::ProtoMessage TMessage>
 [[nodiscard]] TStruct MessageToStruct(const TMessage& msg) {
     TStruct obj;
     MessageToStruct(msg, obj);
     return obj;
 }
 
-/// @brief Converts struct instance @a obj to protobuf message @a msg
-/// @tparam TStruct struct type
+/// @brief Converts proto struct @a obj to protobuf message @a msg
+/// @tparam TStruct proto struct type
 /// @tparam TMessage protobuf message type
-/// @throws ConversionError if conversion failed (in that case `msg` is not modified)
+/// @throws WriteError if conversion has failed
 /// @warning If function throws an exception, @a msg is left in a valid but unspecified state
-///
-/// Function calls `WriteStruct(std::forward<TStruct>(obj), msg)` under the hood which should be foundable by
-/// argument-dependent lookup.
 template <typename TStruct, traits::ProtoMessage TMessage>
 requires traits::ProtoStruct<std::remove_cvref_t<TStruct>>
 void StructToMessage(TStruct&& obj, TMessage& msg) {
-    impl::WriteContext ctx;
-    WriteStruct(ctx, std::forward<TStruct>(obj), msg);
-    UINVARIANT(!ctx.HasError(), "Write context contains error that should have been thrown");
-}
+    io::WriteContext ctx(*msg.GetDescriptor());
 
-/// @brief Converts struct instance @a obj to protobuf message @a msg of the specified type
-/// @tparam TStruct struct type
-/// @tparam TMessage protobuf message type
-/// @throws ConversionError if conversion failed
-///
-/// Function calls `WriteStruct(std::forward<TStruct>(obj), msg)` under the hood which should be foundable by
-/// argument-dependent lookup.
-template <traits::ProtoMessage TMessage, typename TStruct>
-requires traits::ProtoStruct<std::remove_cvref_t<TStruct>>
-[[nodiscard]] TMessage StructToMessage(TStruct&& obj) {
-    TMessage msg;
-    StructToMessage(std::forward<TStruct>(obj), msg);
-    return msg;
+    try {
+        WriteProtoStruct(ctx, std::forward<TStruct>(obj), msg);
+    } catch (const WriteError&) {
+        // simply re-throw proper errors
+        throw;
+    } catch (const std::exception& e) {
+        // some user-defined `WriteProtoStruct` threw an exception instead of adding an error to context,
+        // adding it manually an re-throwing as a proper exception type
+        ctx.AddError(e.what());
+    }
 }
 
-/// @brief Converts struct instance @a obj to it's compatible protobuf message
-/// @tparam TStruct struct type
-/// @throws ConversionError if conversion failed
-///
-/// Compatability information should be provided for `TStruct` with @ref proto_structs::compatible_message, otherwise
-/// compilation will fail.
-///
-/// Function calls `WriteStruct(std::forward<TStruct>(obj), msg)` under the hood which should be foundable by
-/// argument-dependent lookup.
+/// @brief Converts proto struct @a obj to it's compatible protobuf message type
+/// @tparam TStruct proto struct type
+/// @throws WriteError if conversion has failed
 template <typename TStruct>
-requires traits::CompatibleStruct<std::remove_cvref_t<TStruct>>
+requires traits::ProtoStruct<std::remove_cvref_t<TStruct>>
 [[nodiscard]] traits::CompatibleMessageType<std::remove_cvref_t<TStruct>> StructToMessage(TStruct&& obj) {
     using Message = traits::CompatibleMessageType<std::remove_cvref_t<TStruct>>;
-    return StructToMessage<Message>(std::forward<TStruct>(obj));
+    Message msg;
+    StructToMessage(std::forward<TStruct>(obj), msg);
+    return msg;
 }
 
 }  // namespace proto_structs

libraries/proto-structs/include/userver/proto-structs/convert.hpp

@@ -8,6 +8,7 @@
 
 USERVER_NAMESPACE_BEGIN
 
+/// @brief Top namespace for the proto-structs library
 namespace proto_structs {
 
 /// @brief Library basic exception type
@@ -17,35 +18,50 @@ class Error : public std::runtime_error {
     using std::runtime_error::runtime_error;
 };
 
-/// @brief Conversion error
-/// Exception is thrown if protobuf message field can't be converted to/from struct field.
+/// @brief Conversion error base class
 class ConversionError : public Error {
+protected:
+    using Error::Error;
+};
+
+/// @brief Error reading proto struct from protobuf message
+class ReadError final : public ConversionError {
+public:
+    /// @brief Creates error with information what protobuf message field was considered invalid
+    /// Parameter @a path contains dot-separated field names from the top-level message up to erroneous field, for
+    /// example, "msg.field.nested_field".
+    ReadError(std::string_view path, std::string_view reason);
+};
+
+/// @brief Error writing proto struct to protobuf message
+class WriteError final : public ConversionError {
 public:
-    /// @brief Creates error signalling that conversion failed for field @a field_name of message @a message_name
-    ConversionError(std::string_view message_name, std::string_view field_name, std::string_view reason);
+    /// @brief Creates error with information what protobuf message field was not correctly initialized
+    /// Parameter @a path contains dot-separated field names from the top-level message up to field that was not
+    /// initialized, for example, "msg.field.nested_field".
+    WriteError(std::string_view path, std::string_view reason);
 };
 
-/// @brief Trying to access unset @ref proto_structs::Oneof field
-/// @note This exception is also thrown if @ref proto_structs::Oneof is cleared
+/// @brief Invalid attempt to access unset @ref proto_structs::Oneof field
 class OneofAccessError : public Error {
 public:
-    /// @brief Creates error when attempting to access @a field_idx field of `oneof`
+    /// @brief Creates error on invalid attempt to access @a field_idx field of `oneof`
     explicit OneofAccessError(std::size_t field_idx);
 };
 
-/// @brief Failed to pack struct's compatible message to @ref proto_structs::Any underlying storage.
-/// @note This exception is thrown *after* struct to protobuf message conversion.
+/// @brief Error packing protobuf message to @ref proto_structs::Any underlying storage.
 class AnyPackError : public Error {
 public:
-    /// @brief Creates error when trying to pack protobuf message @a message_name
+    /// @brief Creates error with information what protobuf message was not packed
     explicit AnyPackError(std::string_view message_name);
 };
 
-/// @brief Failed to unpack struct's compatible message from @ref proto_structs::Any underlying storage
-/// @note This exception is thrown *before* protobuf message to struct conversion.
+/// @brief Error unpacking protobuf message from @ref proto_structs::Any underlying storage.
+/// The main reason of this exception is the attempt to unpack message type different from the one stored in the
+/// @ref proto_structs::Any underlying storage
 class AnyUnpackError : public Error {
 public:
-    /// @brief Creates error when trying to unpack protobuf message @a message_name
+    /// @brief Creates error with information what protobuf message was not unpacked
     explicit AnyUnpackError(std::string_view message_name);
 };
 

libraries/proto-structs/include/userver/proto-structs/exceptions.hpp

@@ -1,8 +1,9 @@
 #pragma once
 
-/// @file
+/// @file userver/proto-structs/hash_map.hpp
 /// @brief @copybrief proto_structs::HashMap
 
+#include <string_view>
 #include <type_traits>
 #include <unordered_map>