Primary namespace for the Kurlyk library, encompassing initialization, request management, and utility functions. More...

Namespaces
namespace	core
namespace	http
namespace	startup
namespace	utils

Classes
struct	AuthResult
	Encapsulates the outcome of an authentication operation. More...
class	BaseWebSocketClient
	Base class implementing core functionality for WebSocket clients, managing events, states, and message sending. More...
class	Cookie
	Represents an HTTP cookie. More...
class	EmscriptenWebSocketClientAdapter
	A WebSocket client implementation using the Emscripten API. More...
class	HttpBatchRequestHandler
	Handles multiple asynchronous HTTP requests using libcurl's multi interface. More...
class	HttpClient
	Concrete HTTP client for making requests to a specific host. More...
class	HttpRateLimiter
	Manages rate limits for HTTP requests. More...
class	HttpRateLimitHandle
	RAII handle that owns a registered HTTP rate-limit ID. More...
class	HttpRequest
	Represents an HTTP request configuration. More...
class	HttpRequestContext
	Represents the context of an HTTP request, including the request object, callback function, retry attempts, and timing. More...
class	HttpRequestHandler
	Manages asynchronous HTTP requests, including handling responses, retries, and error processing. More...
class	HttpRequestManager
	Manages and processes HTTP requests using a singleton pattern. More...
class	HttpResponse
	Represents an HTTP response. More...
class	IWebSocketClient
	Legacy internal compatibility interface for full WebSocket client implementations. More...
class	IWebSocketSender
	Public sender abstraction used by WebSocketEventData::sender. More...
struct	OAuthConfig
	Stores client configuration for an OAuth2 Authorization Code + PKCE flow. More...
struct	OAuthToken
	Holds the result of an OAuth2 token exchange. More...
struct	RateLimitDelay
	Result type for time-until-allowed queries. More...
class	SimpleWebSocketClientAdapter
	A WebSocket client adapter that leverages the Simple WebSocket Server library for managing WebSocket connections. More...
class	SimpleWebSocketWorker
	Singleton worker that manages asynchronous WebSocket operations. More...
struct	SubmitResult
	Represents the synchronous result of trying to enqueue or submit work. More...
class	WebSocketClient
	Public facade for managing WebSocket connections, events, and message sending. More...
class	WebSocketConfig
	Configuration parameters for establishing and managing WebSocket connections. More...
class	WebSocketEventData
	Encapsulates data for a WebSocket event, providing information about event type, message, status, and errors. More...
class	WebSocketManager
	Manages backend-specific WebSocket client instances and coordinates their lifecycle. More...
class	WebSocketRateLimiter
	Manages rate limiting for WebSocket requests based on predefined limits. More...
class	WebSocketSendInfo
	Holds information for sending a WebSocket message, including rate limiting, close status, and a callback. More...

Typedefs
using	HttpRequestPtr = std::unique_ptr<HttpRequest>
	Owning pointer to an HTTP request.
using	HttpResponsePtr = std::unique_ptr<HttpResponse>
	Owning pointer to an HTTP response.
using	HttpResponseCallback = std::function<void(HttpResponsePtr response)>
	Callback invoked with an HTTP response.
using	HttpRateLimitHandlePtr = std::shared_ptr<HttpRateLimitHandle>
	Shared RAII handle for HTTP rate limits.
using	Headers = utils::CaseInsensitiveMultimap
	Alias for HTTP headers, providing a case-insensitive unordered multimap.
using	QueryParams = utils::CaseInsensitiveMultimap
	Alias for query parameters in HTTP requests, stored case-insensitively.
using	Cookies = utils::CaseInsensitiveCookieMultimap
	Alias for HTTP cookies, stored case-insensitively.
using	WebSocketClientPtr = std::shared_ptr<IWebSocketClient>
	Legacy shared-pointer alias for the internal compatibility interface.
using	WebSocketSenderPtr = std::shared_ptr<IWebSocketSender>
	Shared pointer alias for the sender abstraction used in WebSocketEventData.
using	selected_backend_client_ptr = std::shared_ptr<selected_backend_client_t>
	Shared pointer to the compile-time selected backend client type.
using	selected_backend_client_weak_ptr = std::weak_ptr<selected_backend_client_t>
	Weak pointer to the compile-time selected backend client type.

Enumerations
enum class	AuthError { None , InvalidConfig , HttpError , InvalidResponse , TokenExpired , UnsupportedFlow , StateMismatch }
	Classification of authentication errors. More...
enum class	ProxyType { PROXY_HTTP = 0 , PROXY_HTTPS , PROXY_HTTP_1_0 , PROXY_SOCKS4 , PROXY_SOCKS4A , PROXY_SOCKS5 , PROXY_SOCKS5_HOSTNAME }
	Enumeration of supported proxy types compatible with libcurl. More...
enum class	RateLimitType { RL_GENERAL , RL_SPECIFIC }
	Defines rate limit scope categories. More...
enum class	WebSocketEventType { WS_OPEN , WS_MESSAGE , WS_CLOSE , WS_ERROR }
	Types of WebSocket events. More...

Functions
HttpRateLimitHandlePtr	create_rate_limit (long requests_per_period, long period_ms, bool sequential=false)
	Creates a RAII rate-limit handle with specified parameters.
HttpRateLimitHandlePtr	create_rate_limit_rpm (long requests_per_minute, bool sequential=false)
	Creates a RAII rate-limit based on Requests Per Minute (RPM).
HttpRateLimitHandlePtr	create_rate_limit_rps (long requests_per_second, bool sequential=false)
	Creates a RAII rate-limit based on Requests Per Second (RPS).
HttpRateLimitHandlePtr	get_rate_limit (long limit_id)
	Returns a manager-owned rate-limit handle by ID.
bool	remove_limit (long limit_id)
	Releases manager-owned rate-limit handle by ID.
bool	remove_limit (const HttpRateLimitHandlePtr &limit)
	Releases manager-owned rate-limit handle.
uint64_t	generate_request_id ()
	Generates a new unique request ID.
uint64_t	generate_group_id ()
	Generates a new group ID.
void	set_max_pending_requests (std::size_t max_pending_requests)
	Sets the maximum number of requests accepted into the global pending queue.
std::size_t	max_pending_requests ()
	Returns the current global pending queue limit.
void	cancel_request_by_id (uint64_t request_id, std::function< void()> callback)
	Cancels a request by its unique identifier.
std::future< void >	cancel_request_by_id (uint64_t request_id)
	Cancels a request by its unique identifier and returns a future.
void	cancel_requests_by_group_id (uint64_t group_id, std::function< void()> callback)
	Cancels all requests with the specified group ID.
std::future< void >	cancel_requests_by_group_id (uint64_t group_id)
	Cancels all requests with the specified group ID and returns a future.
HttpResponsePtr	make_submit_error_response (const SubmitResult &submit_result)
	Creates a ready HTTP response describing a synchronous submission rejection.
void	safe_set_response (std::shared_ptr< std::promise< HttpResponsePtr > > promise, HttpResponsePtr response)
	Safely sets an HTTP response on the provided promise.
SubmitResult	submit_http_request (std::unique_ptr< HttpRequest > request_ptr, HttpResponseCallback callback)
	Attempts to submit an HTTP request and reports the admission result.
bool	http_request (std::unique_ptr< HttpRequest > request_ptr, HttpResponseCallback callback)
	Sends an HTTP request with callback.
std::future< HttpResponsePtr >	http_request (std::unique_ptr< HttpRequest > request_ptr)
	Sends an HTTP request asynchronously and returns a future with the response.
uint64_t	http_request (const std::string &method, const std::string &url, const QueryParams &query, const Headers &headers, const std::string &content, HttpResponseCallback callback)
	Sends an HTTP request with detailed parameters and a callback.
uint64_t	http_request (const std::string &method, const std::string &url, const QueryParams &query, const Headers &headers, const std::string &content, bool streaming, HttpResponseCallback callback)
	Sends an HTTP request with detailed parameters, streaming mode, and a callback.
std::pair< uint64_t, std::future< HttpResponsePtr > >	http_request (const std::string &method, const std::string &url, const QueryParams &query, const Headers &headers, const std::string &content)
	Sends an HTTP request asynchronously with detailed parameters and returns a future.
uint64_t	http_request (const std::string &method, const std::string &host, const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content, HttpResponseCallback callback)
	Sends an HTTP request with a specified host, path, and callback.
uint64_t	http_request (const std::string &method, const std::string &host, const std::string &path, const QueryParams &query, const Headers &headers, const std::string &content, bool streaming, HttpResponseCallback callback)
	Sends an HTTP request with host/path parameters, streaming mode, and a callback.
uint64_t	http_get (const std::string &url, const QueryParams &query, const Headers &headers, HttpResponseCallback callback)
	Sends an asynchronous HTTP GET request with a callback.
uint64_t	http_get (const std::string &url, const QueryParams &query, const Headers &headers, bool streaming, HttpResponseCallback callback)
	Sends an asynchronous HTTP GET request with streaming callbacks.
std::pair< uint64_t, std::future< HttpResponsePtr > >	http_get (const std::string &url, const QueryParams &query, const Headers &headers)
	Sends an asynchronous HTTP GET request and returns a future with the response.
uint64_t	http_post (const std::string &url, const QueryParams &query, const Headers &headers, const std::string &content, HttpResponseCallback callback)
	Sends an asynchronous HTTP POST request with a callback.
uint64_t	http_post (const std::string &url, const QueryParams &query, const Headers &headers, const std::string &content, bool streaming, HttpResponseCallback callback)
	Sends an asynchronous HTTP POST request with streaming callbacks.
std::pair< uint64_t, std::future< HttpResponsePtr > >	http_post (const std::string &url, const QueryParams &query, const Headers &headers, const std::string &content)
	Sends an asynchronous HTTP POST request and returns a future with the response.
void	init (const bool use_async=true)
	Initializes the Kurlyk library, setting up necessary managers and the network worker.
void	deinit ()
	Deinitializes the Kurlyk library, stopping async processing or cleaning up synchronous state.
void	process ()
	Processes pending requests (used in synchronous mode).
void	shutdown ()
	Shuts down all network operations, resetting the state of the network worker and clearing pending requests.
void	add_error_handler (::kurlyk::core::NetworkWorker::ErrorHandler handler)
	Registers a global error handler for the network worker.
const std::string &	to_str (ProxyType value) noexcept
	Converts a ProxyType enum value to its string representation.
const std::string &	to_str (RateLimitType value) noexcept
	Converts a RateLimitType enum value to its string representation.
const std::string &	to_str (WebSocketEventType value) noexcept
	Converts a WebSocketEventType enum value to its string representation.
template<typename T>
T	to_enum (const std::string &str)
	Template specialization to convert string to enum value.
template<>
ProxyType	to_enum< ProxyType > (const std::string &str)
template<>
RateLimitType	to_enum< RateLimitType > (const std::string &str)
template<>
WebSocketEventType	to_enum< WebSocketEventType > (const std::string &str)
std::ostream &	operator<< (std::ostream &os, ProxyType type)
std::ostream &	operator<< (std::ostream &os, RateLimitType type)
std::ostream &	operator<< (std::ostream &os, WebSocketEventType type)

Detailed Description

Primary namespace for the Kurlyk library, encompassing initialization, request management, and utility functions.

Typedef Documentation

◆ Cookies

using kurlyk::Cookies = utils::CaseInsensitiveCookieMultimap

Alias for HTTP cookies, stored case-insensitively.

Definition at line 68 of file CaseInsensitiveMultimap.hpp.

◆ Headers

using kurlyk::Headers = utils::CaseInsensitiveMultimap

Alias for HTTP headers, providing a case-insensitive unordered multimap.

Definition at line 62 of file CaseInsensitiveMultimap.hpp.

◆ HttpRateLimitHandlePtr

using kurlyk::HttpRateLimitHandlePtr = std::shared_ptr<HttpRateLimitHandle>

Shared RAII handle for HTTP rate limits.

Requests should store this pointer to keep the referenced rate limit alive while they are pending, active, or waiting for retry.

Definition at line 78 of file HttpRateLimitHandle.hpp.

◆ HttpRequestPtr

using kurlyk::HttpRequestPtr = std::unique_ptr<HttpRequest>

Owning pointer to an HTTP request.

Definition at line 293 of file HttpRequest.hpp.

◆ HttpResponseCallback

using kurlyk::HttpResponseCallback = std::function<void(HttpResponsePtr response)>

Callback invoked with an HTTP response.

Parameters

response Owning pointer to the HTTP response.

Definition at line 40 of file HttpResponse.hpp.

◆ HttpResponsePtr

using kurlyk::HttpResponsePtr = std::unique_ptr<HttpResponse>

Owning pointer to an HTTP response.

Definition at line 36 of file HttpResponse.hpp.

◆ QueryParams

using kurlyk::QueryParams = utils::CaseInsensitiveMultimap

Alias for query parameters in HTTP requests, stored case-insensitively.

Definition at line 65 of file CaseInsensitiveMultimap.hpp.

◆ selected_backend_client_ptr

using kurlyk::selected_backend_client_ptr = std::shared_ptr<selected_backend_client_t>

Shared pointer to the compile-time selected backend client type.

Definition at line 29 of file WebSocketManager.hpp.

◆ selected_backend_client_weak_ptr

using kurlyk::selected_backend_client_weak_ptr = std::weak_ptr<selected_backend_client_t>

Weak pointer to the compile-time selected backend client type.

Definition at line 31 of file WebSocketManager.hpp.

◆ WebSocketClientPtr

using kurlyk::WebSocketClientPtr = std::shared_ptr<IWebSocketClient>

Legacy shared-pointer alias for the internal compatibility interface.

Definition at line 80 of file IWebSocketClient.hpp.

◆ WebSocketSenderPtr

using kurlyk::WebSocketSenderPtr = std::shared_ptr<IWebSocketSender>

Shared pointer alias for the sender abstraction used in WebSocketEventData.

Definition at line 87 of file IWebSocketSender.hpp.

Enumeration Type Documentation

◆ AuthError

enum class kurlyk::AuthError

strong

Classification of authentication errors.

Enumerator
None	No error; operation succeeded.
InvalidConfig	Missing or invalid client configuration.
HttpError	HTTP request failed (non-2xx status or transport error).
InvalidResponse	Server response could not be parsed.
TokenExpired	The token has expired and refresh failed.
UnsupportedFlow	The requested OAuth flow is not supported.
StateMismatch	Returned state parameter does not match expected value.

Definition at line 19 of file AuthResult.hpp.

◆ ProxyType

enum class kurlyk::ProxyType

strong

Enumeration of supported proxy types compatible with libcurl.

Enumerator
PROXY_HTTP	HTTP proxy.
PROXY_HTTPS	HTTPS proxy.
PROXY_HTTP_1_0	HTTP/1.0 proxy.
PROXY_SOCKS4	SOCKS4 proxy.
PROXY_SOCKS4A	SOCKS4A proxy.
PROXY_SOCKS5	SOCKS5 proxy.
PROXY_SOCKS5_HOSTNAME	SOCKS5 proxy with hostname resolution.

Definition at line 12 of file enums.hpp.

◆ RateLimitType

enum class kurlyk::RateLimitType

strong

Defines rate limit scope categories.

Enumerator
RL_GENERAL	Applies globally to all requests.
RL_SPECIFIC	Applies to specific client/request.

Definition at line 24 of file enums.hpp.

◆ WebSocketEventType

enum class kurlyk::WebSocketEventType

strong

Types of WebSocket events.

Enumerator
WS_OPEN	Connection established.
WS_MESSAGE	Message received.
WS_CLOSE	Connection closed.
WS_ERROR	Error occurred.

Definition at line 31 of file enums.hpp.

Function Documentation

◆ add_error_handler()

void kurlyk::add_error_handler ( ::kurlyk::core::NetworkWorker::ErrorHandler handler )

inline

Registers a global error handler for the network worker.

Parameters

handler Callback invoked when an error is reported.

Definition at line 44 of file runtime.hpp.

◆ cancel_request_by_id() [1/2]

std::future< void > kurlyk::cancel_request_by_id ( uint64_t request_id )

inline

Cancels a request by its unique identifier and returns a future.

Parameters

request_id The unique identifier of the request to cancel.

Returns: A std::future<void> that becomes ready when the cancellation process is complete.

Definition at line 98 of file utils.hpp.

◆ cancel_request_by_id() [2/2]

void kurlyk::cancel_request_by_id	(	uint64_t	request_id,
		std::function< void()>	callback )

inline

Cancels a request by its unique identifier.

Parameters

request_id	The unique identifier of the request to cancel.
callback	An optional callback function to execute after cancellation.

Definition at line 90 of file utils.hpp.

◆ cancel_requests_by_group_id() [1/2]

std::future< void > kurlyk::cancel_requests_by_group_id ( uint64_t group_id )

inline

Cancels all requests with the specified group ID and returns a future.

Parameters

group_id The group identifier of requests to cancel.

Returns: A std::future<void> that becomes ready when the cancellation process is complete.

Definition at line 131 of file utils.hpp.

◆ cancel_requests_by_group_id() [2/2]

void kurlyk::cancel_requests_by_group_id	(	uint64_t	group_id,
		std::function< void()>	callback )

inline

Cancels all requests with the specified group ID.

Parameters

group_id	The group identifier of requests to cancel.
callback	An optional callback function to execute after cancellation.

Definition at line 123 of file utils.hpp.

◆ create_rate_limit()

HttpRateLimitHandlePtr kurlyk::create_rate_limit	(	long	requests_per_period,
		long	period_ms,
		bool	sequential = false )

inline

Creates a RAII rate-limit handle with specified parameters.

Parameters

requests_per_period	Maximum number of requests allowed within the specified period.
period_ms	Time period in milliseconds for the rate limit.
sequential	When true, no other request sharing this limit may start until the current request (including all its retries) has finished.

Returns: Handle for the created rate limit.

Definition at line 18 of file utils.hpp.

◆ create_rate_limit_rpm()

HttpRateLimitHandlePtr kurlyk::create_rate_limit_rpm	(	long	requests_per_minute,
		bool	sequential = false )

inline

Creates a RAII rate-limit based on Requests Per Minute (RPM).

Parameters

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

Returns: Handle for the created rate limit.

Definition at line 27 of file utils.hpp.

◆ create_rate_limit_rps()

HttpRateLimitHandlePtr kurlyk::create_rate_limit_rps	(	long	requests_per_second,
		bool	sequential = false )

inline

Creates a RAII rate-limit based on Requests Per Second (RPS).

Parameters

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

Returns: Handle for the created rate limit.

Definition at line 37 of file utils.hpp.

◆ deinit()

void kurlyk::deinit ( )

inline

Deinitializes the Kurlyk library, stopping async processing or cleaning up synchronous state.

Call this function after manual init(true) or init(false) before exiting the application.

Definition at line 26 of file runtime.hpp.

◆ generate_group_id()

uint64_t kurlyk::generate_group_id ( )

inline

Generates a new group ID.

Returns: A new group ID.

Definition at line 71 of file utils.hpp.

◆ generate_request_id()

uint64_t kurlyk::generate_request_id ( )

inline

Generates a new unique request ID.

Returns: A new unique request ID.

Definition at line 65 of file utils.hpp.

◆ get_rate_limit()

HttpRateLimitHandlePtr kurlyk::get_rate_limit ( long limit_id )

inline

Returns a manager-owned rate-limit handle by ID.

Note: Returns empty if the manager-owned handle was already released.

Definition at line 44 of file utils.hpp.

◆ http_get() [1/3]

std::pair< uint64_t, std::future< HttpResponsePtr > > kurlyk::http_get	(	const std::string &	url,
		const QueryParams &	query,
		const Headers &	headers )

inline

Sends an asynchronous HTTP GET request and returns a future with the response.

Parameters

url	The full request URL.
query	Query parameters for the GET request.
headers	HTTP headers to include.

Returns: A pair containing the unique request ID and a future with the response details.

Definition at line 450 of file utils.hpp.

◆ http_get() [2/3]

uint64_t kurlyk::http_get	(	const std::string &	url,
		const QueryParams &	query,
		const Headers &	headers,
		bool	streaming,
		HttpResponseCallback	callback )

inline

Sends an asynchronous HTTP GET request with streaming callbacks.

Parameters

url	Full request URL.
query	Query parameters for the GET request.
headers	HTTP headers to include.
streaming	If true, invokes callback for each received body chunk.
callback	Callback function invoked for chunks and request completion.

Returns: Unique identifier of the HTTP request if successfully added, or 0 on failure.

Definition at line 436 of file utils.hpp.

◆ http_get() [3/3]

uint64_t kurlyk::http_get	(	const std::string &	url,
		const QueryParams &	query,
		const Headers &	headers,
		HttpResponseCallback	callback )

inline

Sends an asynchronous HTTP GET request with a callback.

Parameters

url	The full request URL.
query	Query parameters for the GET request.
headers	HTTP headers to include.
callback	Callback function to be executed upon request completion.

Returns: The unique identifier of the HTTP request if successfully added, or 0 on failure.

Definition at line 421 of file utils.hpp.

◆ http_post() [1/3]

std::pair< uint64_t, std::future< HttpResponsePtr > > kurlyk::http_post	(	const std::string &	url,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content )

inline

Sends an asynchronous HTTP POST request and returns a future with the response.

Parameters

url	The full request URL.
query	Query parameters for the POST request.
headers	HTTP headers to include.
content	The body content for the POST request.

Returns: A pair containing the unique request ID and a future with the response details.

Definition at line 522 of file utils.hpp.

◆ http_post() [2/3]

uint64_t kurlyk::http_post	(	const std::string &	url,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		bool	streaming,
		HttpResponseCallback	callback )

inline

Sends an asynchronous HTTP POST request with streaming callbacks.

Parameters

url	Full request URL.
query	Query parameters for the POST request.
headers	HTTP headers to include.
content	Body content for the POST request.
streaming	If true, invokes callback for each received body chunk.
callback	Callback function invoked for chunks and request completion.

Returns: Unique identifier of the HTTP request if successfully added, or 0 on failure.

Definition at line 506 of file utils.hpp.

◆ http_post() [3/3]

uint64_t kurlyk::http_post	(	const std::string &	url,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		HttpResponseCallback	callback )

inline

Sends an asynchronous HTTP POST request with a callback.

Parameters

url	The full request URL.
query	Query parameters for the POST request.
headers	HTTP headers to include.
content	The body content for the POST request.
callback	Callback function to be executed upon request completion.

Returns: The unique identifier of the HTTP request if successfully added, or 0 on failure.

Definition at line 489 of file utils.hpp.

◆ http_request() [1/7]

uint64_t kurlyk::http_request	(	const std::string &	method,
		const std::string &	host,
		const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		bool	streaming,
		HttpResponseCallback	callback )

inline

Sends an HTTP request with host/path parameters, streaming mode, and a callback.

Parameters

method	HTTP method (e.g., "GET", "POST").
host	Host name or IP address.
path	URL path for the request.
query	Query parameters for the request.
headers	HTTP headers to include.
content	Body content for POST requests.
streaming	If true, invokes callback for each received body chunk.
callback	Callback function invoked for chunks and request completion.

Returns: Unique identifier of the HTTP request if successfully added, or 0 on failure.

Definition at line 388 of file utils.hpp.

◆ http_request() [2/7]

uint64_t kurlyk::http_request	(	const std::string &	method,
		const std::string &	host,
		const std::string &	path,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		HttpResponseCallback	callback )

inline

Sends an HTTP request with a specified host, path, and callback.

Parameters

method	HTTP method (e.g., "GET", "POST").
host	Host name or IP address.
path	URL path for the request.
query	Query parameters for the request.
headers	HTTP headers to include.
content	The body content for POST requests.
callback	Callback function to be executed upon request completion.

Returns: The unique identifier of the HTTP request if successfully added, or 0 on failure.

Definition at line 353 of file utils.hpp.

◆ http_request() [3/7]

std::pair< uint64_t, std::future< HttpResponsePtr > > kurlyk::http_request	(	const std::string &	method,
		const std::string &	url,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content )

inline

Sends an HTTP request asynchronously with detailed parameters and returns a future.

Parameters

method	HTTP method (e.g., "GET", "POST").
url	The full request URL.
query	Query parameters for the request.
headers	HTTP headers to include.
content	The body content for POST requests.

Returns: A pair containing the unique request ID and a future with the response details.

Definition at line 309 of file utils.hpp.

◆ http_request() [4/7]

uint64_t kurlyk::http_request	(	const std::string &	method,
		const std::string &	url,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		bool	streaming,
		HttpResponseCallback	callback )

inline

Sends an HTTP request with detailed parameters, streaming mode, and a callback.

Parameters

method	HTTP method (e.g., "GET", "POST").
url	Full request URL.
query	Query parameters for the request.
headers	HTTP headers to include.
content	Body content for POST requests.
streaming	If true, invokes callback for each received body chunk.
callback	Callback function invoked for chunks and request completion.

Returns: Unique identifier of the HTTP request if successfully added, or 0 on failure.

Definition at line 277 of file utils.hpp.

◆ http_request() [5/7]

uint64_t kurlyk::http_request	(	const std::string &	method,
		const std::string &	url,
		const QueryParams &	query,
		const Headers &	headers,
		const std::string &	content,
		HttpResponseCallback	callback )

inline

Sends an HTTP request with detailed parameters and a callback.

Parameters

method	HTTP method (e.g., "GET", "POST").
url	The full request URL.
query	Query parameters for the request.
headers	HTTP headers to include.
content	The body content for POST requests.
callback	Callback function to be executed upon request completion.

Returns: The unique identifier of the HTTP request if successfully added, or 0 on failure.

Definition at line 245 of file utils.hpp.

◆ http_request() [6/7]

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

inline

Sends an HTTP request asynchronously and returns a future with the response.

Parameters

request_ptr The HTTP request object with the request details.

Returns: A future containing the HttpResponsePtr with the response details.

Definition at line 219 of file utils.hpp.

◆ http_request() [7/7]

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

inline

Sends an HTTP request with callback.

Parameters

request_ptr	The HTTP request object with the request details.
callback	The callback function to be called upon request completion.

Returns: True if the request was successfully added to the manager, false otherwise.

Definition at line 210 of file utils.hpp.

◆ init()

void kurlyk::init ( const bool use_async = true )

inline

Initializes the Kurlyk library, setting up necessary managers and the network worker.

Parameters

use_async If true, enables asynchronous processing for requests. Call this function before using the library to ensure all components are initialized.

Definition at line 13 of file runtime.hpp.

◆ make_submit_error_response()

HttpResponsePtr kurlyk::make_submit_error_response ( const SubmitResult & submit_result )

inline

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 156 of file utils.hpp.

◆ max_pending_requests()

std::size_t kurlyk::max_pending_requests ( )

inline

Returns the current global pending queue limit.

Returns: Configured queue limit, or 0 if the queue is unbounded.

Definition at line 83 of file utils.hpp.

◆ operator<<() [1/3]

std::ostream & kurlyk::operator<<	(	std::ostream &	os,
		ProxyType	type )

inline

Definition at line 79 of file type_utils.hpp.

◆ operator<<() [2/3]

std::ostream & kurlyk::operator<<	(	std::ostream &	os,
		RateLimitType	type )

inline

Definition at line 83 of file type_utils.hpp.

◆ operator<<() [3/3]

std::ostream & kurlyk::operator<<	(	std::ostream &	os,
		WebSocketEventType	type )

inline

Definition at line 87 of file type_utils.hpp.

◆ process()

void kurlyk::process ( )

inline

Processes pending requests (used in synchronous mode).

This function should be called periodically if the library is used in synchronous mode.

Definition at line 32 of file runtime.hpp.

◆ remove_limit() [1/2]

bool kurlyk::remove_limit ( const HttpRateLimitHandlePtr & limit )

inline

Releases manager-owned rate-limit handle.

Note: Physical limit data may remain alive while requests still hold handles.

Returns: True if the rate limit was successfully removed, or false if the rate limit ID was not found.

Definition at line 59 of file utils.hpp.

◆ remove_limit() [2/2]

bool kurlyk::remove_limit ( long limit_id )

inline

Releases manager-owned rate-limit handle by ID.

Note: Physical limit data may remain alive while requests still hold handles.

Parameters

limit_id The unique identifier of the rate limit to be removed.

Returns: True if the rate limit was successfully removed, or false if the rate limit ID was not found.

Definition at line 52 of file utils.hpp.

◆ safe_set_response()

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

inline

Safely sets an HTTP response on the provided promise.

Parameters

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

Definition at line 172 of file utils.hpp.

◆ set_max_pending_requests()

void kurlyk::set_max_pending_requests ( std::size_t max_pending_requests )

inline

Sets the maximum number of requests accepted into the global pending queue.

Parameters

max_pending_requests Queue limit, or 0 to keep the queue unbounded.

Definition at line 77 of file utils.hpp.

◆ shutdown()

void kurlyk::shutdown ( )

inline

Shuts down all network operations, resetting the state of the network worker and clearing pending requests.

Use this function to stop all network operations and prepare the library for shutdown.

Definition at line 38 of file runtime.hpp.

◆ submit_http_request()

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

inline

Attempts to submit an HTTP request and reports the admission result.

Parameters

request_ptr	The HTTP request object with the request details.
callback	The callback function to be called upon request completion.

Returns: SubmitResult describing whether the request was accepted into the queue.

Definition at line 195 of file utils.hpp.

◆ to_enum()

template<typename T>

T kurlyk::to_enum ( const std::string & str )

Template specialization to convert string to enum value.

◆ to_enum< ProxyType >()

template<>

ProxyType kurlyk::to_enum< ProxyType > ( const std::string & str )

inline

Definition at line 40 of file type_utils.hpp.

◆ to_enum< RateLimitType >()

template<>

RateLimitType kurlyk::to_enum< RateLimitType > ( const std::string & str )

inline

Definition at line 56 of file type_utils.hpp.

◆ to_enum< WebSocketEventType >()

template<>

WebSocketEventType kurlyk::to_enum< WebSocketEventType > ( const std::string & str )

inline

Definition at line 67 of file type_utils.hpp.

◆ to_str() [1/3]

const std::string & kurlyk::to_str ( ProxyType value )

inlinenoexcept

Converts a ProxyType enum value to its string representation.

Definition at line 11 of file type_utils.hpp.

◆ to_str() [2/3]

const std::string & kurlyk::to_str ( RateLimitType value )

inlinenoexcept

Converts a RateLimitType enum value to its string representation.

Definition at line 20 of file type_utils.hpp.

◆ to_str() [3/3]

const std::string & kurlyk::to_str ( WebSocketEventType value )

inlinenoexcept

Converts a WebSocketEventType enum value to its string representation.

Definition at line 28 of file type_utils.hpp.

Namespaces

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ Cookies

◆ Headers

◆ HttpRateLimitHandlePtr

◆ HttpRequestPtr

◆ HttpResponseCallback

◆ HttpResponsePtr

◆ QueryParams

◆ selected_backend_client_ptr

◆ selected_backend_client_weak_ptr

◆ WebSocketClientPtr

◆ WebSocketSenderPtr

Enumeration Type Documentation

◆ AuthError

◆ ProxyType

◆ RateLimitType

◆ WebSocketEventType

Function Documentation

◆ add_error_handler()

◆ cancel_request_by_id() [1/2]

◆ cancel_request_by_id() [2/2]

◆ cancel_requests_by_group_id() [1/2]

◆ cancel_requests_by_group_id() [2/2]

◆ create_rate_limit()

◆ create_rate_limit_rpm()

◆ create_rate_limit_rps()

◆ deinit()

◆ generate_group_id()

◆ generate_request_id()

◆ get_rate_limit()

◆ http_get() [1/3]

◆ http_get() [2/3]

◆ http_get() [3/3]

◆ http_post() [1/3]

◆ http_post() [2/3]

◆ http_post() [3/3]

◆ http_request() [1/7]

◆ http_request() [2/7]

◆ http_request() [3/7]

◆ http_request() [4/7]

◆ http_request() [5/7]

◆ http_request() [6/7]

◆ http_request() [7/7]

◆ init()

◆ make_submit_error_response()

◆ max_pending_requests()

◆ operator<<() [1/3]

◆ operator<<() [2/3]

◆ operator<<() [3/3]

◆ process()

◆ remove_limit() [1/2]

◆ remove_limit() [2/2]

◆ safe_set_response()

◆ set_max_pending_requests()

◆ shutdown()

◆ submit_http_request()

◆ to_enum()

◆ to_enum< ProxyType >()

◆ to_enum< RateLimitType >()

◆ to_enum< WebSocketEventType >()

◆ to_str() [1/3]

◆ to_str() [2/3]

◆ to_str() [3/3]