#include <userver/clients/http/request.hpp>

Detailed Description

Class for creating and performing new http requests, usually retieved from clients::http::Client.

Definition at line 82 of file request.hpp.

Public Types
using	Cookies = std::unordered_map<std::string, std::string, utils::StrCaseHash>
	Request cookies container type.

Public Member Functions
Request &	method (HttpMethod method) &
	Specifies method.

Request	method (HttpMethod method) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	get () &
	GET request.

Request	get () &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	get (std::string url) &
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request	get (std::string url) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	head () &
	HEAD request.

Request	head () &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	head (std::string url) &
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request	head (std::string url) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	post () &
	POST request.

Request	post () &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	post (std::string url, std::string data={}) &
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request	post (std::string url, std::string data={}) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	post (std::string url, Form &&form) &
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request	post (std::string url, Form &&form) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	put () &
	PUT request.

Request	put () &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	put (std::string url, std::string data={}) &
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request	put (std::string url, std::string data={}) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	patch () &
	PATCH request.

Request	patch () &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	patch (std::string url, std::string data={}) &
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request	patch (std::string url, std::string data={}) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	delete_method () &
	DELETE request.

Request	delete_method () &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	delete_method (std::string url) &
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request	delete_method (std::string url) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	delete_method (std::string url, std::string data) &
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request	delete_method (std::string url, std::string data) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	set_custom_http_request_method (std::string method) &
	Set custom request method. Only replaces name of the HTTP method.

Request	set_custom_http_request_method (std::string method) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	url (std::string url) &
	url if you don't specify request type with url

Request	url (std::string url) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	data (std::string data) &
	Set data for POST request.

Request	data (std::string data) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	form (Form &&form) &
	Set 'form' for POST request.

Request	form (Form &&form) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	headers (const Headers &headers) &
	Set headers for request.

Request	headers (const Headers &headers) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	headers (const std::initializer_list< std::pair< utils::zstring_view, utils::zstring_view > > &headers) &
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request	headers (const std::initializer_list< std::pair< utils::zstring_view, utils::zstring_view > > &headers) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	http_auth_type (HttpAuthType value, bool auth_only, utils::zstring_view user, utils::zstring_view password) &
	Sets http auth type to use.

Request	http_auth_type (HttpAuthType value, bool auth_only, utils::zstring_view user, utils::zstring_view password) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	proxy_headers (const Headers &headers) &
	Set proxy headers for request.

Request	proxy_headers (const Headers &headers) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	proxy_headers (const std::initializer_list< std::pair< utils::zstring_view, utils::zstring_view > > &headers) &
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request	proxy_headers (const std::initializer_list< std::pair< utils::zstring_view, utils::zstring_view > > &headers) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	user_agent (utils::zstring_view value) &
	Sets the User-Agent header.

Request	user_agent (utils::zstring_view value) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	proxy (utils::zstring_view value) &

Request	proxy (utils::zstring_view value) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	proxy_auth_type (ProxyAuthType value) &
	Sets proxy auth type to use.

Request	proxy_auth_type (ProxyAuthType value) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	cookies (const Cookies &cookies) &
	Cookies for request as HashDos-safe map.

Request	cookies (const Cookies &cookies) &&
	Cookies for request as HashDos-safe map.

Request &	cookies (const std::unordered_map< std::string, std::string > &cookies) &
	Cookies for request as map.

Request	cookies (const std::unordered_map< std::string, std::string > &cookies) &&
	Cookies for request as map.

Request &	follow_redirects (bool follow=true) &
	Follow redirects or not. Default: follow.

Request	follow_redirects (bool follow=true) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	timeout (long timeout_ms) &

Request	timeout (long timeout_ms) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	timeout (std::chrono::milliseconds timeout_ms) &
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request	timeout (std::chrono::milliseconds timeout_ms) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	verify (bool verify=true) &
	Verify host and peer or not. Default: verify.

Request	verify (bool verify=true) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	ca_info (utils::zstring_view file_path) &
	Set file holding one or more certificates to verify the peer with.

Request	ca_info (utils::zstring_view file_path) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	ca (crypto::Certificate cert) &
	Set CA.

Request	ca (crypto::Certificate cert) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	crl_file (utils::zstring_view file_path) &
	Set CRL-file.

Request	crl_file (utils::zstring_view file_path) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	client_key_cert (crypto::PrivateKey pkey, crypto::Certificate cert) &

Request	client_key_cert (crypto::PrivateKey pkey, crypto::Certificate cert) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	http_version (HttpVersion version) &
	Set HTTP version.

Request	http_version (HttpVersion version) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	retry (short retries=3, bool on_fails=true) &

Request	retry (short retries=3, bool on_fails=true) &&

Request &	unix_socket_path (utils::zstring_view path) &

Request	unix_socket_path (utils::zstring_view path) &&

Request &	use_ipv4 () &
	Set CURL_IPRESOLVE_V4 for ipv4 resolving.

Request	use_ipv4 () &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	use_ipv6 () &
	Set CURL_IPRESOLVE_V6 for ipv6 resolving.

Request	use_ipv6 () &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	connect_to (const ConnectTo &connect_to) &

Request	connect_to (const ConnectTo &connect_to) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename T>
std::enable_if_t< std::is_same_v< ConnectTo, T >, Request & >	connect_to (T &&)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	SetPluginsList (const std::vector< utils::NotNull< Plugin * > > &plugins) &
	Override list of plugins from components::HttpClient for specific request.

Request &	SetLoggedUrl (std::string url) &

Request	SetLoggedUrl (std::string url) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	SetUrlTemplate (std::string url_template) &

Request	SetUrlTemplate (std::string url_template) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	SetDestinationMetricName (const std::string &destination) &

Request	SetDestinationMetricName (const std::string &destination) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Request &	DisableReplyDecoding () &
	Disable auto-decoding of received replies. Useful to proxy replies 'as is'.

Request	DisableReplyDecoding () &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	SetCancellationPolicy (CancellationPolicy cp)

Request &	SetTracingManager (const tracing::TracingManagerBase &) &
	Override the default tracing manager from HTTP client for this particular request.

Request	SetTracingManager (const tracing::TracingManagerBase &) &&
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

ResponseFuture	async_perform (utils::impl::SourceLocation location=utils::impl::SourceLocation::Current())

StreamedResponse	async_perform_stream_body (const std::shared_ptr< concurrent::StringStreamQueue > &queue, utils::impl::SourceLocation location=utils::impl::SourceLocation::Current())
	Perform a request with streamed response body.

std::shared_ptr< Response >	perform (utils::impl::SourceLocation location=utils::impl::SourceLocation::Current())

const std::string &	GetUrl () const &
	Returns a reference to the original URL of a request.

const std::string &	GetUrl () &&=delete
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

const std::string &	GetData () const &
	Returns a reference to the HTTP body of a request to send.

const std::string &	GetData () &&=delete
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string	ExtractData ()
	Returns HTTP body of a request, leaving it empty.

Member Typedef Documentation

◆ Cookies

using clients::http::Request::Cookies = std::unordered_map<std::string, std::string, utils::StrCaseHash>

Request cookies container type.

Definition at line 85 of file request.hpp.

Member Function Documentation

◆ async_perform()

ResponseFuture clients::http::Request::async_perform ( utils::impl::SourceLocation location = utils::impl::SourceLocation::Current() )

nodiscard

Perform request asynchronously.

Works well with engine::WaitAny, engine::WaitAnyFor, and engine::WaitUntil functions:

std::size_t ProcessReadyRequests(std::vector<clients::http::ResponseFuture>& requests, engine::Deadline deadline) {
    std::size_t processed_requests = 0;
 
    while (auto indx = engine::WaitAnyUntil(deadline, requests)) {
        ++processed_requests;
 
        const std::shared_ptr<clients::http::Response> response = requests[*indx].Get();
        EXPECT_TRUE(response->IsOk());
    }
 
    return processed_requests;
}

Request object could be reused after retrieval of data from ResponseFuture, all the setup holds:

std::string DifferentUrlsRetry(
    std::string data,
    clients::http::Client& http,
    std::chrono::milliseconds timeout,
    std::initializer_list<std::string> urls_list
) {
    auto request = http.CreateRequest()
                       .post()
                       .data(std::move(data))  // no copying
                       .retry(1)
                       .http_version(USERVER_NAMESPACE::http::HttpVersion::k11)
                       .timeout(timeout);
 
    for (const auto& url : urls_list) {
        request.url(url);  // set URL
        auto future = request.async_perform();
 
        // ... do something while the request if being performed
 
        try {
            auto res = future.Get();
            if (res->IsOk()) {
                return std::move(*res).body();  // no copying
            }
        } catch (const clients::http::TimeoutException&) {
        }
    }
 
    throw std::runtime_error("No alive servers");
}

◆ async_perform_stream_body()

StreamedResponse clients::http::Request::async_perform_stream_body	(	const std::shared_ptr< concurrent::StringStreamQueue > &	queue,
		utils::impl::SourceLocation	location = utils::impl::SourceLocation::Current() )

nodiscard

Perform a request with streamed response body.

The HTTP client uses queue producer. StreamedResponse uses queue consumer.

◆ client_key_cert()

Request & clients::http::Request::client_key_cert	(	crypto::PrivateKey	pkey,
		crypto::Certificate	cert ) &

Set private client key and certificate for request.

Warning: Do not use this function on MacOS as it may cause Segmentation Fault on that platform.

◆ connect_to() [1/2]

Request & clients::http::Request::connect_to ( const ConnectTo & connect_to ) &

Set CURLOPT_CONNECT_TO option

Warning: connect_to argument must outlive Request

◆ connect_to() [2/2]

template<typename T>

std::enable_if_t< std::is_same_v< ConnectTo, T >, Request & > clients::http::Request::connect_to ( T && )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 318 of file request.hpp.

◆ perform()

std::shared_ptr< Response > clients::http::Request::perform ( utils::impl::SourceLocation location = utils::impl::SourceLocation::Current() )

nodiscard

Calls async_perform and wait for timeout_ms on a future. Default time for waiting will be timeout value if it was set. If error occurred it will be thrown as exception.

Request object could be reused after return from perform(), all the setup holds:

std::string DifferentUrlsRetry(
    std::string data,
    clients::http::Client& http,
    std::chrono::milliseconds timeout,
    std::initializer_list<std::string> urls_list
) {
    auto request = http.CreateRequest()
                       .post()
                       .data(std::move(data))  // no copying
                       .retry(1)
                       .http_version(USERVER_NAMESPACE::http::HttpVersion::k11)
                       .timeout(timeout);
 
    for (const auto& url : urls_list) {
        request.url(url);  // set URL
 
        try {
            auto res = request.perform();
            if (res->IsOk()) {
                return std::move(*res).body();  // no copying
            }
        } catch (const clients::http::TimeoutException&) {
        }
    }
 
    throw std::runtime_error("No alive servers");
}

Examples: libraries/easy/samples/4_custom_dependency/main.cpp, and libraries/easy/samples/5_pg_service_template/src/main.cpp.

◆ proxy()

Request & clients::http::Request::proxy ( utils::zstring_view value ) &

Sets proxy to use.

Example: [::1]:1080 Empty string disables proxy.

◆ retry()

Request & clients::http::Request::retry	(	short	retries = 3,
		bool	on_fails = true ) &

Specify number of retries on incorrect status, if on_fails is True retry on network error too. Retries = 3 means that maximum 3 request will be performed.

Retries use exponential backoff with jitter - an exponentially increasing randomized delay is added before each retry of this request.

◆ SetDestinationMetricName()

Request & clients::http::Request::SetDestinationMetricName ( const std::string & destination ) &

Set destination name in metric "httpclient.destinations.<name>". If not set, defaults to HTTP path. Should be called for all requests with parameters in HTTP path.

◆ SetLoggedUrl()

Request & clients::http::Request::SetLoggedUrl ( std::string url ) &

Override log URL. Useful for "there's a secret in the query".

Warning: The query might be logged by other intermediate HTTP agents (nginx, L7 balancer, etc.).

◆ SetUrlTemplate()

Request & clients::http::Request::SetUrlTemplate ( std::string url_template ) &

Set URL template (low-cardinality) for tracing, i.e. /v1/user/{user_id}

See also: https://opentelemetry.io/docs/specs/semconv/registry/attributes/url/

◆ timeout() [1/3]

Request & clients::http::Request::timeout ( long timeout_ms ) &

The maximum time in milliseconds for the entire transfer operation (from name lookup and connection construction to the end of data acquisition).

◆ timeout() [2/3]

Request & clients::http::Request::timeout ( std::chrono::milliseconds timeout_ms ) &

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 250 of file request.hpp.

◆ timeout() [3/3]

Request clients::http::Request::timeout ( std::chrono::milliseconds timeout_ms ) &&

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 252 of file request.hpp.

◆ unix_socket_path()

Request & clients::http::Request::unix_socket_path ( utils::zstring_view path ) &

Set unix domain socket as connection endpoint and provide path to it When enabled, request will connect to the Unix domain socket instead of establishing a TCP connection to a host.

The documentation for this class was generated from the following file:

userver/clients/http/request.hpp

Detailed Description

Public Types

Public Member Functions

Member Typedef Documentation

◆ Cookies

Member Function Documentation

◆ async_perform()

◆ async_perform_stream_body()

◆ client_key_cert()

◆ connect_to() [1/2]

◆ connect_to() [2/2]

◆ perform()

◆ proxy()

◆ retry()

◆ SetDestinationMetricName()

◆ SetLoggedUrl()

◆ SetUrlTemplate()

◆ timeout() [1/3]

◆ timeout() [2/3]

◆ timeout() [3/3]

◆ unix_socket_path()