client.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/error>
#include <idfxx/http/types>
 
#include <chrono>
#include <cstdint>
#include <esp_idf_version.h>
#include <functional>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <system_error>
 
typedef struct esp_http_client* esp_http_client_handle_t;
struct esp_http_client_event;
typedef int esp_err_t;
 
namespace idfxx::http {
 
enum class event_id : int {
    // clang-format off
    error                = 0, 
    on_connected         = 1, 
    headers_sent         = 2, 
    on_header            = 3, 
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0)
    on_headers_complete  = 4, 
    on_status_code       = 5, 
    on_data              = 6, 
    on_finish            = 7, 
    disconnected         = 8, 
    redirect             = 9, 
#else
    on_data              = 4, 
    on_finish            = 5, 
    disconnected         = 6, 
    redirect             = 7, 
#endif
    // clang-format on
};
 
struct event_data {
    enum event_id id;              
    std::span<const uint8_t> data; 
    std::string_view header_key;   
    std::string_view header_value; 
};
 
class client {
public:
    enum class errc : esp_err_t {
        // clang-format off
        max_redirect      = 0x7001, 
        connect           = 0x7002, 
        write_data        = 0x7003, 
        fetch_header      = 0x7004, 
        invalid_transport = 0x7005, 
        connecting        = 0x7006, 
        eagain            = 0x7007, 
        connection_closed = 0x7008, 
        // 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 {
        // Connection
        std::string url = {};                               
        std::string host = {};                              
        int port = 0;                                       
        std::string path = {};                              
        std::string query = {};                             
        enum method method = method::get;                   
        enum transport transport_type = transport::unknown; 
        std::chrono::milliseconds timeout{5000};            
 
        // Authentication
        std::string username = {};                  
        std::string password = {};                  
        enum auth_type auth_type = auth_type::none; 
 
        // TLS (client stores owned copies to keep data alive for the handle)
        std::string cert_pem = {};        
        std::string client_cert_pem = {}; 
        std::string client_key_pem = {};  
 
        // Headers
        std::string user_agent = {}; 
 
        // Redirect
        bool disable_auto_redirect = false; 
        int max_redirection_count = 0;      
        int max_authorization_retries = 0;  
 
        // Buffers
        int buffer_size = 0;    
        int buffer_size_tx = 0; 
 
        // Keep-alive
        bool keep_alive_enable = false;              
        std::chrono::seconds keep_alive_idle{5};     
        std::chrono::seconds keep_alive_interval{5}; 
        int keep_alive_count = 3;                    
 
        // TLS options
        bool use_global_ca_store = false;         
        bool skip_cert_common_name_check = false; 
        std::string common_name = {};             
        std::move_only_function<int(void*) const> crt_bundle_attach = {};
 
        // Event handling
        std::move_only_function<void(const event_data&) const> on_event = {}; 
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit client(config cfg);
#endif
 
    [[nodiscard]] static result<client> make(config cfg);
 
    ~client();
 
    client(const client&) = delete;
    client& operator=(const client&) = delete;
 
    client(client&&) noexcept;
 
    client& operator=(client&&) noexcept;
 
    // =========================================================================
    // Request Configuration
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_url(std::string_view url) { unwrap(try_set_url(url)); }
 
#endif
 
    [[nodiscard]] result<void> try_set_url(std::string_view url);
 
    void set_method(enum method m);
 
    void set_header(std::string_view key, std::string_view value);
 
    void delete_header(std::string_view key);
 
    void set_post_field(std::string_view data);
 
    void set_username(std::string_view username);
 
    void set_password(std::string_view password);
 
    void set_auth_type(enum auth_type type);
 
    template<typename Rep, typename Period>
    void set_timeout(const std::chrono::duration<Rep, Period>& timeout) {
        _set_timeout(std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
    // =========================================================================
    // Simple Request (blocking)
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void perform() { unwrap(try_perform()); }
#endif
 
    [[nodiscard]] result<void> try_perform();
 
    // =========================================================================
    // Streaming API
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void open(size_t write_len = 0) { unwrap(try_open(write_len)); }
 
    void open(int write_len) { open(static_cast<size_t>(write_len)); }
 
    [[nodiscard]] size_t write(std::span<const uint8_t> data) { return unwrap(try_write(data)); }
 
    [[nodiscard]] size_t write(std::string_view data) { return unwrap(try_write(data)); }
 
    int64_t fetch_headers() { return unwrap(try_fetch_headers()); }
 
    [[nodiscard]] size_t read(std::span<uint8_t> buf) { return unwrap(try_read(buf)); }
 
    [[nodiscard]] size_t read(std::span<char> buf) { return unwrap(try_read(buf)); }
 
    void flush_response() { unwrap(try_flush_response()); }
 
    void close() { unwrap(try_close()); }
#endif
 
    [[nodiscard]] result<void> try_open(size_t write_len = 0);
 
    [[nodiscard]] result<void> try_open(int write_len) { return try_open(static_cast<size_t>(write_len)); }
 
    [[nodiscard]] result<size_t> try_write(std::span<const uint8_t> data);
 
    [[nodiscard]] result<size_t> try_write(std::string_view data);
 
    // [[nodiscard]] intentionally omitted: callers may fetch headers for their
    // side effects without needing the returned content-length value.
    result<int64_t> try_fetch_headers();
 
    [[nodiscard]] result<size_t> try_read(std::span<uint8_t> buf);
 
    [[nodiscard]] result<size_t> try_read(std::span<char> buf);
 
    [[nodiscard]] result<void> try_flush_response();
 
    [[nodiscard]] result<void> try_close();
 
    // =========================================================================
    // Response Accessors
    // =========================================================================
 
    [[nodiscard]] int status_code() const;
 
    [[nodiscard]] int64_t content_length() const;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] int chunk_length() const { return unwrap(try_chunk_length()); }
#endif
 
    [[nodiscard]] result<int> try_chunk_length() const;
 
    [[nodiscard]] bool is_chunked_response() const;
 
    [[nodiscard]] std::optional<std::string> get_header(std::string_view key) const;
 
    [[nodiscard]] std::string get_url() const;
 
    // =========================================================================
    // Redirect Control
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_redirection() { unwrap(try_set_redirection()); }
#endif
 
    [[nodiscard]] result<void> try_set_redirection();
 
    void reset_redirect_counter();
 
    // =========================================================================
    // Request Control
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void cancel_request() { unwrap(try_cancel_request()); }
#endif
 
    [[nodiscard]] result<void> try_cancel_request();
 
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0)
    enum class state : int {
        // clang-format off
        uninit              = 0, 
        init                = 1, 
        connecting          = 2, 
        connected           = 3, 
        req_complete_header = 4, 
        req_complete_data   = 5, 
        res_complete_header = 6, 
        res_on_data_start   = 7, 
        res_complete_data   = 8, 
        close               = 9, 
        // clang-format on
    };
 
    [[nodiscard]] enum state get_state() const;
#endif
 
    [[nodiscard]] esp_http_client_handle_t idf_handle() const noexcept { return _handle; }
 
private:
    client(
        esp_http_client_handle_t handle,
        std::move_only_function<void(const event_data&) const> on_event,
        std::move_only_function<int(void*) const> crt_bundle_attach,
        std::string post_data,
        std::string cert_pem,
        std::string client_cert_pem,
        std::string client_key_pem
    );
 
    void _set_timeout(std::chrono::milliseconds timeout);
 
    static result<esp_http_client_handle_t> _init_client(
        config& cfg,
        const std::string& cert_pem,
        const std::string& client_cert_pem,
        const std::string& client_key_pem
    );
    static esp_err_t _http_event_handler(esp_http_client_event* evt);
    static esp_err_t _crt_bundle_trampoline(void* conf);
 
    esp_http_client_handle_t _handle;
    std::move_only_function<void(const event_data&) const> _on_event;
    std::move_only_function<int(void*) const> _crt_bundle_attach;
    std::string _post_data;
    std::string _cert_pem;
    std::string _client_cert_pem;
    std::string _client_key_pem;
};
 
[[nodiscard]] const client::error_category& http_client_category() noexcept;
 
[[nodiscard]] inline std::error_code make_error_code(client::errc e) noexcept {
    return {std::to_underlying(e), http_client_category()};
}
 
[[nodiscard]] std::unexpected<std::error_code> http_client_error(esp_err_t e);
 
} // namespace idfxx::http
 
namespace idfxx {
 
[[nodiscard]] std::string to_string(http::event_id id);
 
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0)
[[nodiscard]] std::string to_string(http::client::state s);
#endif
 
} // namespace idfxx
 
namespace std {
template<>
struct is_error_code_enum<idfxx::http::client::errc> : true_type {};
} // namespace std
#include "sdkconfig.h"
#ifdef CONFIG_IDFXX_STD_FORMAT
#include <algorithm>
#include <format>
namespace std {
 
template<>
struct formatter<idfxx::http::event_id> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::http::event_id id, FormatContext& ctx) const {
        auto s = idfxx::to_string(id);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
 
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0)
template<>
struct formatter<idfxx::http::client::state> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::http::client::state s, FormatContext& ctx) const {
        auto str = idfxx::to_string(s);
        return std::copy(str.begin(), str.end(), ctx.out());
    }
};
#endif
 
} // namespace std
#endif // CONFIG_IDFXX_STD_FORMAT