| Home | Libraries | People | FAQ | More

## HTTP

| Warning
Higher level functions such as Basic Authentication, mime/multipart encoding, cookies, automatic handling of redirects, gzipped transfer encodings, caching, or proxying (to name a few) are not directly provided, but nothing stops users from creating these features using Beast's HTTP message types.

This library offers programmers simple and performant models of HTTP messages and their associated operations including synchronous, asynchronous, and buffer-oriented parsing and serialization of messages in the HTTP/1 wire format using Boost.Asio. Specifically, the library provides:

Message Containers

  Complete HTTP messages are modeled using the `message` class, with possible user customizations.

Stream Reading

  The functions `read`, `read_header`, `read_some`, `async_read`, `async_read_header`, and `async_read_some` read HTTP/1 message data from a stream.

Stream Writing

  The functions `write`, `write_header`, `write_some`, `async_write`, `async_write_header`, and `async_write_some` write HTTP/1 message data to a stream.

Serialization

  The `serializer` produces a series of octet buffers conforming to the rfc7230 wire representation of a `message`.

Parsing

  The `parser` attempts to convert a series of octet buffers into a `message`.

Interfaces for operating on HTTP messages are structured into several layers. The highest level provides ease of use, while lower levels provide progressively more control, options, and flexibility. At the lowest level customization points are provided, where user defined types can replace parts of the implementation. The layers are arranged thusly:

Level | Read/Write What | Description
--- | --- | ---
6 | `message` | At the highest level, these free functions send or receive a complete HTTP message in one call. They are designed for ease of use: `read`, `write`, `async_read`, and `async_write`.
5 | `parser`, `serializer` | For more control, callers may take responsibility for managing the required `parser` or `serializer` transient state objects. This allows additional configuration such as limiting the number of bytes for message components during parsing, or regulating the size of buffers emitted during output. These functions send or receive complete messages using a serializer or parser: `read`, `write`, `async_read`, and `async_write`.
4 | `header` | Sometimes it is necessary to first send or receive the HTTP header. For example, to read the header and take action before continuing to read the body. These functions use a `parser` or `serializer` to read or write the header: `read_header`, `write_header`, `async_read_header`, and `async_write_header`.
3 | partial `message` | All of the stream operations at higher levels thus far have operated on a complete header or message. At this level it is possible to send and receive messages incrementally. This allows resource constrained implementations to perform work bounded on storage, or allows better control when setting timeouts for example. These functions read or write bounded amounts of data and return the number of bytes transacted: `read_some`, `write_some`, `async_read_some`, and `async_write_some`.
2 | chunked-body | Until now parse and serialize operations apply or remove the chunked transfer coding as needed for message payloads whose size is not known ahead of time. For some domain specific niches, it is necessary to assume direct control over incoming or outgoing chunks in a chunk encoded message payload. For parsing this is achieved by setting hooks using the functions `on_chunk_header` and/or `on_chunk_body`. For serializing callers may first emit the header, and then use these buffer sequence adapters to control the contents of each chunk including chunk extensions and the trailer-part: `chunk_body`, `chunk_crlf`, `chunk_header`, and `chunk_last`.
1 | buffers | For ultimate control, the use of library stream algorithms may be bypassed entirely and instead work directly with buffers by calling members of `parser` or `serializer`.
0 | user-defined | In addition to the typical customization points of Stream and DynamicBuffer, user-defined types may replace parts of the library implementation at the lowest level. The customization points include Fields for creating a container to store HTTP fields, Body for defining containers and algorithms used for HTTP message payloads, and user-defined subclasses of `basic_parser` for implementing custom message representation strategies.

| Note
This documentation assumes some familiarity with Boost.Asio and the HTTP protocol specification described in rfc7230. Sample code and identifiers mentioned in this section is written as if these declarations are in effect:
    #include <boost/beast/http.hpp>
    using namespace boost::beast::http;