Detailed Description

Client-side utilities.

Namespaces
namespace	middlewares

Classes
class	AbortedError

class	AlreadyExistsError

class	BaseError
	Base exception for all the client errors. More...

class	CallContext
	gRPC call context More...

class	CallOptions
	Options passed to interface calls. More...

class	CancelledError
	Concrete errors for all the error codes. More...

class	ClientFactory
	Creates gRPC clients. More...

class	ClientFactoryComponent
	Provides a ClientFactory in the component system. More...

struct	ClientFactorySettings
	Settings relating to the ClientFactory. More...

struct	ClientInfo
	Client meta info for a middleware construction. More...

struct	ClientQos

struct	ClientSettings
	Settings relating to creation of a code-generated client. More...

class	CommonComponent
	Contains common machinery that's required for all ugrpc clients. More...

class	DataLossError

class	DeadlineExceededError

class	ErrorWithStatus
	Error with grpc::Status details. More...

class	FailedPreconditionError

class	GenericClient
	Allows to talk to gRPC services (generic and normal) using dynamic method names. More...

struct	GenericOptions

struct	GlobalQos

class	InternalError

class	InvalidArgumentError

class	MiddlewareBase
	Base class for client gRPC middleware. More...

class	MiddlewareCallContext
	Context for middleware-specific data during gRPC call. More...

class	MiddlewarePipelineComponent
	Component to create middlewares pipeline. More...

class	NotFoundError

class	OutOfRangeError

class	PermissionDeniedError

struct	ProxySettings

struct	Qos
	Per-RPC quality-of-service config. Taken from ugrpc::client::ClientQos. Can also be passed to ugrpc client methods manually. More...

class	Reader
	Client-side interface for server-streaming. More...

class	ReaderWriter
	Client-side interface for bi-directional streaming. More...

class	ResourceExhaustedError

class	ResponseFuture
	Controls a single request -> single response RPC. More...

struct	RetryConfig
	Retry configuration for outgoing RPCs. More...

class	RetryLimiter
	Interface for controlling retry behavior based on request outcomes. More...

class	RetryLimiterFactory
	Abstract factory for creating RetryLimiter instances. More...

struct	RetryLimiterSettings
	Settings for a RetryLimiter instance. More...

class	RpcCancelledError
	RPC failed due to task cancellation. More...

class	RpcError
	Error during an RPC. More...

class	RpcInterruptedError
	RPC failed without a status. This means that either the call got cancelled using `TryCancel` or the channel is broken. Note: Deadline expiration throws ugrpc::client::DeadlineExceededError. More...

class	SimpleClientComponent
	Template class for a simple gRPC client. More...

class	StreamReadFuture
	StreamReadFuture for waiting a single read response from stream. More...

class	UnauthenticatedError

class	UnavailableError

class	UnimplementedError

class	UnknownError

class	Writer
	Client-side interface for client-streaming. More...

Typedefs
using	DedicatedMethodsConfig = std::unordered_map<std::string, std::size_t>

using	CompletionStatus = utils::expected<grpc::Status, SpecialCaseCompletionType>
	Result type for gRPC client call completion.

using	MiddlewareFactoryComponentBase
	Factory that creates specific client middlewares for clients.

template<typename Middleware>
using	SimpleMiddlewareFactoryComponent
	The alias for a short-cut client factory.

using	Middlewares = std::vector<std::shared_ptr<const MiddlewareBase>>
	A chain of middlewares.

Enumerations
enum class	AuthType { kInsecure , kSsl }
	Authentication method. More...

enum class	SpecialCaseCompletionType : std::uint8_t { kNetworkError , kTimeoutDeadlinePropagated , kCancelled , kAbandoned }
	Special completion types for gRPC client calls that don't result in a normal `grpc::Status`. More...

Functions
void	ThrowErrorWithStatus (std::string_view call_name, grpc::Status &&status)

AuthType	Parse (const yaml_config::YamlConfig &value, formats::parse::To< AuthType >)

std::shared_ptr< grpc::Channel >	MakeChannel (engine::TaskProcessor &blocking_task_processor, std::shared_ptr< grpc::ChannelCredentials > channel_credentials, const std::string &endpoint)
	Create a new gRPC channel (connection pool) for the endpoint.

template<typename Client>
bool	TryWaitForConnected (Client &client, engine::Deadline deadline, engine::TaskProcessor &blocking_task_processor)
	Wait until the channel state of `client` is `READY`. If the current state is already `READY`, returns `true` immediately. In case of multiple underlying channels, waits for all of them.

std::shared_ptr< grpc::ChannelCredentials >	GetClientCredentials (const ClientFactorySettings &client_factory_settings, const std::string &client_name)

bool	operator== (const GlobalQos &lhs, const GlobalQos &rhs) noexcept

GlobalQos	Parse (const formats::json::Value &value, formats::parse::To< GlobalQos >)

formats::json::Value	Serialize (const GlobalQos &, formats::serialize::To< formats::json::Value >)

bool	operator== (const ClientQos &lhs, const ClientQos &rhs) noexcept

ClientQos	Parse (const formats::json::Value &value, formats::parse::To< ClientQos >)

formats::json::Value	Serialize (const ClientQos &client_qos, formats::serialize::To< formats::json::Value >)

std::size_t	GetMethodChannelCount (const DedicatedMethodsConfig &dedicated_methods_config, std::string_view method_name)

std::string_view	ToString (SpecialCaseCompletionType type)
	Convert SpecialCaseCompletionType to string representation.

std::string_view	GetSpecialCaseCompletionTypeDescription (SpecialCaseCompletionType type)
	Convert SpecialCaseCompletionType to human-readable description.

components::ComponentList	MinimalComponentList ()
	Returns a list of components to do a minimal grpc client configuration.

components::ComponentList	DefaultComponentList ()
	Returns a list of components to do a default grpc client configuration.

template<typename Response>
std::optional< std::size_t >	ReadRemainingAndFinish (Reader< Response > &stream) noexcept
	Read all remaining messages from the stream and call `Finish`.

template<typename Request, typename Response>
std::optional< std::size_t >	ReadRemainingAndFinish (ReaderWriter< Request, Response > &stream) noexcept
	Announce end-of-input to the server, read all remaining messages from the stream and call `Finish`.

template<typename Request, typename Response>
bool	PingPongFinish (ReaderWriter< Request, Response > &stream) noexcept
	Gracefully finish a ping-pong style interaction.

bool	operator== (const Qos &lhs, const Qos &rhs) noexcept

Qos	Parse (const formats::json::Value &value, formats::parse::To< Qos >)

formats::json::Value	Serialize (const Qos &qos, formats::serialize::To< formats::json::Value >)

RetryConfig	Parse (const yaml_config::YamlConfig &value, formats::parse::To< RetryConfig >)

Typedef Documentation

◆ CompletionStatus

using ugrpc::client::CompletionStatus = utils::expected<grpc::Status, SpecialCaseCompletionType>

Result type for gRPC client call completion.

Type alias for CompletionStatus. Represents either a normal gRPC status (value) or a special completion case (error).

See also: SpecialCaseCompletionType; ugrpc::client::MiddlewareBase::PostFinish

Definition at line 68 of file completion_status.hpp.

◆ DedicatedMethodsConfig

using ugrpc::client::DedicatedMethodsConfig = std::unordered_map<std::string, std::size_t>

Definition at line 20 of file client_settings.hpp.

◆ Middlewares

using ugrpc::client::Middlewares = std::vector<std::shared_ptr<const MiddlewareBase>>

A chain of middlewares.

Definition at line 16 of file fwd.hpp.

Enumeration Type Documentation

◆ AuthType

enum class ugrpc::client::AuthType

strong

Authentication method.

Definition at line 13 of file auth_type.hpp.

◆ SpecialCaseCompletionType

enum class ugrpc::client::SpecialCaseCompletionType : std::uint8_t

strong

Special completion types for gRPC client calls that don't result in a normal grpc::Status.

This enum represents exceptional completion scenarios that occur during gRPC client calls when the RPC doesn't complete with a standard gRPC status. These cases are distinguished from normal status codes to provide more precise information about the nature of the failure.

See also: CompletionStatus

Enumerator
kNetworkError	Network-level error occurred before receiving a gRPC status. [special_cases_declaration] Indicates that the underlying network operation failed (e.g., connection lost, socket error) before the server could send a proper gRPC status response. This means that the underlying grpcpp framework returned an error. This is distinct from `grpc::StatusCode::UNAVAILABLE` which is a valid gRPC status.
kTimeoutDeadlinePropagated	Request timed out with deadline propagation enabled. This is distinguished from a regular `grpc::StatusCode::DEADLINE_EXCEEDED` to indicate that the timeout was due to propagated deadline from upstream request.
kCancelled	RPC was explicitly cancelled by the client.
kAbandoned	RPC was abandoned without proper completion. The RPC object was destroyed before the call could complete normally. This happens when: A streaming RPC object goes out of scope before `Finish()` is called An async call future is destroyed without calling `Get()` The client abandons the RPC without waiting for completion [special_cases_declaration]

Definition at line 26 of file completion_status.hpp.

Function Documentation

◆ MakeChannel()

std::shared_ptr< grpc::Channel > ugrpc::client::MakeChannel	(	engine::TaskProcessor &	blocking_task_processor,
		std::shared_ptr< grpc::ChannelCredentials >	channel_credentials,
		const std::string &	endpoint )

Create a new gRPC channel (connection pool) for the endpoint.

Channel creation is expensive, reuse channels if possible.

Each channel is fully thread-safe: it can be used across multiple threads, possibly from multiple clients and using multiple CompletionQueue instances at the same time.

Parameters

blocking_task_processor	task processor for blocking channel creation
channel_credentials	channel credentials
endpoint	string host:port

Returns: shared pointer to the gRPC channel

◆ PingPongFinish()

template<typename Request, typename Response>

bool ugrpc::client::PingPongFinish ( ReaderWriter< Request, Response > & stream )

nodiscardnoexcept

Gracefully finish a ping-pong style interaction.

Announces end-of-output to the server
Ensures there are no more messages to read

Warning: The method will hang indefenitely if the stream is never interrupted or closed by the server

Returns: true if the operation was successful; false if there are more messages in the stream to read or if the operation failed (i.e. due to task cancellation, the stream being already closed for writes, or the server returning an error status)

Definition at line 63 of file graceful_stream_finish.hpp.

◆ ReadRemainingAndFinish() [1/2]

template<typename Response>

std::optional< std::size_t > ugrpc::client::ReadRemainingAndFinish ( Reader< Response > & stream )

noexcept

Read all remaining messages from the stream and call Finish.

Warning: The method will hang indefenitely if the stream is never interrupted or closed by the server

Returns: the number of messages received from the stream; nullopt if the operation failed (i.e. due to task cancellation, the stream being already closed for reads, or the server returning an error status)

Definition at line 28 of file graceful_stream_finish.hpp.

◆ ReadRemainingAndFinish() [2/2]

template<typename Request, typename Response>

std::optional< std::size_t > ugrpc::client::ReadRemainingAndFinish ( ReaderWriter< Request, Response > & stream )

noexcept

Announce end-of-input to the server, read all remaining messages from the stream and call Finish.

Warning: The method will hang indefenitely if the stream is never interrupted or closed by the server

Returns: the number of messages received from the stream; nullopt if the operation failed (i.e. due to task cancellation, the stream being already closed for either reads or writes, or the server returning an error status)

Definition at line 43 of file graceful_stream_finish.hpp.

◆ TryWaitForConnected()

template<typename Client>

bool ugrpc::client::TryWaitForConnected	(	Client &	client,
		engine::Deadline	deadline,
		engine::TaskProcessor &	blocking_task_processor )

nodiscard

Wait until the channel state of client is READY. If the current state is already READY, returns true immediately. In case of multiple underlying channels, waits for all of them.

Returns: true if the state changed before deadline expired

Note: The wait operation does not support task cancellations

Definition at line 52 of file channels.hpp.