Detailed Description

Contains functions and types to start a userver based service/tool.

Classes
class	AuthCheckerSettings
	Component that loads auth configuration settings from a components::Secdist component if the latter was registered in components::ComponentList. More...
class	CachingComponentBase
	Base class for caching components. More...
class	ClickHouse
	ClickHouse client component. More...
class	ComponentBase
	Base class for all application components, it depends on components::Logger and components::Tracer. More...
class	ComponentConfig
	Represents the config of a component that is being constructed; see Component system for introduction into components. More...
class	ComponentContext
	Class to retrieve other components. More...
class	ComponentList
	A list to keep a unique list of components to start with components::Run(), utils::DaemonMain() or components::RunOnce(). More...
class	ComponentsLoadCancelledException
	Exception that is thrown from components::ComponentContext::FindComponent() if a component load failed. More...
class	Container
	A simple Component that creates, hold, and distributes an object of user type T. The component has a name equal to the constexpr std::string_view result of user-defined ContainerName(Of<T>{}). More...
class	DefaultSecdistProvider
	Component that stores security related data (keys, passwords, ...). More...
class	DumpConfigurator
	Helper component that manages common configuration for userver dumps. More...
class	DynamicConfig
	Component that stores the dynamic config. More...
class	DynamicConfigClient
	Component that starts a clients::dynamic_config::Client client. More...
class	DynamicConfigClientUpdater
	Component that does a periodic update of runtime configs. More...
class	DynamicConfigUpdatesSinkBase
	Base class for components acting as dynamic config updates sinks. More...
class	DynamicRedis
	Valkey and Redis dynamic client component, that does not require secdist. More...
class	FsCache
	Component for storing files in memory. More...
class	HttpClient
	Component that manages clients::http::ClientWithMiddlewares. More...
class	HttpClientCore
	Component that manages clients::http::ClientCore. More...
struct	InMemoryConfig
class	Logging
	Logging component More...
class	LoggingConfigurator
	Helper component to configure logging. More...
class	ManagerControllerComponent
	Component that prepares the engine internals and starts all the other components. More...
class	Mongo
	MongoDB client component. More...
class	MongoCache
	Base class for all caches polling mongo collection More...
class	MultiMongo
	Dynamically configurable MongoDB client component. More...
struct	Of
class	PostgreCache
	Caching component for PostgreSQL. See Caching Component for PostgreSQL. More...
class	Postgres
	PosgreSQL client component. More...
class	ProcessStarter
	Component for getting the engine::subprocess::ProcessStarter. More...
class	RabbitMQ
	RabbitMQ (AMQP 0.9.1) client component. More...
class	RawComponentBase
	The base class for all components. Don't use it for application components, use ComponentBase instead. More...
class	Redis
	Valkey and Redis client component. More...
class	Secdist
	Component that stores security related data (keys, passwords, ...). More...
class	Server
	Component that listens for incoming requests, manages incoming connections and passes the requests to the appropriate handler. More...
class	SingleThreadedTaskProcessors
	Component that starts multiple single threaded task processors. More...
class	SQLite
	SQLite client component. More...
class	State
class	StatisticsStorage
	Component that keeps a utils::statistics::Storage storage for metrics. More...
class	SystemStatisticsCollector
	Component for system resource usage statistics collection. More...
class	TcpAcceptorBase
	Component for accepting incoming TCP connections. More...
class	TestsuiteSupport
	Testsuite support component. More...
struct	WithType

Typedefs
using	LoggableComponentBase = ComponentBase
using	ComponentConfigMap = std::unordered_map<std::string, const ComponentConfig&>

Enumerations
enum class	ComponentHealth { kOk , kFallback , kFatal }
	State of the component. More...
enum class	ConfigFileMode { kRequired , kNotRequired }
enum class	ServiceLifetimeStage { kLoading , kOnAllComponentsLoadedIsRunning , kRunning , kGracefulShutdown , kOnAllComponentsAreStoppingIsRunning , kStopping }
	All components pass through these stages during the service lifetime. More...
enum class	ValidationMode { kOnlyTurnedOn , kAll }

Functions
void	Run (const std::string &config_path, const std::optional< std::string > &config_vars_path, const std::optional< std::string > &config_vars_override_path, const ComponentList &component_list)
void	Run (const InMemoryConfig &config, const ComponentList &component_list)
void	RunOnce (const std::string &config_path, const std::optional< std::string > &config_vars_path, const std::optional< std::string > &config_vars_override_path, const ComponentList &component_list)
void	RunOnce (const InMemoryConfig &config, const ComponentList &component_list)
void	RequestStop ()
ComponentList	MinimalServerComponentList ()
	Returns a list of components to start a basic HTTP server.
ComponentList	CommonComponentList ()
	Returns the most common list of components with runtime config updates and HTTP client.
ComponentList	CommonServerComponentList ()
	Returns the most common list of components to start a fully functional server.
ComponentConfig	Parse (const yaml_config::YamlConfig &value, formats::parse::To< ComponentConfig >)
std::string_view	GetCurrentComponentName (const ComponentContext &context)
	Equivalent to components::ComponentContext::GetComponentName, but works with forward declaration of the components::ComponentContext.
engine::TaskProcessor &	GetFsTaskProcessor (const ComponentConfig &config, const ComponentContext &context)
	Returns the config["fs-task-processor"] if it is set; otherwise returns the default blocking task processor that was set in components::ManagerControllerComponent.
template<typename T> requires (formats::common::impl::HasParse<yaml_config::YamlConfig, T> && std::is_class_v<T>)
T	LocateDependency (WithType< T >, const ComponentConfig &config, const ComponentContext &)
	A function that extracts an in-component-stored data (probably, reference) of type T, T&, or const T& from components::ComponentContext.
template<typename T> requires impl::ContainerHasName<T>
T &	LocateDependency (WithType< T >, const ComponentConfig &, const ComponentContext &context)
template<typename T> requires std::is_base_of_v<RawComponentBase, T>
T &	LocateDependency (WithType< T >, const ComponentConfig &, const ComponentContext &context)
ComponentList	MinimalComponentList ()
	Returns a list of components to do basic logging, component initialization and configuration.
std::string_view	ToString (ServiceLifetimeStage)
	Converts a components::ServiceLifetimeStage to debug string for logging.
ValidationMode	Parse (const yaml_config::YamlConfig &value, formats::parse::To< ValidationMode >)
dynamic_config::Source	LocateDependency (const components::WithType< dynamic_config::Source > &, const components::ComponentConfig &config, const components::ComponentContext &context)

Variables
template<>
constexpr bool	kHasValidate< HttpClient > = true
template<>
constexpr auto	kConfigFileMode< HttpClient > = ConfigFileMode::kNotRequired
template<>
constexpr bool	kHasValidate< Postgres > = true
template<>
constexpr bool	kHasValidate< Secdist > = true
template<>
constexpr auto	kConfigFileMode< Secdist > = ConfigFileMode::kNotRequired
template<>
constexpr bool	kHasValidate< DefaultSecdistProvider > = true
template<>
constexpr bool	kHasValidate< TestsuiteSupport > = true
template<>
constexpr bool	kHasValidate< HttpClientCore > = true
template<>
constexpr auto	kConfigFileMode< HttpClientCore > = ConfigFileMode::kNotRequired
template<>
constexpr bool	kHasValidate< DumpConfigurator > = true
template<>
constexpr bool	kHasValidate< FsCache > = true
template<>
constexpr bool	kHasValidate< LoggingConfigurator > = true
	}@
template<>
constexpr auto	kConfigFileMode< ManagerControllerComponent > = ConfigFileMode::kNotRequired
template<>
constexpr bool	kHasValidate< ProcessStarter > = true
template<typename Component>
constexpr bool	kHasValidate = false
template<typename Component>
constexpr bool	kForceNoValidation = false
template<typename Component>
constexpr auto	kConfigFileMode = impl::kDefaultConfigFileMode<Component>
template<>
constexpr bool	kHasValidate< SingleThreadedTaskProcessors > = true
template<>
constexpr bool	kHasValidate< StatisticsStorage > = true
template<>
constexpr auto	kConfigFileMode< StatisticsStorage > = ConfigFileMode::kNotRequired
template<>
constexpr bool	kHasValidate< DynamicConfigClient > = true
template<>
constexpr bool	kHasValidate< DynamicConfig > = true
template<>
constexpr auto	kConfigFileMode< DynamicConfig > = ConfigFileMode::kNotRequired
template<>
constexpr bool	kHasValidate< DynamicConfigClientUpdater > = true
template<>
constexpr bool	kHasValidate< Logging > = true
template<>
constexpr bool	kHasValidate< Server > = true
template<>
constexpr bool	kHasValidate< AuthCheckerSettings > = true
template<>
constexpr auto	kConfigFileMode< AuthCheckerSettings > = ConfigFileMode::kNotRequired
template<>
constexpr bool	kHasValidate< SystemStatisticsCollector > = true
const std::string	kFetchAndParseStage = "fetch_and_parse"
constexpr std::chrono::milliseconds	kCpuRelaxThreshold {10}
constexpr std::chrono::milliseconds	kCpuRelaxInterval {2}
template<class MongoCacheTraits>
constexpr bool	kHasValidate< MongoCache< MongoCacheTraits > > = true
template<>
constexpr bool	kHasValidate< Mongo > = true
template<>
constexpr bool	kHasValidate< MultiMongo > = true
template<typename PostgreCachePolicy>
constexpr bool	kHasValidate< PostgreCache< PostgreCachePolicy > > = true
template<>
constexpr bool	kHasValidate< Redis > = true
template<>
constexpr bool	kHasValidate< DynamicRedis > = true
template<>
constexpr bool	kHasValidate< ClickHouse > = true
template<typename Client>
constexpr bool	kHasValidate< ugrpc::client::SimpleClientComponent< Client > > = true
template<>
constexpr bool	kHasValidate< RabbitMQ > = true
template<>
constexpr bool	kHasValidate< urabbitmq::ConsumerComponentBase > = true
template<>
constexpr bool	kHasValidate< SQLite > = true

Typedef Documentation

◆ ComponentConfigMap

using components::ComponentConfigMap = std::unordered_map<std::string, const ComponentConfig&>

Definition at line 36 of file component_config.hpp.

◆ LoggableComponentBase

using components::LoggableComponentBase = ComponentBase

Deprecated: use components::ComponentBase instead.

Examples: samples/s3api/src/s3api_client.hpp.

Definition at line 83 of file component_base.hpp.

Enumeration Type Documentation

◆ ComponentHealth

enum class components::ComponentHealth

strong

State of the component.

Enumerator
kOk	component is alive and fine
kFallback	component in fallback state, but the service keeps working
kFatal	component is sick, service can not work without it

Definition at line 25 of file raw_component_base.hpp.

◆ ConfigFileMode

enum class components::ConfigFileMode

strong

Whether the static config for the component must always be present, or can be missing

Enumerator
kRequired	component must be setup in config
kNotRequired	component must be not setup in config

Definition at line 36 of file raw_component_base.hpp.

◆ ServiceLifetimeStage

enum class components::ServiceLifetimeStage

strong

All components pass through these stages during the service lifetime.

See also: Component system

Enumerator
kLoading	Constructors are running for all registered components. Components can depend on each other at this stage by calling components::ComponentContext::FindComponent and friends. If any component throws an exception, then the service transitions into ServiceLifetimeStage::kOnAllComponentsAreStoppingIsRunning stage.
kOnAllComponentsLoadedIsRunning	components::ComponentBase::OnAllComponentsLoaded (noop by default) is running for all components. This stage starts after constructors for all components have completed without an exception. The order of OnAllComponentsLoaded hooks invocations respects the order of components defined at ServiceLifetimeStage::kLoading stage.
kRunning	This stage marks that all OnAllComponentsLoaded hooks (as described in ServiceLifetimeStage::kOnAllComponentsLoadedIsRunning) have completed successfully (without an exception). At this point the service is fully running. This stage ends once the service receives a shutdown signal (SIGINT or SIGTERM).
kGracefulShutdown	The service performs a graceful shutdown if either graceful_shutdown_continue_accepting_requests_interval or graceful_shutdown_pending_requests_completion_interval is non-zero. First, it waits for graceful_shutdown_pending_requests_completion_interval unless the interval is zero. Second, it stops accepting new requests and continues processing of already running requests for graceful_shutdown_pending_requests_completion_interval unless the interval is zero. Then the normal shutdown procedure continues in ServiceLifetimeStage::kOnAllComponentsAreStoppingIsRunning. See also Graceful shutdown components::ManagerControllerComponent Example: components_manager: graceful_shutdown_continue_accepting_requests_interval: 10s graceful_shutdown_pending_requests_completion_interval: 5s
kOnAllComponentsAreStoppingIsRunning	components::ComponentBase::OnAllComponentsAreStopping (noop by default) is running for all components. This stage starts once the service has received a shutdown signal (see ServiceLifetimeStage::kRunning) and ServiceLifetimeStage::kGracefulShutdown stage (if any) has completed. If an error occurs during service startup, then OnAllComponentsAreStopping runs after components::ComponentBase::OnLoadingCancelled for all constructed components. The order of OnAllComponentsAreStopping hooks invocations respects the order of components defined at ServiceLifetimeStage::kLoading stage (they run in the reverse-dependency order).
kStopping	Destructors are running for all components. This stage starts once ServiceLifetimeStage::kOnAllComponentsAreStoppingIsRunning stage. If an error occurs during service startup, then destructors run after ServiceLifetimeStage::kOnAllComponentsAreStoppingIsRunning for all constructed components. The order of destructor invocations respects the order of components defined at ServiceLifetimeStage::kLoading stage (they run in the reverse-dependency order).

Definition at line 45 of file state.hpp.

◆ ValidationMode

enum class components::ValidationMode

strong

Definition at line 15 of file static_config_validator.hpp.

Function Documentation

◆ LocateDependency() [1/3]

template<typename T>
requires std::is_base_of_v<RawComponentBase, T>

T & components::LocateDependency	(	WithType< T >	,
		const ComponentConfig &	,
		const ComponentContext &	context )

Definition at line 103 of file container.hpp.

◆ LocateDependency() [2/3]

template<typename T>
requires impl::ContainerHasName<T>

T & components::LocateDependency	(	WithType< T >	,
		const ComponentConfig &	,
		const ComponentContext &	context )

Definition at line 96 of file container.hpp.

◆ LocateDependency() [3/3]

template<typename T>
requires (formats::common::impl::HasParse<yaml_config::YamlConfig, T> && std::is_class_v<T>)

T components::LocateDependency	(	WithType< T >	,
		const ComponentConfig &	config,
		const ComponentContext &	)

A function that extracts an in-component-stored data (probably, reference) of type T, T&, or const T& from components::ComponentContext.

You may define your own version of LocateDependency for a custom type T either in T's namespace or (if T's namespace is not extendable for some reason) in USERVER_NAMESPACE::components namespace. Usually it is defined for a component C that returns T from C::GetSomeT() as following:

dynamic_config::Source LocateDependency(
    const components::WithType<dynamic_config::Source>&,
    const components::ComponentConfig&,
    const components::ComponentContext& context
)
{
    return context.FindComponent<components::DynamicConfig>().GetSource();
}

Definition at line 89 of file container.hpp.

◆ RequestStop()

void components::RequestStop ( )

Requests stop of the component system. The service will be eventually stopped.

◆ Run() [1/2]

void components::Run	(	const InMemoryConfig &	config,
		const ComponentList &	component_list )

Starts a server with the provided component list and config. Reopens the logging files on SIGUSR1.

See also: utils::DaemonMain

◆ Run() [2/2]

void components::Run	(	const std::string &	config_path,
		const std::optional< std::string > &	config_vars_path,
		const std::optional< std::string > &	config_vars_override_path,
		const ComponentList &	component_list )

Starts a server with the provided component list and config loaded from file. Reopens the logging files on SIGUSR1.

See also: utils::DaemonMain

◆ RunOnce() [1/2]

void components::RunOnce	(	const InMemoryConfig &	config,
		const ComponentList &	component_list )

Runs the component list once with the config.

See also: utils::DaemonMain

◆ RunOnce() [2/2]

void components::RunOnce	(	const std::string &	config_path,
		const std::optional< std::string > &	config_vars_path,
		const std::optional< std::string > &	config_vars_override_path,
		const ComponentList &	component_list )