Documentation Index
Fetch the complete documentation index at: https://mintlify.com/avsm/httpz/llms.txt
Use this file to discover all available pages before exploring further.
The Err module provides zero-cost abstractions for raising parse errors with various status codes. All functions are inlined for performance, making error handling both ergonomic and efficient.
Status Type
Parse status enumeration (re-exported from Buf_read.status).Parsing completed successfully
Need more input data to continue parsing
HTTP method is invalid or unsupported
Request target (URI) is malformed
HTTP version is invalid or unsupported
Header name or value is malformed
Headers exceed maximum allowed size
General protocol format violation
Content-Length value exceeds maximum allowed
Both Content-Length and Transfer-Encoding present
Bare CR found (security violation)
Required Host header is missing (HTTP/1.1)
Unsupported_transfer_encoding
Transfer-Encoding other than chunked is not supported
Exception
Parse_error
exception Parse_error of status
try
parse_request buffer
with
| Err.Parse_error status ->
match status with
| Invalid_method -> respond_with 400 "Bad Request"
| Headers_too_large -> respond_with 431 "Request Header Fields Too Large"
| Content_length_overflow -> respond_with 413 "Payload Too Large"
| _ -> respond_with 400 "Bad Request"
Direct Fail Combinators
These functions immediately raise a Parse_error with the specified status.
fail
Raise Parse_error with the given status.
The error status to raise
if not (is_valid_method method_str) then
Err.fail Invalid_method
partial
Raise Parse_error Partial. Use when more input is needed.
Example:
if pos + 4 > buffer_length then
Err.partial ()
val malformed : unit -> 'a
Parse_error Malformed. Use for format violations.
Example:
if byte <> '\r' then
Err.malformed ()
Conditional Raises (when condition is TRUE)
These functions raise errors when the condition is true.
when_
val when_ : bool -> status -> unit
Parse_error status if condition is true.
The error status to raise if condition is true
Err.when_ (header_count > max_headers) Headers_too_large
partial_when
val partial_when : bool -> unit
Parse_error Partial if condition is true.
Example:
Err.partial_when (pos + needed > available)
val malformed_when : bool -> unit
Parse_error Malformed if condition is true.
Example:
Err.malformed_when (byte = '\r' && next_byte <> '\n')
Guard Combinators (raise when condition is FALSE)
These functions raise errors when the condition is false (i.e., they “guard” that the condition must be true).
guard
val guard : bool -> status -> unit
Parse_error status if condition is false.
Condition that must be true
The error status to raise if condition is false
Err.guard (version = "HTTP/1.1" || version = "HTTP/1.0") Invalid_version
partial_unless
val partial_unless : bool -> unit
Parse_error Partial if condition is false.
Use for buffer boundary checks where you require more data.
Condition that must be true (enough data available)
Err.partial_unless (pos + 2 <= buffer_length)
val malformed_unless : bool -> unit
Parse_error Malformed if condition is false.
Use for validation checks where you require a condition to hold.
Condition that must be true (valid format)
Err.malformed_unless (byte >= '0' && byte <= '9')
Recovery Combinator
optional
val optional : save:(unit -> 'pos) -> restore:('pos -> unit) -> (unit -> 'a) -> 'a or_null
Or_null.some. On Parse_error, restores state using restore (save ()) and returns Or_null.none.
Function to save current parser position/state
Function to restore parser position/state
Parser function to attempt
let optional_content_length =
Err.optional
~save:(fun () -> !pos)
~restore:(fun p -> pos := p)
(fun () -> parse_content_length ())
in
match Or_null.to_option optional_content_length with
| Some length -> (* Content-Length found *)
...
| None -> (* No Content-Length, continue *)
...
Usage Patterns
let parse_request_line buffer pos =
(* Ensure we have enough data *)
Err.partial_unless (pos + 14 <= buffer_length);
(* Parse method *)
let method_end = find_space buffer pos in
Err.malformed_unless (method_end > pos);
(* Validate HTTP version *)
let version = substring buffer version_start 8 in
Err.guard (version = "HTTP/1.1" || version = "HTTP/1.0") Invalid_version;
...
Security Checks
let parse_content_length buffer span =
let max_allowed = Int64.of_int 10_000_000 in
let #(length, overflow) =
Span.parse_int64_limited buffer span ~max_value:max_allowed in
(* Reject if overflow or too large *)
Err.when_ overflow Content_length_overflow;
(* Reject if invalid *)
Err.malformed_when (Int64.compare length (Int64.of_int (-1)) = 0);
length
let find_optional_header buffer headers name =
Err.optional
~save:(fun () -> 0) (* No state to save *)
~restore:(fun _ -> ()) (* No state to restore *)
(fun () ->
match find_header headers name with
| Some h -> h
| None -> Err.fail Partial (* Trigger recovery *)
)
