clients::http::Request Class Reference

Table of Contents

• Public Types
• Public Member Functions
• Detailed Description
• Member Typedef Documentation
• Cookies
• Member Function Documentation
• async_perform()
• async_perform_stream_body()
• client_key_cert()
• connect_to() [1/2]
• connect_to() [2/2]
• DisableReplyDecoding()
• perform()
• retry()
• SetDestinationMetricName()
• SetLoggedUrl()
• timeout() [1/2]
• timeout() [2/2]
• unix_socket_path()

Class for creating and performing new http requests. More...

#include <userver/clients/http/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) &&
Request &	get () &
	GET request.
Request	get () &&
Request &	get (const std::string &url) &
	GET request with url.
Request	get (const std::string &url) &&
Request &	head () &
	HEAD request.
Request	head () &&
Request &	head (const std::string &url) &
	HEAD request with url.
Request	head (const std::string &url) &&
Request &	post () &
	POST request.
Request	post () &&
Request &	post (const std::string &url, std::string data={}) &
	POST request with url and data.
Request	post (const std::string &url, std::string data={}) &&
Request &	post (const std::string &url, const Form &form) &
	POST request with url and multipart/form-data.
Request	post (const std::string &url, const Form &form) &&
Request &	put () &
	PUT request.
Request	put () &&
Request &	put (const std::string &url, std::string data={}) &
	PUT request with url and data.
Request	put (const std::string &url, std::string data={}) &&
Request &	patch () &
	PATCH request.
Request	patch () &&
Request &	patch (const std::string &url, std::string data={}) &
	PATCH request with url and data.
Request	patch (const std::string &url, std::string data={}) &&
Request &	delete_method () &
	DELETE request.
Request	delete_method () &&
Request &	delete_method (const std::string &url) &
	DELETE request with url.
Request	delete_method (const std::string &url) &&
Request &	delete_method (const std::string &url, std::string data) &
	DELETE request with url and data.
Request	delete_method (const std::string &url, std::string data) &&
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) &&
Request &	url (const std::string &url) &
	url if you don't specify request type with url
Request	url (const std::string &url) &&
Request &	data (std::string data) &
	data for POST request
Request	data (std::string data) &&
Request &	form (const Form &form) &
	form for POST request
Request	form (const Form &form) &&
Request &	headers (const Headers &headers) &
	Headers for request as map.
Request	headers (const Headers &headers) &&
Request &	headers (const std::initializer_list< std::pair< std::string_view, std::string_view > > &headers) &
	Headers for request as list.
Request	headers (const std::initializer_list< std::pair< std::string_view, std::string_view > > &headers) &&
Request &	http_auth_type (HttpAuthType value, bool auth_only, std::string_view user, std::string_view password) &
	Sets http auth type to use.
Request	http_auth_type (HttpAuthType value, bool auth_only, std::string_view user, std::string_view password) &&
Request &	proxy_headers (const Headers &headers) &
	Proxy headers for request as map.
Request	proxy_headers (const Headers &headers) &&
Request &	proxy_headers (const std::initializer_list< std::pair< std::string_view, std::string_view > > &headers) &
	Proxy headers for request as list.
Request	proxy_headers (const std::initializer_list< std::pair< std::string_view, std::string_view > > &headers) &&
Request &	user_agent (const std::string &value) &
	Sets the User-Agent header.
Request	user_agent (const std::string &value) &&
Request &	proxy (const std::string &value) &
	Sets proxy to use. Example: [::1]:1080.
Request	proxy (const std::string &value) &&
Request &	proxy_auth_type (ProxyAuthType value) &
	Sets proxy auth type to use.
Request	proxy_auth_type (ProxyAuthType value) &&
Request &	cookies (const Cookies &cookies) &
	Cookies for request as HashDos-safe map.
Request	cookies (const Cookies &cookies) &&
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) &&
Request &	follow_redirects (bool follow=true) &
	Follow redirects or not. Default: follow.
Request	follow_redirects (bool follow=true) &&
Request &	timeout (long timeout_ms) &
	Set timeout in ms for request.
Request	timeout (long timeout_ms) &&
Request &	timeout (std::chrono::milliseconds timeout_ms) &
Request	timeout (std::chrono::milliseconds timeout_ms) &&
Request &	verify (bool verify=true) &
	Verify host and peer or not. Default: verify.
Request	verify (bool verify=true) &&
Request &	ca_info (const std::string &file_path) &
	Set file holding one or more certificates to verify the peer with.
Request	ca_info (const std::string &file_path) &&
Request &	ca (crypto::Certificate cert) &
	Set CA.
Request	ca (crypto::Certificate cert) &&
Request &	crl_file (const std::string &file_path) &
	Set CRL-file.
Request	crl_file (const std::string &file_path) &&
Request &	client_key_cert (crypto::PrivateKey pkey, crypto::Certificate cert) &
Request	client_key_cert (crypto::PrivateKey pkey, crypto::Certificate cert) &&
Request &	http_version (HttpVersion version) &
	Set HTTP version.
Request	http_version (HttpVersion version) &&
Request &	retry (short retries=3, bool on_fails=true) &
Request	retry (short retries=3, bool on_fails=true) &&
Request &	unix_socket_path (const std::string &path) &
Request	unix_socket_path (const std::string &path) &&
Request &	use_ipv4 () &
	Set CURL_IPRESOLVE_V4 for ipv4 resolving.
Request	use_ipv4 () &&
Request &	use_ipv6 () &
	Set CURL_IPRESOLVE_V6 for ipv6 resolving.
Request	use_ipv6 () &&
Request &	connect_to (const ConnectTo &connect_to) &
Request	connect_to (const ConnectTo &connect_to) &&
template<typename T >
std::enable_if_t< std::is_same_v< ConnectTo, T >, Request & >	connect_to (T &&)
Request &	SetLoggedUrl (std::string url) &
Request	SetLoggedUrl (std::string url) &&
Request &	SetDestinationMetricName (const std::string &destination) &
Request	SetDestinationMetricName (const std::string &destination) &&
Request &	DisableReplyDecoding () &
Request	DisableReplyDecoding () &&
Request &	SetTracingManager (const tracing::TracingManagerBase &) &
Request	SetTracingManager (const tracing::TracingManagerBase &) &&
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
const std::string &	GetData () const &
	Returns a reference to the HTTP body of a request to send.
const std::string &	GetData () &&=delete
std::string	ExtractData ()
	Returns HTTP body of a request, leaving it empty.

Detailed Description

Class for creating and performing new http requests.

Definition at line 87 of file request.hpp.

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 90 of file request.hpp.

Member Function Documentation

async_perform()

ResponseFuture clients::http::Request::async_perform

(

utils::impl::SourceLocation

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

)

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;
 
    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(clients::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()
	)

Perform a request with streamed response body.

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

See also

src/clients/http/partial_pesponse.hpp

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

Definition at line 265 of file request.hpp.

DisableReplyDecoding()

Request & clients::http::Request::DisableReplyDecoding

(

)

&

Disable auto-decoding of received replies. Useful to proxy replies 'as is'.

perform()

std::shared_ptr< Response > clients::http::Request::perform

(

utils::impl::SourceLocation

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

)

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(clients::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");
}

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. Usefull for "there's a secret in the query".

Warning

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

timeout() [1/2]

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

inline

Definition at line 209 of file request.hpp.

timeout() [2/2]

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

inline

Definition at line 212 of file request.hpp.

unix_socket_path()

Request & clients::http::Request::unix_socket_path

(

const std::string &

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