http::basic_parser

A parser for decoding HTTP/1 wire format messages.

Synopsis

Defined in header <boost/beast/http/basic_parser.hpp>

template<
    bool isRequest,
    class Derived>
class basic_parser :
    private basic_parser_base

Types

Name	Description
is_request	true if this parser parses requests, false for responses.

Member Functions

Name	Description
base	Returns a reference to this object as a basic_parser. Returns a constant reference to this object as a basic_parser.
basic_parser	Copy constructor.
body_limit	Set the limit on the payload body.
chunked	Returns true if the last value for Transfer-Encoding is "chunked".
content_length	Returns the optional value of Content-Length if known.
eager	Returns true if the eager parse option is set. Set the eager parse option.
got_some	Returns true if the parser has received at least one byte of input.
header_limit	Set a limit on the total size of the header.
is_done	Returns true if the message is complete.
is_header_done	Returns true if a the parser has produced the full header.
keep_alive	Returns true if the message has keep-alive connection semantics.
need_eof	Returns true if the message semantics require an end of file.
operator=	Copy assignment.
put	Write a buffer sequence to the parser.
put_eof	Inform the parser that the end of stream was reached.
skip	Returns true if the skip parse option is set. Set the skip parse option.
upgrade	Returns true if the message is an upgrade message.
~basic_parser	Destructor.

Protected Member Functions

Name	Description
basic_parser	Default constructor. Move constructor.
operator=	Move assignment.

Name

Description

basic_parser

Default constructor.

Move constructor.

operator=

Move assignment.

This parser is designed to efficiently parse messages in the HTTP/1 wire format. It allocates no memory when input is presented as a single contiguous buffer, and uses minimal state. It will handle chunked encoding and it understands the semantics of the Connection, Content-Length, and Upgrade fields. The parser is optimized for the case where the input buffer sequence consists of a single contiguous buffer. The flat_buffer class is provided, which guarantees that the input sequence of the stream buffer will be represented by exactly one contiguous buffer. To ensure the optimum performance of the parser, use flat_buffer with HTTP algorithms such as http::read, http::read_some, http::async_read, and http::async_read_some. Alternatively, the caller may use custom techniques to ensure that the structured portion of the HTTP message (header or chunk header) is contained in a linear buffer.

The interface uses CRTP (Curiously Recurring Template Pattern). To use this class directly, derive from http::basic_parser. When bytes are presented, the implementation will make a series of zero or more calls to derived class members functions (termed "callbacks" in this context) matching a specific signature.

Every callback must be provided by the derived class, or else a compilation error will be generated. This exemplar shows the signature and description of the callbacks required in the derived class. For each callback, the function will ensure that !ec is true if there was no error or set to the appropriate error code if there was one. If an error is set, the value is propagated to the caller of the parser.

Derived Class Requirements

template<bool isRequest>
class derived
    : public basic_parser<isRequest, derived<isRequest>>
{
private:
    // The friend declaration is needed,
    // otherwise the callbacks must be made public.
    friend class basic_parser<isRequest, derived>;

    void
    on_request_impl(
        verb method,                // The method verb, verb::unknown if no match
        string_view method_str,     // The method as a string
        string_view target,         // The request-target
        int version,                // The HTTP-version
        error_code& ec);            // The error returned to the caller, if any

    void
    on_response_impl(
        int code,                   // The status-code
        string_view reason,         // The obsolete reason-phrase
        int version,                // The HTTP-version
        error_code& ec);            // The error returned to the caller, if any

    void
    on_field_impl(
        field f,                    // The known-field enumeration constant
        string_view name,           // The field name string.
        string_view value,          // The field value
        error_code& ec);            // The error returned to the caller, if any

    void
    on_header_impl(
        error_code& ec);            // The error returned to the caller, if any

    void
    on_body_init_impl(
        boost::optional<
            std::uint64_t> const&
                content_length,     // Content length if known, else `boost::none`
        error_code& ec);            // The error returned to the caller, if any

    std::size_t
    on_body_impl(
        string_view s,              // A portion of the body
        error_code& ec);            // The error returned to the caller, if any

    void
    on_chunk_header_impl(
        std::uint64_t size,         // The size of the upcoming chunk,
                                    // or zero for the last chunk
        string_view extension,      // The chunk extensions (may be empty)
        error_code& ec);            // The error returned to the caller, if any

    std::size_t
    on_chunk_body_impl(
        std::uint64_t remain,       // The number of bytes remaining in the chunk,
                                    // including what is being passed here.
                                    // or zero for the last chunk
        string_view body,           // The next piece of the chunk body
        error_code& ec);            // The error returned to the caller, if any

    void
    on_finish_impl(error_code& ec);

public:
    derived() = default;
};

Template Parameters

Type	Description
`isRequest`	A `bool` indicating whether the parser will be presented with request or response message.
`Derived`	The derived class type. This is part of the Curiously Recurring Template Pattern interface.

Remarks

If the parser encounters a field value with obs-fold longer than 4 kilobytes in length, an error is generated.

Convenience header <boost/beast/http.hpp>