...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
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:
Complete HTTP messages are modeled using the message
class, with possible
user customizations.
The functions read
, read_header
, read_some
, async_read
, async_read_header
, and async_read_some
read HTTP/1
message data from a stream.
The functions write
, write_header
, write_some
, async_write
, async_write_header
, and async_write_some
write HTTP/1
message data to a stream.
The serializer
produces a series
of octet buffers conforming to the rfc7230
wire representation of a message
.
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 |
At the highest level, these free functions send or receive a complete
HTTP message in one call. They are designed for ease of use: |
|
5 |
For more control, callers may take responsibility for managing the
required |
|
4 |
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 |
|
3 |
partial |
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:
|
2 |
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 |
|
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 |
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 |
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; |