template<bool isRequest, class Derived>
class boost::beast::http::basic_parser< isRequest, Derived >
A parser for decoding HTTP/1 wire format messages.
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 read, read_some, async_read, and 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 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
{
private:
void
on_request_impl(
void
on_response_impl(
int code,
void
on_field_impl(
void
on_header_impl(
void
on_body_init_impl(
std::uint64_t> const&
std::size_t
on_body_impl(
void
on_chunk_header_impl(
std::uint64_t size,
std::size_t
on_chunk_body_impl(
std::uint64_t remain,
void
public:
derived() = default;
};
- Template Parameters
-
| 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. |
- Note
- If the parser encounters a field value with obs-fold longer than 4 kilobytes in length, an error is generated.
template<bool isRequest, class Derived>
Set the limit on the payload body.
This function sets the maximum allowed size of the payload body, before any encodings except chunked have been removed. Depending on the message semantics, one of these cases will apply:
- The Content-Length is specified and exceeds the limit. In this case the result error::body_limit is returned immediately after the header is parsed.
- The Content-Length is unspecified and the chunked encoding is not specified as the last encoding. In this case the end of message is determined by the end of file indicator on the associated stream or input source. If a sufficient number of body payload octets are presented to the parser to exceed the configured limit, the parse fails with the result error::body_limit
- The Transfer-Encoding specifies the chunked encoding as the last encoding. In this case, when the number of payload body octets produced by removing the chunked encoding exceeds the configured limit, the parse fails with the result error::body_limit.
Setting the limit after any body octets have been parsed results in undefined behavior.
The default limit is 1MB for requests and 8MB for responses.
- Parameters
-
| v | The payload body limit to set |
template<bool isRequest, class Derived>
Set the eager parse option.
Normally the parser returns after successfully parsing a structured element (header, chunk header, or chunk body) even if there are octets remaining in the input. This is necessary when attempting to parse the header first, or when the caller wants to inspect information which may be invalidated by subsequent parsing, such as a chunk extension. The eager option controls whether the parser keeps going after parsing structured element if there are octets remaining in the buffer and no error occurs. This option is automatically set or cleared during certain stream operations to improve performance with no change in functionality.
The default setting is false.
- Parameters
-
| v | true to set the eager parse option or false to disable it. |
template<bool isRequest, class Derived>
Set a limit on the total size of the header.
This function sets the maximum allowed size of the header including all field name, value, and delimiter characters and also including the CRLF sequences in the serialized input. If the end of the header is not found within the limit of the header size, the error error::header_limit is returned by put.
Setting the limit after any header octets have been parsed results in undefined behavior.
template<bool isRequest, class Derived >
template<class ConstBufferSequence >
Write a buffer sequence to the parser.
This function attempts to incrementally parse the HTTP message data stored in the caller provided buffers. Upon success, a positive return value indicates that the parser made forward progress, consuming that number of bytes.
In some cases there may be an insufficient number of octets in the input buffer in order to make forward progress. This is indicated by the code error::need_more. When this happens, the caller should place additional bytes into the buffer sequence and call put again.
The error code error::need_more is special. When this error is returned, a subsequent call to put may succeed if the buffers have been updated. Otherwise, upon error the parser may not be restarted.
- Parameters
-
| buffers | An object meeting the requirements of ConstBufferSequence that represents the next chunk of message data. If the length of this buffer sequence is one, the implementation will not allocate additional memory. The class beast::flat_buffer is provided as one way to meet this requirement |
| ec | Set to the error, if any occurred. |
- Returns
- The number of octets consumed in the buffer sequence. The caller should remove these octets even if the error is set.
template<bool isRequest, class Derived >
Inform the parser that the end of stream was reached.
In certain cases, HTTP needs to know where the end of the stream is. For example, sometimes servers send responses without Content-Length and expect the client to consume input (for the body) until EOF. Callbacks and errors will still be processed as usual.
This is typically called when a read from the underlying stream object sets the error code to boost::asio::error::eof.
- Note
- Only valid after parsing a complete header.
- Parameters
-
| ec | Set to the error, if any occurred. |
template<bool isRequest, class Derived >
Set the skip parse option.
This option controls whether or not the parser expects to see an HTTP body, regardless of the presence or absence of certain fields such as Content-Length or a chunked Transfer-Encoding. Depending on the request, some responses do not carry a body. For example, a 200 response to a CONNECT request from a tunneling proxy, or a response to a HEAD request. In these cases, callers may use this function inform the parser that no body is expected. The parser will consider the message complete after the header has been received.
- Parameters
-
| v | true to set the skip body option or false to disable it. |
- Note
- This function must called before any bytes are processed.
1.8.11