Detailed Description

Asynchronous gRPC driver.

Namespaces
namespace	client
	Client-side utilities.

namespace	server
	Server-side utilities.

namespace	tests
	userver gRPC testing facilities

Classes
class	BaseVisitor
	Base class for FieldsVisitor and MessagesVisitor. Provides the interface and contains common code to use the data collected in the VisitorCompiler. More...

class	DateConversionError
	Exception thrown when date conversion functions receive/produce invalid `google::type::Date` accrording to `IsValid` or otherwise lead to undefined behavior due to integer overflow. More...

class	DurationConversionError
	Exception thrown when duration conversion functions receive/produce invalid `google::protobuf::Duration` accrording to `IsValid` or otherwise lead to undefined behavior due to integer overflow. More...

class	FieldsVisitor
	Collects knowledge of the structure of the protobuf messages allowing for efficient loops over fields to apply a callback to the ones selected by the 'selector' function. More...

class	MessagesVisitor
	Collects knowledge of the structure of the protobuf messages allowing for efficient loops over nested messages to apply a callback to the ones selected by the 'selector' function. More...

class	TimestampConversionError
	Exception thrown when timestamp conversion functions receive/produce invalid `google::protobuf::Timestamp` accrording to `IsValid` or otherwise lead to undefined behavior due to integer overflow. More...

class	VisitorCompiler
	Base class for BaseVisitor. Constructs and manages the descriptor graph to collect the data about the messages and enable the visitors to find all selected structures. More...

Typedefs
using	MessageVisitCallback = utils::function_ref<void(google::protobuf::Message&)>

using	FieldVisitCallback

using	DescriptorList = std::vector<const google::protobuf::Descriptor*>

using	FieldDescriptorList = std::vector<const google::protobuf::FieldDescriptor*>

Functions
grpc::Status	ToGrpcStatus (const google::rpc::Status &gstatus)
	Converts `google::rpc::Status` from googleapis to `grpc::Status` . `google::rpc::Status` is used to initialize `grpc::Status` code and message and also added to status details.

std::optional< google::rpc::Status >	ToGoogleRpcStatus (const grpc::Status &status)
	Creates `google::rpc::Status` parsing it from `grpc::Status` details.

std::string	GetGStatusLimitedMessage (const google::rpc::Status &status)
	Outputs status to string using protobuf's text format.

gpr_timespec	DurationToTimespec (const engine::Deadline::Duration &duration) noexcept
	Converts `engine::Deadline::Duration` to `gpr_timespec`.

template<typename Rep, typename Period>
gpr_timespec	DurationToTimespec (const std::chrono::duration< Rep, Period > &duration) noexcept

engine::Deadline::Duration	TimespecToDuration (gpr_timespec t) noexcept
	Converts `gpr_timespec` to `engine::Deadline::Duration`

gpr_timespec	DeadlineToTimespec (const engine::Deadline &deadline) noexcept
	Converts `engine::Deadline` to `gpr_timespec`.

engine::Deadline	TimespecToDeadline (gpr_timespec t) noexcept
	Converts `gpr_timespec` to `engine::Deadline`

grpc::ByteBuffer	SerializeToByteBuffer (const ::google::protobuf::Message &message, std::size_t block_size=kDefaultSerializeBlockSize)
	Serialize a Protobuf message to the wire format.

bool	ParseFromByteBuffer (grpc::ByteBuffer &&buffer, ::google::protobuf::Message &message)
	Parse a Protobuf message from the wire format.

bool	IsValid (const google::protobuf::Timestamp &grpc_ts)
	Checks if `google::protobuf::Timestamp` contains a valid value according to protobuf documentation.

template<class Duration>
google::protobuf::Timestamp	ToProtoTimestamp (const std::chrono::time_point< std::chrono::system_clock, Duration > &system_tp)
	Creates `google::protobuf::Timestamp` from `std::chrono::time_point`.

template<class Duration = std::chrono::system_clock::duration>
std::chrono::time_point< std::chrono::system_clock, Duration >	ToTimePoint (const google::protobuf::Timestamp &grpc_ts)
	Creates `std::chrono::system_clock::time_point` from `google::protobuf::Timestamp`.

google::protobuf::Timestamp	NowTimestamp ()
	Returns current (possibly, mocked) timestamp as a `google::protobuf::Timestamp`.

bool	IsValid (const google::type::Date &grpc_date)
	Checks if `google::type::Date` contains a valid value according to protobuf documentation.

google::type::Date	ToProtoDate (const utils::datetime::Date &utils_date)
	Creates `google::type::Date` from `utils::datetime::Date`.

utils::datetime::Date	ToUtilsDate (const google::type::Date &grpc_date)
	Creates `utils::datetime::Date` from `google::type::Date`.

template<class Duration>
google::type::Date	ToProtoDate (const std::chrono::time_point< std::chrono::system_clock, Duration > &system_tp)
	Creates `google::type::Date` from `std::chrono::time_point`.

std::chrono::time_point< std::chrono::system_clock, utils::datetime::Days >	ToTimePoint (const google::type::Date &grpc_date)
	Creates `std::chrono::system_clock::time_point` from `google::type::Date`.

google::type::Date	NowDate ()
	Returns current (possibly, mocked) timestamp as a `google::type::Date`.

bool	IsValid (const google::protobuf::Duration &grpc_duration)
	Checks if `google::protobuf::Duration` contains a valid value according to protobuf documentation.

template<class Duration = std::chrono::microseconds>
Duration	ToDuration (const google::protobuf::Duration &grpc_duration)
	Creates `std::chrono::duration` from `google::protobuf::Duration`.

template<class Rep, class Period>
google::protobuf::Duration	ToProtoDuration (const std::chrono::duration< Rep, Period > &duration)
	Creates `google::protobuf::Duration` from `std::chrono::duration`.

formats::json::Value	MessageToJson (const google::protobuf::Message &message)
	Returns formats::json::Value representation of protobuf message.

formats::json::Value	MessageToJson (const google::protobuf::Message &message, const google::protobuf::util::JsonPrintOptions &options)
	Returns formats::json::Value representation of protobuf message.

std::string	ToJsonString (const google::protobuf::Message &message)
	Returns Json-string representation of protobuf message.

std::string	ToJsonString (const google::protobuf::Message &message, const google::protobuf::util::JsonPrintOptions &options)
	Returns Json-string representation of protobuf message.

template<typename Message>
Message	JsonToMessage (const formats::json::Value &json)
	Parses Json to a protobuf message. Throws on unknown enum values and unknown fields by default.

template<typename Message>
Message	JsonToMessage (const formats::json::Value &json, const google::protobuf::util::JsonParseOptions &options)
	Parses Json to a protobuf message. Throws on unknown enum values.

template<typename Message>
Message	FromJsonString (std::string_view json_string)
	Parses Json to a protobuf message. Throws on unknown enum values and unknown fields by default.

template<typename Message>
Message	FromJsonString (std::string_view json_string, const google::protobuf::util::JsonParseOptions &options)
	Parses Json to a protobuf message. Throws on unknown enum values.

std::string	ToLimitedDebugString (const google::protobuf::Message &message, std::size_t limit)
	Convert protobuf message to limited debug string for logging.

std::string	ToUnlimitedDebugString (const google::protobuf::Message &message)
	Convert protobuf message to unlimited debug string for logging.

std::string	ToLimitedDebugString (const grpc::Status &status, std::size_t max_size=kDefaultDebugStringLimit)
	Get error details from `grpc::Status` for logging with size limit.

std::string	ToUnlimitedDebugString (const grpc::Status &status)
	Get error details from `grpc::Status` for logging without size limit.

void	VisitFields (google::protobuf::Message &message, FieldVisitCallback callback)
	Execute a callback for all non-empty fields of the message.

void	VisitMessagesRecursive (google::protobuf::Message &message, MessageVisitCallback callback)
	Execute a callback for the message and its non-empty submessages.

void	VisitFieldsRecursive (google::protobuf::Message &message, FieldVisitCallback callback)
	Execute a callback for all fields of the message and its non-empty submessages.

void	VisitNestedMessage (google::protobuf::Message &message, const google::protobuf::FieldDescriptor &field, MessageVisitCallback callback)
	Execute a callback for the submessage contained in the given field.

FieldDescriptorList	GetFieldDescriptors (const google::protobuf::Descriptor &descriptor)
	Get the descriptors of fields in the message.

DescriptorList	GetNestedMessageDescriptors (const google::protobuf::Descriptor &descriptor)
	Get the descriptors of current and nested messages.

const google::protobuf::Descriptor *	FindGeneratedMessage (std::string_view name)
	Find a generated type by name.

const google::protobuf::FieldDescriptor *	FindField (const google::protobuf::Descriptor *descriptor, std::string_view field)
	Find the field of a generated type by name.

grpc::StatusCode	StatusCodeFromString (std::string_view str)
	Convert string to grpc::StatusCode.

std::string	ToString (grpc::StatusCode code) noexcept
	Convert grpc::StatusCode to string.

bool	IsServerError (grpc::StatusCode code) noexcept
	Whether a given status code is definitely a server-side error.

Variables
constexpr std::size_t	kDefaultSerializeBlockSize = 4096

constexpr std::size_t	kDefaultDebugStringLimit = 1024

Typedef Documentation

◆ DescriptorList

using ugrpc::DescriptorList = std::vector<const google::protobuf::Descriptor*>

Definition at line 50 of file protobuf_visit.hpp.

◆ FieldDescriptorList

using ugrpc::FieldDescriptorList = std::vector<const google::protobuf::FieldDescriptor*>

Definition at line 52 of file protobuf_visit.hpp.

◆ FieldVisitCallback

using ugrpc::FieldVisitCallback

Initial value:

utils::function_ref<void(google::protobuf::Message&, const google::protobuf::FieldDescriptor&)>

Definition at line 31 of file protobuf_visit.hpp.

◆ MessageVisitCallback

using ugrpc::MessageVisitCallback = utils::function_ref<void(google::protobuf::Message&)>

Definition at line 29 of file protobuf_visit.hpp.

Function Documentation

◆ DurationToTimespec()

template<typename Rep, typename Period>

gpr_timespec ugrpc::DurationToTimespec ( const std::chrono::duration< Rep, Period > & duration )

noexcept

Definition at line 15 of file time_utils.hpp.

◆ FromJsonString() [1/2]

template<typename Message>

Message ugrpc::FromJsonString ( std::string_view json_string )

Parses Json to a protobuf message. Throws on unknown enum values and unknown fields by default.

Exceptions

formats::json::Exception on invalid json, field type mismatch, unknown enum values and unknown fields.

Definition at line 69 of file proto_json.hpp.

◆ FromJsonString() [2/2]

template<typename Message>

Message ugrpc::FromJsonString	(	std::string_view	json_string,
		const google::protobuf::util::JsonParseOptions &	options )

Parses Json to a protobuf message. Throws on unknown enum values.

Exceptions

formats::json::Exception on invalid json, field type mismatch and unknown enum values.

Definition at line 78 of file proto_json.hpp.

◆ IsServerError()

bool ugrpc::IsServerError ( grpc::StatusCode code )

noexcept

Whether a given status code is definitely a server-side error.

Currently includes:

UNKNOWN
UNIMPLEMENTED
INTERNAL
UNAVAILABLE
DATA_LOSS

We intentionally do not include CANCELLED and DEADLINE_EXPIRED here, because the situation may either be considered not erroneous at all (when a client explicitly cancels an RPC; when a client attempts an RPC with a very short deadline), or there is no single obvious service to blame (when the collective deadline expires for an RPC tree).

◆ IsValid() [1/3]

bool ugrpc::IsValid ( const google::protobuf::Duration & grpc_duration )

Checks if google::protobuf::Duration contains a valid value according to protobuf documentation.

Seconds must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years For durations of one second or more, a non-zero value for the nanos field must be of the same sign as seconds. Nanos must also be from -999,999,999 to +999,999,999 inclusive.

◆ IsValid() [2/3]

bool ugrpc::IsValid ( const google::protobuf::Timestamp & grpc_ts )

Checks if google::protobuf::Timestamp contains a valid value according to protobuf documentation.

The timestamp must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive and 'nanos' must be from 0 to 999,999,999 inclusive.

◆ IsValid() [3/3]

bool ugrpc::IsValid ( const google::type::Date & grpc_date )

Checks if google::type::Date contains a valid value according to protobuf documentation.

Year must be from 1 to 9999. Month must be from 1 to 12. Day must be from 1 to 31 and valid for the year and month.

◆ JsonToMessage() [1/2]

template<typename Message>

Message ugrpc::JsonToMessage ( const formats::json::Value & json )

Parses Json to a protobuf message. Throws on unknown enum values and unknown fields by default.

Exceptions

formats::json::Exception on field type mismatch, unknown enum values and unknown fields.

Definition at line 51 of file proto_json.hpp.

◆ JsonToMessage() [2/2]

template<typename Message>

Message ugrpc::JsonToMessage	(	const formats::json::Value &	json,
		const google::protobuf::util::JsonParseOptions &	options )

Parses Json to a protobuf message. Throws on unknown enum values.

Exceptions

formats::json::Exception on field type mismatch and unknown enum values.

Definition at line 60 of file proto_json.hpp.

◆ MessageToJson() [1/2]

formats::json::Value ugrpc::MessageToJson ( const google::protobuf::Message & message )

Returns formats::json::Value representation of protobuf message.

Exceptions

formats::json::Exception

◆ MessageToJson() [2/2]

formats::json::Value ugrpc::MessageToJson	(	const google::protobuf::Message &	message,
		const google::protobuf::util::JsonPrintOptions &	options )

Returns formats::json::Value representation of protobuf message.

Exceptions

formats::json::Exception

◆ ParseFromByteBuffer()

bool ugrpc::ParseFromByteBuffer	(	grpc::ByteBuffer &&	buffer,
		::google::protobuf::Message &	message )

Parse a Protobuf message from the wire format.

Parameters

buffer	the buffer that might be tempered with during deserialization
message	will contain the parsing result on success

Returns: true on success, false if buffer does not contain a valid message, according to the derived type of message

◆ SerializeToByteBuffer()

grpc::ByteBuffer ugrpc::SerializeToByteBuffer	(	const ::google::protobuf::Message &	message,
		std::size_t	block_size = kDefaultSerializeBlockSize )

Serialize a Protobuf message to the wire format.

Parameters

message	the message to serialize
block_size	can be used for performance tuning, too small chunk size results in extra allocations, too large chunk size results in wasting memory

Exceptions

std::runtime_error on serialization errors (supposedly only happens on extremely rare allocation failures or proto reflection malfunctioning).

◆ StatusCodeFromString()

grpc::StatusCode ugrpc::StatusCodeFromString ( std::string_view str )

Convert string to grpc::StatusCode.

Exceptions

std::runtime_error

◆ ToDuration()

template<class Duration = std::chrono::microseconds>

Duration ugrpc::ToDuration ( const google::protobuf::Duration & grpc_duration )

Creates std::chrono::duration from google::protobuf::Duration.

Exceptions

DurationConversionError if the value is not valid according to IsValid or does not fit the Duration.

Definition at line 154 of file datetime_utils.hpp.

◆ ToJsonString() [1/2]

std::string ugrpc::ToJsonString ( const google::protobuf::Message & message )

Returns Json-string representation of protobuf message.

Exceptions

formats::json::Exception

◆ ToJsonString() [2/2]

std::string ugrpc::ToJsonString	(	const google::protobuf::Message &	message,
		const google::protobuf::util::JsonPrintOptions &	options )

Returns Json-string representation of protobuf message.

Exceptions

formats::json::Exception

◆ ToLimitedDebugString() [1/2]

std::string ugrpc::ToLimitedDebugString	(	const google::protobuf::Message &	message,
		std::size_t	limit )

Convert protobuf message to limited debug string for logging.

Differences from built-in DebugString:

Fields marked with [debug_redact] option are hidden (DebugString only does so since Protobuf v30).
When the character limit is reached, serialization stops immediately (DebugString still wastes CPU on serializing the entire message regardless).

Parameters

message	The protobuf message to convert.
limit	Maximum size of the resulting string. Avoid setting this to very large values as it may cause OOM (Out of Memory) issues.

Returns: String representation of the message, truncated if necessary.

Warning: This is a debug representation of protobuf that is unstable and should only be used for diagnostics. The order of keys in maps is unstable; the format itself can change even within a single run. You CANNOT parse back from this debug text representation. You CANNOT use it for equality match with reference values in gtest.

◆ ToLimitedDebugString() [2/2]

std::string ugrpc::ToLimitedDebugString	(	const grpc::Status &	status,
		std::size_t	max_size = kDefaultDebugStringLimit )

Get error details from grpc::Status for logging with size limit.

Parameters

status	The `grpc::Status` to extract details from.
max_size	Maximum size of the resulting string. Avoid setting this to very large values as it may cause OOM (Out of Memory) issues.

Returns: String representation of error details, truncated if necessary.

Warning: This is a debug representation of protobuf that is unstable and should only be used for diagnostics. The order of keys in maps is unstable; the format itself can change even within a single run. You CANNOT parse back from this debug text representation. You CANNOT use it for equality match with reference values in gtest.

◆ ToProtoDate() [1/2]

template<class Duration>

google::type::Date ugrpc::ToProtoDate ( const std::chrono::time_point< std::chrono::system_clock, Duration > & system_tp )

Creates google::type::Date from std::chrono::time_point.

Exceptions

DateConversionError if the value is not valid according to IsValid.

Definition at line 122 of file datetime_utils.hpp.

◆ ToProtoDate() [2/2]

google::type::Date ugrpc::ToProtoDate ( const utils::datetime::Date & utils_date )

Creates google::type::Date from utils::datetime::Date.

Exceptions

DateConversionError if the value is not valid according to IsValid.

◆ ToProtoDuration()

template<class Rep, class Period>

google::protobuf::Duration ugrpc::ToProtoDuration ( const std::chrono::duration< Rep, Period > & duration )

Creates google::protobuf::Duration from std::chrono::duration.

Exceptions

DurationConversionError if the value is not valid according to IsValid.

Definition at line 174 of file datetime_utils.hpp.

◆ ToProtoTimestamp()

template<class Duration>

google::protobuf::Timestamp ugrpc::ToProtoTimestamp ( const std::chrono::time_point< std::chrono::system_clock, Duration > & system_tp )

Creates google::protobuf::Timestamp from std::chrono::time_point.

Exceptions

TimestampConversionError if the value is not valid according to IsValid.

Definition at line 41 of file datetime_utils.hpp.

◆ ToTimePoint() [1/2]

template<class Duration = std::chrono::system_clock::duration>

std::chrono::time_point< std::chrono::system_clock, Duration > ugrpc::ToTimePoint ( const google::protobuf::Timestamp & grpc_ts )

Creates std::chrono::system_clock::time_point from google::protobuf::Timestamp.

Exceptions

TimestampConversionError if the value is not valid according to IsValid or does not fit the time_point.

Definition at line 61 of file datetime_utils.hpp.

◆ ToTimePoint() [2/2]

std::chrono::time_point< std::chrono::system_clock, utils::datetime::Days > ugrpc::ToTimePoint ( const google::type::Date & grpc_date )

Creates std::chrono::system_clock::time_point from google::type::Date.

Exceptions

DateConversionError if the value is not valid according to IsValid.

◆ ToUnlimitedDebugString() [1/2]

std::string ugrpc::ToUnlimitedDebugString ( const google::protobuf::Message & message )

Convert protobuf message to unlimited debug string for logging.

Differences from built-in DebugString:

Fields marked with [debug_redact] option are hidden (DebugString only does so since Protobuf v30).

Parameters

message The protobuf message to convert.

Returns: String representation of the message.

Warning: This is a debug representation of protobuf that is unstable and should only be used for diagnostics. The order of keys in maps is unstable; the format itself can change even within a single run. You CANNOT parse back from this debug text representation. You CANNOT use it for equality match with reference values in gtest.

◆ ToUnlimitedDebugString() [2/2]

std::string ugrpc::ToUnlimitedDebugString ( const grpc::Status & status )

Get error details from grpc::Status for logging without size limit.

Parameters

status The grpc::Status to extract details from.

Returns: String representation of error details.

Warning: This is a debug representation of protobuf that is unstable and should only be used for diagnostics. The order of keys in maps is unstable; the format itself can change even within a single run. You CANNOT parse back from this debug text representation. You CANNOT use it for equality match with reference values in gtest.

◆ ToUtilsDate()

utils::datetime::Date ugrpc::ToUtilsDate ( const google::type::Date & grpc_date )

Creates utils::datetime::Date from google::type::Date.

Exceptions

DateConversionError if the value is not valid according to IsValid.

Variable Documentation

◆ kDefaultDebugStringLimit

std::size_t ugrpc::kDefaultDebugStringLimit = 1024

inlineconstexpr

Definition at line 14 of file protobuf_logging.hpp.

◆ kDefaultSerializeBlockSize

std::size_t ugrpc::kDefaultSerializeBlockSize = 4096

inlineconstexpr

See also: SerializeToByteBuffer

Definition at line 16 of file byte_buffer_utils.hpp.

Detailed Description

Namespaces

Classes

Typedefs

Functions

Variables

Typedef Documentation

◆ DescriptorList

◆ FieldDescriptorList

◆ FieldVisitCallback

◆ MessageVisitCallback

Function Documentation

◆ DurationToTimespec()

◆ FromJsonString() [1/2]

◆ FromJsonString() [2/2]

◆ IsServerError()

◆ IsValid() [1/3]

◆ IsValid() [2/3]

◆ IsValid() [3/3]

◆ JsonToMessage() [1/2]

◆ JsonToMessage() [2/2]

◆ MessageToJson() [1/2]

◆ MessageToJson() [2/2]

◆ ParseFromByteBuffer()

◆ SerializeToByteBuffer()

◆ StatusCodeFromString()

◆ ToDuration()

◆ ToJsonString() [1/2]

◆ ToJsonString() [2/2]

◆ ToLimitedDebugString() [1/2]

◆ ToLimitedDebugString() [2/2]

◆ ToProtoDate() [1/2]

◆ ToProtoDate() [2/2]

◆ ToProtoDuration()

◆ ToProtoTimestamp()

◆ ToTimePoint() [1/2]

◆ ToTimePoint() [2/2]

◆ ToUnlimitedDebugString() [1/2]

◆ ToUnlimitedDebugString() [2/2]

◆ ToUtilsDate()

Variable Documentation

◆ kDefaultDebugStringLimit

◆ kDefaultSerializeBlockSize