corespace::http_client Class Reference

Minimal, synchronous HTTP GET client built on libcurl. More...

#include <include/http_client.hpp>

Collaboration diagram for corespace::http_client:

Public Member Functions
	http_client ()
	Construct a client and initialize libcurl.
http_response	get (std::string_view url, const parameter_list &params={}, std::string_view override={})
	Perform an HTTP GET to url with optional query params.
http_response	post_form (std::string_view url, const parameter_list &form, const parameter_list &query={}, std::string_view override={})
http_response	post_raw (std::string_view url, std::string_view body, std::string_view content_type, const parameter_list &query={}, std::string_view override={})
const network_metrics &	metrics_info () const
	Access aggregated network metrics.

Private Types
using	curl_url_ptr = std::unique_ptr<CURLU, decltype(&curl_url_cleanup)>
	Unique pointer type for CURLU with proper deleter.

Private Member Functions
http_response	request_get (CURLU *url_handle, std::chrono::milliseconds &elapsed, std::string_view override={}) const
	Execute a single HTTP GET using the prepared URL handle.
http_response	request_post (CURLU *url_handle, std::chrono::milliseconds &elapsed, std::string_view content_type, std::string_view body, std::string_view override) const
std::string	build_form_body (const parameter_list &form) const
void	update_headers (http_response &response) const
	Refresh the header multimap from the last transfer.
void	update_metrics (const http_response &response, std::chrono::milliseconds elapsed)
	Update counters and histograms after an attempt.
long long	next_delay (int attempt) const
	Compute the next backoff delay for attempt (1-based).
void	apply_server_retry_hint (long long &sleep_ms) const
	Apply server-provided retry hint if present.

Static Private Member Functions
static curl_url_ptr	build_url (std::string_view url, const parameter_list &params)
	Construct a CURLU handle from url and append params.
static bool	status_good (const http_response &response)
	Success predicate: transport OK and HTTP 2xx.
static bool	status_retry (const http_response &response, bool net_ok)
	Retry predicate for transient outcomes.
static size_t	write_callback (const char *ptr, size_t size, size_t n, void *data)
	libcurl write callback: append chunk to response body.

Private Attributes
const network_options	opt {}
	Fixed options installed at construction.
network_metrics	metrics
	Aggregated metrics (atomic counters).
std::mutex	mu
std::unique_ptr< CURL, decltype(&curl_easy_cleanup)>	curl
	Reused easy handle (not thread-safe).
std::unique_ptr< curl_slist, decltype(&curl_slist_free_all)>	header_list
	Owned request header list.

Detailed Description

Minimal, synchronous HTTP GET client built on libcurl.

Responsibilities:

• Build request URLs with encoded query parameters.
• Issue HTTP GET requests with redirect following enabled.
• Apply bounded exponential backoff with jitter for retryable outcomes: network errors, 408 (Request Timeout), 429 (Too Many Requests), and 5xx.
• Aggregate lightweight, thread-safe network metrics.

Lifetime and thread-safety:

• A single easy handle (CURL*) is owned by the instance and reused across requests; therefore an http_client object is not thread-safe. Use one instance per calling thread.
• curl_global_init is performed once per process via std::call_once.

Definition at line 50 of file http_client.hpp.

Member Typedef Documentation

curl_url_ptr

using corespace::http_client::curl_url_ptr = std::unique_ptr<CURLU, decltype(&curl_url_cleanup)>

private

Unique pointer type for CURLU with proper deleter.

Definition at line 112 of file http_client.hpp.

Constructor & Destructor Documentation

http_client()

corespace::http_client::http_client ( )

explicit

Construct a client and initialize libcurl.

Effects:

• Ensures curl_global_init is called exactly once process-wide.
• Creates an easy handle and installs default options: user agent, Accept header, redirect following, transparent decoding, timeouts, and signal suppression.

Exceptions

std::runtime_error

if libcurl initialization fails or header allocation fails.

Definition at line 42 of file http_client.cpp.

                         {
    std::call_once(global_curl, curl_inited);
 
    curl.reset(curl_easy_init());
    if (!curl) {
        throw std::runtime_error("curl_easy_init failed");
    }
 
    const std::string accept_header = "Accept: " + opt.accept;
    curl_slist* headers = curl_slist_append(nullptr, accept_header.c_str());
    if (!headers) {
        throw std::runtime_error("failed to allocate curl headers");
    }
    header_list.reset(headers);
 
    curl_easy_setopt(curl.get(), CURLOPT_USERAGENT, opt.user_agent.c_str());
    curl_easy_setopt(curl.get(), CURLOPT_HTTPHEADER, header_list.get());
    curl_easy_setopt(curl.get(), CURLOPT_FOLLOWLOCATION, 1L);
    curl_easy_setopt(curl.get(), CURLOPT_ACCEPT_ENCODING, "");
    curl_easy_setopt(curl.get(), CURLOPT_NOSIGNAL, 1L);
    curl_easy_setopt(curl.get(), CURLOPT_TIMEOUT_MS, opt.timeout_ms);
    curl_easy_setopt(curl.get(), CURLOPT_CONNECTTIMEOUT_MS, opt.connect_ms);
}

References corespace::anonymous_namespace{http_client.cpp}::curl_inited(), and corespace::anonymous_namespace{http_client.cpp}::global_curl.

Here is the call graph for this function:

Member Function Documentation

apply_server_retry_hint()

void corespace::http_client::apply_server_retry_hint ( long long & sleep_ms ) const

private

Apply server-provided retry hint if present.

If CURLINFO_RETRY_AFTER yields a non-negative value, interpret it as seconds and raise sleep_ms to at least that many milliseconds.

Parameters

sleep_ms

In/out: proposed client backoff in milliseconds.

Definition at line 360 of file http_client.cpp.

                                                                   {
    curl_off_t retry_after = -1;
    if (curl_easy_getinfo(curl.get(), CURLINFO_RETRY_AFTER, &retry_after)
            == CURLE_OK
        && retry_after >= 0) {
        const long long server_hint_ms
            = std::chrono::duration_cast<std::chrono::milliseconds>(
                  std::chrono::seconds(retry_after)
            )
                  .count();
        sleep_ms = std::max(sleep_ms, server_hint_ms);
    }
}

Referenced by get(), post_form(), and post_raw().

Here is the caller graph for this function:

build_form_body()

std::string corespace::http_client::build_form_body ( const parameter_list & form ) const

private

Definition at line 292 of file http_client.cpp.

                                                                       {
    std::string body;
    bool first = true;
    for (const auto& [key, value] : form) {
        char* ekey = curl_easy_escape(
            curl.get(), key.c_str(), static_cast<int>(key.size())
        );
        char* evalue = curl_easy_escape(
            curl.get(), value.data(), static_cast<int>(value.size())
        );
        if (!first) {
            body.push_back('&');
        }
        body.append(ekey ? ekey : "");
        body.push_back('=');
        body.append(evalue ? evalue : "");
        if (ekey) {
            curl_free(ekey);
        }
        if (evalue) {
            curl_free(evalue);
        }
        first = false;
    }
    return body;
}

build_url()

http_client::curl_url_ptr corespace::http_client::build_url ( std::string_view url, const parameter_list & params )

staticprivate

Construct a CURLU handle from url and append params.

Each parameter is URL-encoded and appended via CURLU_APPENDQUERY.

Parameters

url	Base URL.
params	Query parameters.

Returns

Owning smart pointer to a configured CURLU handle.

Exceptions

std::runtime_error

if allocation or URL assembly fails.

Definition at line 173 of file http_client.cpp.

  {
    curl_url_ptr url_handle(curl_url(), &curl_url_cleanup);
    if (!url_handle) {
        throw std::runtime_error("curl_url failed");
    }
 
    const std::string url_copy(url);
    if (curl_url_set(url_handle.get(), CURLUPART_URL, url_copy.c_str(), 0)
        != CURLUE_OK) {
        throw std::runtime_error("failed to set request url");
    }
 
    for (const auto& [key, value] : params) {
        std::string parameter = key + "=" + std::string(value);
        if (curl_url_set(
                url_handle.get(), CURLUPART_QUERY, parameter.c_str(),
                CURLU_APPENDQUERY | CURLU_URLENCODE
            )
            != CURLUE_OK) {
            throw std::runtime_error("failed to append query parameter");
        }
    }
 
    return url_handle;
}

get()

http_response corespace::http_client::get	(	std::string_view	url,
		const parameter_list &	params = {},
		std::string_view	override = {} )

Perform an HTTP GET to url with optional query params.

Behavior:

• Builds a CURLU URL with params URL-encoded and appended.
• Executes the request; on non-2xx or transport errors, applies the retry policy up to opt.max_retries with jittered backoff and an optional server Retry-After hint.
• On success (2xx + CURLE_OK) returns the populated response.

Failure:

• If all attempts fail with a libcurl error, throws std::runtime_error("curl error: ...").
• If all attempts return non-success HTTP codes, throws std::runtime_error("http error: <status>").

Metrics:

• Updates metrics after each attempt (including retries).

Parameters

url	Absolute or base URL.
params	Optional list of query parameters to append.
override

Returns

http_response on success (2xx).

Exceptions

std::runtime_error

on terminal failure as described above.

Definition at line 68 of file http_client.cpp.

  {
    std::lock_guard lk(mu);
    const auto url_handle = build_url(url, params);
    for (int attempt = 1;; ++attempt) {
        std::chrono::milliseconds elapsed { 0l };
        http_response response
            = request_get(url_handle.get(), elapsed, override);
 
        update_metrics(response, elapsed);
 
        const bool net_ok = (response.error_code == CURLE_OK);
        if (status_good(response)) {
            return response;
        }
        if (attempt <= opt.max_retries && status_retry(response, net_ok)) {
            ++metrics.retries;
            long long sleep_ms = next_delay(attempt);
            apply_server_retry_hint(sleep_ms);
            metrics.sleep_ms += sleep_ms;
            std::this_thread::sleep_for(std::chrono::milliseconds(sleep_ms));
            continue;
        }
 
        if (!net_ok) {
            throw std::runtime_error("curl error: " + response.error_message);
        }
        throw std::runtime_error(
            "http error: " + std::to_string(response.status_code)
        );
    }
}

References apply_server_retry_hint(), corespace::http_response::error_code, next_delay(), status_good(), and update_metrics().

Here is the call graph for this function:

metrics_info()

const network_metrics & corespace::http_client::metrics_info ( ) const

nodiscard

Access aggregated network metrics.

Returns

Const reference to the metrics snapshot.

Definition at line 66 of file http_client.cpp.

{ return metrics; }

next_delay()

long long corespace::http_client::next_delay ( int attempt ) const

nodiscardprivate

Compute the next backoff delay for attempt (1-based).

Strategy: exponential backoff with full jitter. The base grows as retry_base_ms * 2^(attempt-1) and a uniform random component in [0, base] is added; the result is capped at retry_max_ms.

Parameters

attempt

Attempt number starting from 1.

Returns

Milliseconds to sleep before the next attempt.

Definition at line 354 of file http_client.cpp.

                                                         {
    const long long base = opt.retry_base_ms * (1 << (attempt - 1));
    std::uniform_int_distribution<long long> d(0, base);
    return std::min(base + d(rng()), opt.retry_max_ms);
}

Referenced by get(), post_form(), and post_raw().

Here is the caller graph for this function:

post_form()

http_response corespace::http_client::post_form	(	std::string_view	url,
		const parameter_list &	form,
		const parameter_list &	query = {},
		std::string_view	override = {} )

Definition at line 103 of file http_client.cpp.

  {
    std::lock_guard lk(mu);
    const auto url_handle = build_url(url, query);
    const std::string body = build_form_body(form);
    for (int attempt = 1;; ++attempt) {
        std::chrono::milliseconds elapsed { 0l };
        http_response response = request_post(
            url_handle.get(), elapsed, "application/x-www-form-urlencoded",
            body, override
        );
        update_metrics(response, elapsed);
        const bool net_ok = (response.error_code == CURLE_OK);
        if (status_good(response)) {
            return response;
        }
        if (attempt <= opt.max_retries && status_retry(response, net_ok)) {
            ++metrics.retries;
            long long sleep_ms = next_delay(attempt);
            apply_server_retry_hint(sleep_ms);
            metrics.sleep_ms += sleep_ms;
            std::this_thread::sleep_for(std::chrono::milliseconds(sleep_ms));
            continue;
        }
        if (!net_ok) {
            throw std::runtime_error("curl error: " + response.error_message);
        }
        throw std::runtime_error(
            "http error: " + std::to_string(response.status_code)
        );
    }
}

References apply_server_retry_hint(), corespace::http_response::error_code, next_delay(), status_good(), and update_metrics().

Here is the call graph for this function:

post_raw()

http_response corespace::http_client::post_raw	(	std::string_view	url,
		std::string_view	body,
		std::string_view	content_type,
		const parameter_list &	query = {},
		std::string_view	override = {} )

Definition at line 138 of file http_client.cpp.

  {
    std::lock_guard lk(mu);
    const auto url_handle = build_url(url, query);
    const std::string body_copy(body);
    for (int attempt = 1;; ++attempt) {
        std::chrono::milliseconds elapsed { 0l };
        http_response response = request_post(
            url_handle.get(), elapsed, content_type, body_copy, override
        );
        update_metrics(response, elapsed);
        const bool net_ok = (response.error_code == CURLE_OK);
        if (status_good(response)) {
            return response;
        }
        if (attempt <= opt.max_retries && status_retry(response, net_ok)) {
            ++metrics.retries;
            long long sleep_ms = next_delay(attempt);
            apply_server_retry_hint(sleep_ms);
            metrics.sleep_ms += sleep_ms;
            std::this_thread::sleep_for(std::chrono::milliseconds(sleep_ms));
            continue;
        }
        if (!net_ok) {
            throw std::runtime_error("curl error: " + response.error_message);
        }
        throw std::runtime_error(
            "http error: " + std::to_string(response.status_code)
        );
    }
}

References apply_server_retry_hint(), corespace::http_response::error_code, next_delay(), status_good(), and update_metrics().

Here is the call graph for this function:

request_get()

http_response corespace::http_client::request_get ( CURLU * url_handle, std::chrono::milliseconds & elapsed, std::string_view override = {} ) const

private

Execute a single HTTP GET using the prepared URL handle.

Side effects:

• Installs write callback to accumulate the response body.
• Measures elapsed steady-clock time and returns it via elapsed.
• Reads HTTP status and headers after the transfer.

Parameters

url_handle	Prepared CURLU handle (owned by caller).
elapsed	Out: time spent in curl_easy_perform.
override

Returns

Populated http_response (may carry a libcurl error).

Definition at line 201 of file http_client.cpp.

        {
    using namespace std::chrono;
 
    http_response response;
 
    curl_slist* tmp_headers = nullptr;
    if (!override.empty()) {
        const std::string h = "Accept: " + std::string(override);
        tmp_headers = curl_slist_append(nullptr, h.c_str());
        curl_easy_setopt(curl.get(), CURLOPT_HTTPHEADER, tmp_headers);
    } else {
        curl_easy_setopt(curl.get(), CURLOPT_HTTPHEADER, header_list.get());
    }
 
    curl_easy_setopt(curl.get(), CURLOPT_HTTPGET, 1L);
    curl_easy_setopt(curl.get(), CURLOPT_CURLU, url_handle);
    curl_easy_setopt(curl.get(), CURLOPT_WRITEFUNCTION, write_callback);
    curl_easy_setopt(curl.get(), CURLOPT_WRITEDATA, &response.text);
 
    const auto t0 = steady_clock::now();
    response.error_code = curl_easy_perform(curl.get());
    curl_easy_setopt(curl.get(), CURLOPT_CURLU, nullptr);
    const auto t1 = steady_clock::now();
    elapsed = duration_cast<milliseconds>(t1 - t0);
 
    curl_easy_getinfo(
        curl.get(), CURLINFO_RESPONSE_CODE, &response.status_code
    );
    update_headers(response);
 
    if (response.error_code != CURLE_OK) {
        response.error_message = curl_easy_strerror(response.error_code);
    }
 
    if (tmp_headers) {
        curl_easy_setopt(curl.get(), CURLOPT_HTTPHEADER, header_list.get());
        curl_slist_free_all(tmp_headers);
    }
 
    return response;
}

References corespace::http_response::error_code, corespace::http_response::error_message, and update_headers().

Here is the call graph for this function:

request_post()

http_response corespace::http_client::request_post ( CURLU * url_handle, std::chrono::milliseconds & elapsed, std::string_view content_type, std::string_view body, std::string_view override ) const

private

Definition at line 246 of file http_client.cpp.

        {
    using namespace std::chrono;
    http_response response;
    curl_slist* tmp_headers = nullptr;
 
    const std::string ct = "Content-Type: " + std::string(content_type);
    tmp_headers = curl_slist_append(tmp_headers, ct.c_str());
    const std::string acc = "Accept: "
        + std::string(override.empty() ? opt.accept : std::string(override));
    tmp_headers = curl_slist_append(tmp_headers, acc.c_str());
    curl_easy_setopt(curl.get(), CURLOPT_HTTPHEADER, tmp_headers);
 
    curl_easy_setopt(curl.get(), CURLOPT_CURLU, url_handle);
    curl_easy_setopt(curl.get(), CURLOPT_POST, 1L);
    curl_easy_setopt(curl.get(), CURLOPT_POSTFIELDS, body.data());
    curl_easy_setopt(
        curl.get(), CURLOPT_POSTFIELDSIZE, static_cast<long>(body.size())
    );
    curl_easy_setopt(curl.get(), CURLOPT_WRITEFUNCTION, write_callback);
    curl_easy_setopt(curl.get(), CURLOPT_WRITEDATA, &response.text);
    const auto t0 = steady_clock::now();
    response.error_code = curl_easy_perform(curl.get());
    curl_easy_setopt(curl.get(), CURLOPT_POSTFIELDS, nullptr);
    curl_easy_setopt(curl.get(), CURLOPT_POSTFIELDSIZE, 0L);
    curl_easy_setopt(curl.get(), CURLOPT_POST, 0L);
    curl_easy_setopt(curl.get(), CURLOPT_CURLU, nullptr);
    const auto t1 = steady_clock::now();
    elapsed = duration_cast<milliseconds>(t1 - t0);
    curl_easy_getinfo(
        curl.get(), CURLINFO_RESPONSE_CODE, &response.status_code
    );
    update_headers(response);
    if (response.error_code != CURLE_OK) {
        response.error_message = curl_easy_strerror(response.error_code);
    }
    curl_easy_setopt(curl.get(), CURLOPT_HTTPHEADER, header_list.get());
    if (tmp_headers) {
        curl_slist_free_all(tmp_headers);
    }
    return response;
}

References corespace::http_response::error_code, corespace::http_response::error_message, and update_headers().

Here is the call graph for this function:

status_good()

bool corespace::http_client::status_good ( const http_response & response )

staticnodiscardprivate

Success predicate: transport OK and HTTP 2xx.

Parameters

response

Response to check.

Returns

true if CURLE_OK and 200 <= status < 300.

Definition at line 342 of file http_client.cpp.

                                                           {
    return response.error_code == CURLE_OK && response.status_code >= 200
        && response.status_code < 300;
}

References corespace::http_response::error_code.

Referenced by get(), post_form(), and post_raw().

Here is the caller graph for this function:

status_retry()

bool corespace::http_client::status_retry ( const http_response & response, bool net_ok )

staticnodiscardprivate

Retry predicate for transient outcomes.

Retries on:

• any libcurl error (i.e., !net_ok),
• HTTP 408 (Request Timeout),
• HTTP 429 (Too Many Requests),
• HTTP 5xx.

Parameters

response	Response to inspect.
net_ok	Whether the transport completed without libcurl error.

Returns

true if another attempt should be made.

Definition at line 347 of file http_client.cpp.

  {
    return !net_ok || response.status_code == 429 || response.status_code == 408
        || (response.status_code >= 500 && response.status_code < 600);
}

update_headers()

void corespace::http_client::update_headers ( http_response & response ) const

private

Refresh the header multimap from the last transfer.

Enumerates headers via curl_easy_nextheader and fills response.header.

Parameters

response

Response object to update.

Definition at line 319 of file http_client.cpp.

                                                              {
    response.header.clear();
    for (curl_header* header = nullptr;;) {
        header = curl_easy_nextheader(curl.get(), CURLH_HEADER, 0, header);
        if (!header) {
            break;
        }
        response.header.emplace(header->name, header->value);
    }
}

Referenced by request_get(), and request_post().

Here is the caller graph for this function:

update_metrics()

void corespace::http_client::update_metrics ( const http_response & response, std::chrono::milliseconds elapsed )

private

Update counters and histograms after an attempt.

Increments requests, accumulates network_ms, bumps status histogram (if within bounds), and adds to bytes_received.

Parameters

response	Result of the attempt.
elapsed	Duration spent in libcurl during the attempt.

Definition at line 330 of file http_client.cpp.

  {
    ++metrics.requests;
    metrics.network_ms += elapsed.count();
 
    if (response.status_code < metrics.statuses.size()) {
        ++metrics.statuses[response.status_code];
    }
    metrics.bytes_received += response.text.size();
}

Referenced by get(), post_form(), and post_raw().

Here is the caller graph for this function:

write_callback()

size_t corespace::http_client::write_callback ( const char * ptr, size_t size, size_t n, void * data )

staticprivate

libcurl write callback: append chunk to response body.

Parameters

ptr	Pointer to received data.
size	Element size.
n	Number of elements.
data	std::string* accumulator (response body).

Returns

Number of bytes consumed (size * n).

Definition at line 374 of file http_client.cpp.

  {
    const size_t total = size * n;
    auto* text = static_cast<std::string*>(data);
    text->append(ptr, total);
    return total;
}

Member Data Documentation

curl

std::unique_ptr<CURL, decltype(&curl_easy_cleanup)> corespace::http_client::curl

private

Initial value:

{
        nullptr, &curl_easy_cleanup
    }

Reused easy handle (not thread-safe).

Definition at line 226 of file http_client.hpp.

                                                           {
        nullptr, &curl_easy_cleanup
    }; 

header_list

std::unique_ptr<curl_slist, decltype(&curl_slist_free_all)> corespace::http_client::header_list

private

Initial value:

{
        nullptr, &curl_slist_free_all
    }

Owned request header list.

Definition at line 229 of file http_client.hpp.

                                                                          {
        nullptr, &curl_slist_free_all
    }; 

metrics

network_metrics corespace::http_client::metrics

private

Aggregated metrics (atomic counters).

Definition at line 224 of file http_client.hpp.

mu

std::mutex corespace::http_client::mu

mutableprivate

Definition at line 225 of file http_client.hpp.

opt

const network_options corespace::http_client::opt {}

private

Fixed options installed at construction.

Definition at line 223 of file http_client.hpp.

{}; 

---

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

• http_client.hpp
• http_client.cpp