[/
    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:primer Protocol Primer]

The HTTP protocol defines the
[@https://tools.ietf.org/html/rfc7230#section-2.1 client and server roles]:
clients send requests and servers send back responses. A request
or response is an
[@https://tools.ietf.org/html/rfc7230#section-3 HTTP message]
(referred to hereafter as "message"), with two parts:
a header containing structured metadata and an optional variable-length
body containing arbitrary data. A serialized header is one or more text
lines where each line ends in a carriage return followed by linefeed
(`"\r\n"`). An empty line marks the end of the header. The first line
in the header is called the ['start-line]. The start line contents are
different for requests and responses.

Every message contains a set of zero or more field name/value pairs,
collectively called "fields". The names and values are represented using
text strings with various requirements. A serialized field contains the
field name, then a colon followed by a space (`": "`), and finally the field
value.

When a client and server have established a connection and intend to
use HTTP, the client sends a series of requests while the server reads
sends back at least one response for each request in the order those
requests were received.

[heading Requests]

Clients send requests, which contain a
[@https://tools.ietf.org/html/rfc7230#section-3.1.1 method]
and
[@https://tools.ietf.org/html/rfc7230#section-5.3 request-target],
and
[@https://tools.ietf.org/html/rfc7230#section-2.6 HTTP-version].
The method identifies the operation to be performed while the target
identifies the object on the server to which the operation applies.
The version is almost always 1.1, but older programs sometimes use 1.0.

[table
[[Serialized Request][Description]]
[[
```
    GET / HTTP/1.1\r\n
    User-Agent: Beast\r\n
    \r\n
```
][
    This request has a method of "GET", a target of "/", and indicates
    HTTP version 1.1. It contains a single field called "User-Agent"
    whose value is "Beast". There is no message body.
]]
]

[heading Responses]

Servers send responses, which contain a
[@https://tools.ietf.org/html/rfc7231#section-6 status-code],
[@https://tools.ietf.org/html/rfc7230#section-3.1.2 reason-phrase], and
[@https://tools.ietf.org/html/rfc7230#section-2.6 HTTP-version].
The reason phrase is
[@https://tools.ietf.org/html/rfc7230#section-3.1.2 obsolete]:
clients SHOULD ignore the reason-phrase content. Here is a response which
includes a body. The special
[@https://tools.ietf.org/html/rfc7230#section-3.3.2  Content-Length]
field informs the remote host of the size of the body which follows.

[table
[[Serialized Response][Description]]
[[
```
    HTTP/1.1 200 OK\r\n
    Server: Beast\r\n
    Content-Length: 13\r\n
    \r\n
    Hello, world!
```
][
    This response has a
    [@https://tools.ietf.org/html/rfc7231#section-6 200 status code]
    meaning the operation requested completed successfully. The obsolete
    reason phrase is "OK". It specifies HTTP version 1.1, and contains
    a body 13 octets in size with the text "Hello, world!".
]]
]

[heading Special Fields]

Certain fields appearing in messages are special. The library understands
these fields when performing serialization and parsing, taking automatic
action as needed when the fields are present:

[table Special Fields
[[Field][Description]]
[
    [
        [@https://tools.ietf.org/html/rfc7230#section-6.1 [*`Connection`]]

        [@https://tools.ietf.org/html/rfc7230#appendix-A.1.2 [*`Proxy-Connection`]]
    ][
        This field allows the sender to indicate desired control options
        for the current connection. Common values include "close",
        "keep-alive", and "upgrade".
    ]
][
    [
        [@https://tools.ietf.org/html/rfc7230#section-3.3.2 [*`Content-Length`]]
    ][
        When present, this field informs the recipient about the exact
        size in bytes of the body which follows the message header.
    ]
][
    [
        [@https://tools.ietf.org/html/rfc7230#section-3.3.1 [*`Transfer-Encoding`]]
    ][
        This optional field lists the names of the sequence of transfer codings
        that have been (or will be) applied to the content payload to form
        the message body.

        Beast understands the "chunked" coding scheme when it is the last
        (outermost) applied coding. The library will automatically apply
        chunked encoding when the content length is not known ahead of time
        during serialization, and the library will automatically removed chunked
        encoding from parsed messages.
    ]
][
    [
        [@https://tools.ietf.org/html/rfc7230#section-6.7 [*`Upgrade`]]
    ][
        The Upgrade header field provides a mechanism to transition from
        HTTP/1.1 to another protocol on the same connection. For example, it
        is the mechanism used by WebSocket's initial HTTP handshake to
        establish a WebSocket connection.
    ]
]
]

[endsect]