HttpClient

HttpClient is a C++17 HTTP client library built on top of libcurl multi/easy APIs.

It provides:

• blocking requests via HttpTransfer
• async/concurrent requests via pooled HttpClient
• runtime transfer control (cancel, pause, resume)
• pluggable retry condition + backoff scheduling
• hashing helpers based on OpenSSL EVP

• C++17 compiler
• CMake >= 3.14
• OpenSSL
• libcurl >= 8.10.0 (or vendored curl auto-built by CMake)

cmake -S . -B build
cmake --build build

cmake -S . -B build -DHTTPCLIENT_BUILD_EXAMPLES=ON
cmake --build build
./build/example

Notes:

• HTTPCLIENT_BUILD_EXAMPLES controls only examples/example.cpp.
• If system libcurl is missing or too old, CMake fetches and builds curl-8_11_1 with HTTP-only options.

add_subdirectory(path/to/HttpClient)
target_link_libraries(your_target PRIVATE HttpClient)

include(FetchContent)

FetchContent_Declare(
  HttpClient
  GIT_REPOSITORY https://github.com/lzqlzzq/HttpClient.git
  GIT_TAG main
)
FetchContent_MakeAvailable(HttpClient)

target_link_libraries(your_target PRIVATE HttpClient)

maxConcurrentRequests limits admitted requests (default 12), independently of maxConnections, the libcurl connection cache size (default 24). Paused transfers and requests waiting for retry release their request slots. maxHostConnections and maxTotalConnections limit active connections, not requests; zero means unlimited for these two libcurl settings. Both client constructors use the same defaults. Settings must outlive the client.

http_client::HttpClientSettings settings;
settings.maxConcurrentRequests = 6;
settings.maxConnections = 24;
settings.maxHostConnections = 8;
settings.maxTotalConnections = 24;
http_client::HttpClient client(settings);

Migration: custom clients previously also used maxConnections as their request limit. Set maxConcurrentRequests explicitly to preserve that concurrency while sizing the connection cache separately. Rebuild dependents after updating the library because the settings layout changes.

#include "httpclient/HttpClient.hpp"

int main() {
    http_client::HttpRequest req;
    req.url = "https://httpbin.org/get";
    req.methodName = "GET";

    http_client::HttpTransfer transfer(req);
    transfer.perform_blocking();

    const auto& resp = transfer.getResponse();
    // resp.status / resp.headers / resp.body / resp.error
}

#include "httpclient/HttpClient.hpp"

auto& client = http_client::HttpClient::getDefault();

http_client::HttpRequest req;
req.url = "https://httpbin.org/get";
req.methodName = "GET";

auto state = client.send_request(req);
auto resp = state->future.get();

Static convenience API:

auto resp = http_client::HttpClient::Request(req);

auto state = http_client::HttpClient::SendRequest(req);
state->pause();
state->resume();
// state->cancel();
auto resp = state->future.get();

#include "httpclient/HttpClient.hpp"
#include "httpclient/RetryStrategies.hpp"

http_client::RetryPolicy retry;
retry.maxRetries = 3;
retry.totalTimeout = 30.0f;
retry.shouldRetry = http_client::retry::httpStatusCondition({500, 502, 503, 504});
retry.getNextRetryTime = http_client::retry::exponentialBackoff(1.0, 10.0, 2.0, 0.2);

auto resp = http_client::HttpClient::Request(req, http_client::RequestPolicy(), retry);

Default RetryPolicy():

• maxRetries = 3
• totalTimeout = 0 (unbounded total time)
• shouldRetry = retry::defaultCondition()
• getNextRetryTime = retry::exponentialBackoff()

#include "httpclient/HashHelper.hpp"

std::string bin = http_client::Hash::sha256("hello");
std::string hex = http_client::Hash::hexdigest(bin);

• url
• methodName (e.g. GET, POST, PATCH, PUT, DELETE, HEAD)
• headers
• body

• timeout (seconds)
• connTimeout (seconds)
• lowSpeedLimit, lowSpeedTime
• sendSpeedLimit, recvSpeedLimit
• curlBufferSize

• status
• headers
• body
• error (curl error buffer)
• transferInfo (timing breakdown)

• future
• pause(), resume(), cancel()
• get_state()
• hasRetry(), getAttempt(), getRetryContext()

State values:

• Pending, Ongoing, Completed, Pause, Paused, Resume, Failed, Cancel

Conditions:

• defaultCondition()
• httpStatusCondition(codes)
• anyOf(...)
• allOf(...)

Backoff:

• exponentialBackoff(baseDelay, maxDelay, multiplier, jitterFactor)
• linearBackoff(initialDelay, increment, maxDelay)
• fixedDelay(delay)
• immediate()
• maxOf(...)
• minOf(...)

• Set HTTPCLIENT_CURL_VERBOSE=1 to enable libcurl verbose output for requests.
• HttpClientSettings can be subclassed to override curl easy/multi options.
• If you construct HttpClient with a custom HttpClientSettings reference, ensure the settings object outlives the client.
• examples/example.cpp requires internet access (https://httpbin.org).

See LICENSE.