mirror of
https://github.com/boostorg/beast.git
synced 2026-05-05 04:04:30 +02:00
Vinnie Falco
145 lines
5.1 KiB
Plaintext
145 lines
5.1 KiB
Plaintext
[/
|
|
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 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 with a trailing CRLF.
|
|
|
|
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]
|