For HTTP we model the message to maximize flexibility of implementation strategies
while allowing familiar verbs such as
write. The HTTP interface is
further driven by the needs of the WebSocket module, as a WebSocket session
requires a HTTP Upgrade handshake exchange at the start. Other design goals:
The HTTP interface doesn't try to reinvent the wheel, it just uses
that you set up beforehand. Callers use the interfaces already existing
on those objects to make outgoing connections, accept incoming connections,
or establish TLS sessions with certificates. We find the available
Asio examples for performing these tasks sufficient.
We presume this means a facility to match expressions against the URI in HTTP requests, and dispatch them to calling code. The authors feel that this is a responsibility of higher level code. Beast.HTTP does not try to offer a web server.
Cookies, or managing these types of HTTP headers in general, is the responsibility of higher levels. Beast.HTTP just tries to get complete messages to and from the calling code. It deals in the HTTP headers just enough to process the message body and leaves the rest to callers. However, for forms and file uploads the symmetric interface of the message class allows HTTP requests to include arbitrary body types including those needed to upload a file or fill out a form.
Beast.HTTP does not provide direct facilities for implementing TLS
connections; however, the interfaces already existing on the
boost::asio::ssl::stream are available and can be used
to establish secure connections. Then, functions like
can work with those encrypted connections with no problem.
The design goal for the library is to not try to invent a web server. We feel that there is a strong need for a basic implementation that models the HTTP message and provides functions to send and receive them over Asio. Such an implementation should serve as a building block upon which higher abstractions such as the aforementioned HTTP service or cgi-gateway can be built.
One of the example programs implements a simple HTTP server that delivers files from the filesystem.
The Beast interface needs to support this functionality (by allowing this special case of partial message parsing and serialization). Specifically, it should let callers read the request up to just before the body, and let callers write the request up to just before the body. However, making use of this behavior should be up to callers (since Beast is low level).
Many reviewers feel that HTTP/2 support is an essential feature of a HTTP library. The authors agree that HTTP/2 is important but also feel that the most sensible implementation is one that does not re-use the same network reading and writing interface for 2 as that for 1.0 and 1.1.
The Beast.HTTP message model is suitable for HTTP/2 and can be re-used. The IETF HTTP Working Group adopted message compatiblity with HTTP/1.x as an explicit goal. A parser can simply emit full headers after decoding the compressed HTTP/2 headers. The stream ID is not logically part of the message but rather message metadata and should be communicated out-of-band (see below). HTTP/2 sessions begin with a traditional HTTP/1.1 Upgrade similar in fashion to the WebSocket upgrade. An HTTP/2 implementation can use existing Beast.HTTP primitives to perform this handshake.
Free functions for HTTP/2 sessions are not possible because of the
requirement to maintain per-session state. For example, to decode the
compressed headers. Or to remember and respect the remote peer's window
settings. The authors propose that a HTTP/2 implementation be written
as a separate class template, similar to the
but with additional interfaces to support version 2 features. We feel
that Beast.HTTP offers enough useful functionality to justify inclusion,
so that developers can take advantage of it right away instead of waiting.