xahaud/doc/http.qbk

[/
    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)
]

[/
ideas:
    - complete send request walkthrough (client)
    - complete receive response walkthrough (client)
    - complete receive request walkthrough (server)
    - complete send response walkthrough (server)

    - Introduce concepts from simple to complex
    - Smooth progression of new ideas building on the previous ideas

    - do we show a simplified message with collapsed fields?
    - do we introduce `header` or `message` first?


contents:
    Message (and header, fields)
        Create request
        Create response
    Algorithms
        Write
        Read
        Parse
    Examples
        Send Request
        Receive Response
        Receive Request
        Send Response
    Advanced
        Responding to HEAD
        Expect: 100-continue
    Body (user defined)


section beast.http.examples Examples

note
  In the example code which follows, `socket` refers to an object of type
  `boost::asio::ip::tcp::socket` which is currently connected to a remote peer.
]



[section:http Using HTTP]

[block '''
<informaltable frame="all"><tgroup cols="1"><colspec colname="a"/><tbody><row><entry valign="top"><simplelist>
  <member><link linkend="beast.http.message">Message</link></member>
  <member><link linkend="beast.http.fields">Fields</link></member>
  <member><link linkend="beast.http.body">Body</link></member>
  <member><link linkend="beast.http.algorithms">Algorithms</link></member>
</simplelist></entry></row></tbody></tgroup></informaltable>
''']

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 <beast/core.hpp>
    #include <beast/http.hpp>
    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 650px] [height 390px]]

For notational convenience, these template type aliases are provided which
supply typical choices for the [*`Fields`] type:
```
using request_header = header<true, fields>;
using response_header = header<false, fields>;

template<class Body, class Fields = fields>
using request = message<true, Body, Fields>;

template<class Body, class Fields = fields>
using response = message<false, Body, Fields>;
```

The code examples below show how to create and fill in a request and response
object:

[table Create Message
[[HTTP Request] [HTTP Response]]
[[
    ```
    request<empty_body> req;
    req.version = 11;   // HTTP/1.1
    req.method = "GET";
    req.url = "/index.htm"
    req.fields.insert("Accept", "text/html");
    req.fields.insert("Connection", "keep-alive");
    req.fields.insert("User-Agent", "Beast");
    ```
][
    ```
    response<string_body> res;
    res.version = 11;   // HTTP/1.1
    res.status = 200;
    res.reason = "OK";
    res.fields.insert("Sever", "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<class Body>
    void set_fields(request<Body>& 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__empty_body [*`empty_body`:]] An empty message body.
Used in GET requests where there is no message body. Example:
```
    request<empty_body> 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<string_body> res;
    static_assert(std::is_same<decltype(res.body), std::string>::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]

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<empty_body> 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<empty_body> 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<string_body> 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<string_body> 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<string_body> 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]