boost::burl::parser

A parser for HTTP/1 messages.

Synopsis

Declared in <boost/burl/parser.hpp>

class parser;

Description

The parser performs no I/O. Received bytes are handed to it through prepare and commit, and each parsing operation reports http::error::need_data when it requires more. Driving the parser over a stream is the job of message_reader.

The parser uses a single block of memory allocated during construction and never exceeds it. The space is reused across messages, one at a time, and holds:

raw octets received from the stream,
the message header, with O(1) access to the start line,
all or part of the message body, and
decoded output when the body is encoded.

Operations

The body can be retrieved three ways, which differ in where the octets end up:

flatten_body returns the whole body in place, without copying,
read_some copies into caller‐supplied memory, or lets the content decoder write into it directly, and
pull borrows the parser's own buffers, which consume then releases.

Each parses the header first when it has not been parsed already, so a caller with no interest in the header never has to call parse_header.

Content Decoding

When config::decode is set, a body whose Content‐Encoding is gzip, deflate, br, or zstd is decoded as it is parsed, using the decode service installed for that coding in the system context. A body whose coding has no installed service, or which the parser does not know, is delivered as sent.

Errors

Errors which ask for more input are:

http::error::need_data — fill prepare, call commit, and try again. Reported only while prepare has room.
http::error::in_place_overflow — more input is required but no writable space remains.
http::error::incomplete — more input is required but commit_eof was called.
http::error::end_of_stream — the stream closed cleanly before the message began.