---
title: "ClikaRT::http::HttpServer"
sidebar_label: "HttpServer"
description: "An async HTTP / HTTPS server. Move-only."
---

<!-- Generated by tools/doxygen2mdx from Doxygen XML. Do not edit. -->

<span class="api-kind api-kind--class">class</span>

**Header:** `ClikaRT/http/server.h`

An async HTTP / HTTPS server. Move-only.

## Exact-path routes (root level)

### get() {#get}

<div class="api-signature">

`void` **`get`**(`std::string_view` `path`, [`Handler`](./index.md#Handler) `handler`)

</div>

<div class="api-declared">

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

</div>

### post() {#post}

<div class="api-signature">

`void` **`post`**(`std::string_view` `path`, [`Handler`](./index.md#Handler) `handler`)

</div>

POST.

<div class="api-declared">

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

</div>

### put() {#put}

<div class="api-signature">

`void` **`put`**(`std::string_view` `path`, [`Handler`](./index.md#Handler) `handler`)

</div>

PUT.

<div class="api-declared">

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

</div>

### patch() {#patch}

<div class="api-signature">

`void` **`patch`**(`std::string_view` `path`, [`Handler`](./index.md#Handler) `handler`)

</div>

PATCH.

<div class="api-declared">

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

</div>

### del() {#del}

<div class="api-signature">

`void` **`del`**(`std::string_view` `path`, [`Handler`](./index.md#Handler) `handler`)

</div>

DELETE (named [`del`](./HttpServer.md#del); `delete` is a C++ keyword).

<div class="api-declared">

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

</div>

### head() {#head}

<div class="api-signature">

`void` **`head`**(`std::string_view` `path`, [`Handler`](./index.md#Handler) `handler`)

</div>

HEAD (an unrouted HEAD falls back to the matching GET handler).

<div class="api-declared">

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

</div>

### options() {#options}

<div class="api-signature">

`void` **`options`**(`std::string_view` `path`, [`Handler`](./index.md#Handler) `handler`)

</div>

OPTIONS.

<div class="api-declared">

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

</div>

## Static member functions

### create() {#create}

<div class="api-signature">

`static` [`HttpServer`](./HttpServer.md) **`create`**()

</div>

Create a server (HTTPS is always available via [`set_tls`](./HttpServer.md#set_tls)).

<div class="api-declared">

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

</div>

## Member functions

### HttpServer() {#HttpServer}

<div class="api-signature">

**`HttpServer`**(`HttpServer&&`) `noexcept`

</div>

<div class="api-declared">

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

</div>

### operator=() {#operator-assign}

<div class="api-signature">

[`HttpServer`](./HttpServer.md)`&` **`operator=`**([`HttpServer`](./HttpServer.md)`&&`) `noexcept`

</div>

Move-assign: transfers the server.

<div class="api-declared">

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

</div>

### \~HttpServer() {#HttpServer-2}

<div class="api-signature">

**`~HttpServer`**()

</div>

Releases the server handle.

<div class="api-declared">

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

</div>

### route() {#route}

<div class="api-signature">

`void` **`route`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`Method`](./index.md#Method) `method`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::string_view` `pattern`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`Handler`](./index.md#Handler) `handler`<br />
)

</div>

re2-pattern route (positional + named captures, read in the handler via [`ServerRequest::param`](./ServerRequest.md#param)). Same containment and registration contract as the exact-path group.

**Throws**

- `ClikaRT::Error`: when the pattern or registration is rejected.

<div class="api-declared">

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

</div>

### group() {#group}

<div class="api-signature">

[`RouteGroup`](./RouteGroup.md) **`group`**(`std::string_view` `prefix`)

</div>

A route group, e.g. `server.group("/api/v1").use(auth)`.

<div class="api-declared">

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

</div>

### use() {#use}

<div class="api-signature">

`void` **`use`**([`Middleware`](./index.md#Middleware) `middleware`)

</div>

Append to the GLOBAL middleware chain (runs for every route, groups included, in registration order). A throw from the middleware is contained caller-side (see detail::contain). An empty middleware adds nothing.

**Throws**

- `ClikaRT::Error`: when the registration is rejected.

<div class="api-declared">

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

</div>

### mount() {#mount}

<div class="api-signature">

`void` **`mount`**(`std::string_view` `url_prefix`, `std::string_view` `dir`)

</div>

Serve the files under directory `dir` at `url_prefix` (MIME inferred from each file's extension; see [`set_mime_type`](./HttpServer.md#set_mime_type) to extend the map).

**Throws**

- `ClikaRT::Error`: when the mount is rejected.

<div class="api-declared">

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

</div>

### add\_static\_file() {#add_static_file}

<div class="api-signature">

`void` **`add_static_file`**(`std::string_view` `url_path`, `std::string_view` `file`)

</div>

Serve one file at one exact URL path.

**Throws**

- `ClikaRT::Error`: when the registration is rejected.

<div class="api-declared">

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

</div>

### set\_mime\_type() {#set_mime_type}

<div class="api-signature">

`void` **`set_mime_type`**(`std::string_view` `extension`, `std::string_view` `mime`)

</div>

Map a file extension (e.g. `".wasm"`) to a MIME type for the static routes.

**Throws**

- `ClikaRT::Error`: when the mapping is rejected.

<div class="api-declared">

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

</div>

### set\_exception\_handler() {#set_exception_handler}

<div class="api-signature">

`void` **`set_exception_handler`**([`ExceptionHandler`](./index.md#ExceptionHandler) `handler`)

</div>

Customize the response for a FAILED handler, one that threw or returned a failure [`Result`](../Result.md) (default: an opaque 500). Contrast [`set_error_handler`](./HttpServer.md#set_error_handler), which styles deliberate error statuses. Installing one does not suppress the `Warn` log line on [`ClikaRT::logging::logger()`](../logging/index.md#logger). An empty handler restores the default.

<div class="api-declared">

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

</div>

### set\_error\_handler() {#set_error_handler}

<div class="api-signature">

`void` **`set_error_handler`**([`ErrorHandler`](./index.md#ErrorHandler) `handler`)

</div>

Customize the page for responses carrying an HTTP error status (a 404, an explicit `error(N)`, …). Not invoked for a failed handler; that is [`set_exception_handler`](./HttpServer.md#set_exception_handler)'s job. An empty handler restores the default page.

<div class="api-declared">

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

</div>

### set\_logger() {#set_logger}

<div class="api-signature">

`void` **`set_logger`**([`Logger`](./index.md#Logger) `logger`)

</div>

Install the per-request access logger (runs after each response; a throwing logger is contained and its line dropped, never the request). An empty logger removes the one installed before.

**Throws**

- `ClikaRT::Error`: when installation is rejected.

<div class="api-declared">

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

</div>

### set\_read\_timeout() {#set_read_timeout}

<div class="api-signature">

`void` **`set_read_timeout`**(`int` `seconds`)

</div>

The per-READ idle timer, in seconds: how long one read may wait for the NEXT byte of a request (reset by every byte that arrives). It closes a client that goes silent mid-request; it does not bound one that keeps trickling, which [`set_header_deadline`](./HttpServer.md#set_header_deadline) / [`set_body_deadline`](./HttpServer.md#set_body_deadline) do.

**Throws**

- `ClikaRT::Error`: when the value is rejected.

<div class="api-declared">

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

</div>

### set\_write\_timeout() {#set_write_timeout}

<div class="api-signature">

`void` **`set_write_timeout`**(`int` `seconds`)

</div>

Per-connection write timeout, in seconds.

**Throws**

- `ClikaRT::Error`: when the value is rejected.

<div class="api-declared">

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

</div>

### set\_header\_deadline() {#set_header_deadline}

<div class="api-signature">

`void` **`set_header_deadline`**(`int` `seconds`)

</div>

The header deadline, in seconds (default [`kDefaultHeaderDeadlineSec`](./index.md#kDefaultHeaderDeadlineSec); `0` disables it): a ceiling on the time from a request's first byte to the end of its headers. A request past it is answered `408 Request Timeout` (the status runs through [`set_error_handler`](./HttpServer.md#set_error_handler) like a 413, so you shape its body) and its connection is closed, at the deadline, however slowly the client keeps sending. One `Warn` line on [`ClikaRT::logging::logger()`](../logging/index.md#logger) names the peer.

**Throws**

- `ClikaRT::Error`: when the value is rejected.

<div class="api-declared">

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

</div>

### set\_body\_deadline() {#set_body_deadline}

<div class="api-signature">

`void` **`set_body_deadline`**(`int` `seconds`)

</div>

The body deadline, in seconds (default [`kDefaultBodyDeadlineSec`](./index.md#kDefaultBodyDeadlineSec); `0` disables it): a ceiling on the time from the end of a request's headers to the end of its declared body, with the same 408, close and log line. Size it with [`set_payload_max_length`](./HttpServer.md#set_payload_max_length): the largest body you accept must arrive within it over the slowest uplink you serve.

**Throws**

- `ClikaRT::Error`: when the value is rejected.

<div class="api-declared">

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

</div>

### set\_keep\_alive\_timeout() {#set_keep_alive_timeout}

<div class="api-signature">

`void` **`set_keep_alive_timeout`**(`int` `seconds`)

</div>

How long an open connection may sit idle, between requests and before its first request's byte, before the server closes it, in seconds (default [`kDefaultKeepAliveTimeoutSec`](./index.md#kDefaultKeepAliveTimeoutSec)).

**Throws**

- `ClikaRT::Error`: when the value is rejected.

<div class="api-declared">

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

</div>

### set\_payload\_max\_length() {#set_payload_max_length}

<div class="api-signature">

`void` **`set_payload_max_length`**(`std::size_t` `bytes`)

</div>

Largest request body accepted, in bytes; a larger payload is refused before the handler runs.

**Throws**

- `ClikaRT::Error`: when the value is rejected.

<div class="api-declared">

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

</div>

### set\_max\_connections() {#set_max_connections}

<div class="api-signature">

`void` **`set_max_connections`**(`std::size_t` `max_connections`)

</div>

Concurrent-connection ceiling; `0` means unlimited.

**Throws**

- `ClikaRT::Error`: when the value is rejected.

<div class="api-declared">

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

</div>

### set\_default\_header() {#set_default_header}

<div class="api-signature">

`void` **`set_default_header`**(`std::string_view` `name`, `std::string_view` `value`)

</div>

A header appended to every response (repeat for several values).

**Throws**

- `ClikaRT::Error`: when the header is rejected.

<div class="api-declared">

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

</div>

### set\_tls() {#set_tls}

<div class="api-signature">

`void` **`set_tls`**(`std::string_view` `cert`, `std::string_view` `key`)

</div>

Serve HTTPS: load this certificate + private key (PEM file paths); every later `listen*()` speaks TLS.

**Throws**

- `ClikaRT::Error`: when the pair cannot be loaded.

<div class="api-declared">

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

</div>

### listen() {#listen}

<div class="api-signature">

`void` **`listen`**(`std::string_view` `host`, `int` `port`)

</div>

Serve on `host:`[`port`](./HttpServer.md#port), BLOCKING this thread until [`stop()`](./HttpServer.md#stop) (call [`stop`](./HttpServer.md#stop) from another thread; this call returns after the drain).

**Throws**

- `ClikaRT::Error`: when the socket cannot bind or listen.

<div class="api-declared">

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

</div>

### listen\_async() {#listen_async}

<div class="api-signature">

`void` **`listen_async`**(`std::string_view` `host`, `int` `port`)

</div>

Serve on `host:`[`port`](./HttpServer.md#port) on a background thread; returns once the server is accepting (pair with [`wait_until_ready`](./HttpServer.md#wait_until_ready) when racing a first request).

**Throws**

- `ClikaRT::Error`: when the socket cannot bind or listen.

<div class="api-declared">

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

</div>

### bind\_to\_any\_port() {#bind_to_any_port}

<div class="api-signature">

`int` **`bind_to_any_port`**(`std::string_view` `host`)

</div>

[`listen_async`](./HttpServer.md#listen_async) with an OS-chosen port: binds, serves in the background, and returns the port (read it again later via [`port()`](./HttpServer.md#port)).

**Throws**

- `ClikaRT::Error`: when no port can be bound.

<div class="api-declared">

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

</div>

### stop() {#stop}

<div class="api-signature">

`void` **`stop`**()

</div>

Stop accepting new connections and DRAIN: in-flight handlers run to completion and their responses flush before the serving loop exits (a blocking [`listen()`](./HttpServer.md#listen) then returns).

**Throws**

- `ClikaRT::Error`: when the stop cannot be issued.

<div class="api-declared">

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

</div>

### wait\_until\_ready() {#wait_until_ready}

<div class="api-signature">

`void` **`wait_until_ready`**(`int` `timeout_ms` `=` `30000`)

</div>

Block until the server is accepting, or `timeout_ms` elapses (→ error).

<div class="api-declared">

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

</div>

### is\_running() {#is_running}

<div class="api-signature">

`bool` **`is_running`**() `const`

</div>

<div class="api-declared">

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

</div>

### port() {#port}

<div class="api-signature">

`int` **`port`**() `const`

</div>

<div class="api-declared">

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

</div>