server.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/cpu>
#include <idfxx/error>
#include <idfxx/http/types>
 
#include <chrono>
#include <cstdint>
#include <functional>
#include <list>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <system_error>
#include <utility>
#include <vector>
 
typedef void* httpd_handle_t;
struct httpd_config;
struct httpd_req;
typedef struct httpd_req httpd_req_t;
typedef int esp_err_t;
 
namespace idfxx::http {
 
class server;
 
class request {
public:
    request(const request&) = delete;
    request& operator=(const request&) = delete;
    request(request&&) = delete;
    request& operator=(request&&) = delete;
 
    // =========================================================================
    // Request Properties
    // =========================================================================
 
    [[nodiscard]] enum method method() const;
 
    [[nodiscard]] std::string_view uri() const;
 
    [[nodiscard]] size_t content_length() const;
 
    [[nodiscard]] int socket_fd() const;
 
    // =========================================================================
    // Headers
    // =========================================================================
 
    [[nodiscard]] std::optional<std::string> header(std::string_view field) const;
 
    // =========================================================================
    // Query String
    // =========================================================================
 
    [[nodiscard]] std::optional<std::string> query_string() const;
 
    [[nodiscard]] std::optional<std::string> query_param(std::string_view key) const;
 
    // =========================================================================
    // Request Body
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] size_t recv(std::span<uint8_t> buf) { return unwrap(try_recv(buf)); }
 
    [[nodiscard]] size_t recv(std::span<char> buf) { return unwrap(try_recv(buf)); }
 
    [[nodiscard]] std::string recv_body() { return unwrap(try_recv_body()); }
#endif
 
    [[nodiscard]] result<size_t> try_recv(std::span<uint8_t> buf);
 
    [[nodiscard]] result<size_t> try_recv(std::span<char> buf);
 
    [[nodiscard]] result<std::string> try_recv_body();
 
    // =========================================================================
    // Response Setup
    // =========================================================================
 
    void set_status(std::string_view status);
 
    void set_status(int code);
 
    void set_content_type(std::string_view content_type);
 
    void set_header(std::string_view field, std::string_view value);
 
    // =========================================================================
    // Response Sending
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void send(std::string_view body) { unwrap(try_send(body)); }
 
    void send(std::span<const uint8_t> body) { unwrap(try_send(body)); }
 
    void send_chunk(std::string_view chunk) { unwrap(try_send_chunk(chunk)); }
 
    void end_chunked() { unwrap(try_end_chunked()); }
 
    void send_error(int code, std::string_view message = {}) { unwrap(try_send_error(code, message)); }
#endif
 
    [[nodiscard]] result<void> try_send(std::string_view body);
 
    [[nodiscard]] result<void> try_send(std::span<const uint8_t> body);
 
    [[nodiscard]] result<void> try_send_chunk(std::string_view chunk);
 
    [[nodiscard]] result<void> try_end_chunked();
 
    [[nodiscard]] result<void> try_send_error(int code, std::string_view message = {});
 
    // =========================================================================
    // WebSocket
    // =========================================================================
 
#ifdef CONFIG_HTTPD_WS_SUPPORT
    enum class ws_frame_type : int {
        // clang-format off
        continuation = 0x0, 
        text         = 0x1, 
        binary       = 0x2, 
        close        = 0x8, 
        ping         = 0x9, 
        pong         = 0xA, 
        // clang-format on
    };
 
    struct ws_frame {
        ws_frame_type type;            
        bool final = true;             
        std::span<const uint8_t> data; 
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] ws_frame ws_recv(std::span<uint8_t> buf) { return unwrap(try_ws_recv(buf)); }
 
    void ws_send_text(std::string_view text) { unwrap(try_ws_send_text(text)); }
 
    void ws_send_binary(std::span<const uint8_t> data) { unwrap(try_ws_send_binary(data)); }
 
    void ws_send(const ws_frame& frame) { unwrap(try_ws_send(frame)); }
#endif
 
    [[nodiscard]] result<ws_frame> try_ws_recv(std::span<uint8_t> buf);
 
    [[nodiscard]] result<void> try_ws_send_text(std::string_view text);
 
    [[nodiscard]] result<void> try_ws_send_binary(std::span<const uint8_t> data);
 
    [[nodiscard]] result<void> try_ws_send(const ws_frame& frame);
#endif // CONFIG_HTTPD_WS_SUPPORT
 
    // =========================================================================
    // Escape Hatch
    // =========================================================================
 
    [[nodiscard]] httpd_req_t* idf_handle() const noexcept { return _req; }
 
private:
    friend class server;
    explicit request(httpd_req_t* req)
        : _req(req) {}
 
    httpd_req_t* _req;
    std::string _status_str;
    std::string _content_type;
    std::vector<std::pair<std::string, std::string>> _resp_headers;
    mutable bool _query_fetched = false;
    mutable std::optional<std::string> _query_cache;
};
 
class server {
public:
    using handler_type = std::move_only_function<result<void>(request&) const>;
 
    enum class errc : esp_err_t {
        // clang-format off
        handlers_full    = 0xb001, 
        handler_exists   = 0xb002, 
        invalid_request  = 0xb003, 
        result_truncated = 0xb004, 
        resp_header      = 0xb005, 
        resp_send        = 0xb006, 
        alloc_mem        = 0xb007, 
        task             = 0xb008, 
        // clang-format on
    };
 
    class error_category : public std::error_category {
    public:
        [[nodiscard]] const char* name() const noexcept override final;
 
        [[nodiscard]] std::string message(int ec) const override final;
    };
 
    struct config {
        // Task
        task_priority priority = 5;                          
        size_t stack_size = 4096;                            
        std::optional<core_id> core_affinity = std::nullopt; 
 
        // Network
        uint16_t server_port = 80;  
        uint16_t ctrl_port = 32768; 
        uint16_t backlog_conn = 5;  
 
        // Limits
        uint16_t max_open_sockets = 7; 
        uint16_t max_uri_handlers = 8; 
        uint16_t max_resp_headers = 8; 
        size_t max_req_hdr_len = 0;    
        size_t max_uri_len = 0;        
 
        // Timeouts
        std::chrono::seconds recv_wait_timeout{5}; 
        std::chrono::seconds send_wait_timeout{5}; 
 
        // LRU
        bool lru_purge_enable = false; 
 
        // SO_LINGER
        bool enable_so_linger = false;          
        std::chrono::seconds linger_timeout{0}; 
 
        // Keep-alive
        bool keep_alive_enable = false;              
        std::chrono::seconds keep_alive_idle{0};     
        std::chrono::seconds keep_alive_interval{0}; 
        int keep_alive_count = 0;                    
 
        // URI matching
        bool wildcard_uri_match = false; 
 
        // Session callbacks
        std::move_only_function<result<void>(int) const> on_session_open = {};
        std::move_only_function<void(int) const> on_session_close = {};
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit server(config cfg);
#endif
 
    [[nodiscard]] static result<server> make(config cfg);
 
    virtual ~server();
 
    server(const server&) = delete;
    server& operator=(const server&) = delete;
 
    server(server&&) noexcept;
 
    server& operator=(server&&) noexcept;
 
    // =========================================================================
    // Handler Registration
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void on(enum method m, std::string uri, handler_type handler) {
        unwrap(try_on(m, std::move(uri), std::move(handler)));
    }
 
    void on_any(std::string uri, handler_type handler) { unwrap(try_on_any(std::move(uri), std::move(handler))); }
 
    void on_get(std::string uri, handler_type handler) { unwrap(try_on_get(std::move(uri), std::move(handler))); }
 
    void on_post(std::string uri, handler_type handler) { unwrap(try_on_post(std::move(uri), std::move(handler))); }
 
    void on_put(std::string uri, handler_type handler) { unwrap(try_on_put(std::move(uri), std::move(handler))); }
 
    void on_patch(std::string uri, handler_type handler) { unwrap(try_on_patch(std::move(uri), std::move(handler))); }
 
    void on_delete(std::string uri, handler_type handler) { unwrap(try_on_delete(std::move(uri), std::move(handler))); }
 
    void on_head(std::string uri, handler_type handler) { unwrap(try_on_head(std::move(uri), std::move(handler))); }
#endif
 
    [[nodiscard]] result<void> try_on(enum method m, std::string uri, handler_type handler);
 
    [[nodiscard]] result<void> try_on_any(std::string uri, handler_type handler);
 
    [[nodiscard]] result<void> try_on_get(std::string uri, handler_type handler) {
        return try_on(method::get, std::move(uri), std::move(handler));
    }
 
    [[nodiscard]] result<void> try_on_post(std::string uri, handler_type handler) {
        return try_on(method::post, std::move(uri), std::move(handler));
    }
 
    [[nodiscard]] result<void> try_on_put(std::string uri, handler_type handler) {
        return try_on(method::put, std::move(uri), std::move(handler));
    }
 
    [[nodiscard]] result<void> try_on_patch(std::string uri, handler_type handler) {
        return try_on(method::patch, std::move(uri), std::move(handler));
    }
 
    [[nodiscard]] result<void> try_on_delete(std::string uri, handler_type handler) {
        return try_on(method::delete_, std::move(uri), std::move(handler));
    }
 
    [[nodiscard]] result<void> try_on_head(std::string uri, handler_type handler) {
        return try_on(method::head, std::move(uri), std::move(handler));
    }
 
    // =========================================================================
    // Handler Unregistration
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void unregister_handler(enum method m, std::string_view uri) { unwrap(try_unregister_handler(m, uri)); }
#endif
 
    [[nodiscard]] result<void> try_unregister_handler(enum method m, std::string_view uri);
 
    // =========================================================================
    // WebSocket
    // =========================================================================
 
#ifdef CONFIG_HTTPD_WS_SUPPORT
    struct ws_config {
        bool handle_control_frames = false;     
        std::string supported_subprotocol = {}; 
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void on_ws(std::string uri, handler_type handler, ws_config ws_cfg = {}) {
        unwrap(try_on_ws(std::move(uri), std::move(handler), std::move(ws_cfg)));
    }
#endif
 
    [[nodiscard]] result<void> try_on_ws(std::string uri, handler_type handler, ws_config ws_cfg = {});
#endif // CONFIG_HTTPD_WS_SUPPORT
 
    // =========================================================================
    // Session Control
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void close_session(int sockfd) { unwrap(try_close_session(sockfd)); }
#endif
 
    [[nodiscard]] result<void> try_close_session(int sockfd);
 
    // =========================================================================
    // Escape Hatch
    // =========================================================================
 
    [[nodiscard]] httpd_handle_t idf_handle() const noexcept { return _handle; }
 
protected:
    using stop_fn_type = esp_err_t (*)(httpd_handle_t);
 
    struct server_ctx {
        server* self;
    };
 
    server(
        httpd_handle_t handle,
        std::unique_ptr<server_ctx> ctx,
        std::move_only_function<result<void>(int) const> on_session_open,
        std::move_only_function<void(int) const> on_session_close,
        stop_fn_type stop_fn
    );
 
    static esp_err_t _session_open_trampoline(httpd_handle_t hd, int sockfd);
    static void _session_close_trampoline(httpd_handle_t hd, int sockfd);
 
    template<typename Config>
    static void _populate_httpd_config(
        struct httpd_config& httpd_cfg,
        const Config& cfg,
        server_ctx* ctx,
        bool has_session_open,
        bool has_session_close
    );
 
private:
    struct handler_record {
        std::string uri;
        unsigned httpd_method; // httpd_method_t value (from http_parser enum)
        handler_type handler;
#ifdef CONFIG_HTTPD_WS_SUPPORT
        bool is_websocket = false;
        bool handle_ws_control_frames = false;
        std::string supported_subprotocol;
#endif
    };
 
    [[nodiscard]] result<void> _register_handler(handler_record& record);
    [[nodiscard]] result<void> _try_register(unsigned httpd_method, std::string uri, handler_type handler);
    [[nodiscard]] static result<httpd_handle_t>
    _start_server(const config& cfg, server_ctx* ctx, bool has_session_open, bool has_session_close);
 
    static esp_err_t _uri_handler_trampoline(httpd_req_t* req);
 
    httpd_handle_t _handle;
    stop_fn_type _stop_fn;
    std::unique_ptr<server_ctx> _ctx;
    std::list<handler_record> _handlers;
    std::move_only_function<result<void>(int) const> _on_session_open;
    std::move_only_function<void(int) const> _on_session_close;
};
 
[[nodiscard]] const server::error_category& http_server_category() noexcept;
 
[[nodiscard]] inline std::error_code make_error_code(server::errc e) noexcept {
    return {std::to_underlying(e), http_server_category()};
}
 
[[nodiscard]] std::unexpected<std::error_code> http_server_error(esp_err_t e);
 
} // namespace idfxx::http
 
namespace std {
template<>
struct is_error_code_enum<idfxx::http::server::errc> : true_type {};
} // namespace std