HTTP/1.1 REQUEST HEAD: strict, bounded parser

Structures

	Name
struct	n_http_request A parsed request head.
struct	n_http_req_limits Limits for n_http_request_parse_ex().
struct	n_http_req_header One header line, as offsets into the parsed buffer: the name is [name_off, name_off + name_len), the value (surrounding spaces and tabs trimmed) is [value_off, value_off + value_len).

Types

	Name
enum	n_http_req_status { N_HTTP_REQ_OK = 0, N_HTTP_REQ_INCOMPLETE = 1, N_HTTP_REQ_ERROR = 2} Result of n_http_request_parse.
enum	n_http_req_method { N_HTTP_REQ_POST = 1, N_HTTP_REQ_HEAD = 2, N_HTTP_REQ_GET = 0} The methods accepted.

Functions

	Name
n_http_req_status	n_http_request_parse_ex(const char * buf, size_t len, const n_http_req_limits * limits, n_http_request * out) parse an HTTP/1.1 request head with caller-chosen limits
n_http_req_status	n_http_request_parse(const char * buf, size_t len, n_http_request * out) parse an HTTP/1.1 request head from [buf, buf+len)
size_t	n_http_request_header_count(const n_http_request * req, const char * buf, const char * name) count the headers of a parsed request that carry a name
const char *	n_http_request_header(const n_http_request * req, const char * buf, const char * name, size_t * value_len) find a header of a parsed request

Defines

	Name
	N_HTTP_REQ_PATH_MAX Longest origin-form request target ('/'-prefixed, query included).
	N_HTTP_REQ_METHOD_BIT(m) Bit of a method in n_http_req_limits.methods.
	N_HTTP_REQ_HEAD_MAX Largest request head (request line + headers, through CRLFCRLF) accepted.
	N_HTTP_REQ_HEADERS_MAX Maximum number of header lines.
	N_HTTP_REQ_BODY_MAX Maximum declared Content-Length (body size), in bytes, for n_http_request_parse().
	N_HTTP_REQ_BODY_LIMIT_MAX Highest body cap n_http_request_parse_ex() accepts (1 GiB).
	N_HTTP_REQ_AUTH_MAX Longest captured Authorization header value.

Types Documentation

enum n_http_req_status

Enumerator	Value	Description
N_HTTP_REQ_OK	0	a complete, valid head was parsed
N_HTTP_REQ_INCOMPLETE	1	no CRLFCRLF yet, still under the cap
N_HTTP_REQ_ERROR	2	malformed / oversized / unsupported

Result of n_http_request_parse.

The INCOMPLETE / ERROR split lets a transport read incrementally: keep buffering on INCOMPLETE, close on ERROR.

enum n_http_req_method

Enumerator	Value	Description
N_HTTP_REQ_POST	1
N_HTTP_REQ_HEAD	2
N_HTTP_REQ_GET	0

The methods accepted.

Append-only.

Functions Documentation

function n_http_request_parse_ex

n_http_req_status n_http_request_parse_ex(
    const char * buf,
    size_t len,
    const n_http_req_limits * limits,
    n_http_request * out
)

parse an HTTP/1.1 request head with caller-chosen limits

Parameters:

• buf the received bytes (may be NULL)
• len number of bytes in buf
• limits accepted methods, body cap, Host rule
• out the request head to fill (zeroed first)

Return: one of n_http_req_status

Same rules and results as n_http_request_parse(), except that the accepted methods, the largest Content-Length and the Host requirement come from limits. n_http_request_parse() is this function with GET and POST, N_HTTP_REQ_BODY_MAX and no Host requirement. A NULL limits, an empty method set or a body_max outside 0..N_HTTP_REQ_BODY_LIMIT_MAX is an error.

function n_http_request_parse

n_http_req_status n_http_request_parse(
    const char * buf,
    size_t len,
    n_http_request * out
)

parse an HTTP/1.1 request head from [buf, buf+len)

Parameters:

• buf the received bytes (may be NULL)
• len number of bytes in buf
• out the request head to fill (zeroed first)

Return: one of n_http_req_status

Returns N_HTTP_REQ_OK only when a complete head (through CRLFCRLF) is present and every rule holds: the method is GET or POST; the target is origin-form ('/'-prefixed, no spaces or control bytes, no fragment, within N_HTTP_REQ_PATH_MAX); the version is HTTP/1.0 or 1.1; at most N_HTTP_REQ_HEADERS_MAX headers; no Transfer-Encoding; at most one Content-Length, a valid non-negative integer within N_HTTP_REQ_BODY_MAX. On OK, out is filled and out->head_len marks the body start.

Returns N_HTTP_REQ_INCOMPLETE when no CRLFCRLF has arrived yet and the buffered bytes are still under N_HTTP_REQ_HEAD_MAX (read more), and N_HTTP_REQ_ERROR for anything malformed, unsupported, or over the head cap. Bounded and over-read safe on every path.

function n_http_request_header_count

size_t n_http_request_header_count(
    const n_http_request * req,
    const char * buf,
    const char * name
)

count the headers of a parsed request that carry a name

Parameters:

• req the parsed request
• buf the same buffer that was parsed, unchanged since
• name the header name, any case

Return: the number of header lines named name, 0 on a NULL argument

Lets a caller refuse a repeated header that must be unique (Host, Cookie, Content-Type...).

function n_http_request_header

const char * n_http_request_header(
    const n_http_request * req,
    const char * buf,
    const char * name,
    size_t * value_len
)

find a header of a parsed request

Parameters:

• req the parsed request
• buf the same buffer that was parsed, unchanged since
• name the header name, any case
• value_len receives the value length (may be NULL)

Return: a pointer to the value inside buf, or NULL if absent or on a NULL argument

Looks for the first header whose name matches name, ASCII case-insensitively, among the headers n_http_request_parse() / n_http_request_parse_ex() recorded from buf. The value is not NUL-terminated: use value_len.

Macros Documentation

define N_HTTP_REQ_PATH_MAX

#define N_HTTP_REQ_PATH_MAX 2048u

Longest origin-form request target ('/'-prefixed, query included).

define N_HTTP_REQ_METHOD_BIT

#define N_HTTP_REQ_METHOD_BIT(
    m
)
(1u << (unsigned)(m))

Bit of a method in n_http_req_limits.methods.

define N_HTTP_REQ_HEAD_MAX

#define N_HTTP_REQ_HEAD_MAX 16384u

Largest request head (request line + headers, through CRLFCRLF) accepted.

define N_HTTP_REQ_HEADERS_MAX

#define N_HTTP_REQ_HEADERS_MAX 64u

Maximum number of header lines.

define N_HTTP_REQ_BODY_MAX

#define N_HTTP_REQ_BODY_MAX (1024u * 1024u)

Maximum declared Content-Length (body size), in bytes, for n_http_request_parse().

n_http_request_parse_ex() takes its own cap.

define N_HTTP_REQ_BODY_LIMIT_MAX

#define N_HTTP_REQ_BODY_LIMIT_MAX (1024LL * 1024LL * 1024LL)

Highest body cap n_http_request_parse_ex() accepts (1 GiB).

define N_HTTP_REQ_AUTH_MAX

#define N_HTTP_REQ_AUTH_MAX 256u

Longest captured Authorization header value.