dwserver.h File Reference

Layer 7 (Application) - public HTTP routing API. More...

#include "network_drivers/presentation/json/json.h"
#include "network_drivers/presentation/presentation.h"
#include "network_drivers/session/session.h"
#include "network_drivers/session/worker.h"
#include <Arduino.h>

Go to the source code of this file.

Classes
struct	Route
	Internal route entry stored in the routing table. More...
class	DetWebServer
	Single-port HTTP server with deterministic, zero-allocation execution. More...

Typedefs
typedef void(*	Handler) (uint8_t slot_id, HttpReq *request)
	Callback signature for HTTP request handlers.
typedef const char *(*	TemplateVar) (const char *name)
	Resolver for {{name}} template placeholders used by send_template().
typedef void(*	RequestLogCb) (const char *method, const char *path, int status, int body_len)
	Per-request access-log callback (see DetWebServer::on_request_log()).
typedef MwResult(*	Middleware) (uint8_t slot_id, HttpReq *request)
	Composable pre-dispatch middleware (see DetWebServer::use()).
typedef size_t(*	ChunkSource) (uint8_t *buf, size_t cap, void *ctx)
	Source callback that produces a chunked response body incrementally.

Enumerations
enum class	HttpMethod : uint8_t {   HTTP_GET , HTTP_POST , HTTP_PUT , HTTP_DELETE ,   HTTP_PATCH , HTTP_HEAD , HTTP_OPTIONS , HTTP_METHOD_UNKNOWN }
	HTTP request methods supported by the router. More...
enum class	MwResult : uint8_t { MW_NEXT = 0 , MW_HALT = 1 }
	Outcome of a middleware function (see Middleware). More...
enum class	RouteType : uint8_t { ROUTE_HTTP }
	Discriminates between HTTP, WebSocket, and SSE route entries. More...
enum class	DetWebServerResult : int32_t { DETWS_OK = 1 , DETWS_ERR_NO_LISTENERS = -1 , DETWS_ERR_LISTENER_FULL = -2 , DETWS_ERR_LISTEN_FAILED = -3 }
	Result codes for listen(), begin(), and restart(). More...

Detailed Description

Layer 7 (Application) - public HTTP routing API.

This is the only header most application code needs to include. The full OSI include chain is pulled in automatically:

dwserver.h                  (L7 Application)
  ├── network_drivers/presentation/presentation.h (L6 Presentation)
  │       ├── network_drivers/presentation/http_parser/http_parser.h (parser types)
  │       └── network_drivers/transport/tcp.h      (L4 Transport)
  │               └── ServerConfig.h   (compile-time config)
  └── network_drivers/session/session.h      (L5 Session - event drain)

Feature flags - define any of these to 0 before including to strip the feature from the build entirely:

#define DETWS_ENABLE_WEBSOCKET    0
#define DETWS_ENABLE_SSE          0
#define DETWS_ENABLE_MULTIPART    0
#define DETWS_ENABLE_FILE_SERVING 0
#define DETWS_ENABLE_AUTH         0
#include <dwserver.h>

Determinism guarantees

• All buffers are statically allocated; no heap usage after begin().
• Every operation has O(1) or O(MAX_ROUTES) worst-case time.
• handle() is safe to call every Arduino loop() iteration.

Author

Douglas Quigg (dstroy0)

Date

2026

Copyright

Copyright (C) 2026 Douglas Quigg (dstroy0). AGPL-3.0-or-later.

Definition in file dwserver.h.

Typedef Documentation

Handler

typedef void(* Handler) (uint8_t slot_id, HttpReq *request)

Callback signature for HTTP request handlers.

The callback receives the connection slot index and a pointer to the fully-parsed request. Call DetWebServer::send() or DetWebServer::send_empty() from inside the callback to write a response.

Parameters

slot_id	Index into the connection pool (0 … MAX_CONNS-1).
request	Pointer to the parsed HTTP request. Valid only during the callback; do not cache this pointer.

Note

If the callback returns without calling send(), the framework will reset the slot automatically (no response is sent to the client).

Definition at line 106 of file dwserver.h.

TemplateVar

typedef const char *(* TemplateVar) (const char *name)

Resolver for {{name}} template placeholders used by send_template().

Called with a placeholder name; returns the replacement string, or nullptr to substitute an empty string. The pointer must stay valid for the duration of the send_template() call, and the resolver must be deterministic (it is invoked twice: once to size the body, once to emit it).

Definition at line 116 of file dwserver.h.

RequestLogCb

typedef void(* RequestLogCb) (const char *method, const char *path, int status, int body_len)

Per-request access-log callback (see DetWebServer::on_request_log()).

Invoked once per response with the request method/path, the HTTP status code, and the response body length in bytes. The strings are valid only for the duration of the call. This is a thin hook - the library does no buffering or formatting; route the data to Serial, syslog, etc. as you see fit.

Definition at line 126 of file dwserver.h.

Middleware

typedef MwResult(* Middleware) (uint8_t slot_id, HttpReq *request)

Composable pre-dispatch middleware (see DetWebServer::use()).

Each registered middleware runs - in registration order - on every request before route matching, receiving the same (slot_id, request) pair a handler does. A middleware may inspect the request, queue response headers (DetWebServer::add_response_header()), short-circuit by sending a response and returning MwResult::MW_HALT, or fall through with MwResult::MW_NEXT. Middlewares reference the application's server instance the same way handlers do (the global object), so they can call send() / send_empty() to short-circuit.

Parameters

slot_id	Connection slot index (0 … MAX_CONNS-1).
request	Parsed request; valid only during the call (do not cache).

Returns

MwResult::MW_NEXT to continue, MwResult::MW_HALT to stop (response already sent).

Definition at line 158 of file dwserver.h.

ChunkSource

typedef size_t(* ChunkSource) (uint8_t *buf, size_t cap, void *ctx)

Source callback that produces a chunked response body incrementally.

Passed to DetWebServer::send_chunked() and called repeatedly - possibly across several server loops, as the TCP send window drains - until it returns 0. Each call writes up to cap bytes of the next body piece into buf and returns the count; the HTTP chunk framing (size line + CRLFs + terminator) is added by the server. Track your position across calls in ctx. This pull/generator model lets the server page an arbitrarily large body to the socket in constant memory without ever blocking the worker or truncating at the send window.

Warning

ctx must stay valid until the body is fully sent. A body that fits in a single send window finishes during the send_chunked() call, but a larger one resumes on later loops, so ctx must NOT point at the caller's stack: use static / global storage (a per-connection instance if requests can overlap), or generate the body from durable state.

Parameters

buf	destination for the next body bytes.
cap	maximum bytes to write into buf on this call.
ctx	caller state pointer, passed through from send_chunked().

Returns

bytes written into buf (<= cap), or 0 to end the body.

Definition at line 310 of file dwserver.h.

Enumeration Type Documentation

HttpMethod

enum class HttpMethod : uint8_t

strong

HTTP request methods supported by the router.

Pass one of these values to DetWebServer::on() to bind a route to a specific method. PATCH, HEAD, and OPTIONS were added in v1.0 alongside CORS preflight support.

Enumerator
HTTP_GET	Safe, idempotent read.
HTTP_POST	Non-idempotent create / action.
HTTP_PUT	Idempotent replace.
HTTP_DELETE	Idempotent delete.
HTTP_PATCH	Partial update.
HTTP_HEAD	Same as GET but no response body.
HTTP_OPTIONS	Capability query / CORS preflight.
HTTP_METHOD_UNKNOWN	Unrecognized method token → 501 Not Implemented.

Definition at line 76 of file dwserver.h.

MwResult

enum class MwResult : uint8_t

strong

Outcome of a middleware function (see Middleware).

Returning MwResult::MW_NEXT passes the request to the next middleware in the chain and, once the chain is exhausted, on to the matching route handler. Returning MwResult::MW_HALT stops the chain: the route handler is NOT invoked, so a middleware that halts must have already written a response (the dispatcher treats the request as fully handled).

Enumerator
MW_NEXT	Continue to the next middleware / the route handler.
MW_HALT	Stop dispatch; the middleware already sent a response.

Definition at line 137 of file dwserver.h.

RouteType

enum class RouteType : uint8_t

strong

Discriminates between HTTP, WebSocket, and SSE route entries.

Enumerator
ROUTE_HTTP	Standard HTTP request/response.

Definition at line 202 of file dwserver.h.

DetWebServerResult

enum class DetWebServerResult : int32_t

strong

Result codes for listen(), begin(), and restart().

Success is a positive value (DetWebServerResult::DETWS_OK). Failures are distinct negative codes so a caller can tell why startup failed.

Enumerator
DETWS_OK	Success.
DETWS_ERR_NO_LISTENERS	begin() called before any listen() / begin(port).
DETWS_ERR_LISTENER_FULL	listen(): listener pool (MAX_LISTENERS) is full.
DETWS_ERR_LISTEN_FAILED	A listener failed to open (bind/listen/lwIP error).

Definition at line 229 of file dwserver.h.