[/ Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com) Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] [section:http Using HTTP] [block ''' Messages Headers Body Algorithms Sockets '''] Beast.HTTP offers programmers simple and performant models of HTTP messages and their associated operations including synchronous and asynchronous reading and writing of messages in the HTTP/1 wire format using Boost.Asio. A HTTP message (referred to hereafter as "message") contains request or response specific attributes, a series of zero or more name/value pairs (collectively termed "headers"), and a series of octets called the message body which may be zero in length. The HTTP protocol defines the client and server roles: clients send messages called requests and servers send back messages called responses. [note The following documentation assumes familiarity with both Boost.Asio and the HTTP protocol specification described in __rfc7230__. Sample code and identifiers mentioned in this section are written as if the following declarations are in effect: ``` #include using namespace beast; using namespace beast::http; ``` ] [section:message Messages] The __message__ class template models HTTP/1 and HTTP/2 requests and responses. These class templates are complete: they contain all the information needed by the algorithms. Objects of this type are first class: They may be returned from functions, moved, copied, passed as arguments, and stored in containers. Request and response messages are distinct types; functions may be overloaded on just one or the other if desired. Because this class template supports HTTP/1 and HTTP/2, it is sometimes referred to as the universal message model. There are three important template parameters in the message class: ``` template< bool isRequest, class Body, class Headers > class message; ``` * [*`isRequest`]: Controls whether or not the message is a request or response. Depending on the value, different data members will be present in the resulting type. * [*`Body`]: determines both the kind of container used to represent the message body and the algorithms used to parse and serialize it. * [*`Headers`]: determines the container used to represent the HTTP headers. For notational convenience, the following template type aliases are provided: ``` template< class Body, class Headers = basic_headers>> using request = message; template< class Body, class Headers = basic_headers>> using response = message; ``` The message class template has different data members depending on whether it represents a request or response. These simplified declarations notionally illustrate the members of HTTP/1 messages: ``` template struct request { int version; // 10 for HTTP/1.0, 11 for HTTP/1.1 std::string method; std::string url; Headers headers; typename Body::value_type body; }; template struct response { int version; // 10 for HTTP/1.0, 11 for HTTP/1.1 int status; std::string reason; Headers headers; typename Body::value_type body; }; ``` These statements set fields in request and response message objects: ``` request req; req.version = 11; // HTTP/1.1 req.method = "GET"; req.url = "/index.html"; req.headers.insert("User-Agent", "Beast.HTTP"); req.body = ""; response res; res.version = 10; // HTTP/1.0 res.status = 404; res.reason = "Not Found"; res.headers.insert("Server", "Beast.HTTP"); res.body = "The requested resource was not found."; ``` [endsect] [section:headers Headers] The [*`Headers`] type represents a container that can set or retrieve the headers in a message. Beast provides the [link beast.ref.http__basic_headers `basic_headers`] class which serves the needs for most users. It supports modification and inspection of values. The field names are not case-sensitive. These statements change the values of the headers in the message passed: ``` template void set_fields(request& req) { if(! req.exists("User-Agent")) req.insert("User-Agent", "myWebClient"); if(req.exists("Accept-Charset")) req.erase("Accept-Charset"); req.replace("Accept", "text/plain"); } ``` [heading Advanced] This illustration shows more detail about the [link beast.ref.http__message [*`message`]] class template (boilerplate present in the actual declaration has been removed for clarity): [$images/message.png [width 580px] [height 225px]] User defined [*`Headers`] types are possible. To support serialization, the type must meet the requirements of __FieldSequence__. To support parsing using the provided parser, the type must provide the `insert` member function. [endsect] [section:body Body] The message [*`Body`] template parameter controls both the type of the data member of the resulting message object, and the algorithms used during parsing and serialization. Beast provides three very common [*`Body`] types: * [link beast.ref.http__empty_body [*`empty_body`:]] An empty message body. Used in GET requests where there is no message body. Example: ``` request req; req.version = 11; req.method = "GET"; req.url = "/index.html"; ``` * [link beast.ref.http__string_body [*`string_body`:]] A body with a `value_type` as `std::string`. Useful for quickly putting together a request or response with simple text in the message body (such as an error message). Has the same insertion complexity of `std::string`. This is the type of body used in the examples: ``` response res; static_assert(std::is_same::value); res.body = "Here is the data you requested"; ``` * [link beast.ref.http__streambuf_body [*`streambuf_body`:]] A body with a `value_type` of [link beast.ref.streambuf `streambuf`]: an efficient storage object which uses multiple octet arrays of varying lengths to represent data. [heading Advanced] User-defined types are possible for the message body, where the type meets the [link beast.ref.Body [*`Body`]] requirements. This simplified class declaration shows the customization points available to user-defined body types: [$images/body.png [width 510px] [height 210px]] * [*`value_type`]: Determines the type of the [link beast.ref.http__message.body `message::body`] member. If this type defines default construction, move, copy, or swap, then message objects declared with this [*`Body`] will have those operations defined. * [*`reader`]: An optional nested type meeting the requirements of [link beast.ref.Reader [*`Reader`]]. If present, this defines the algorithm used for parsing bodies of this type. * [*`writer`]: An optional nested type meeting the requirements of [link beast.ref.Writer [*`Writer`]]. If present, this defines the algorithm used for serializing bodies of this type. The examples included with this library provide a Body implementation that serializing message bodies that come from a file. [endsect] [section:algorithms Algorithms] In addition to the universal message model, Beast provides synchronous algorithms which operate on HTTP/1 messages: * [link beast.ref.http__read [*read]]: Parse a message from a stream * [link beast.ref.http__write [*write]]: Serialize a message into its wire format on a stream Asynchronous versions of these algorithms are also available: * [link beast.ref.http__async_read [*async_read]]: Parse a message from a stream * [link beast.ref.http__async_write [*async_write]]: Serialize a message into its wire format on a stream [endsect] [section:sockets Using Sockets] The library provides simple free functions modeled after Boost.Asio to send and receive messages on TCP/IP sockets, SSL streams, or any object which meets the Boost.Asio type requirements (SyncReadStream, SyncWriteStream, AsyncReadStream, and AsyncWriteStream depending on the types of operations performed). To send messages synchronously, use one of the [link beast.ref.http__write `write`] functions: ``` void send_request(boost::asio::ip::tcp::socket& sock) { request req; req.version = 11; req.method = "GET"; req.url = "/index.html"; ... write(sock, req); // Throws exception on error ... // Alternatively boost::system::error:code ec; write(sock, req, ec); if(ec) std::cerr << "error writing http message: " << ec.message(); } ``` An asynchronous interface is available: ``` void handle_write(boost::system::error_code); ... request req; ... async_write(sock, req, std::bind(&handle_write, std::placeholders::_1)); ``` When the implementation reads messages from a socket, it can read bytes lying after the end of the message if they are present (the alternative is to read a single byte at a time which is unsuitable for performance reasons). To store and re-use these extra bytes on subsequent messages, the read interface requires an additional parameter: a [link beast.ref.DynamicBuffer [*`DynamicBuffer`]] object. This example reads a message from the socket, with the extra bytes stored in the streambuf parameter for use in a subsequent call to read: ``` boost::asio::streambuf sb; ... response res; read(sock, sb, res); // Throws exception on error ... // Alternatively boost::system::error:code ec; read(sock, sb, res, ec); if(ec) std::cerr << "error reading http message: " << ec.message(); ``` As with the write function, an asynchronous interface is available. The stream buffer parameter must remain valid until the completion handler is called: ``` void handle_read(boost::system::error_code); ... boost::asio::streambuf sb; response res; ... async_read(sock, res, std::bind(&handle_read, std::placeholders::_1)); ``` An alternative to using a `boost::asio::streambuf` is to use a __streambuf__, which meets the requirements of __DynamicBuffer__ and is optimized for performance: ``` void handle_read(boost::system::error_code); ... beast::streambuf sb; response res; read(sock, sb, res); ``` The `read` implementation can use any object meeting the requirements of __DynamicBuffer__, allowing callers to define custom memory management strategies used by the implementation. [endsect] [endsect]