Concrete HTTP client for making requests to a specific host. More...

#include <HttpClient.hpp>

Public Member Functions
	HttpClient ()
	Default constructor for HttpClient.
	HttpClient (const std::string &host)
	Constructs an HttpClient with the specified host.
	HttpClient (const HttpClient &)=delete
HttpClient &	operator= (const HttpClient &)=delete
	HttpClient (HttpClient &&)=delete
HttpClient &	operator= (HttpClient &&)=delete
	~HttpClient ()
	Destroys the client, cancels requests associated with this client, and releases owned rate limits.
void	cancel_requests ()
	Cancels requests associated with this client and waits for cancellation callbacks.
void	wait_requests ()
	Waits until all requests associated with this client group finish.
bool	wait_requests_for (std::chrono::milliseconds timeout)
	Waits until all requests associated with this client group finish or timeout expires.
void	set_max_in_flight (std::size_t max_in_flight)
	Sets maximum number of requests this client may submit while its group is busy.
std::size_t	max_in_flight () const
	Returns this client's configured admission cap.
std::size_t	in_flight_requests () const
	Returns number of pending, active, and retry requests currently observed for this client group.
void	clear_rate_limit (RateLimitType type=RateLimitType::RL_GENERAL)
	Clears the configured rate limit of the specified type.
void	set_host (const std::string &host)
	Sets the host URL for the HTTP client.
void	set_headers (const kurlyk::Headers &headers)
	Sets the default headers for HTTP requests.
bool	assign_rate_limit_id (long limit_id, RateLimitType type=RateLimitType::RL_GENERAL)
	Assigns an existing rate limit to future requests by ID.
bool	assign_rate_limit_handle (const HttpRateLimitHandlePtr &limit, RateLimitType type=RateLimitType::RL_GENERAL)
	Assigns an existing rate-limit handle to future requests.
bool	set_rate_limit_id (long limit_id, RateLimitType type=RateLimitType::RL_GENERAL)
	Sets the rate limit ID for the HTTP request (alias for assign_rate_limit_id).
bool	set_rate_limit_handle (const HttpRateLimitHandlePtr &limit, RateLimitType type=RateLimitType::RL_GENERAL)
	Sets an existing rate-limit handle for future requests.
void	set_rate_limit (long requests_per_period, long period_ms, RateLimitType type=RateLimitType::RL_GENERAL, bool sequential=false)
	Creates and assigns an owned rate limit for future requests.
void	set_rate_limit_rpm (long requests_per_minute, RateLimitType type=RateLimitType::RL_GENERAL, bool sequential=false)
	Sets the rate limit based on requests per minute (RPM).
void	set_rate_limit_rps (long requests_per_second, RateLimitType type=RateLimitType::RL_GENERAL, bool sequential=false)
	Sets the rate limit based on requests per second (RPS).
void	set_rate_limit_key (const std::string &key)
	Sets the partition key for both rate limits (general and specific).
void	set_general_rate_limit_key (const std::string &key)
	Sets the partition key for the general rate limit.
void	set_specific_rate_limit_key (const std::string &key)
	Sets the partition key for the specific rate limit.
void	set_rate_limit_keys (const std::string &general_key, const std::string &specific_key)
	Sets independent partition keys for general and specific rate limits.
void	set_accept_encoding (bool identity=false, bool deflate=false, bool gzip=false, bool brotli=false)
	Sets the Accept-Encoding header.
void	set_accept_encoding (const std::string &value)
	Sets a custom Accept-Encoding header value.
void	set_accept_language (const std::string &value)
	Sets the Accept-Language header value.
void	set_content_type (const std::string &value)
	Sets the Content-Type header value.
void	set_origin (const std::string &value)
	Sets the Origin header value.
void	set_referer (const std::string &value)
	Sets the Referer header value.
void	set_dnt (const bool value)
	Sets the Do Not Track (DNT) header value.
void	set_follow_location (bool value)
	Configures whether to follow redirects automatically.
void	set_auto_referer (bool value)
	Configures whether to automatically set the Referer header on redirects.
void	set_proxy_tunnel (bool value)
	Configures whether to use a tunneling proxy for HTTP requests.
void	set_head_only (bool value)
	Configures whether to send only the HTTP headers (HEAD request).
void	set_streaming (bool streaming)
	Enables or disables intermediate callbacks for response body chunks.
void	set_proxy (const std::string &ip, int port, ProxyType type=ProxyType::PROXY_HTTP)
	Sets the proxy server address.
void	set_proxy (const std::string &ip, const int port, const std::string &username, const std::string &password, ProxyType type=ProxyType::PROXY_HTTP)
	Sets the proxy server address with authentication details.
void	set_proxy_auth (const std::string &username, const std::string &password)
	Sets proxy authentication credentials.
void	set_proxy_server (const std::string &server)
	Sets the proxy server address.
void	set_proxy_auth (const std::string &auth)
	Sets the proxy authentication credentials.
void	set_proxy_type (ProxyType type)
	Sets the proxy type.
void	set_retry_attempts (long retry_attempts, long retry_delay_ms)
	Sets retry attempts and delay between retries for HTTP requests.
void	add_valid_status (long status)
	Adds a valid HTTP status code to the request.
void	set_valid_statuses (const std::set< long > &statuses)
	Replaces all valid HTTP status codes for the request.
void	clear_valid_statuses ()
	Clears the set of valid HTTP status codes for the request.
void	set_user_agent (const std::string &user_agent)
	Sets the User-Agent header.
void	set_cookie (const std::string &cookie)
	Sets the cookie string for HTTP requests.
void	set_cert_file (const std::string &cert_file)
	Sets the client certificate file path.
void	set_ca_file (const std::string &ca_file)
	Sets the path to the CA certificate file.
void	set_timeout (long timeout)
	Sets the timeout duration for HTTP requests.
void	set_connect_timeout (long connect_timeout)
	Sets the connection timeout duration.
void	set_verbose (bool verbose)
	Enables or disables verbose output.
void	set_debug_header (bool debug_header)
	Enables or disables debug headers.
void	set_max_redirects (long max_redirects)
	Sets the maximum number of redirects for the client.
SubmitResult	submit_request (std::unique_ptr< HttpRequest > request_ptr, HttpResponseCallback callback)
	Attempts to submit a prepared request to the global HTTP manager.
bool	request (const std::string &method, const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content, HttpResponseCallback callback)
	Sends an HTTP request with the specified method, path, and parameters.
bool	request (const std::string &method, const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content, long specific_rate_limit_id, HttpResponseCallback callback)
	Sends an HTTP request with a temporary specific rate limit found by ID.
bool	request (const std::string &method, const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content, const HttpRateLimitHandlePtr &specific_rate_limit, HttpResponseCallback callback)
	Sends an HTTP request with a temporary specific rate limit.
bool	get (const std::string &path, const QueryParams &query, const Headers &headers, HttpResponseCallback callback)
	Sends a GET request.
bool	post (const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content, HttpResponseCallback callback)
	Sends a POST request.
bool	get (const std::string &path, const QueryParams &query, const Headers &headers, long specific_rate_limit_id, HttpResponseCallback callback)
	Sends a GET request with a temporary specific rate limit found by ID.
bool	get (const std::string &path, const QueryParams &query, const Headers &headers, const HttpRateLimitHandlePtr &specific_rate_limit, HttpResponseCallback callback)
	Sends a GET request with a temporary specific rate limit.
bool	post (const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content, long specific_rate_limit_id, HttpResponseCallback callback)
	Sends a POST request with a temporary specific rate limit found by ID.
bool	post (const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content, const HttpRateLimitHandlePtr &specific_rate_limit, HttpResponseCallback callback)
	Sends a POST request with a temporary specific rate limit.
std::future< HttpResponsePtr >	request (const std::string &method, const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content)
	Sends an HTTP request with a specified method, path, and parameters, and returns a future with the response.
std::future< HttpResponsePtr >	request (const std::string &method, const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content, long specific_rate_limit_id)
	Sends an HTTP request with a temporary specific rate limit found by ID and returns a future with the response.
std::future< HttpResponsePtr >	request (const std::string &method, const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content, const HttpRateLimitHandlePtr &specific_rate_limit)
	Sends an HTTP request with a temporary specific rate limit and returns a future with the response.
std::future< HttpResponsePtr >	get (const std::string &path, const QueryParams &query, const Headers &headers)
	Sends a GET request asynchronously and returns a future with the response.
std::future< HttpResponsePtr >	post (const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content)
	Sends a POST request asynchronously and returns a future with the response.
std::future< HttpResponsePtr >	get (const std::string &path, const QueryParams &query, const Headers &headers, long specific_rate_limit_id)
	Sends an asynchronous GET request with a temporary specific rate limit found by ID.
std::future< HttpResponsePtr >	post (const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content, long specific_rate_limit_id)
	Sends an asynchronous POST request with a temporary specific rate limit found by ID.
std::future< HttpResponsePtr >	get (const std::string &path, const QueryParams &query, const Headers &headers, const HttpRateLimitHandlePtr &specific_rate_limit)
	Sends an asynchronous GET request with a temporary specific rate limit.
std::future< HttpResponsePtr >	post (const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content, const HttpRateLimitHandlePtr &specific_rate_limit)
	Sends an asynchronous POST request with a temporary specific rate limit.

Private Member Functions
bool	request (std::unique_ptr< HttpRequest > request_ptr, HttpResponseCallback callback)
	Adds the request to the request manager and notifies the worker to process it.
void	set_header (const std::string &name, const std::string &value)
std::unique_ptr< HttpRequest >	make_request (const std::string &method, const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content) const
std::future< HttpResponsePtr >	submit_future_request (std::unique_ptr< HttpRequest > request_ptr)
std::future< void >	make_wait_requests_future ()
	Creates a future that becomes ready when all requests in this client group finish.
void	safe_submit_request (std::shared_ptr< std::promise< HttpResponsePtr > > promise, std::unique_ptr< HttpRequest > request_ptr, HttpResponseCallback callback)
	Submits a request and propagates any failure to the provided promise.

Static Private Member Functions
static void	safe_set_response (std::shared_ptr< std::promise< HttpResponsePtr > > promise, HttpResponsePtr response)
	Safely sets the response value on the given promise.
static HttpResponsePtr	make_submit_error_response (const SubmitResult &submit_result)
	Creates a ready HTTP response describing a synchronous submission rejection.
static void	ensure_initialized ()
	Ensures that the network worker and request manager are initialized.

Private Attributes
HttpRequest	m_request
	Request defaults shared by requests created by this client.
std::string	m_host
	The base host URL for the HTTP client.
bool	m_owns_general_rate_limit = false
	Flag indicating if the client owns the general rate limit.
bool	m_owns_specific_rate_limit = false
	Flag indicating if the client owns the specific rate limit.
std::mutex	m_submit_mutex
	Protects client-side submission settings and admission checks.
std::size_t	m_max_in_flight = 0
	Maximum number of in-flight requests for this client group, or 0 for disabled.

Detailed Description

Concrete HTTP client for making requests to a specific host.

Provides configuration helpers for rate limiting, proxy settings, retry logic, and request defaults.

Definition at line 17 of file HttpClient.hpp.

Constructor & Destructor Documentation

◆ HttpClient() [1/4]

kurlyk::HttpClient::HttpClient ( )

inline

Default constructor for HttpClient.

Definition at line 21 of file HttpClient.hpp.

◆ HttpClient() [2/4]

kurlyk::HttpClient::HttpClient ( const std::string & host )

inline

Constructs an HttpClient with the specified host.

Parameters

host	The base host URL for the HTTP client.

Definition at line 28 of file HttpClient.hpp.

◆ HttpClient() [3/4]

kurlyk::HttpClient::HttpClient ( const HttpClient & )

delete

◆ HttpClient() [4/4]

kurlyk::HttpClient::HttpClient ( HttpClient && )

delete

◆ ~HttpClient()

kurlyk::HttpClient::~HttpClient ( )

inline

Destroys the client, cancels requests associated with this client, and releases owned rate limits.

Warning: This method blocks until cancellation callback is delivered. It must not be called from the network worker thread.

Definition at line 42 of file HttpClient.hpp.

Member Function Documentation

◆ add_valid_status()

void kurlyk::HttpClient::add_valid_status ( long status )

inline

Adds a valid HTTP status code to the request.

Parameters

status The HTTP status code to allow.

Definition at line 510 of file HttpClient.hpp.

◆ assign_rate_limit_handle()

bool kurlyk::HttpClient::assign_rate_limit_handle	(	const HttpRateLimitHandlePtr &	limit,
		RateLimitType	type = RateLimitType::RL_GENERAL )

inline

Assigns an existing rate-limit handle to future requests.

Parameters

limit	Shared rate-limit handle to assign.
type	Rate limit type to configure.

Returns: True if the handle was assigned; false if the handle is empty.

Note: The client does not own externally assigned limits and will not release the manager-owned handle for them.

Definition at line 237 of file HttpClient.hpp.

◆ assign_rate_limit_id()

bool kurlyk::HttpClient::assign_rate_limit_id	(	long	limit_id,
		RateLimitType	type = RateLimitType::RL_GENERAL )

inline

Assigns an existing rate limit to future requests by ID.

Parameters

limit_id	The unique identifier of the rate limit to assign.
type	Rate limit type to configure.

Returns: True if the rate limit was found and assigned; false otherwise.

Definition at line 224 of file HttpClient.hpp.

◆ cancel_requests()

void kurlyk::HttpClient::cancel_requests ( )

inline

Cancels requests associated with this client and waits for cancellation callbacks.

Note: All requests created by one HttpClient share the same group_id.

Warning: This method blocks until cancellation callback is delivered. It must not be called from the network worker thread.

Definition at line 52 of file HttpClient.hpp.

◆ clear_rate_limit()

void kurlyk::HttpClient::clear_rate_limit ( RateLimitType type = RateLimitType::RL_GENERAL )

inline

Clears the configured rate limit of the specified type.

Parameters

type	Rate limit type to clear.

Definition at line 158 of file HttpClient.hpp.

◆ clear_valid_statuses()

void kurlyk::HttpClient::clear_valid_statuses ( )

inline

Clears the set of valid HTTP status codes for the request.

Definition at line 521 of file HttpClient.hpp.

◆ ensure_initialized()

void kurlyk::HttpClient::ensure_initialized ( )

inlinestaticprivate

Ensures that the network worker and request manager are initialized.

Definition at line 1079 of file HttpClient.hpp.

◆ get() [1/6]

std::future< HttpResponsePtr > kurlyk::HttpClient::get	(	const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers )

inline

Sends a GET request asynchronously and returns a future with the response.

Parameters

path	The URL path for the request.
query	The query arguments.
headers	The HTTP headers.

Returns: A future containing the HttpResponsePtr object.

Definition at line 841 of file HttpClient.hpp.

◆ get() [2/6]

std::future< HttpResponsePtr > kurlyk::HttpClient::get	(	const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const HttpRateLimitHandlePtr &	specific_rate_limit )

inline

Sends an asynchronous GET request with a temporary specific rate limit.

Parameters

path	URL path for the request.
query	Query parameters.
headers	Additional HTTP headers.
specific_rate_limit	Specific rate-limit handle applied only to this request.

Returns: A future containing the HttpResponsePtr object.

Definition at line 900 of file HttpClient.hpp.

◆ get() [3/6]

bool kurlyk::HttpClient::get	(	const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const HttpRateLimitHandlePtr &	specific_rate_limit,
		HttpResponseCallback	callback )

inline

Sends a GET request with a temporary specific rate limit.

Parameters

path	URL path for the request.
query	Query parameters.
headers	Additional HTTP headers.
specific_rate_limit	Specific rate-limit handle applied only to this request.
callback	Callback invoked when the request completes.

Returns: True if the request was accepted into the queue.

Definition at line 729 of file HttpClient.hpp.

◆ get() [4/6]

bool kurlyk::HttpClient::get	(	const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		HttpResponseCallback	callback )

inline

Sends a GET request.

Parameters

path	The URL path for the request.
query	The query arguments.
headers	The HTTP headers.
callback	The callback function to be called when the request is completed.

Returns: true if the request was successfully added to the RequestManager; false otherwise.

Definition at line 681 of file HttpClient.hpp.

◆ get() [5/6]

std::future< HttpResponsePtr > kurlyk::HttpClient::get	(	const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		long	specific_rate_limit_id )

inline

Sends an asynchronous GET request with a temporary specific rate limit found by ID.

Parameters

path	The URL path for the request.
query	The query arguments.
headers	The HTTP headers.
specific_rate_limit_id	ID of a registered rate limit.

Returns: A future containing the HttpResponsePtr object.

Note: If the ID is not found, the request is submitted without an additional specific limit.

Definition at line 869 of file HttpClient.hpp.

◆ get() [6/6]

bool kurlyk::HttpClient::get	(	const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		long	specific_rate_limit_id,
		HttpResponseCallback	callback )

inline

Sends a GET request with a temporary specific rate limit found by ID.

Parameters

path	The URL path for the request.
query	The query arguments.
headers	The HTTP headers.
specific_rate_limit_id	ID of a registered rate limit.
callback	The callback function to be called when the request is completed.

Returns: true if the request was successfully added to the RequestManager; false otherwise.

Note: If the ID is not found, the request is submitted without an additional specific limit.

Definition at line 713 of file HttpClient.hpp.

◆ in_flight_requests()

std::size_t kurlyk::HttpClient::in_flight_requests ( ) const

inline

Returns number of pending, active, and retry requests currently observed for this client group.

Returns: Number of currently managed requests with this client's group ID.

Note: This is a snapshot of HttpRequestManager state and may change immediately in concurrent code.

Definition at line 152 of file HttpClient.hpp.

◆ make_request()

std::unique_ptr< HttpRequest > kurlyk::HttpClient::make_request	(	const std::string &	method,
		const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content ) const

inlineprivate

Definition at line 950 of file HttpClient.hpp.

◆ make_submit_error_response()

HttpResponsePtr kurlyk::HttpClient::make_submit_error_response ( const SubmitResult & submit_result )

inlinestaticprivate

Creates a ready HTTP response describing a synchronous submission rejection.

Parameters

submit_result Submission result containing the rejection error code.

Returns: A ready HttpResponsePtr describing the rejection.

Definition at line 1039 of file HttpClient.hpp.

◆ make_wait_requests_future()

std::future< void > kurlyk::HttpClient::make_wait_requests_future ( )

inlineprivate

Creates a future that becomes ready when all requests in this client group finish.

Returns: A future that is satisfied when the group becomes idle.

Definition at line 989 of file HttpClient.hpp.

◆ max_in_flight()

std::size_t kurlyk::HttpClient::max_in_flight ( ) const

inline

Returns this client's configured admission cap.

Returns: Configured per-client admission cap, or 0 if disabled.

Definition at line 144 of file HttpClient.hpp.

◆ operator=() [1/2]

HttpClient & kurlyk::HttpClient::operator= ( const HttpClient & )

delete

◆ operator=() [2/2]

HttpClient & kurlyk::HttpClient::operator= ( HttpClient && )

delete

◆ post() [1/6]

std::future< HttpResponsePtr > kurlyk::HttpClient::post	(	const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content )

inline

Sends a POST request asynchronously and returns a future with the response.

Parameters

path	The URL path for the request.
query	The query arguments.
headers	The HTTP headers.
content	The request body content.

Returns: A future containing the HttpResponsePtr object.

Definition at line 854 of file HttpClient.hpp.

◆ post() [2/6]

std::future< HttpResponsePtr > kurlyk::HttpClient::post	(	const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		const HttpRateLimitHandlePtr &	specific_rate_limit )

inline

Sends an asynchronous POST request with a temporary specific rate limit.

Parameters

path	URL path for the request.
query	Query parameters.
headers	Additional HTTP headers.
content	Request body content.
specific_rate_limit	Specific rate-limit handle applied only to this request.

Returns: A future containing the HttpResponsePtr object.

Definition at line 915 of file HttpClient.hpp.

◆ post() [3/6]

bool kurlyk::HttpClient::post	(	const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		const HttpRateLimitHandlePtr &	specific_rate_limit,
		HttpResponseCallback	callback )

inline

Sends a POST request with a temporary specific rate limit.

Parameters

path	URL path for the request.
query	Query parameters.
headers	Additional HTTP headers.
content	Request body content.
specific_rate_limit	Specific rate-limit handle applied only to this request.
callback	Callback invoked when the request completes.

Returns: True if the request was accepted into the queue.

Definition at line 765 of file HttpClient.hpp.

◆ post() [4/6]

bool kurlyk::HttpClient::post	(	const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		HttpResponseCallback	callback )

inline

Sends a POST request.

Parameters

path	The URL path for the request.
query	The query arguments.
headers	The HTTP headers.
content	The request body content.
callback	The callback function to be called when the request is completed.

Returns: true if the request was successfully added to the RequestManager; false otherwise.

Definition at line 696 of file HttpClient.hpp.

◆ post() [5/6]

std::future< HttpResponsePtr > kurlyk::HttpClient::post	(	const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		long	specific_rate_limit_id )

inline

Sends an asynchronous POST request with a temporary specific rate limit found by ID.

Parameters

path	The URL path for the request.
query	The query arguments.
headers	The HTTP headers.
content	The request body content.
specific_rate_limit_id	ID of a registered rate limit.

Returns: A future containing the HttpResponsePtr object.

Note: If the ID is not found, the request is submitted without an additional specific limit.

Definition at line 885 of file HttpClient.hpp.

◆ post() [6/6]

bool kurlyk::HttpClient::post	(	const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		long	specific_rate_limit_id,
		HttpResponseCallback	callback )

inline

Sends a POST request with a temporary specific rate limit found by ID.

Parameters

path	The URL path for the request.
query	The query arguments.
headers	The HTTP headers.
content	The request body content.
specific_rate_limit_id	ID of a registered rate limit.
callback	The callback function to be called when the request is completed.

Returns: true if the request was successfully added to the RequestManager; false otherwise.

Note: If the ID is not found, the request is submitted without an additional specific limit.

Definition at line 747 of file HttpClient.hpp.

◆ request() [1/7]

std::future< HttpResponsePtr > kurlyk::HttpClient::request	(	const std::string &	method,
		const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content )

inline

Sends an HTTP request with a specified method, path, and parameters, and returns a future with the response.

Parameters

method	The HTTP method (e.g., "GET", "POST").
path	The URL path for the request.
query	The query arguments.
headers	The HTTP headers.
content	The request body content.

Returns: A future containing the HttpResponsePtr object.

Definition at line 782 of file HttpClient.hpp.

◆ request() [2/7]

std::future< HttpResponsePtr > kurlyk::HttpClient::request	(	const std::string &	method,
		const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		const HttpRateLimitHandlePtr &	specific_rate_limit )

inline

Sends an HTTP request with a temporary specific rate limit and returns a future with the response.

Parameters

method	HTTP method, e.g. "GET" or "POST".
path	URL path for the request.
query	Query parameters.
headers	Additional HTTP headers.
content	Request body content.
specific_rate_limit	Specific rate-limit handle applied only to this request.

Returns: A future containing the HttpResponsePtr object.

Definition at line 824 of file HttpClient.hpp.

◆ request() [3/7]

bool kurlyk::HttpClient::request	(	const std::string &	method,
		const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		const HttpRateLimitHandlePtr &	specific_rate_limit,
		HttpResponseCallback	callback )

inline

Sends an HTTP request with a temporary specific rate limit.

Parameters

method	HTTP method, e.g. "GET" or "POST".
path	URL path for the request.
query	Query parameters.
headers	Additional HTTP headers.
content	Request body content.
specific_rate_limit	Specific rate-limit handle applied only to this request.
callback	Callback invoked when the request completes.

Returns: True if the request was accepted into the queue.

Definition at line 662 of file HttpClient.hpp.

◆ request() [4/7]

bool kurlyk::HttpClient::request	(	const std::string &	method,
		const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		HttpResponseCallback	callback )

inline

Sends an HTTP request with the specified method, path, and parameters.

Parameters

method	The HTTP method (e.g., "GET", "POST").
path	The URL path for the request.
query	The query arguments.
headers	The HTTP headers.
content	The request body content.
callback	The callback function to be called when the request is completed.

Returns: true if the request was accepted into the queue; false if admission was rejected.

Definition at line 615 of file HttpClient.hpp.

◆ request() [5/7]

std::future< HttpResponsePtr > kurlyk::HttpClient::request	(	const std::string &	method,
		const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		long	specific_rate_limit_id )

inline

Sends an HTTP request with a temporary specific rate limit found by ID and returns a future with the response.

Parameters

method	The HTTP method (e.g., "GET", "POST").
path	The URL path for the request.
query	The query arguments.
headers	The HTTP headers.
content	The request body content.
specific_rate_limit_id	ID of a registered rate limit.

Returns: A future containing the HttpResponsePtr object.

Note: If the ID is not found, the request is submitted without an additional specific limit.

Definition at line 800 of file HttpClient.hpp.

◆ request() [6/7]

bool kurlyk::HttpClient::request	(	const std::string &	method,
		const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		long	specific_rate_limit_id,
		HttpResponseCallback	callback )

inline

Sends an HTTP request with a temporary specific rate limit found by ID.

Parameters

method	The HTTP method (e.g., "GET", "POST").
path	The URL path for the request.
query	The query arguments.
headers	The HTTP headers.
content	The request body content.
specific_rate_limit_id	ID of a registered rate limit.
callback	The callback function to be called when the request is completed.

Returns: true if the request was accepted into the queue; false if admission was rejected.

Note: If the ID is not found, the request is submitted without an additional specific limit.

Definition at line 635 of file HttpClient.hpp.

◆ request() [7/7]

bool kurlyk::HttpClient::request	(	std::unique_ptr< HttpRequest >	request_ptr,
		HttpResponseCallback	callback )

inlineprivate

Adds the request to the request manager and notifies the worker to process it.

Parameters

request_ptr	The HTTP request to be sent.
callback	The callback function to be called when the request is completed.

Returns: true if the request was successfully added to the RequestManager; false otherwise.

Definition at line 939 of file HttpClient.hpp.

◆ safe_set_response()

void kurlyk::HttpClient::safe_set_response	(	std::shared_ptr< std::promise< HttpResponsePtr > >	promise,
		HttpResponsePtr	response )

inlinestaticprivate

Safely sets the response value on the given promise.

Parameters

promise	Promise that receives the HTTP response.
response	Completed HTTP response to forward to the caller.

Definition at line 1017 of file HttpClient.hpp.

◆ safe_submit_request()

void kurlyk::HttpClient::safe_submit_request	(	std::shared_ptr< std::promise< HttpResponsePtr > >	promise,
		std::unique_ptr< HttpRequest >	request_ptr,
		HttpResponseCallback	callback )

inlineprivate

Submits a request and propagates any failure to the provided promise.

Parameters

promise	Promise to signal upon success or failure.
request_ptr	Prepared HTTP request to enqueue.
callback	Callback executed when the request completes.

Definition at line 1056 of file HttpClient.hpp.

◆ set_accept_encoding() [1/2]

void kurlyk::HttpClient::set_accept_encoding	(	bool	identity = false,
		bool	deflate = false,
		bool	gzip = false,
		bool	brotli = false )

inline

Sets the Accept-Encoding header.

Parameters

identity	Enable identity encoding.
deflate	Enable deflate encoding.
gzip	Enable gzip encoding.
brotli	Enable brotli encoding.

Definition at line 346 of file HttpClient.hpp.

◆ set_head_only()

void kurlyk::HttpClient::set_head_only ( bool value )

inline

Configures whether to send only the HTTP headers (HEAD request).

Parameters

value If true, the request will not download the response body (uses CURLOPT_NOBODY internally). Useful for measuring latency or checking resource availability without downloading content.

Definition at line 438 of file HttpClient.hpp.

◆ set_header()

void kurlyk::HttpClient::set_header	(	const std::string &	name,
		const std::string &	value )

inlineprivate

Definition at line 945 of file HttpClient.hpp.

◆ set_headers()

void kurlyk::HttpClient::set_headers ( const kurlyk::Headers & headers )

inline

Sets the default headers for HTTP requests.

Parameters

headers The headers to be included with each request.

Definition at line 188 of file HttpClient.hpp.

◆ set_host()

void kurlyk::HttpClient::set_host ( const std::string & host )

inline

Sets the host URL for the HTTP client.

Parameters

host	The base host URL for HTTP requests.

Definition at line 182 of file HttpClient.hpp.

◆ set_max_in_flight()

void kurlyk::HttpClient::set_max_in_flight ( std::size_t max_in_flight )

inline

Sets maximum number of requests this client may submit while its group is busy.

Parameters

max_in_flight Maximum observed managed requests for this client's group. 0 disables the limit.

Note: This is a per-client admission guard. It is checked before this HttpClient submits a request and does not enforce a global per-group invariant for requests submitted directly through HttpRequestManager or other producers.; Concurrent submissions through the same HttpClient are serialized for this admission check.

Definition at line 137 of file HttpClient.hpp.

◆ set_max_redirects()

void kurlyk::HttpClient::set_max_redirects ( long max_redirects )

inline

Sets the maximum number of redirects for the client.

Parameters

max_redirects The maximum number of redirects allowed.

Definition at line 575 of file HttpClient.hpp.

◆ set_origin()

void kurlyk::HttpClient::set_origin ( const std::string & value )

inline

Sets the Origin header value.

Parameters

value The origin to be sent with the Origin header.

Definition at line 400 of file HttpClient.hpp.

◆ set_proxy() [1/2]

void kurlyk::HttpClient::set_proxy	(	const std::string &	ip,
		const int	port,
		const std::string &	username,
		const std::string &	password,
		ProxyType	type = ProxyType::PROXY_HTTP )

inline

Sets the proxy server address with authentication details.

Parameters

ip	Proxy server IP address.
port	Proxy server port.
username	Proxy username.
password	Proxy password.
type	The type of proxy, defaulting to HTTP.

Definition at line 465 of file HttpClient.hpp.

◆ set_proxy() [2/2]

void kurlyk::HttpClient::set_proxy	(	const std::string &	ip,
		int	port,
		ProxyType	type = ProxyType::PROXY_HTTP )

inline

Sets the proxy server address.

Parameters

ip	Proxy server IP address.
port	Proxy server port.
type	The type of proxy, defaulting to HTTP.

Definition at line 452 of file HttpClient.hpp.

◆ set_proxy_auth() [1/2]

void kurlyk::HttpClient::set_proxy_auth ( const std::string & auth )

inline

Sets the proxy authentication credentials.

Parameters

auth	Proxy authentication in <username:password> format.

Definition at line 491 of file HttpClient.hpp.

◆ set_proxy_auth() [2/2]

void kurlyk::HttpClient::set_proxy_auth	(	const std::string &	username,
		const std::string &	password )

inline

Sets proxy authentication credentials.

Parameters

username	Proxy username.
password	Proxy password.

Definition at line 477 of file HttpClient.hpp.

◆ set_proxy_server()

void kurlyk::HttpClient::set_proxy_server ( const std::string & server )

inline

Sets the proxy server address.

Parameters

server Proxy address in <ip:port> format.

Definition at line 485 of file HttpClient.hpp.

◆ set_proxy_tunnel()

void kurlyk::HttpClient::set_proxy_tunnel ( bool value )

inline

Configures whether to use a tunneling proxy for HTTP requests.

Parameters

value If true, enables tunneling through the proxy server. Tunneling proxies are typically used for HTTPS requests to securely forward traffic.

Definition at line 431 of file HttpClient.hpp.

◆ set_proxy_type()

void kurlyk::HttpClient::set_proxy_type ( ProxyType type )

inline

Sets the proxy type.

Parameters

type	Type of proxy.

Definition at line 497 of file HttpClient.hpp.

◆ set_rate_limit()

void kurlyk::HttpClient::set_rate_limit	(	long	requests_per_period,
		long	period_ms,
		RateLimitType	type = RateLimitType::RL_GENERAL,
		bool	sequential = false )

inline

Creates and assigns an owned rate limit for future requests.

Parameters

requests_per_period	Maximum requests allowed within the period. 0 means unlimited.
period_ms	Period duration in milliseconds.
type	Rate limit type to configure.
sequential	When true, no other request sharing this limit may start until the current request (including all its retries) has finished.

Definition at line 285 of file HttpClient.hpp.

◆ set_rate_limit_handle()

bool kurlyk::HttpClient::set_rate_limit_handle	(	const HttpRateLimitHandlePtr &	limit,
		RateLimitType	type = RateLimitType::RL_GENERAL )

inline

Sets an existing rate-limit handle for future requests.

Parameters

limit	Shared rate-limit handle to assign.
type	Rate limit type to configure.

Returns: True if the handle was assigned; false if the handle is empty.

Definition at line 273 of file HttpClient.hpp.

◆ set_rate_limit_id()

bool kurlyk::HttpClient::set_rate_limit_id	(	long	limit_id,
		RateLimitType	type = RateLimitType::RL_GENERAL )

inline

Sets the rate limit ID for the HTTP request (alias for assign_rate_limit_id).

Parameters

limit_id	The unique identifier of the rate limit to assign.
type	Specifies the rate limit type (general or specific).

Returns: True if the rate limit was found and assigned; false otherwise.

Note: This method is an alias for assign_rate_limit_id.

Definition at line 263 of file HttpClient.hpp.

◆ set_rate_limit_key()

void kurlyk::HttpClient::set_rate_limit_key ( const std::string & key )

inline

Sets the partition key for both rate limits (general and specific).

Parameters

key	Partition key used to separate rate-limit state within the same limit ID. Empty string means the default shared state.

Definition at line 338 of file HttpClient.hpp.

◆ set_rate_limit_keys()

void kurlyk::HttpClient::set_rate_limit_keys	(	const std::string &	general_key,
		const std::string &	specific_key )

inline

Sets independent partition keys for general and specific rate limits.

Parameters

general_key	Partition key for the general rate limit.
specific_key	Partition key for the specific rate limit.

Definition at line 360 of file HttpClient.hpp.

◆ set_rate_limit_rpm()

void kurlyk::HttpClient::set_rate_limit_rpm	(	long	requests_per_minute,
		RateLimitType	type = RateLimitType::RL_GENERAL,
		bool	sequential = false )

inline

Sets the rate limit based on requests per minute (RPM).

Parameters

requests_per_minute	Maximum number of requests allowed per minute.
type	The type of rate limit (either general or specific).
sequential	When true, no other request sharing this limit may start until the current request (including all its retries) has finished.

Definition at line 314 of file HttpClient.hpp.

◆ set_rate_limit_rps()

void kurlyk::HttpClient::set_rate_limit_rps	(	long	requests_per_second,
		RateLimitType	type = RateLimitType::RL_GENERAL,
		bool	sequential = false )

inline

Sets the rate limit based on requests per second (RPS).

Parameters

requests_per_second	Maximum number of requests allowed per second.
type	The type of rate limit (either general or specific).
sequential	When true, no other request sharing this limit may start until the current request (including all its retries) has finished.

Definition at line 327 of file HttpClient.hpp.

◆ set_referer()

void kurlyk::HttpClient::set_referer ( const std::string & value )

inline

Sets the Referer header value.

Parameters

value The referer URL to be sent with the Referer header.

Definition at line 406 of file HttpClient.hpp.

◆ set_retry_attempts()

void kurlyk::HttpClient::set_retry_attempts	(	long	retry_attempts,
		long	retry_delay_ms )

inline

Sets retry attempts and delay between retries for HTTP requests.

Parameters

retry_attempts	Number of retry attempts.
retry_delay_ms	Delay in milliseconds between retry attempts.

Definition at line 504 of file HttpClient.hpp.

◆ set_specific_rate_limit_key()

void kurlyk::HttpClient::set_specific_rate_limit_key ( const std::string & key )

inline

Sets the partition key for the specific rate limit.

Parameters

key	Partition key used to separate specific rate-limit state. Empty string means the default shared state.

Definition at line 353 of file HttpClient.hpp.

◆ set_streaming()

void kurlyk::HttpClient::set_streaming ( bool streaming )

inline

Enables or disables intermediate callbacks for response body chunks.

Parameters

streaming Enable (true) or disable (false) streaming callbacks.

Definition at line 444 of file HttpClient.hpp.

◆ set_timeout()

void kurlyk::HttpClient::set_timeout ( long timeout )

inline

Sets the timeout duration for HTTP requests.

Parameters

timeout Timeout duration in seconds.

Definition at line 551 of file HttpClient.hpp.

◆ set_user_agent()

void kurlyk::HttpClient::set_user_agent ( const std::string & user_agent )

inline

Sets the User-Agent header.

Parameters

user_agent User-Agent string.

Definition at line 527 of file HttpClient.hpp.

◆ set_valid_statuses()

void kurlyk::HttpClient::set_valid_statuses ( const std::set< long > & statuses )

inline

Replaces all valid HTTP status codes for the request.

Parameters

statuses The set of HTTP status codes to allow.

Definition at line 516 of file HttpClient.hpp.

◆ set_verbose()

void kurlyk::HttpClient::set_verbose ( bool verbose )

inline

Enables or disables verbose output.

Parameters

verbose Enable (true) or disable (false) verbose output.

Definition at line 563 of file HttpClient.hpp.

◆ submit_future_request()

std::future< HttpResponsePtr > kurlyk::HttpClient::submit_future_request ( std::unique_ptr< HttpRequest > request_ptr )

inlineprivate

Definition at line 975 of file HttpClient.hpp.

◆ submit_request()

SubmitResult kurlyk::HttpClient::submit_request	(	std::unique_ptr< HttpRequest >	request_ptr,
		HttpResponseCallback	callback )

inline

Attempts to submit a prepared request to the global HTTP manager.

Parameters

request_ptr	Prepared HTTP request to be enqueued.
callback	Callback function to be called when the request is completed.

Returns: SubmitResult describing whether the request was accepted into the queue. Returns ClientError::QueueLimitExceeded when this client's max-in-flight admission cap is reached.

Definition at line 585 of file HttpClient.hpp.

◆ wait_requests()

void kurlyk::HttpClient::wait_requests ( )

inline

Waits until all requests associated with this client group finish.

Warning: Blocks until all callbacks for this client's group are delivered. Must not be called from the network worker thread.

Exceptions

std::logic_error If called from the network worker thread.

Definition at line 91 of file HttpClient.hpp.

◆ wait_requests_for()

bool kurlyk::HttpClient::wait_requests_for ( std::chrono::milliseconds timeout )

inline

Waits until all requests associated with this client group finish or timeout expires.

Parameters

timeout Maximum time to wait.

Returns: True if all requests finished; false on timeout or when called from the network worker thread.

Warning: Must not be called from the network worker thread.

Todo: A timed-out waiter callback remains registered in HttpRequestManager until the group becomes idle or shutdown fires. For rapid repeated calls this may accumulate callbacks.

Protects client-side submission settings and admission checks.

Definition at line 929 of file HttpClient.hpp.

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

include/kurlyk/http/HttpClient.hpp

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ HttpClient() [1/4]

◆ HttpClient() [2/4]

◆ HttpClient() [3/4]

◆ HttpClient() [4/4]

◆ ~HttpClient()

Member Function Documentation

◆ add_valid_status()

◆ assign_rate_limit_handle()

◆ assign_rate_limit_id()

◆ cancel_requests()

◆ clear_rate_limit()

◆ clear_valid_statuses()

◆ ensure_initialized()

◆ get() [1/6]

◆ get() [2/6]

◆ get() [3/6]

◆ get() [4/6]

◆ get() [5/6]

◆ get() [6/6]

◆ in_flight_requests()

◆ make_request()

◆ make_submit_error_response()

◆ make_wait_requests_future()

◆ max_in_flight()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ post() [1/6]

◆ post() [2/6]

◆ post() [3/6]

◆ post() [4/6]

◆ post() [5/6]

◆ post() [6/6]

◆ request() [1/7]

◆ request() [2/7]

◆ request() [3/7]

◆ request() [4/7]

◆ request() [5/7]

◆ request() [6/7]

◆ request() [7/7]

◆ safe_set_response()

◆ safe_submit_request()

◆ set_accept_encoding() [1/2]

◆ set_accept_encoding() [2/2]

◆ set_accept_language()

◆ set_auto_referer()

◆ set_ca_file()

◆ set_cert_file()

◆ set_connect_timeout()

◆ set_content_type()

◆ set_cookie()

◆ set_debug_header()

◆ set_dnt()

◆ set_follow_location()

◆ set_general_rate_limit_key()

◆ set_head_only()

◆ set_header()

◆ set_headers()

◆ set_host()

◆ set_max_in_flight()

◆ set_max_redirects()

◆ set_origin()

◆ set_proxy() [1/2]

◆ set_proxy() [2/2]

◆ set_proxy_auth() [1/2]

◆ set_proxy_auth() [2/2]

◆ set_proxy_server()

◆ set_proxy_tunnel()

◆ set_proxy_type()

◆ set_rate_limit()

◆ set_rate_limit_handle()

◆ set_rate_limit_id()

◆ set_rate_limit_key()

◆ set_rate_limit_keys()

◆ set_rate_limit_rpm()