--- title: "ClikaRT::http" sidebar_label: "http" description: "Namespace ClikaRT::http" --- namespace ## Classes | Name | Description | | --- | --- | | [`Cookie`](./Cookie.md) | A cookie to set on a response ([`ServerResponse::with_cookie`](./ServerResponse.md#with_cookie)). | | [`DownloadOptions`](./DownloadOptions.md) | Options for a download. | | [`FormFile`](./FormFile.md) | One uploaded file part of a `multipart/form-data` body. | | [`FormPart`](./FormPart.md) | One part of a `multipart/form-data` body (text fields and file parts). A text field has an empty [`filename`](./FormPart.md#filename) + [`content_type`](./FormPart.md#content_type); a file part carries both. | | [`Headers`](./Headers.md) | Case-insensitive HTTP header bag (RFC 7230 names). A plain value type: [`entries`](./Headers.md#entries) holds the headers in arrival order (a name may repeat; multi-valued headers keep every value); [`get`](./Headers.md#get) / [`contains`](./Headers.md#contains) match the name case-insensitively. | | [`HttpResponse`](./HttpResponse.md) | 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`](./HttpResponse.md#status) (or [`ok()`](./HttpResponse.md#ok)). Only a request that could not complete at all (connection, TLS, timeout, cancellation) is an error on the [`Result`](../Result.md) channel. For a fetch that streamed its body elsewhere ([`fetch_file`](./index.md#fetch_file)), [`body`](./HttpResponse.md#body) is empty; status / reason / headers still apply. | | [`HttpServer`](./HttpServer.md) | An async HTTP / HTTPS server. Move-only. | | [`RouteGroup`](./RouteGroup.md) | A handle for registering routes under a shared path prefix + middleware chain. Valid only while its [`HttpServer`](./HttpServer.md) is alive and not yet serving. | | [`ServerRequest`](./ServerRequest.md) | 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`](./ServerRequest.md#path) / [`body`](./ServerRequest.md#body) / [`client_ip`](./ServerRequest.md#client_ip)) point into request-owned storage with the same lifetime. | | [`ServerResponse`](./ServerResponse.md) | A response a handler returns. Build with a factory and chain [`with_header`](./ServerResponse.md#with_header) / [`with_cookie`](./ServerResponse.md#with_cookie). Move-only. | | [`ServerSentEvent`](./ServerSentEvent.md) | One Server-Sent-Events frame. On the server ([`ServerResponse::sse`](./ServerResponse.md#sse)) [`data`](./ServerSentEvent.md#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`](./index.md#get_sse) / [`post_sse`](./index.md#post_sse)) it is one parsed incoming event. | ## Enumerations ### enum Method {#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 {#SameSite}

`enum class` **`SameSite`** `:` `std::uint8_t`

[`SameSite`](./index.md#SameSite) cookie attribute. | Enumerator | Description | | --- | --- | | `Lax` | | | `Strict` | | | `None` | |

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

## Type aliases ### using ChunkSink {#ChunkSink}

`using` **`ChunkSink`** `=` `std::function<`[`Result`](../Result.md)`(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 150

### using SseEventSink {#SseEventSink}

`using` **`SseEventSink`** `=` `std::function<`[`Result`](../Result.md)`(const` [`ServerSentEvent`](./ServerSentEvent.md) `&event)>`

Per-event sibling of [`ChunkSink`](./index.md#ChunkSink); same abort-on-failure contract.

Declared in `ClikaRT/http/client.h`, line 152

### using Handler {#Handler}

`using` **`Handler`** `=` `std::function<`[`Result`](../Result.md)`<`[`ServerResponse`](./ServerResponse.md)`>(`[`ServerRequest`](./ServerRequest.md) `&request)>`

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

Declared in `ClikaRT/http/server.h`, line 223

### using Next {#Next}

`using` **`Next`** `=` `std::function<`[`Result`](../Result.md)`<`[`ServerResponse`](./ServerResponse.md)`>()>`

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 227

### using Middleware {#Middleware}

`using` **`Middleware`** `=` `std::function<`[`Result`](../Result.md)`<`[`ServerResponse`](./ServerResponse.md)`>(`[`ServerRequest`](./ServerRequest.md) `&request, const` [`Next`](./index.md#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 232

### using ExceptionHandler {#ExceptionHandler}

`using` **`ExceptionHandler`** `=` `std::function<`[`ServerResponse`](./ServerResponse.md)`(const` [`ServerRequest`](./ServerRequest.md) `&request, std::string_view what)>`

Produces the response when a handler could not produce one (it threw, or returned a failure [`Result`](../Result.md). This is the FAILURE path (contrast [`ErrorHandler`](./index.md#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()`](../logging/index.md#logger).

Declared in `ClikaRT/http/server.h`, line 240

### using ErrorHandler {#ErrorHandler}

`using` **`ErrorHandler`** `=` `std::function<`[`Result`](../Result.md)`<`[`ServerResponse`](./ServerResponse.md)`>(const` [`ServerRequest`](./ServerRequest.md) `&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`](./index.md#ExceptionHandler)'s job). A failure [`Result`](../Result.md) declines customization and leaves the transport's default page in place.

Declared in `ClikaRT/http/server.h`, line 246

### using Logger {#Logger}

`using` **`Logger`** `=` `std::function`

Per-request access logger.

Declared in `ClikaRT/http/server.h`, line 249

## Variables ### kDefaultHeaderDeadlineSec {#kDefaultHeaderDeadlineSec}

`int` **`kDefaultHeaderDeadlineSec`** `= 30`

first byte → end of the headers The server's request-arrival deadlines and its idle bound, in seconds: the values `set_header_deadline` / `set_body_deadline` / `set_keep_alive_timeout` apply when you set nothing. A server that sets nothing is still protected: a client trickling its request one byte at a time is answered `408 Request Timeout` at the deadline and its connection is closed.

Declared in `ClikaRT/http/server.h`, line 57

### kDefaultBodyDeadlineSec {#kDefaultBodyDeadlineSec}

`int` **`kDefaultBodyDeadlineSec`** `= 120`

end of the headers → end of the declared body

Declared in `ClikaRT/http/server.h`, line 58

### kDefaultKeepAliveTimeoutSec {#kDefaultKeepAliveTimeoutSec}

`int` **`kDefaultKeepAliveTimeoutSec`** `= 5`

idle between requests before the close

Declared in `ClikaRT/http/server.h`, line 59

## Functions ### download\_file() {#download_file}

`std::string` **`download_file`**(
    `std::string_view` `url`,
    `std::string_view` `dest_path`,
    `const` [`DownloadOptions`](./DownloadOptions.md)`&` `options` `=` `{}`
)

Declared in `ClikaRT/http/client.h`, line 72

### get\_text() {#get_text}

`std::string` **`get_text`**(`std::string_view` `url`, `const` [`DownloadOptions`](./DownloadOptions.md)`&` `options` `=` `{}`)

Declared in `ClikaRT/http/client.h`, line 80

### download\_file\_into\_bytes() {#download_file_into_bytes}

`std::vector` **`download_file_into_bytes`**(
`std::string_view` `url`,
`const` [`DownloadOptions`](./DownloadOptions.md)`&` `options` `=` `{}`
)

Declared in `ClikaRT/http/client.h`, line 91

### fetch() {#fetch}

[`HttpResponse`](./HttpResponse.md) **`fetch`**(`std::string_view` `url`, `const` [`DownloadOptions`](./DownloadOptions.md)`&` `options` `=` `{}`)

Declared in `ClikaRT/http/client.h`, line 103

### fetch\_file() {#fetch_file}

[`HttpResponse`](./HttpResponse.md) **`fetch_file`**(
    `std::string_view` `url`,
    `std::string_view` `dest_path`,
    `const` [`DownloadOptions`](./DownloadOptions.md)`&` `options` `=` `{}`
)

Declared in `ClikaRT/http/client.h`, line 114

### post\_text() {#post_text}

`std::string` **`post_text`**(
    `std::string_view` `url`,
    `std::string_view` `body`,
    `std::string_view` `content_type` `=` `"application/json"`,
    `const` [`DownloadOptions`](./DownloadOptions.md)`&` `options` `=` `{}`
)

Declared in `ClikaRT/http/client.h`, line 122

### post() {#post}

[`HttpResponse`](./HttpResponse.md) **`post`**(
    `std::string_view` `url`,
    `std::string_view` `body`,
    `std::string_view` `content_type` `=` `"application/json"`,
    `const` [`DownloadOptions`](./DownloadOptions.md)`&` `options` `=` `{}`
)

Declared in `ClikaRT/http/client.h`, line 133

### del() {#del}

[`HttpResponse`](./HttpResponse.md) **`del`**(`std::string_view` `url`, `const` [`DownloadOptions`](./DownloadOptions.md)`&` `options` `=` `{}`)

Declared in `ClikaRT/http/client.h`, line 143

### get\_stream() {#get_stream}

`void` **`get_stream`**(
    `std::string_view` `url`,
    [`ChunkSink`](./index.md#ChunkSink) `on_chunk`,
    `const` [`DownloadOptions`](./DownloadOptions.md)`&` `options` `=` `{}`
)

Declared in `ClikaRT/http/client.h`, line 208

### get\_sse() {#get_sse}

`void` **`get_sse`**(
    `std::string_view` `url`,
    [`SseEventSink`](./index.md#SseEventSink) `on_event`,
    `const` [`DownloadOptions`](./DownloadOptions.md)`&` `options` `=` `{}`
)

Declared in `ClikaRT/http/client.h`, line 215

### post\_stream() {#post_stream}

`void` **`post_stream`**(
    `std::string_view` `url`,
    `std::string_view` `body`,
    `std::string_view` `content_type`,
    [`ChunkSink`](./index.md#ChunkSink) `on_chunk`,
    `const` [`DownloadOptions`](./DownloadOptions.md)`&` `options` `=` `{}`
)

Declared in `ClikaRT/http/client.h`, line 222

### post\_sse() {#post_sse}

`void` **`post_sse`**(
    `std::string_view` `url`,
    `std::string_view` `body`,
    `std::string_view` `content_type`,
    [`SseEventSink`](./index.md#SseEventSink) `on_event`,
    `const` [`DownloadOptions`](./DownloadOptions.md)`&` `options` `=` `{}`
)

Declared in `ClikaRT/http/client.h`, line 229

## `ClikaRT/http/server.h` {#server-h} ```cpp #include ``` 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` and the library never throws. A `Handler` you write returns `Result`; 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()`](../logging/index.md#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`](../logging/Logger.md)). 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` {#types-h} ```cpp #include ``` HTTP wire types shared by the client and server surfaces (`ClikaRT/http/ `[`client.h`](./DownloadOptions.md) consumes an SSE stream; [`ClikaRT/http/server.h`](./index.md#server-h) produces one).