User-facing configuration for DeterministicESPAsyncWebServer. More...

#include <stdint.h>

Classes
struct	WebServerConfig
	Runtime-tunable server parameters. More...

Macros
#define	MAX_CONNS 4
	Maximum simultaneous TCP connections.

#define	RX_BUF_SIZE 1024
	Ring-buffer capacity in bytes per connection slot.

#define	CONN_TIMEOUT_MS 5000
	Compile-time default for connection idle timeout in milliseconds.

#define	MAX_HEADERS 8
	Maximum HTTP headers stored per request.

#define	MAX_PATH_LEN 64
	Maximum URL path length (including leading `/`).

#define	MAX_KEY_LEN 24
	Maximum header field-name length (e.g. `"Content-Type"`).

#define	MAX_VAL_LEN 48
	Maximum header field-value length.

#define	MAX_QUERY_LEN 128
	Maximum raw query-string length (everything after `?`).

#define	MAX_QUERY_PARAMS 8
	Maximum number of parsed query-string parameters.

#define	QUERY_KEY_LEN 24
	Maximum query-parameter key length.

#define	QUERY_VAL_LEN 48
	Maximum query-parameter value length.

#define	BODY_BUF_SIZE 256
	Maximum request body bytes stored in `HttpReq::body`.

#define	MAX_ROUTES 16
	Maximum simultaneously registered routes.

#define	MAX_WS_CONNS 2
	Maximum simultaneous WebSocket connections.

#define	WS_FRAME_SIZE 512
	Maximum WebSocket frame payload in bytes.

#define	MAX_SSE_CONNS 2
	Maximum simultaneous SSE connections.

#define	SSE_BUF_SIZE 256
	Output buffer size in bytes for a single SSE event.

#define	FILE_CHUNK_SIZE 512
	Bytes read from the filesystem and passed to tcp_write() per loop().

#define	MAX_AUTH_LEN 32
	Maximum username or password length for HTTP Basic Authentication.

#define	MAX_MULTIPART_PARTS 4
	Maximum simultaneously parsed multipart parts per request.

#define	MAX_BOUNDARY_LEN 72
	Maximum MIME boundary length (RFC 2046 allows up to 70 characters).

#define	EVT_QUEUE_DEPTH 16
	Depth of the FreeRTOS event queue shared between lwIP callbacks and the main-loop task.

#define	RESP_HDR_BUF_SIZE 512
	Stack buffer for HTTP response header lines in send() / send_empty() / send_unauth() / serve_file().

#define	WS_HDR_BUF_SIZE 256
	Stack buffer for the HTTP 101 Switching Protocols response sent during the WebSocket handshake.

#define	CORS_HDR_BUF_SIZE 192
	Size of the pre-built CORS header block stored in DetWebServer.

#define	DETWS_ENABLE_WEBSOCKET 1
	WebSocket support (RFC 6455 framing + SHA-1/base64 handshake).

#define	DETWS_ENABLE_SSE 1
	Server-Sent Events push support.

#define	DETWS_ENABLE_MULTIPART 1
	multipart/form-data body parser.

#define	DETWS_ENABLE_FILE_SERVING 1
	Static file serving via Arduino FS (LittleFS, SPIFFS, SD).

#define	DETWS_ENABLE_AUTH 1
	HTTP Basic Authentication per-route.

#define	DETWS_ENABLE_DIAG 0
	Expose a diagnostic JSON endpoint via server.diag().

Detailed Description

User-facing configuration for DeterministicESPAsyncWebServer.

Compile-time sizing constants These govern static array dimensions and must be set before the first library header is included. Define any of them in your sketch or in a build flag before including this file to override the defaults:

// platformio.ini

build_flags = -DMAX_CONNS=8 -DBODY_BUF_SIZE=512

Runtime parameters — flash or RAM, your choice WebServerConfig holds values that can be changed without a rebuild. On ESP32, PROGMEM is a no-op (const data lands in DROM automatically). On AVR it places data in flash and requires pgm_read_* accessors — this library targets ESP32 only, so both forms read identically via pointer:

// Flash (PROGMEM, no RAM cost at runtime):
const WebServerConfig my_cfg PROGMEM = { .conn_timeout_ms = 10000 };
 
// RAM (can be changed at runtime):
WebServerConfig my_cfg = { .conn_timeout_ms = 10000 };
 
server.begin(80, &my_cfg);

Pass nullptr (or omit the argument) to use DET_DEFAULT_CONFIG.

Definition in file DetWebServerConfig.h.

Macro Definition Documentation

◆ MAX_CONNS

#define MAX_CONNS 4

Maximum simultaneous TCP connections.

Definition at line 45 of file DetWebServerConfig.h.

◆ RX_BUF_SIZE

#define RX_BUF_SIZE 1024

Ring-buffer capacity in bytes per connection slot.

Definition at line 50 of file DetWebServerConfig.h.

◆ CONN_TIMEOUT_MS

#define CONN_TIMEOUT_MS 5000

Compile-time default for connection idle timeout in milliseconds.

The actual runtime value is stored in WebServerConfig::conn_timeout_ms and loaded into DeterministicAsyncTCP::conn_timeout_ms by init().

Definition at line 60 of file DetWebServerConfig.h.

◆ MAX_HEADERS

#define MAX_HEADERS 8

Maximum HTTP headers stored per request.

Definition at line 65 of file DetWebServerConfig.h.

◆ MAX_PATH_LEN

#define MAX_PATH_LEN 64

Maximum URL path length (including leading /).

Definition at line 70 of file DetWebServerConfig.h.

◆ MAX_KEY_LEN

#define MAX_KEY_LEN 24

Maximum header field-name length (e.g. "Content-Type").

Definition at line 75 of file DetWebServerConfig.h.

◆ MAX_VAL_LEN

#define MAX_VAL_LEN 48

Maximum header field-value length.

Definition at line 80 of file DetWebServerConfig.h.

◆ MAX_QUERY_LEN

#define MAX_QUERY_LEN 128

Maximum raw query-string length (everything after ?).

Definition at line 85 of file DetWebServerConfig.h.

◆ MAX_QUERY_PARAMS

#define MAX_QUERY_PARAMS 8

Maximum number of parsed query-string parameters.

Definition at line 90 of file DetWebServerConfig.h.

◆ QUERY_KEY_LEN

#define QUERY_KEY_LEN 24

Maximum query-parameter key length.

Definition at line 95 of file DetWebServerConfig.h.

◆ QUERY_VAL_LEN

#define QUERY_VAL_LEN 48

Maximum query-parameter value length.

Definition at line 100 of file DetWebServerConfig.h.

◆ BODY_BUF_SIZE

#define BODY_BUF_SIZE 256

Maximum request body bytes stored in HttpReq::body.

Bodies larger than this trigger a 413 Payload Too Large response — the parser detects the overflow via Content-Length before any body bytes arrive, so no data is read or stored for oversized requests.

Definition at line 111 of file DetWebServerConfig.h.

◆ MAX_ROUTES

#define MAX_ROUTES 16

Maximum simultaneously registered routes.

Definition at line 116 of file DetWebServerConfig.h.

◆ MAX_WS_CONNS

#define MAX_WS_CONNS 2

Maximum simultaneous WebSocket connections.

Each connection occupies one TCP slot from MAX_CONNS and one entry in ws_pool[]. MAX_WS_CONNS + MAX_SSE_CONNS must not exceed MAX_CONNS.

Definition at line 130 of file DetWebServerConfig.h.

◆ WS_FRAME_SIZE

#define WS_FRAME_SIZE 512

Maximum WebSocket frame payload in bytes.

Frames larger than this are rejected with Close code 1009 (Message Too Big). Fragmented messages are not supported; each message must fit in one frame.

Definition at line 140 of file DetWebServerConfig.h.

◆ MAX_SSE_CONNS

#define MAX_SSE_CONNS 2

Maximum simultaneous SSE connections.

Each connection occupies one TCP slot from MAX_CONNS and one entry in sse_pool[]. MAX_WS_CONNS + MAX_SSE_CONNS must not exceed MAX_CONNS.

Definition at line 154 of file DetWebServerConfig.h.

◆ SSE_BUF_SIZE

#define SSE_BUF_SIZE 256

Output buffer size in bytes for a single SSE event.

An event larger than this is silently truncated. The buffer holds the formatted data: ...\n\n line before it is handed to tcp_write().

Definition at line 164 of file DetWebServerConfig.h.

◆ FILE_CHUNK_SIZE

#define FILE_CHUNK_SIZE 512

Bytes read from the filesystem and passed to tcp_write() per loop().

Smaller values reduce peak stack use; larger values improve throughput. Must be <= RX_BUF_SIZE to avoid stalling the TCP send window.

Definition at line 178 of file DetWebServerConfig.h.

◆ MAX_AUTH_LEN

#define MAX_AUTH_LEN 32

Maximum username or password length for HTTP Basic Authentication.

Both username and password must fit in this many bytes including the null terminator. Longer credentials are silently rejected with 401.

Definition at line 192 of file DetWebServerConfig.h.

◆ MAX_MULTIPART_PARTS

#define MAX_MULTIPART_PARTS 4

Maximum simultaneously parsed multipart parts per request.

Parts beyond this limit are silently ignored. A typical upload form has 1-4 fields; increase this for forms with more.

Definition at line 206 of file DetWebServerConfig.h.

◆ MAX_BOUNDARY_LEN

#define MAX_BOUNDARY_LEN 72

Maximum MIME boundary length (RFC 2046 allows up to 70 characters).

Definition at line 213 of file DetWebServerConfig.h.

◆ EVT_QUEUE_DEPTH

#define EVT_QUEUE_DEPTH 16

Depth of the FreeRTOS event queue shared between lwIP callbacks and the main-loop task.

Each slot holds one TcpEvt (8 bytes). The queue is the only heap allocation the library makes at begin() time:

heap = sizeof(StaticQueue_t) + EVT_QUEUE_DEPTH * sizeof(TcpEvt)

Must be large enough to absorb a burst of MAX_CONNS * 4 events without blocking the lwIP thread. DeterministicAsyncTCP::heap_needed() returns the exact byte count; call DetWebServer::heap_available() before begin() to verify a contiguous block exists.

Definition at line 235 of file DetWebServerConfig.h.

◆ RESP_HDR_BUF_SIZE

#define RESP_HDR_BUF_SIZE 512

Stack buffer for HTTP response header lines in send() / send_empty() / send_unauth() / serve_file().

Must be large enough to hold the status line, Content-Type, Content-Length, Connection, and any CORS headers. The CORS block alone can reach CORS_HDR_BUF_SIZE bytes, so this value should be at least CORS_HDR_BUF_SIZE + 96.

Definition at line 252 of file DetWebServerConfig.h.

◆ WS_HDR_BUF_SIZE

#define WS_HDR_BUF_SIZE 256

Stack buffer for the HTTP 101 Switching Protocols response sent during the WebSocket handshake.

Must hold: status line + Upgrade + Connection + Sec-WebSocket-Accept (28 base64 chars) + CRLF pairs. Minimum is ~120 bytes; default leaves margin.

Definition at line 263 of file DetWebServerConfig.h.

◆ CORS_HDR_BUF_SIZE

#define CORS_HDR_BUF_SIZE 192

Size of the pre-built CORS header block stored in DetWebServer.

Built once by set_cors() and injected into every response. Must hold Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Headers lines for the configured origin.

Definition at line 274 of file DetWebServerConfig.h.

◆ DETWS_ENABLE_WEBSOCKET

#define DETWS_ENABLE_WEBSOCKET 1

WebSocket support (RFC 6455 framing + SHA-1/base64 handshake).

Definition at line 288 of file DetWebServerConfig.h.

◆ DETWS_ENABLE_SSE

#define DETWS_ENABLE_SSE 1

Server-Sent Events push support.

Definition at line 293 of file DetWebServerConfig.h.

◆ DETWS_ENABLE_MULTIPART

#define DETWS_ENABLE_MULTIPART 1

multipart/form-data body parser.

Definition at line 298 of file DetWebServerConfig.h.

◆ DETWS_ENABLE_FILE_SERVING

#define DETWS_ENABLE_FILE_SERVING 1

Static file serving via Arduino FS (LittleFS, SPIFFS, SD).

Definition at line 303 of file DetWebServerConfig.h.

◆ DETWS_ENABLE_AUTH

#define DETWS_ENABLE_AUTH 1

HTTP Basic Authentication per-route.

Definition at line 308 of file DetWebServerConfig.h.

◆ DETWS_ENABLE_DIAG

#define DETWS_ENABLE_DIAG 0

Expose a diagnostic JSON endpoint via server.diag().

Disabled by default — enabling it exposes compile-time configuration (buffer sizes, feature flags) which could aid an attacker. Only enable in development or behind an authenticated route.

When enabled, DETWS_DIAG_JSON is a compile-time string constant you can serve from any route handler:

server.on("/diag", HTTP_GET, [](uint8_t id, HttpReq *) {
    server.diag(id);        // convenience wrapper
    // or:
    server.send(id, 200, "application/json", DETWS_DIAG_JSON);
});

Definition at line 329 of file DetWebServerConfig.h.

Classes

Macros