Kurlyk Library

Introduction

Kurlyk is a header-only C++ library that currently wraps libcurl and Simple-WebSocket-Server** to provide convenient HTTP and WebSocket clients. Its core is backend-agnostic, so alternative implementations can be plugged in if needed—planned support includes an Emscripten backend. The library hides much of the networking boilerplate and offers an easy way to issue asynchronous requests, process WebSocket events and apply rate limiting.

Features

• HTTP and WebSocket clients with a common, class-based API.
• Asynchronous or synchronous execution via a background worker.
• Rate limiting for both HTTP requests and WebSocket messages.
• Automatic reconnection logic for WebSocket connections.
• Proxy support, configurable timeouts and custom headers.
• Retry logic and ability to cancel outstanding requests.
• Standalone helper functions for one-off HTTP calls.
• Header-only design, works with C++11 and newer.

Usage

By default Kurlyk initializes itself before main and shuts down automatically thanks to an internal startup::AutoInitializer. It registers HttpRequestManager and WebSocketManager with the core::NetworkWorker and starts the worker thread using the KURLYK_AUTO_INIT_USE_ASYNC setting. A shutdown happens when the program exits, so you can usually skip explicit kurlyk::init() and kurlyk::deinit() calls.

Manual control is still possible by disabling automatic startup:

#define KURLYK_AUTO_INIT 0        // opt out of AutoInitializer
#include <kurlyk.hpp>
int main() {
    kurlyk::init(true);           // start worker thread explicitly
    // ... use HTTP or WebSocket clients ...
    kurlyk::deinit();             // stop the worker (or kurlyk::shutdown())
}

HTTP Client

Basic GET request

kurlyk::HttpClient http("https://httpbin.org");
http.get("/ip", {}, {}, [](kurlyk::HttpResponsePtr res) {
    std::cout << res->content << std::endl;
});

Using a proxy

kurlyk::HttpClient client("https://httpbin.org");
client.set_proxy("127.0.0.1", 8080, "user", "pass", kurlyk::ProxyType::HTTP);
client.get("/ip", {}, {}, [](kurlyk::HttpResponsePtr res) {
    std::cout << res->content << std::endl;
});

Measuring latency

#include <chrono>
kurlyk::HttpClient client("https://httpbin.org");
auto start = std::chrono::steady_clock::now();
client.get("/ip", {}, {}, [start](kurlyk::HttpResponsePtr res) {
    auto ms = std::chrono::duration_cast<std::chrono::milliseconds>(
        std::chrono::steady_clock::now() - start);
    std::cout << "Ping: " << ms.count() << " ms" << std::endl;
});

Calling HTTP requests

Requests can be issued with callbacks, futures or standalone functions:

kurlyk::HttpClient cli("https://httpbin.org");
auto fut = cli.get("/ip", {}, {});
auto resp = fut.get();
 
auto [id, future] = kurlyk::http_get("https://httpbin.org/ip", {}, {});
auto resp2 = future.get();

WebSocket Client

kurlyk::WebSocketClient ws("wss://echo-websocket.fly.dev/");
ws.on_event([](std::unique_ptr<kurlyk::WebSocketEventData> e) {
    if (e->event_type == kurlyk::WebSocketEventType::WS_MESSAGE)
        std::cout << "Message: " << e->message << std::endl;
});
ws.connect_and_wait();
ws.send_message("Hello!");
ws.disconnect_and_wait();

Error Handling

The library centralizes exception reporting through the core::NetworkWorker. Applications may register callbacks with kurlyk::add_error_handler to intercept errors raised inside Kurlyk and forward them to a logging system or metrics collector.

Handlers use the kurlyk::core::NetworkWorker::ErrorHandler signature:

using ErrorHandler = std::function<
    void(const std::exception&,
         const char* msg,
         const char* file,
         int line,
         const char* func)>;

Whenever an internal operation encounters an exception and invokes KURLYK_HANDLE_ERROR, all registered handlers receive the exception, an optional message, source file, line and function. This allows detailed logging of issues without terminating the program.

kurlyk::add_error_handler([](const std::exception& ex,
                             const char* msg,
                             const char* file,
                             int line,
                             const char* func) {
    std::cerr << "Kurlyk error: " << msg
              << " (" << ex.what() << ") at "
              << file << ':' << line
              << " in " << func << std::endl;
});

Installation

Add the include directory to your compiler search path and include <kurlyk.hpp> in your sources. The repository contains third party dependencies used by the examples, but for your own project you need libcurl, OpenSSL and either Boost.Asio or standalone Asio together with Simple-WebSocket-Server. Kurlyk itself is header-only and works with C++11 or later.

Configuration Macros

Several macros can be defined before including the library to tailor the build:

• KURLYK_HTTP_SUPPORT and KURLYK_WEBSOCKET_SUPPORT toggle the HTTP or WebSocket parts of the library.
• KURLYK_AUTO_INIT controls automatic manager registration during static initialization, while KURLYK_AUTO_INIT_USE_ASYNC runs the worker thread in the background when auto init is enabled.

Repository

Kurlyk Library GitHub repository.

License

This library is licensed under the MIT License. See the LICENSE file for more details.