• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1[/
2    Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
3
4    Distributed under the Boost Software License, Version 1.0. (See accompanying
5    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6
7    Official repository: https://github.com/boostorg/beast
8]
9
10[section Protocol Primer]
11
12The HTTP protocol defines the
13[@https://tools.ietf.org/html/rfc7230#section-2.1 client and server roles]:
14clients send requests and servers send back responses. When a client and
15server have established a connection, the client sends a series of requests
16while the server sends back at least one response for each received request
17in the order those requests were received.
18
19A request or response is an
20[@https://tools.ietf.org/html/rfc7230#section-3 HTTP message]
21(referred to hereafter as "message") having two parts:
22a header with structured metadata and an optional variable-length body
23holding arbitrary data. A serialized header is one or more text lines
24where each line ends in a carriage return followed by linefeed (`"\r\n"`).
25An empty line marks the end of the header. The first line in the header
26is called the ['start-line]. The contents of the start line contents are
27different for requests and responses.
28
29Every message contains a set of zero or more field name/value pairs,
30collectively called "fields". The names and values are represented using
31text strings with various requirements. A serialized field contains the
32field name, then a colon followed by a space (`": "`), and finally the field
33value with a trailing CRLF.
34
35[heading Requests]
36
37Clients send requests, which contain a
38[@https://tools.ietf.org/html/rfc7230#section-3.1.1 method]
39and
40[@https://tools.ietf.org/html/rfc7230#section-5.3 request-target],
41and
42[@https://tools.ietf.org/html/rfc7230#section-2.6 HTTP-version].
43The method identifies the operation to be performed while the target
44identifies the object on the server to which the operation applies.
45The version is almost always 1.1, but older programs sometimes use 1.0.
46
47[table
48[[Serialized Request][Description]]
49[[
50```
51    GET / HTTP/1.1\r\n
52    User-Agent: Beast\r\n
53    \r\n
54```
55][
56    This request has a method of "GET", a target of "/", and indicates
57    HTTP version 1.1. It contains a single field called "User-Agent"
58    whose value is "Beast". There is no message body.
59]]
60]
61
62[heading Responses]
63
64Servers send responses, which contain a
65[@https://tools.ietf.org/html/rfc7231#section-6 status-code],
66[@https://tools.ietf.org/html/rfc7230#section-3.1.2 reason-phrase], and
67[@https://tools.ietf.org/html/rfc7230#section-2.6 HTTP-version].
68The reason phrase is
69[@https://tools.ietf.org/html/rfc7230#section-3.1.2 obsolete]:
70clients SHOULD ignore the reason-phrase content. Here is a response which
71includes a body. The special
72[@https://tools.ietf.org/html/rfc7230#section-3.3.2  Content-Length]
73field informs the remote host of the size of the body which follows.
74
75[table
76[[Serialized Response][Description]]
77[[
78```
79    HTTP/1.1 200 OK\r\n
80    Server: Beast\r\n
81    Content-Length: 13\r\n
82    \r\n
83    Hello, world!
84```
85][
86    This response has a
87    [@https://tools.ietf.org/html/rfc7231#section-6 200 status code]
88    meaning the operation requested completed successfully. The obsolete
89    reason phrase is "OK". It specifies HTTP version 1.1, and contains
90    a body 13 octets in size with the text "Hello, world!".
91]]
92]
93
94[heading Body]
95
96Messages may optionally carry a body. The size of the message body
97is determined by the semantics of the message and the special fields
98Content-Length and Transfer-Encoding.
99[@https://tools.ietf.org/html/rfc7230#section-3.3 rfc7230 section 3.3]
100provides a comprehensive description for how the body length is
101determined.
102
103[heading Special Fields]
104
105Certain fields appearing in messages are special. The library understands
106these fields when performing serialization and parsing, taking automatic
107action as needed when the fields are parsed in a message and also setting
108the fields if the caller requests it.
109
110[table Special Fields
111[[Field][Description]]
112[
113    [
114        [@https://tools.ietf.org/html/rfc7230#section-6.1 [*`Connection`]]
115
116        [@https://tools.ietf.org/html/rfc7230#appendix-A.1.2 [*`Proxy-Connection`]]
117    ][
118        This field allows the sender to indicate desired control options
119        for the current connection. Common values include "close",
120        "keep-alive", and "upgrade".
121    ]
122][
123    [
124        [@https://tools.ietf.org/html/rfc7230#section-3.3.2 [*`Content-Length`]]
125    ][
126        When present, this field informs the recipient about the exact
127        size in bytes of the body which follows the message header.
128    ]
129][
130    [
131        [@https://tools.ietf.org/html/rfc7230#section-3.3.1 [*`Transfer-Encoding`]]
132    ][
133        This optional field lists the names of the sequence of transfer codings
134        that have been (or will be) applied to the content payload to form
135        the message body.
136
137        Beast understands the "chunked" coding scheme when it is the last
138        (outermost) applied coding. The library will automatically apply
139        chunked encoding when the content length is not known ahead of time
140        during serialization, and the library will automatically remove chunked
141        encoding from parsed messages when present.
142    ]
143][
144    [
145        [@https://tools.ietf.org/html/rfc7230#section-6.7 [*`Upgrade`]]
146    ][
147        The Upgrade header field provides a mechanism to transition from
148        HTTP/1.1 to another protocol on the same connection. For example, it
149        is the mechanism used by WebSocket's initial HTTP handshake to
150        establish a WebSocket connection.
151    ]
152]
153]
154
155[endsect]
156