DetWebServer Class Reference

Single-port HTTP server with deterministic, zero-allocation execution. More...

#include <DeterministicESPAsyncWebServer.h>

Public Member Functions
	DetWebServer ()
	Construct a DetWebServer with an empty routing table.
int32_t	begin (uint16_t port, const WebServerConfig *cfg=nullptr)
	Initialise all connection slots and open the TCP listener.
void	stop ()
	Gracefully stop the server.
int32_t	restart (const WebServerConfig *cfg=nullptr)
	Hard-reset all connections and reinitialise the server on the same port that was passed to begin().
void	on (const char *path, HttpMethod method, Handler callback)
	Register a route handler.
void	on_not_found (Handler callback)
	Register a fallback handler for unmatched requests.
void	set_cors (const char *origin)
	Enable CORS by pre-building the Access-Control headers.
void	handle ()
	Drive the server — call every Arduino loop() iteration.
void	send (uint8_t slot_id, int code, const char *content_type, const char *payload)
	Send an HTTP response with a body and close the connection.
void	send_empty (uint8_t slot_id, int code)
	Send a headers-only HTTP response and close the connection.

Static Public Member Functions
static size_t	heap_needed ()
	Bytes of contiguous heap that begin() will allocate.
static bool	heap_available ()
	True if the largest contiguous free heap block >= heap_needed().

Detailed Description

Single-port HTTP server with deterministic, zero-allocation execution.

Typical usage

DetWebServer server;
 
void handle_api(uint8_t slot_id, HttpReq *req) {
    server.send(slot_id, 200, "application/json", "{\"ok\":true}");
}
 
void setup() {
    WiFi.begin("SSID", "PASSWORD");
    server.on("/api/*", HTTP_GET, handle_api);
    server.set_cors("*");
    int32_t result = server.begin(80);
    if (result < 0) { } // abs(result) == heap bytes needed
}
 
void loop() {
    server.handle();   // call every iteration — O(MAX_CONNS) per call
}

Design constraints

• Maximum simultaneous connections: MAX_CONNS (default 4).
• Maximum registered routes: MAX_ROUTES (default 16).
• Responses are sent synchronously and the TCP connection is closed immediately after every response (HTTP/1.0 close semantics).

Definition at line 227 of file DeterministicESPAsyncWebServer.h.

Constructor & Destructor Documentation

DetWebServer()

DetWebServer::DetWebServer

(

)

Construct a DetWebServer with an empty routing table.

All route slots are marked inactive. CORS is disabled. The not-found handler is null (falls back to built-in 404 response).

Definition at line 138 of file DeterministicESPAsyncWebServer.cpp.

References MAX_ROUTES.

Member Function Documentation

heap_needed()

size_t DetWebServer::heap_needed ( )

static

Bytes of contiguous heap that begin() will allocate.

The event queue is the library's only dynamic allocation. Compare this value against heap_caps_get_largest_free_block(MALLOC_CAP_8BIT) to verify a suitable block exists before calling begin().

if (!DetWebServer::heap_available()) {
    Serial.printf("need %u contiguous bytes, largest block is %u\n",
                  DetWebServer::heap_needed(),
                  heap_caps_get_largest_free_block(MALLOC_CAP_8BIT));
    return;
}
server.begin(80);

Definition at line 135 of file DeterministicESPAsyncWebServer.cpp.

References DeterministicAsyncTCP::heap_needed().

heap_available()

bool DetWebServer::heap_available ( )

static

True if the largest contiguous free heap block >= heap_needed().

A false return means begin() will fail; check heap fragmentation or reduce EVT_QUEUE_DEPTH.

Definition at line 136 of file DeterministicESPAsyncWebServer.cpp.

References DeterministicAsyncTCP::heap_available().

begin()

int32_t DetWebServer::begin	(	uint16_t	port,
		const WebServerConfig *	cfg = nullptr
	)

Initialise all connection slots and open the TCP listener.

Resets the HTTP parser pool and delegates to DeterministicAsyncTCP::init(). Pass a WebServerConfig to tune runtime parameters (timeout, etc.) at init time; the config may live in PROGMEM (flash) or RAM.

Parameters

port	TCP port to listen on (typically 80).
cfg	Optional runtime configuration. Pass nullptr for defaults.

Returns

Positive value on success; negative value whose absolute value is the number of heap bytes needed when initialisation fails.

Definition at line 145 of file DeterministicESPAsyncWebServer.cpp.

References http_reset(), DeterministicAsyncTCP::init(), MAX_CONNS, sse_init(), and ws_init().

Referenced by restart().

stop()

void DetWebServer::stop

(

)

Gracefully stop the server.

Aborts all active connections, closes the listener, frees the event queue, and resets all HTTP parser slots. The WiFi and TCP/IP stack remain active. Call begin() or restart() to bring the server back up.

Definition at line 167 of file DeterministicESPAsyncWebServer.cpp.

References http_reset(), MAX_CONNS, sse_init(), DeterministicAsyncTCP::stop(), and ws_init().

Referenced by restart().

restart()

int32_t DetWebServer::restart

(

const WebServerConfig *

cfg = nullptr

)

Hard-reset all connections and reinitialise the server on the same port that was passed to begin().

Equivalent to stop() followed by begin() with the original port and an optional new runtime config. The WiFi and TCP/IP stack are not touched. Returns the same values as begin(): positive on success, negative whose absolute value is the heap bytes needed on failure.

Calling restart() before begin() has no effect and returns -1.

Parameters

cfg	Optional new runtime configuration. Pass nullptr to reuse the compile-time default (CONN_TIMEOUT_MS).

Definition at line 159 of file DeterministicESPAsyncWebServer.cpp.

References begin(), and stop().

on()

void DetWebServer::on	(	const char *	path,
		HttpMethod	method,
		Handler	callback
	)

Register a route handler.

Routes are matched in registration order (first match wins). A trailing * in path enables prefix matching: "/api/*" matches "/api/users", "/api/devices", etc.

Parameters

path	URL path pattern, e.g. "/api/status" or "/files/*". Must be ≤ MAX_PATH_LEN - 1 characters.
method	HTTP method this route accepts.
callback	Function called when this route is matched.

Note

Registering more than MAX_ROUTES routes silently drops extras.

Definition at line 203 of file DeterministicESPAsyncWebServer.cpp.

References Route::callback, MAX_ROUTES, Route::method, ROUTE_HTTP, and Route::type.

on_not_found()

void DetWebServer::on_not_found

(

Handler

callback

)

Register a fallback handler for unmatched requests.

Called instead of sending a built-in 404 when no route matches. The callback may call send() to return a custom error page.

Parameters

callback

Handler to invoke on a 404 condition.

Definition at line 264 of file DeterministicESPAsyncWebServer.cpp.

set_cors()

void DetWebServer::set_cors

(

const char *

origin

)

Enable CORS by pre-building the Access-Control headers.

Enable CORS and pre-build the Access-Control response header block.

Once called, every response produced by send() and send_empty() includes the CORS headers. OPTIONS requests are intercepted and answered with 204 automatically (preflight short-circuit).

Parameters

origin

Access-Control-Allow-Origin value, e.g. "*" or "https://example.com". Pass "" to disable CORS.

The header string is constructed once here rather than at response time to avoid repeated snprintf calls on the hot path. It is stored in _cors_header_buf[] and injected verbatim into every response when _cors_enabled is true.

Passing an empty or null origin disables CORS without clearing the buffer — only the _cors_enabled flag matters at dispatch time.

Parameters

origin

Value for the Access-Control-Allow-Origin header, e.g. "*".

Definition at line 282 of file DeterministicESPAsyncWebServer.cpp.

References CORS_HDR_BUF_SIZE.

handle()

void DetWebServer::handle

(

)

Drive the server — call every Arduino loop() iteration.

Main application tick — tick the session layer then dispatch completed requests.

Internally this:

1. Calls DeterministicAsyncTCP::check_timeouts() to kill stale connections.
2. Drains the event queue (connections, data, disconnects, errors).
3. Scans all connection slots for PARSE_COMPLETE requests and dispatches them to the matching route handler.
4. Auto-sends 400 for any slot stuck in PARSE_ERROR.
5. Auto-sends 413 for any slot stuck in PARSE_ENTITY_TOO_LARGE.
6. Auto-sends 414 for any slot stuck in PARSE_URI_TOO_LONG.

Call this repeatedly from loop(). Each call:

1. Calls server_tick() which runs timeout sweeps + drains the event queue.
2. Walks all slots; any in PARSE_COMPLETE is dispatched via match_and_execute().
3. Any slot left in PARSE_COMPLETE after dispatch (i.e., callback did not send a response) is reset so it doesn't block the slot.
4. Any slot in PARSE_ERROR receives an automatic 400 response.
5. Any slot in PARSE_ENTITY_TOO_LARGE receives an automatic 413 response.
6. Any slot in PARSE_URI_TOO_LONG receives an automatic 414 response.

Definition at line 331 of file DeterministicESPAsyncWebServer.cpp.

References http_pool, http_reset(), MAX_CONNS, PARSE_COMPLETE, PARSE_ENTITY_TOO_LARGE, PARSE_ERROR, WsConn::parse_state, PARSE_URI_TOO_LONG, send(), server_tick(), sse_find(), ws_close(), WS_CLOSED, WS_ERROR, ws_find(), WS_FRAME_READY, ws_free(), WsConn::ws_id, ws_parse(), and ws_reset_frame().

send()

void DetWebServer::send	(	uint8_t	slot_id,
		int	code,
		const char *	content_type,
		const char *	payload
	)

Send an HTTP response with a body and close the connection.

Build and transmit an HTTP response with a body.

Writes status line, Content-Type, Content-Length, optional CORS headers, and the payload; then calls tcp_close (tcp_abort on failure). Always calls http_reset() at the end to free the parser slot.

Parameters

slot_id	Connection slot index returned by the router.
code	HTTP status code (200, 404, 500, …).
content_type	MIME type string, e.g. "application/json".
payload	Null-terminated response body.

Note

If the underlying PCB has already been freed (e.g. by a concurrent timeout), this function is a no-op that just resets the slot.

Uses a 512-byte stack buffer for headers. CORS headers are appended when _cors_enabled. The slot is freed (state → CONN_FREE, pcb → nullptr) before the tcp_write + tcp_close sequence to ensure any error callback that lwIP fires during the write sees the slot as already released.

If the slot's connection is not active (e.g., already timed-out or the PCB is null) the slot is reset and the function returns without writing.

Parameters

slot_id	Connection slot index.
code	HTTP status code, e.g. 200.
content_type	MIME type string, e.g. "application/json".
payload	Null-terminated body string to send.

Definition at line 639 of file DeterministicESPAsyncWebServer.cpp.

References CONN_ACTIVE, CONN_FREE, conn_pool, http_reset(), TcpConn::pcb, RESP_HDR_BUF_SIZE, and TcpConn::state.

Referenced by handle().

send_empty()

void DetWebServer::send_empty	(	uint8_t	slot_id,
		int	code
	)

Send a headers-only HTTP response and close the connection.

Build and transmit an HTTP response with no body.

Equivalent to send() with an empty body and Content-Length: 0. Useful for 204 No Content, 304 Not Modified, HEAD responses, and CORS preflight replies.

Parameters

slot_id	Connection slot index.
code	HTTP status code.

Used for CORS preflight (204) and any response where only status headers are needed. Behaves identically to send() regarding slot lifecycle and PCB ownership transfer — the slot is freed before the lwIP write call.

Parameters

slot_id	Connection slot index.
code	HTTP status code, e.g. 204.

Definition at line 689 of file DeterministicESPAsyncWebServer.cpp.

References CONN_ACTIVE, CONN_FREE, conn_pool, http_reset(), TcpConn::pcb, RESP_HDR_BUF_SIZE, and TcpConn::state.

---

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

• src/DeterministicESPAsyncWebServer.h
• src/DeterministicESPAsyncWebServer.cpp