# idfxx_http_server
Type-safe HTTP server for ESP32.
## Features
- RAII lifecycle management (start/stop)
- URI handler registration with `std::move_only_function` handlers
- Convenience methods for GET, POST, PUT, PATCH, DELETE, HEAD
- Wildcard and any-method URI matching
- Server-wide error handlers for custom error responses (e.g. 404 pages), also callable from URI
handlers
- Request header, query string, and body parsing; the body is readable as an `idfxx::byte_source`
- Chunked and complete response sending
- Session open/close callbacks
- WebSocket endpoint support (when `CONFIG_HTTPD_WS_SUPPORT` is enabled)
- Reading WebSocket frames larger than the receive buffer in parts (ESP-IDF 6.1+)
- Binding the server to a single network interface (ESP-IDF 6.1+)
- Chrono-typed timeouts and keep-alive intervals
- Dual API: exception-based and result-based error handling
## Requirements
- ESP-IDF 5.5 or later
- C++23 compiler
## Installation
### ESP-IDF Component Manager
Add to your project's `idf_component.yml`:
```yaml
dependencies:
idfxx_http_server:
version: "^2.0.0"
```
Or add `idfxx_http_server` to the `REQUIRES` list in your component's `CMakeLists.txt`.
## Usage
### Simple GET Handler
If `CONFIG_COMPILER_CXX_EXCEPTIONS` is enabled:
```cpp
#include <idfxx/http/server>
#include <idfxx/log>
try {
idfxx::http::server srv({.server_port = 80});
srv.on_get("/api/status", [](idfxx::http::request& req) -> idfxx::result<void> {
req.set_content_type("application/json");
req.send(R"({"status": "ok"})");
return {};
});
srv.on_post("/api/data", [](idfxx::http::request& req) -> idfxx::result<void> {
auto body = req.read_body();
idfxx::log::info("HTTP", "Received: {}", body);
req.send("accepted");
return {};
});
// Server runs until srv goes out of scope
} catch (const std::system_error& e) {
// Starting the server or registering a handler failed. Exceptions thrown
// by handlers never reach here (see Important Notes).
idfxx::log::error("HTTP", "Server failed: {}", e.what());
}
```
### Result-based API
If `CONFIG_COMPILER_CXX_EXCEPTIONS` is *not* enabled, the result-based API must be used:
```cpp
#include <idfxx/http/server>
#include <idfxx/log>
auto result = idfxx::http::server::make({.server_port = 80});
if (!result) {
idfxx::log::error("HTTP", "Failed to start server: {}", result.error().message());
return;
}
auto& srv = *result;
auto r = srv.try_on_get("/api/status", [](idfxx::http::request& req) -> idfxx::result<void> {
if (auto res = req.try_set_content_type("text/plain"); !res) return res;
return req.try_send("hello");
});
if (!r) {
idfxx::log::error("HTTP", "Failed to register handler: {}", r.error().message());
}
```
### Custom Error Responses
Register a handler to replace the default response for an HTTP error, whether the server detects it
itself or a URI handler raises it with `handle_error()`:
```cpp
using idfxx::http::status_code;
srv.on_error(status_code::not_found, [](idfxx::http::request& req, status_code) -> idfxx::result<void> {
req.set_status(404);
req.set_content_type("text/html");
req.send("<h1>Page not found</h1>");
return {}; // keep the connection open
});
srv.on_get("/items", [&](idfxx::http::request& req) -> idfxx::result<void> {
auto id = req.query_param("id");
if (!id || !items.contains(*id)) {
req.handle_error(status_code::not_found); // sends the custom 404 page
return {};
}
req.send(items.at(*id));
return {};
});
```
Only the error statuses the server can raise itself are accepted (`error_status`); a constant
`status_code` outside that set fails to compile, and a status code known only at run time is checked
with `error_status::from()`.
### Reading Large WebSocket Frames
From ESP-IDF 6.1, a WebSocket handler can read a frame's payload in parts, so frames larger than the
available buffer can be processed:
```cpp
srv.on_ws("/ws", [](idfxx::http::request& req) -> idfxx::result<void> {
auto reader = req.ws_recv_begin();
if (reader.type() != idfxx::http::request::ws_frame_type::binary) {
reader.skip(); // discard frames we don't handle
return {};
}
std::array<std::byte, 256> buf;
while (reader.remaining() > 0) {
idfxx::byte_span part = reader.read(buf); // unmasked payload, the front of buf
process(part);
}
return {};
});
```
The whole payload must be read, or discarded with `skip()`, before the handler returns — see
[Important Notes](#important-notes).
### Binding to a Network Interface
From ESP-IDF 6.1, the server can be restricted to connections arriving through a single network
interface, identified by its lwIP name:
```cpp
idfxx::http::server srv({.server_port = 80, .bind_to_device = "st1"});
```
## API Overview
### Types
- `request` - Non-owning view of an HTTP request (valid only during handler invocation)
- `request::ws_frame_reader` - Reads one WebSocket frame's payload in parts (ESP-IDF 6.1+)
- `server` - HTTP server with RAII lifecycle and handler registration
- `status_code` - HTTP response status codes
- `error_status` - A `status_code` the server can pass to an error handler (checked at compile time,
or at run time with `error_status::from()`)
### `request`
**Properties:**
- `method()` - HTTP method
- `uri()` - Request URI
- `content_length()` - Body length
- `socket_fd()` - Connection socket
**Headers & Query:**
- `header(field)` - Get request header (returns `std::optional`)
- `query_string()` - Full query string (returns `std::optional`)
- `query_param(key)` - Single query parameter (returns `std::optional`)
**Body:**
- `read(buf)` / `try_read(buf)` - Read the next part of the body into a byte or `char` buffer; 0 at
the end of the body (after `content_length()` bytes), `invalid_request` if the connection closes
before then. `try_read(idfxx::byte_span)` makes the request an `idfxx::byte_source`
- `read_body()` / `try_read_body()` - Read the rest of the body as a string; `invalid_request` if
the connection closes before the whole body arrives
**Response:**
- `set_status(code)` / `set_status(str)` / `try_set_status(str)` - Set response status
- `set_content_type(type)` / `try_set_content_type(type)` - Set Content-Type
- `set_header(field, value)` / `try_set_header(field, value)` - Add response header (at most
`max_resp_headers`)
- `send(body)` / `try_send(body)` - Send complete response (text or bytes)
- `send_chunk(data)` / `try_send_chunk(data)` - Send one chunk of a chunked response (text or
bytes); empty data sends nothing
- `end_chunked()` / `try_end_chunked()` - End chunked response
- `send_error(code, msg)` / `try_send_error(code, msg)` - Send error response
- `handle_error(status)` / `try_handle_error(status)` - Respond with the server's error handler for
`status`, or the default error response
**WebSocket (CONFIG_HTTPD_WS_SUPPORT):**
- `ws_recv(buf)` / `try_ws_recv(buf)` - Receive WebSocket frame (the payload must fit in `buf`)
- `ws_recv_begin()` / `try_ws_recv_begin()` - Begin receiving a frame whose payload is read in parts
(ESP-IDF 6.1+)
- `ws_send_text(text)` / `try_ws_send_text(text)` - Send text frame
- `ws_send_binary(data)` / `try_ws_send_binary(data)` - Send binary frame
- `ws_send(frame)` / `try_ws_send(frame)` - Send arbitrary frame
### `request::ws_frame_reader` (ESP-IDF 6.1+, CONFIG_HTTPD_WS_SUPPORT)
- `type()` / `final()` - Frame type and FIN flag
- `size()` / `remaining()` - Total payload length and bytes not yet read
- `read(buf)` / `try_read(buf)` - Read the next part of the payload into `buf`, returning the
filled front of `buf` as an `idfxx::byte_span`
- `skip()` / `try_skip()` - Discard the rest of the payload
### `server`
**Creation:**
- `server(cfg)` - Constructor (exception-based, if enabled)
- `make(cfg)` - Create server (result-based)
- `config::bind_to_device` - Accept connections on one network interface only (ESP-IDF 6.1+)
**Handler Registration:**
- `on(method, uri, handler)` / `try_on(...)` - Register for specific method
- `on_any(uri, handler)` / `try_on_any(...)` - Register for any method
- `on_get` / `on_post` / `on_put` / `on_patch` / `on_delete` / `on_head` + `try_` variants
- `unregister_handler(method, uri)` / `try_unregister_handler(...)`
**Error Handlers:**
- `on_error(status, handler)` / `try_on_error(...)` - Register a server-wide handler for an HTTP
error
- `unregister_error_handler(status)` / `try_unregister_error_handler(...)` - Restore the default
error response
**WebSocket (CONFIG_HTTPD_WS_SUPPORT):**
- `on_ws(uri, handler[, ws_cfg])` / `try_on_ws(...)` - Register WebSocket endpoint
**Session:**
- `close_session(sockfd)` / `try_close_session(sockfd)` - Close client connection
## Error Handling
- **HTTP server errors**: `server::errc` enum maps to ESP-IDF `ESP_ERR_HTTPD_*` codes
- `handlers_full` - All URI handler slots are full
- `handler_exists` - Duplicate handler registration
- `invalid_request` - Invalid or incomplete request, or receiving it failed (including a
connection that closes before the whole request body arrives)
- `result_truncated` - Result string truncated
- `resp_header` - Too many response headers (over `max_resp_headers`), or headers too large
- `resp_send` - Error sending response
- `alloc_mem` - Memory allocation failed
- `task` - Failed to create server task
- **Dual API Pattern**: `try_*` methods return `idfxx::result<T>`, throwing methods raise
`std::system_error`
## Important Notes
- **Handler lifetime**: Handlers are stored internally and must not reference stack-local data that
goes out of scope
- **Exceptions in callbacks**: With exceptions enabled, handlers and session callbacks may throw. An
exception thrown by a handler closes the connection: a `std::system_error` is treated exactly like
returning its error code, and any other exception is also logged as an error. An exception thrown
by `on_session_open` rejects the session, and one thrown by `on_session_close` is logged and
ignored. The server keeps running either way
- **Stopping the server**: Destroying a server, or move-assigning over one that is running, stops
it and waits for in-flight handlers and session callbacks to return. Never do either from within
one of that server's own handlers or callbacks: the server cannot stop until they return, so it
deadlocks. If the server cannot be stopped (for example while the network stack is out of
buffers), it retries briefly and then aborts, since releasing what the server is still using
would be unsafe
- **Request lifetime**: The `request` object is only valid during the handler invocation; do not
store references to it
- **Thread safety**: Handler registration is not thread-safe; register all handlers before the
server begins accepting connections
- **Response strings**: `set_status()`, `set_content_type()` and `set_header()` copy their strings
and keep them until the response is sent. They reject text that would corrupt the response
(`invalid_arg`): a carriage return, line feed or null character, or a header name that isn't an
HTTP token. The string forms throw, so without exceptions use `try_set_status()`,
`try_set_content_type()` and `try_set_header()`; `set_status(int)` can't fail and is always
available
- **WebSocket**: WebSocket support requires `CONFIG_HTTPD_WS_SUPPORT` to be enabled in menuconfig
- **WebSocket frame size**: `ws_recv()` needs the whole payload to fit in the buffer. A larger frame
fails with `invalid_size` and its payload is left unread; since the connection cannot continue
past unread payload, it is closed when the handler returns, even if the handler reports success.
The same applies when receiving the frame fails, since the position in the stream is then unknown.
From ESP-IDF 6.1, use `ws_recv_begin()` for frames that may not fit
- **Consume the whole WebSocket frame**: When using `ws_recv_begin()`, read the whole payload or
discard the rest with `skip()` before the handler returns. Unread payload would otherwise be
parsed as the next frame, so if a `ws_frame_reader` is destroyed with payload left unread, or
receiving the frame fails, the connection is closed when the handler returns (even if the handler
reports success) and a warning is logged. `ws_recv_begin()` can be called at most once per handler
invocation, and not together with `ws_recv()`. The reader must not outlive the handler invocation
- **Error handlers and the connection**: An error handler that returns success keeps the connection
open, except for `internal_server_error`, which always closes it; one that returns an error closes
it. After `handle_error()`, the response is complete, so send nothing further; the connection is
closed once the URI handler returns if the error handler failed, the status is
`internal_server_error`, or no error handler is registered (the default error response is sent
then). For errors the server detects while receiving a request (e.g. `bad_request`,
`request_timeout`, `uri_too_long`, `request_header_fields_too_large`), the handler may see a
partially parsed request, so `uri()` and headers can be incomplete or empty
- **Limits and keep-alive tuning**: `max_req_hdr_len` and `max_uri_len` default to the project's
`CONFIG_HTTPD_MAX_REQ_HDR_LEN` and `CONFIG_HTTPD_MAX_URI_LEN` settings; `keep_alive_idle`,
`keep_alive_interval` and `keep_alive_count` default to `std::nullopt` to let the driver choose.
An explicit value of zero or less is rejected with `invalid_arg`
- **Interface binding**: `bind_to_device` takes the lwIP interface name (e.g. `"st1"`, from
`esp_netif_get_netif_impl_name()`), not the esp_netif key. The interface must exist when the
server starts, otherwise starting fails; names of 6 or more characters are rejected with
`invalid_arg`
## License
Apache License 2.0 - see [LICENSE](LICENSE) for details.
57caa7b2aabd577aa3ac24211bda868e980767b0
idf.py add-dependency "cleishm/idfxx_http_server^3.0.0"