[/ Copyright (c) 2013-2017 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 ''' Message Fields Body Algorithms '''] Beast offers programmers simple and performant models of HTTP messages and their associated operations including synchronous and asynchronous reading and writing of messages and headers in the HTTP/1 wire format using Boost.Asio. [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 #include using namespace beast; using namespace beast::http; ``` ] [section:message Message] The HTTP protocol defines the client and server roles: clients send messages called requests and servers send back messages called responses. A HTTP message (referred to hereafter as "message") contains request or response specific attributes (contained in the "Start Line"), a series of zero or more name/value pairs (collectively termed "Fields"), and an optional series of octets called the message body which may be zero in length. The start line for a HTTP request includes a string called the method, a string called the URL, and a version number indicating HTTP/1.0 or HTTP/1.1. For a response, the start line contains an integer status code and a string called the reason phrase. Alternatively, a HTTP message can be viewed as two parts: a header, followed by a body. [note The Reason-Phrase is obsolete as of rfc7230. ] The __header__ class template models the header for HTTP/1 and HTTP/2 messages. This class template is a family of specializations, one for requests and one for responses, depending on the [*`isRequest`] template value. The [*`Fields`] template type determines the type of associative container used to store the field values. The provided __basic_fields__ class template and __fields__ type alias are typical choices for the [*`Fields`] type, but advanced applications may supply user defined types which meet the requirements. The __message__ class template models the header and optional body for HTTP/1 and HTTP/2 requests and responses. It is derived from the __header__ class template with the same shared template parameters, and adds the `body` data member. The message class template requires an additional template argument type [*`Body`]. This type controls the container used to represent the body, if any, as well as the algorithms needed to serialize and parse bodies of that type. This illustration shows the declarations and members of the __header__ and __message__ class templates, as well as the inheritance relationship: [$images/message.png [width 711px] [height 424px]] For notational convenience, these template type aliases are provided which supply typical choices for the [*`Fields`] type: ``` /// A typical HTTP request template using request = message; /// A typical HTTP response template using response = message; ``` The code examples below show how to create and fill in request and response objects: [table Create Message [[HTTP Request] [HTTP Response]] [[ ``` request req; req.version = 11; // HTTP/1.1 req.method("GET"); req.target("/index.htm"); req.fields.insert("Accept", "text/html"); req.fields.insert("Connection", "keep-alive"); req.fields.insert("User-Agent", "Beast"); ``` ][ ``` response res; res.version = 11; // HTTP/1.1 res.status = 200; res.reason("OK"); res.fields.insert("Server", "Beast"); res.fields.insert("Content-Length", 4); res.body = "****"; ``` ]]] In the serialized format of a HTTP message, the header is represented as a series of text lines ending in CRLF (`"\r\n"`). The end of the header is indicated by a line containing only CRLF. Here are examples of serialized HTTP request and response objects. The objects created above will produce these results when serialized. Note that only the response has a body: [table Serialized HTTP Request and Response [[HTTP Request] [HTTP Response]] [[ ``` GET /index.htm HTTP/1.1\r\n Accept: text/html\r\n Connection: keep-alive\r\n User-Agent: Beast\r\n \r\n ``` ][ ``` 200 OK HTTP/1.1\r\n Server: Beast\r\n Content-Length: 4\r\n \r\n **** ``` ]]] [endsect] [section:fields Fields] The [*`Fields`] type represents a container that can set or retrieve the fields in a message. Beast provides the [link beast.ref.http__basic_fields `basic_fields`] 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"); } ``` User defined [*`Fields`] 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__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__dynamic_body [*`dynamic_body`:]] A body with a `value_type` of [link beast.ref.multi_buffer `multi_buffer`]: an efficient storage object which uses multiple octet arrays of varying lengths to represent data. * [link beast.ref.http__buffer_body [*`buffer_body`:]] A write-only body with a `value_type` representing a __ConstBufferSequence__. This special body allows the caller to implement their own write loop for advanced use-cases such as relaying. * [link beast.ref.http__empty_body [*`empty_body`:]] A write-only body with an empty `value_type` representing an HTTP message with no content body. [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. * [*`body_writer`]: An optional nested type meeting the requirements of [link beast.ref.BodyWriter [*BodyWriter]]. If present, this defines the algorithm used to transfer parsed octets into buffers representing the body. * [*`body_reader`]: An optional nested type meeting the requirements of [link beast.ref.BodyReader [*BodyReader]]. If present, this defines the algorithm used to obtain buffers representing a body 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] Algorithms are provided to serialize and deserialize HTTP/1 messages on streams. * [link beast.ref.http__read [*read]]: Deserialize a HTTP/1 __header__ or __message__ from a stream. * [link beast.ref.http__write [*write]]: Serialize a HTTP/1 __header__ or __message__ to a stream. Asynchronous versions of these algorithms are also available: * [link beast.ref.http__async_read [*async_read]]: Deserialize a HTTP/1 __header__ or __message__ asynchronously from a stream. * [link beast.ref.http__async_write [*async_write]]: Serialize a HTTP/1 __header__ or __message__ asynchronously to a stream. [heading Using Sockets] The free function algorithms are 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.target("/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 __multi_buffer__, which meets the requirements of __DynamicBuffer__ and is optimized for performance: ``` void handle_read(boost::system::error_code); ... beast::multi_buffer 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]