userver: clients::http::Request Class Reference
Loading...
Searching...
No Matches
clients::http::Request Class Referencefinal

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

Detailed Description

Class for creating and performing new http requests.

Definition at line 87 of file request.hpp.

Public Types

using Cookies
 Request cookies container type.
 

Public Member Functions

Requestmethod (HttpMethod method) &
 Specifies method.
 
Request method (HttpMethod method) &&
 
Requestget () &
 GET request.
 
Request get () &&
 
Requestget (const std::string &url) &
 GET request with url.
 
Request get (const std::string &url) &&
 
Requesthead () &
 HEAD request.
 
Request head () &&
 
Requesthead (const std::string &url) &
 HEAD request with url.
 
Request head (const std::string &url) &&
 
Requestpost () &
 POST request.
 
Request post () &&
 
Requestpost (const std::string &url, std::string data={}) &
 POST request with url and data.
 
Request post (const std::string &url, std::string data={}) &&
 
Requestpost (const std::string &url, Form &&form) &
 POST request with url and multipart/form-data.
 
Request post (const std::string &url, Form &&form) &&
 
Requestput () &
 PUT request.
 
Request put () &&
 
Requestput (const std::string &url, std::string data={}) &
 PUT request with url and data.
 
Request put (const std::string &url, std::string data={}) &&
 
Requestpatch () &
 PATCH request.
 
Request patch () &&
 
Requestpatch (const std::string &url, std::string data={}) &
 PATCH request with url and data.
 
Request patch (const std::string &url, std::string data={}) &&
 
Requestdelete_method () &
 DELETE request.
 
Request delete_method () &&
 
Requestdelete_method (const std::string &url) &
 DELETE request with url.
 
Request delete_method (const std::string &url) &&
 
Requestdelete_method (const std::string &url, std::string data) &
 DELETE request with url and data.
 
Request delete_method (const std::string &url, std::string data) &&
 
Requestset_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) &&
 
Requesturl (const std::string &url) &
 url if you don't specify request type with url
 
Request url (const std::string &url) &&
 
Requestdata (std::string data) &
 data for POST request
 
Request data (std::string data) &&
 
Requestform (Form &&form) &
 form for POST request
 
Request form (Form &&form) &&
 
Requestheaders (const Headers &headers) &
 Headers for request as map.
 
Request headers (const Headers &headers) &&
 
Requestheaders (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) &&
 
Requesthttp_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) &&
 
Requestproxy_headers (const Headers &headers) &
 Proxy headers for request as map.
 
Request proxy_headers (const Headers &headers) &&
 
Requestproxy_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) &&
 
Requestuser_agent (const std::string &value) &
 Sets the User-Agent header.
 
Request user_agent (const std::string &value) &&
 
Requestproxy (const std::string &value) &
 Sets proxy to use. Example: [::1]:1080.
 
Request proxy (const std::string &value) &&
 
Requestproxy_auth_type (ProxyAuthType value) &
 Sets proxy auth type to use.
 
Request proxy_auth_type (ProxyAuthType value) &&
 
Requestcookies (const Cookies &cookies) &
 Cookies for request as HashDos-safe map.
 
Request cookies (const Cookies &cookies) &&
 
Requestcookies (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) &&
 
Requestfollow_redirects (bool follow=true) &
 Follow redirects or not. Default: follow.
 
Request follow_redirects (bool follow=true) &&
 
Requesttimeout (long timeout_ms) &
 Set timeout in ms for request.
 
Request timeout (long timeout_ms) &&
 
Requesttimeout (std::chrono::milliseconds timeout_ms) &
 
Request timeout (std::chrono::milliseconds timeout_ms) &&
 
Requestverify (bool verify=true) &
 Verify host and peer or not. Default: verify.
 
Request verify (bool verify=true) &&
 
Requestca_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) &&
 
Requestca (crypto::Certificate cert) &
 Set CA.
 
Request ca (crypto::Certificate cert) &&
 
Requestcrl_file (const std::string &file_path) &
 Set CRL-file.
 
Request crl_file (const std::string &file_path) &&
 
Requestclient_key_cert (crypto::PrivateKey pkey, crypto::Certificate cert) &
 
Request client_key_cert (crypto::PrivateKey pkey, crypto::Certificate cert) &&
 
Requesthttp_version (HttpVersion version) &
 Set HTTP version.
 
Request http_version (HttpVersion version) &&
 
Requestretry (short retries=3, bool on_fails=true) &
 
Request retry (short retries=3, bool on_fails=true) &&
 
Requestunix_socket_path (const std::string &path) &
 
Request unix_socket_path (const std::string &path) &&
 
Requestuse_ipv4 () &
 Set CURL_IPRESOLVE_V4 for ipv4 resolving.
 
Request use_ipv4 () &&
 
Requestuse_ipv6 () &
 Set CURL_IPRESOLVE_V6 for ipv6 resolving.
 
Request use_ipv6 () &&
 
Requestconnect_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 &&)
 
RequestSetLoggedUrl (std::string url) &
 
Request SetLoggedUrl (std::string url) &&
 
RequestSetDestinationMetricName (const std::string &destination) &
 
Request SetDestinationMetricName (const std::string &destination) &&
 
RequestDisableReplyDecoding () &
 
Request DisableReplyDecoding () &&
 
void SetCancellationPolicy (CancellationPolicy cp)
 
RequestSetTracingManager (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< Responseperform (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.
 

Member Typedef Documentation

◆ Cookies

Initial value:
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)
.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
}
}
}
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)
.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
}
}
}
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.).

◆ SetTracingManager()

Request & clients::http::Request::SetTracingManager ( const tracing::TracingManagerBase & ) &

Override the default tracing manager from HTTP client for this particular request.

◆ 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: