http_parser.h File Reference

Standalone HTTP/1.1 request parser - no transport dependency. More...

#include "ServerConfig.h"
#include <Arduino.h>

Go to the source code of this file.

Classes
struct	Header
	A single HTTP header field (key: value). More...
struct	QueryParam
	A single parsed query-string parameter. More...
struct	HttpReq
	Fully-parsed HTTP/1.1 request. More...

Enumerations
enum class	ParseState : uint8_t {   PARSE_METHOD , PARSE_PATH , PARSE_QUERY , PARSE_VERSION ,   PARSE_HEADER_KEY , PARSE_HEADER_VAL , PARSE_EXPECT_LF , PARSE_EXPECT_BODY_LF ,   PARSE_BODY , PARSE_COMPLETE , PARSE_ERROR , PARSE_ENTITY_TOO_LARGE ,   PARSE_URI_TOO_LONG }
	States of the HTTP/1.1 request parser. More...
enum class	HttpVersion : uint8_t { HTTP_UNKNOWN = 0 , HTTP_10 , HTTP_11 }
	Parsed HTTP protocol version. More...

Functions
void	http_parser_reset (HttpReq *req)
	Reset a parser context to the initial (ParseState::PARSE_METHOD) state.
void	http_parser_feed (HttpReq *req, uint8_t byte)
	Feed one byte to the parser state machine.
const char *	http_get_header (const HttpReq *req, const char *key)
	Look up a header value by name (case-insensitive).
bool	http_get_cookie (const HttpReq *req, const char *name, char *out, size_t out_size)
	Read a named cookie from the request Cookie header (RFC 6265 4.2.1).
bool	http_forwarded_client (const HttpReq *req, char *ip_out, size_t ip_cap, bool *is_https)
	Recover the original client from a reverse-proxy Forwarded (RFC 7239) or de-facto X-Forwarded-For / X-Forwarded-Proto header.
const char *	http_get_query (const HttpReq *req, const char *key)
	Look up a query parameter value by name (case-sensitive).
bool	http_get_form (const HttpReq *req, const char *key, char *out, size_t out_size)
	Look up an application/x-www-form-urlencoded body field by name.
const char *	http_get_param (const HttpReq *req, const char *key)
	Look up a captured path parameter by name (case-sensitive).

Variables
HttpReq	http_pool [CONN_POOL_SLOTS]
	Pool of parser contexts, one per connection-pool slot (incl. reserved dispatch slots).

Detailed Description

Standalone HTTP/1.1 request parser - no transport dependency.

The parser is a pure byte-stream state machine. It has no knowledge of ring buffers, TCP PCBs, or FreeRTOS. Feed it bytes one at a time via http_parser_feed() and inspect HttpReq::parse_state to know when the request is ready.

State machine

ParseState::PARSE_METHOD       ──space──────► ParseState::PARSE_PATH
ParseState::PARSE_PATH         ──space──────► ParseState::PARSE_VERSION
ParseState::PARSE_PATH         ──'?'────────► ParseState::PARSE_QUERY
ParseState::PARSE_QUERY        ──space──────► ParseState::PARSE_VERSION  (calls parse_query_params)
ParseState::PARSE_VERSION      ──CR─────────► ParseState::PARSE_EXPECT_LF
ParseState::PARSE_EXPECT_LF    ──LF─────────► ParseState::PARSE_HEADER_KEY
ParseState::PARSE_HEADER_KEY   ──':'────────► ParseState::PARSE_HEADER_VAL
ParseState::PARSE_HEADER_KEY   ──CR─────────► ParseState::PARSE_EXPECT_BODY_LF  (blank line)
ParseState::PARSE_HEADER_VAL   ──CR─────────► ParseState::PARSE_EXPECT_LF  (stores header)
ParseState::PARSE_EXPECT_BODY_LF ──LF (CL=0)──► ParseState::PARSE_COMPLETE
ParseState::PARSE_EXPECT_BODY_LF ──LF (CL>BUF)► ParseState::PARSE_ENTITY_TOO_LARGE  (→ 413)
ParseState::PARSE_EXPECT_BODY_LF ──LF (else)──► ParseState::PARSE_BODY
ParseState::PARSE_BODY         ──(all read)──► ParseState::PARSE_COMPLETE
ParseState::PARSE_PATH (overflow) ───────────► ParseState::PARSE_URI_TOO_LONG       (→ 414)
Any state + protocol error ──────► ParseState::PARSE_ERROR             (→ 400)

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file http_parser.h.

Enumeration Type Documentation

ParseState

enum class ParseState : uint8_t

strong

States of the HTTP/1.1 request parser.

Advance via http_parser_feed(). The application layer inspects this after each feed call or after draining a complete chunk.

Enumerator
PARSE_METHOD	Reading the HTTP method (GET, POST, …).
PARSE_PATH	Reading the URL path component.
PARSE_QUERY	Reading the raw query string (after ?).
PARSE_VERSION	Accumulating HTTP/1.x - hashed for validation.
PARSE_HEADER_KEY	Reading a header field name.
PARSE_HEADER_VAL	Reading a header field value.
PARSE_EXPECT_LF	Consuming the LF of a header-line CRLF pair.
PARSE_EXPECT_BODY_LF	Consuming the LF of the blank-line CRLF.
PARSE_BODY	Reading the request body.
PARSE_COMPLETE	Full request parsed; ready for dispatch.
PARSE_ERROR	Unrecoverable parse failure → 400.
PARSE_ENTITY_TOO_LARGE	Content-Length > BODY_BUF_SIZE → 413.
PARSE_URI_TOO_LONG	Path exceeds MAX_PATH_LEN → 414.

Definition at line 52 of file http_parser.h.

HttpVersion

enum class HttpVersion : uint8_t

strong

Parsed HTTP protocol version.

Populated from the request line (HTTP/1.0 or HTTP/1.1) using an FNV-1a hash accumulated during ParseState::PARSE_VERSION. The application layer may use this to drive keep-alive semantics: HTTP/1.1 defaults to persistent connections; HTTP/1.0 defaults to close.

Enumerator
HTTP_UNKNOWN	Version string did not match any known token.
HTTP_10	HTTP/1.0 - close semantics by default.
HTTP_11	HTTP/1.1 - persistent connection by default.

Definition at line 77 of file http_parser.h.

Function Documentation

http_parser_reset()

void http_parser_reset

(

HttpReq *

req

)

Reset a parser context to the initial (ParseState::PARSE_METHOD) state.

Zeroes all fields and sets parse_state = ParseState::PARSE_METHOD. Call before the first use, after each completed or failed request, and on connection events.

Parameters

req	Parser context to reset. Must not be null.

Definition at line 148 of file http_parser.cpp.

References HttpReq::_version_hash, PARSE_COMPLETE, PARSE_METHOD, HttpReq::parse_state, and HttpReq::slot_id.

Referenced by http_reset().

http_parser_feed()

void http_parser_feed	(	HttpReq *	req,
		uint8_t	byte
	)

Feed one byte to the parser state machine.

Returns immediately without modifying state when parse_state is already ParseState::PARSE_COMPLETE, ParseState::PARSE_ERROR, ParseState::PARSE_ENTITY_TOO_LARGE, or ParseState::PARSE_URI_TOO_LONG.

Parameters

req	Parser context for this request.
byte	Next byte from the HTTP stream.

Definition at line 165 of file http_parser.cpp.

References HttpReq::_version_hash, HttpReq::body, BODY_BUF_SIZE, HttpReq::body_bytes_read, HttpReq::body_len, HttpReq::content_length, HttpReq::content_length_count, HttpReq::cur_key, HttpReq::cur_val, HttpReq::current_token_idx, DETWS_AUTH_HDR_CAP, HttpReq::header_count, HttpReq::headers, HttpReq::host_count, HTTP_10, HTTP_11, HTTP_UNKNOWN, Header::key, MAX_HEADERS, MAX_KEY_LEN, MAX_PATH_LEN, MAX_QUERY_LEN, MAX_VAL_LEN, HttpReq::method, PARSE_BODY, PARSE_COMPLETE, PARSE_ENTITY_TOO_LARGE, PARSE_ERROR, PARSE_EXPECT_BODY_LF, PARSE_EXPECT_LF, PARSE_HEADER_KEY, PARSE_HEADER_VAL, PARSE_METHOD, PARSE_PATH, PARSE_QUERY, HttpReq::parse_state, PARSE_URI_TOO_LONG, PARSE_VERSION, HttpReq::path, HttpReq::path_idx, HttpReq::query, HttpReq::query_idx, Header::val, and HttpReq::version.

Referenced by http_parse().

http_get_header()

const char * http_get_header	(	const HttpReq *	req,
		const char *	key
	)

Look up a header value by name (case-insensitive).

Parameters

req	Parsed request.
key	Header field name (e.g. "Content-Type").

Returns

Pointer to the null-terminated value, or nullptr if not found.

Definition at line 506 of file http_parser.cpp.

References HttpReq::header_count, HttpReq::headers, Header::key, and Header::val.

Referenced by http_forwarded_client(), http_get_cookie(), http_get_form(), and multipart_parse().

http_get_cookie()

bool http_get_cookie	(	const HttpReq *	req,
		const char *	name,
		char *	out,
		size_t	out_size
	)

Read a named cookie from the request Cookie header (RFC 6265 4.2.1).

Parses the name1=value1; name2=value2 list and copies the value of cookie name (case-sensitive) into out (null-terminated, bounded by out_size; a surrounding DQUOTE pair is stripped). Pairs with the session / CSRF / auth features (e.g. reading a session-id cookie).

Returns

true if the cookie was found (value in out), false otherwise.

Definition at line 516 of file http_parser.cpp.

References http_get_header(), and MAX_VAL_LEN.

http_forwarded_client()

bool http_forwarded_client	(	const HttpReq *	req,
		char *	ip_out,
		size_t	ip_cap,
		bool *	is_https
	)

Recover the original client from a reverse-proxy Forwarded (RFC 7239) or de-facto X-Forwarded-For / X-Forwarded-Proto header.

Writes the leftmost (original-client) address into ip_out as its RFC 5952 canonical text (bounded by ip_cap; use DET_IP_STR_MAX for the widest IPv6), and sets is_https from proto=https / X-Forwarded-Proto: https. Both IPv4 (with an optional :port) and IPv6 (bracketed for="[2001:db8::1]:port" or a bare X-Forwarded-For literal) are recovered; the candidate is validated with det_ip_parse, so unknown / obfuscated _id identifiers and malformed tokens are rejected. The CALLER must only trust this when the TCP peer is a configured trusted upstream - the header is client-spoofable.

Returns

true if a valid client address (IPv4 or IPv6) was written to ip_out.

Definition at line 636 of file http_parser.cpp.

References http_get_header(), and MAX_VAL_LEN.

http_get_query()

const char * http_get_query	(	const HttpReq *	req,
		const char *	key
	)

Look up a query parameter value by name (case-sensitive).

Parameters

req	Parsed request.
key	Parameter name.

Returns

Pointer to the null-terminated value (empty string if key= with no value), or nullptr if the key is absent.

Definition at line 693 of file http_parser.cpp.

References QueryParam::key, HttpReq::query_count, HttpReq::query_params, and QueryParam::val.

http_get_form()

bool http_get_form	(	const HttpReq *	req,
		const char *	key,
		char *	out,
		size_t	out_size
	)

Look up an application/x-www-form-urlencoded body field by name.

Parses the request body on demand (no extra per-request storage) when the Content-Type is application/x-www-form-urlencoded, and copies the raw (not percent-decoded, matching http_get_query()) value of key into out. Useful for classic HTML form POSTs.

Parameters

req	Parsed request (body must be buffered, i.e. not streamed).
key	Field name (case-sensitive).
out	Caller buffer; always null-terminated on a true return.
out_size	Size of out in bytes (must be >= 1).

Returns

true and fills out if the field is present; false otherwise (out is set to an empty string).

Definition at line 703 of file http_parser.cpp.

References HttpReq::body, HttpReq::body_len, and http_get_header().

http_get_param()

const char * http_get_param	(	const HttpReq *	req,
		const char *	key
	)

Look up a captured path parameter by name (case-sensitive).

Path parameters are the :name segments of a matched route pattern (e.g. route "/users/:id" matching "/users/42" captures id→"42"). Populated by the dispatcher when the route matches; valid for the duration of the handler.

Parameters

req	Parsed request.
key	Parameter name without the leading :.

Returns

Pointer to the null-terminated value, or nullptr if absent.

Definition at line 753 of file http_parser.cpp.

References QueryParam::key, HttpReq::path_param_count, HttpReq::path_params, and QueryParam::val.

Variable Documentation

http_pool

HttpReq http_pool[CONN_POOL_SLOTS]

extern

Pool of parser contexts, one per connection-pool slot (incl. reserved dispatch slots).

Definition at line 16 of file http_parser.cpp.

Referenced by http_parse(), DetWebServer::http_poll_slot(), http_reset(), req_is_head(), and DetWebServer::send_chunked().