ClikaRT::http

namespace

Classes

Name	Description
`Cookie`	A cookie to set on a response (`ServerResponse::with_cookie`).
`DownloadOptions`	Options for a download.
`FormFile`	One uploaded file part of a `multipart/form-data` body.
`FormPart`	One part of a `multipart/form-data` body (text fields and file parts). A text field has an empty `filename` + `content_type`; a file part carries both.
`Headers`	Case-insensitive HTTP header bag (RFC 7230 names). A plain value type: `entries` holds the headers in arrival order (a name may repeat; multi-valued headers keep every value); `get` / `contains` match the name case-insensitively.
`HttpResponse`	A finished HTTP response, the OUTCOME of a request the server answered. Any answered status is an outcome, not an error: a 404 or 401 arrives here as data, and you branch on `status` (or `ok()`). Only a request that could not complete at all (connection, TLS, timeout, cancellation) is an error on the `Result` channel. For a fetch that streamed its body elsewhere (`fetch_file`), `body` is empty; status / reason / headers still apply.
`HttpServer`	An async HTTP / HTTPS server. Move-only.
`RouteGroup`	A handle for registering routes under a shared path prefix + middleware chain. Valid only while its `HttpServer` is alive and not yet serving.
`ServerRequest`	A request as seen by a handler / middleware. A borrowed handle: it is valid only for the duration of the handler call and does NOT own the underlying request; never store it or use it after your handler returns. The view-returning observers (`path` / `body` / `client_ip`) point into request-owned storage with the same lifetime.
`ServerResponse`	A response a handler returns. Build with a factory and chain `with_header` / `with_cookie`. Move-only.
`ServerSentEvent`	One Server-Sent-Events frame. On the server (`ServerResponse::sse`) `data` is the payload to send (often a JSON delta) and a CR/LF in any field is stripped/normalized by the framer so it cannot inject extra SSE fields; on the client (`get_sse` / `post_sse`) it is one parsed incoming event.

Enumerations

enum Method

enum class Method : std::uint8_t

HTTP method. HEAD falls back to the matching GET handler when no explicit HEAD route is registered.

Enumerator	Description
`Get`
`Post`
`Put`
`Patch`
`Delete`
`Head`
`Options`

Declared in ClikaRT/http/server.h, line 47

enum SameSite

enum class SameSite : std::uint8_t

SameSite cookie attribute.

Enumerator	Description
`Lax`
`Strict`
`None`

Declared in ClikaRT/http/server.h, line 50

Type aliases

using ChunkSink

using ChunkSink = std::function<Result<void>(std::string_view chunk)>

The streaming consumer callbacks. Result-returning by design (the containment carve-out): return a failure to ABORT the transfer; the call then fails with that status. The chunk/event views are valid only for the duration of the callback.

Declared in ClikaRT/http/client.h, line 149

using SseEventSink

using SseEventSink = std::function<Result<void>(const ServerSentEvent &event)>

Per-event sibling of ChunkSink; same abort-on-failure contract.

Declared in ClikaRT/http/client.h, line 151

using Handler

using Handler = std::function<Result<ServerResponse>(ServerRequest &request)>

A route handler: receives the request (non-const; it may set attributes) and returns a response or a failure Result (→ the error/exception path → 500). A consumer can return ServerResponse::json(...) directly (implicit Result<T>(T)).

Declared in ClikaRT/http/server.h, line 212

using Next

using Next = std::function<Result<ServerResponse>()>

Runs the rest of the middleware chain + the handler. Call it at most once; not calling it short-circuits the chain (e.g. return a 401 without next()).

Declared in ClikaRT/http/server.h, line 216

using Middleware

using Middleware = std::function<Result<ServerResponse>(ServerRequest &request, const Next &next)>

"Around" middleware: inspect the request, optionally set_attr, then either call next() and inspect/modify the response, or return your own response without calling it.

Declared in ClikaRT/http/server.h, line 221

using ExceptionHandler

using ExceptionHandler = std::function<ServerResponse(const ServerRequest &request, std::string_view what)>

Produces the response when a handler could not produce one (it threw, or returned a failure Result. This is the FAILURE path (contrast ErrorHandler, the error-STATUS path). what is the diagnostic; do not echo it to untrusted clients verbatim. Without one installed the client gets an opaque 500; either way the failure is logged at Warn on ClikaRT::logging::logger().

Declared in ClikaRT/http/server.h, line 229

using ErrorHandler

using ErrorHandler = std::function<Result<ServerResponse>(const ServerRequest &request, int status)>

Produces the page for a response that WAS produced but carries an HTTP error status (a 404, an explicit error(N), …), a deliberate outcome, not a failed handler (that is ExceptionHandler's job). A failure Result declines customization and leaves the transport's default page in place.

Declared in ClikaRT/http/server.h, line 235

using Logger

using Logger = std::function<void(const ServerRequest &request, int status)>

Per-request access logger.

Declared in ClikaRT/http/server.h, line 238

Functions

download_file()

std::string download_file(
    std::string_view url,
    std::string_view dest_path,
    const DownloadOptions& options = {}
)

Declared in ClikaRT/http/client.h, line 71

get_text()

std::string get_text(std::string_view url, const DownloadOptions& options = {})

Declared in ClikaRT/http/client.h, line 79

download_file_into_bytes()

std::vector<std::byte> download_file_into_bytes(
std::string_view url,
const DownloadOptions& options = {}
)

Declared in ClikaRT/http/client.h, line 90

fetch()

HttpResponse fetch(std::string_view url, const DownloadOptions& options = {})

Declared in ClikaRT/http/client.h, line 102

fetch_file()

HttpResponse fetch_file(
    std::string_view url,
    std::string_view dest_path,
    const DownloadOptions& options = {}
)

Declared in ClikaRT/http/client.h, line 113

post_text()

std::string post_text(
    std::string_view url,
    std::string_view body,
    std::string_view content_type = "application/json",
    const DownloadOptions& options = {}
)

Declared in ClikaRT/http/client.h, line 121

post()

HttpResponse post(
    std::string_view url,
    std::string_view body,
    std::string_view content_type = "application/json",
    const DownloadOptions& options = {}
)

Declared in ClikaRT/http/client.h, line 132

del()

HttpResponse del(std::string_view url, const DownloadOptions& options = {})

Declared in ClikaRT/http/client.h, line 142

get_stream()

void get_stream(
    std::string_view url,
    ChunkSink on_chunk,
    const DownloadOptions& options = {}
)

Declared in ClikaRT/http/client.h, line 202

get_sse()

void get_sse(
    std::string_view url,
    SseEventSink on_event,
    const DownloadOptions& options = {}
)

Declared in ClikaRT/http/client.h, line 209

post_stream()

void post_stream(
    std::string_view url,
    std::string_view body,
    std::string_view content_type,
    ChunkSink on_chunk,
    const DownloadOptions& options = {}
)

Declared in ClikaRT/http/client.h, line 216

post_sse()

void post_sse(
    std::string_view url,
    std::string_view body,
    std::string_view content_type,
    SseEventSink on_event,
    const DownloadOptions& options = {}
)

Declared in ClikaRT/http/client.h, line 223

`ClikaRT/http/server.h`

#include <ClikaRT/http/server.h>

An async HTTP / HTTPS server: register route handlers, compose middleware, serve static files and streaming / Server-Sent-Events responses, and run real work in a handler. Built for serving a model over HTTP.

Error model: every configuration and run-control method returns Result<T> and the library never throws. A Handler you write returns Result<ServerResponse>; and if it does throw, the server contains the exception (turns it into a 500) so a single bad handler can never crash the process. Turn a failure Result into an exception on your own side with .value_or_throw(), or inspect .ok() / .status() / .message().

Failure diagnostics: when a handler / middleware / streaming producer throws or returns a failure Result, the client receives only an opaque 500 Internal Server Error; the diagnostic never leaks to the network. The failure itself (method, path, reason) is logged at Warn on the default ClikaRT::logging::logger() channel, so a broken handler is visible server-side with zero setup; silence or redirect it via the logging API (ClikaRT/logging/logging.h). Install set_exception_handler to customize the failure response; the log line is emitted either way.

Threading: configure routes / middleware / mounts BEFORE listen*(); they are immutable while serving. Handlers run concurrently on a dedicated I/O pool; synchronize any shared mutable state a handler captures.

`ClikaRT/http/types.h`

#include <ClikaRT/http/types.h>

HTTP wire types shared by the client and server surfaces (ClikaRT/http/ client.h consumes an SSE stream; ClikaRT/http/server.h produces one).

Classes​

Enumerations​

enum Method​

enum SameSite​

Type aliases​

using ChunkSink​

using SseEventSink​

using Handler​

using Next​

using Middleware​

using ExceptionHandler​

using ErrorHandler​

using Logger​

Functions​

download_file()​

get_text()​

download_file_into_bytes()​

fetch()​

fetch_file()​

post_text()​

post()​

del()​

get_stream()​

get_sse()​

post_stream()​

post_sse()​

ClikaRT/http/server.h​

ClikaRT/http/types.h​