HTTP server with URI handler registration and RAII lifecycle. More...

Inheritance diagram for idfxx::http::server:

Classes
struct	config
	HTTP server configuration. More...

class	error_category
	Error category for HTTP server errors. More...

Public Types
enum class	errc : esp_err_t { handlers_full = 0xb001 , handler_exists = 0xb002 , invalid_request = 0xb003 , result_truncated = 0xb004 , resp_header = 0xb005 , resp_send = 0xb006 , alloc_mem = 0xb007 , task = 0xb008 }
	Error codes for HTTP server operations. More...

using	handler_type = std::move_only_function< result< void >(request &) const >
	Handler function type for URI handlers.

Public Member Functions
	server (config cfg)
	Creates and starts an HTTP server.

virtual	~server ()
	Stops the server and releases all resources.

	server (const server &)=delete

server &	operator= (const server &)=delete

	server (server &&) noexcept
	Move constructor.

server &	operator= (server &&) noexcept
	Move assignment.

void	on (enum method m, std::string uri, handler_type handler)
	Registers a URI handler for a specific HTTP method.

void	on_any (std::string uri, handler_type handler)
	Registers a URI handler that matches any HTTP method.

void	on_get (std::string uri, handler_type handler)
	Registers a GET handler.

void	on_post (std::string uri, handler_type handler)
	Registers a POST handler.

void	on_put (std::string uri, handler_type handler)
	Registers a PUT handler.

void	on_patch (std::string uri, handler_type handler)
	Registers a PATCH handler.

void	on_delete (std::string uri, handler_type handler)
	Registers a DELETE handler.

void	on_head (std::string uri, handler_type handler)
	Registers a HEAD handler.

result< void >	try_on (enum method m, std::string uri, handler_type handler)
	Registers a URI handler for a specific HTTP method.

result< void >	try_on_any (std::string uri, handler_type handler)
	Registers a URI handler that matches any HTTP method.

result< void >	try_on_get (std::string uri, handler_type handler)
	Registers a GET handler.

result< void >	try_on_post (std::string uri, handler_type handler)
	Registers a POST handler.

result< void >	try_on_put (std::string uri, handler_type handler)
	Registers a PUT handler.

result< void >	try_on_patch (std::string uri, handler_type handler)
	Registers a PATCH handler.

result< void >	try_on_delete (std::string uri, handler_type handler)
	Registers a DELETE handler.

result< void >	try_on_head (std::string uri, handler_type handler)
	Registers a HEAD handler.

void	unregister_handler (enum method m, std::string_view uri)
	Unregisters a URI handler.

result< void >	try_unregister_handler (enum method m, std::string_view uri)
	Unregisters a URI handler.

void	close_session (int sockfd)
	Closes a client session by socket file descriptor.

result< void >	try_close_session (int sockfd)
	Closes a client session by socket file descriptor.

httpd_handle_t	idf_handle () const noexcept
	Returns the underlying ESP-IDF HTTP server handle.

Static Public Member Functions
static result< server >	make (config cfg)
	Creates and starts an HTTP server.

Detailed Description

HTTP server with URI handler registration and RAII lifecycle.

Manages an HTTP server instance. Register URI handlers as C++ callables, which are invoked when matching requests arrive. Supports standard HTTP methods and optional WebSocket endpoints.

Not thread-safe for handler registration — register all handlers before serving concurrent requests.

Definition at line 478 of file server.hpp.

Member Typedef Documentation

◆ handler_type

using idfxx::http::server::handler_type = std::move_only_function<result<void>(request&) const>

Handler function type for URI handlers.

Definition at line 481 of file server.hpp.

Member Enumeration Documentation

◆ errc

enum class idfxx::http::server::errc : esp_err_t

strong

Error codes for HTTP server operations.

Enumerator
handlers_full	All URI handler slots are full.
handler_exists	URI handler already registered for this method and URI.
invalid_request	Invalid request pointer.
result_truncated	Result string was truncated.
resp_header	Response header field too large.
resp_send	Error sending response.
alloc_mem	Memory allocation failed.
task	Failed to create server task.

Definition at line 486 of file server.hpp.

Constructor & Destructor Documentation

◆ server() [1/3]

idfxx::http::server::server ( config cfg )

explicit

Creates and starts an HTTP server.

Parameters

cfg	Server configuration.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ ~server()

virtual idfxx::http::server::~server ( )

virtual

Stops the server and releases all resources.

◆ server() [2/3]

idfxx::http::server::server ( const server & )

delete

◆ server() [3/3]

idfxx::http::server::server ( server && )

noexcept

Move constructor.

Transfers server ownership.

Member Function Documentation

◆ close_session()

void idfxx::http::server::close_session ( int sockfd )

inline

Closes a client session by socket file descriptor.

Parameters

sockfd The socket file descriptor to close.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 861 of file server.hpp.

References try_close_session(), and idfxx::unwrap().

◆ idf_handle()

httpd_handle_t idfxx::http::server::idf_handle ( ) const

inlinenoexcept

Returns the underlying ESP-IDF HTTP server handle.

Returns: The httpd_handle_t.

Definition at line 880 of file server.hpp.

◆ make()

static result< server > idfxx::http::server::make ( config cfg )

static

Creates and starts an HTTP server.

Parameters

cfg	Server configuration.

Returns: The new server, or an error.

◆ on()

void idfxx::http::server::on	(	enum method	m,
		std::string	uri,
		handler_type	handler
	)

inline

Registers a URI handler for a specific HTTP method.

idfxx::http::server srv({});
srv.on(idfxx::http::method::get, "/api/status", [](idfxx::http::request& req) -> idfxx::result<void> {
    req.set_content_type("application/json");
    req.send(R"({"status": "ok"})");
    return {};
});

Parameters

m	The HTTP method to handle.
uri	The URI pattern to match.
handler	The handler function.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 619 of file server.hpp.

References try_on(), and idfxx::unwrap().

◆ on_any()

void idfxx::http::server::on_any	(	std::string	uri,
		handler_type	handler
	)

inline

Registers a URI handler that matches any HTTP method.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 631 of file server.hpp.

References try_on_any(), and idfxx::unwrap().

◆ on_delete()

void idfxx::http::server::on_delete	(	std::string	uri,
		handler_type	handler
	)

inline

Registers a DELETE handler.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 681 of file server.hpp.

References try_on_delete(), and idfxx::unwrap().

◆ on_get()

void idfxx::http::server::on_get	(	std::string	uri,
		handler_type	handler
	)

inline

Registers a GET handler.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 641 of file server.hpp.

References try_on_get(), and idfxx::unwrap().

◆ on_head()

void idfxx::http::server::on_head	(	std::string	uri,
		handler_type	handler
	)

inline

Registers a HEAD handler.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 691 of file server.hpp.

References try_on_head(), and idfxx::unwrap().

◆ on_patch()

void idfxx::http::server::on_patch	(	std::string	uri,
		handler_type	handler
	)

inline

Registers a PATCH handler.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 671 of file server.hpp.

References try_on_patch(), and idfxx::unwrap().

◆ on_post()

void idfxx::http::server::on_post	(	std::string	uri,
		handler_type	handler
	)

inline

Registers a POST handler.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 651 of file server.hpp.

References try_on_post(), and idfxx::unwrap().

◆ on_put()

void idfxx::http::server::on_put	(	std::string	uri,
		handler_type	handler
	)

inline

Registers a PUT handler.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 661 of file server.hpp.

References try_on_put(), and idfxx::unwrap().

◆ operator=() [1/2]

server & idfxx::http::server::operator= ( const server & )

delete

◆ operator=() [2/2]

server & idfxx::http::server::operator= ( server && )

noexcept

Move assignment.

Transfers server ownership.

◆ try_close_session()

result< void > idfxx::http::server::try_close_session ( int sockfd )

Closes a client session by socket file descriptor.

Parameters

sockfd The socket file descriptor to close.

Returns: Success, or an error.

Referenced by close_session().

◆ try_on()

result< void > idfxx::http::server::try_on	(	enum method	m,
		std::string	uri,
		handler_type	handler
	)

Registers a URI handler for a specific HTTP method.

Parameters

m	The HTTP method to handle.
uri	The URI pattern to match.
handler	The handler function.

Returns: Success, or an error.

Referenced by on(), try_on_delete(), try_on_get(), try_on_head(), try_on_patch(), try_on_post(), and try_on_put().

◆ try_on_any()

result< void > idfxx::http::server::try_on_any	(	std::string	uri,
		handler_type	handler
	)

Registers a URI handler that matches any HTTP method.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Returns: Success, or an error.

Referenced by on_any().

◆ try_on_delete()

result< void > idfxx::http::server::try_on_delete	(	std::string	uri,
		handler_type	handler
	)

inline

Registers a DELETE handler.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Returns: Success, or an error.

Definition at line 764 of file server.hpp.

References idfxx::http::delete_, and try_on().

Referenced by on_delete().

◆ try_on_get()

result< void > idfxx::http::server::try_on_get	(	std::string	uri,
		handler_type	handler
	)

inline

Registers a GET handler.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Returns: Success, or an error.

Definition at line 720 of file server.hpp.

References idfxx::http::get, and try_on().

Referenced by on_get().

◆ try_on_head()

result< void > idfxx::http::server::try_on_head	(	std::string	uri,
		handler_type	handler
	)

inline

Registers a HEAD handler.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Returns: Success, or an error.

Definition at line 775 of file server.hpp.

References idfxx::http::head, and try_on().

Referenced by on_head().

◆ try_on_patch()

result< void > idfxx::http::server::try_on_patch	(	std::string	uri,
		handler_type	handler
	)

inline

Registers a PATCH handler.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Returns: Success, or an error.

Definition at line 753 of file server.hpp.

References idfxx::http::patch, and try_on().

Referenced by on_patch().

◆ try_on_post()

result< void > idfxx::http::server::try_on_post	(	std::string	uri,
		handler_type	handler
	)

inline

Registers a POST handler.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Returns: Success, or an error.

Definition at line 731 of file server.hpp.

References idfxx::http::post, and try_on().

Referenced by on_post().

◆ try_on_put()

result< void > idfxx::http::server::try_on_put	(	std::string	uri,
		handler_type	handler
	)

inline

Registers a PUT handler.

Parameters

uri	The URI pattern to match.
handler	The handler function.

Returns: Success, or an error.

Definition at line 742 of file server.hpp.

References idfxx::http::put, and try_on().

Referenced by on_put().

◆ try_unregister_handler()

result< void > idfxx::http::server::try_unregister_handler	(	enum method	m,
		std::string_view	uri
	)

Unregisters a URI handler.

Parameters

m	The HTTP method of the handler to remove.
uri	The URI of the handler to remove.

Returns: Success, or an error.

Referenced by unregister_handler().

◆ unregister_handler()

void idfxx::http::server::unregister_handler	(	enum method	m,
		std::string_view	uri
	)

inline

Unregisters a URI handler.

Parameters

m	The HTTP method of the handler to remove.
uri	The URI of the handler to remove.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 792 of file server.hpp.

References try_unregister_handler(), and idfxx::unwrap().

The documentation for this class was generated from the following file:

idfxx_http_server/include/idfxx/http/server.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ handler_type

Member Enumeration Documentation

◆ errc

Constructor & Destructor Documentation

◆ server() [1/3]

◆ ~server()

◆ server() [2/3]

◆ server() [3/3]

Member Function Documentation

◆ close_session()

◆ idf_handle()

◆ make()

◆ on()

◆ on_any()

◆ on_delete()

◆ on_get()

◆ on_head()

◆ on_patch()

◆ on_post()

◆ on_put()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ try_close_session()

◆ try_on()

◆ try_on_any()

◆ try_on_delete()

◆ try_on_get()

◆ try_on_head()

◆ try_on_patch()

◆ try_on_post()

◆ try_on_put()

◆ try_unregister_handler()

◆ unregister_handler()