ugrpc Namespace Reference

Detailed Description

Asynchronous gRPC driver.

Namespaces
namespace	client
	Client-side utilities.
namespace	server
	Server-side utilities.
namespace	tests
	userver gRPC testing facilities

Classes
struct	BadRequest
	Describes violations in a client request. This error type focuses on the syntactic aspects of the request. More...
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...
struct	DebugInfo
	Provides debugging information such as stack traces. 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...
struct	ErrorInfo
	Provides structured error information about the cause of an error. 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...
struct	FieldViolation
	Describes a single field validation error. More...
struct	Help
	Provides links to documentation and help resources. More...
struct	HelpLink
	Describes a single help link. More...
struct	LocalizedMessage
	Provides a localized error message that is safe to return to the user. 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...
struct	PreconditionFailure
	Describes preconditions that failed during request processing. More...
struct	PreconditionViolation
	Describes a single precondition violation. More...
struct	QuotaFailure
	Describes quota violations that caused the request to fail. More...
struct	QuotaViolation
	Describes a single quota violation. More...
struct	RequestInfo
	Contains metadata about the request for debugging and logging. More...
struct	ResourceInfo
	Provides information about a resource that is related to the error. More...
struct	RetryInfo
	Describes when the client can retry a failed request. More...
class	RichStatus
	A wrapper around google::rpc::Status that provides a convenient API for creating and managing gRPC status responses with rich error details. 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 (with GPR_TIMESPAN clock_type).
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 (with GPR_CLOCK_MONOTONIC clock_type).
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 73 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 82 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 55 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 64 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).
• When truncated, the string ends with ...(truncated) marker to indicate that the output was cut off.

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 error details part. Avoid setting this to very large values as it may cause OOM (Out of Memory) issues.

Returns

String representation of error details, formatted as "code: {code}, error message: {message}\nerror details:\n{details}". The error details part may be truncated if it exceeds max_size, in which case it ends with ...(truncated) marker.

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 173 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 60 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.