123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155 |
- [/
- Copyright (c) 2016-2019 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)
- Official repository: https://github.com/boostorg/beast
- ]
- [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. When a client and
- server have established a connection, the client sends a series of requests
- while the server sends back at least one response for each received request
- in the order those requests were received.
- A request or response is an
- [@https://tools.ietf.org/html/rfc7230#section-3 HTTP message]
- (referred to hereafter as "message") having two parts:
- a header with structured metadata and an optional variable-length body
- holding 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 contents of 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.
- [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 Body]
- Messages may optionally carry a body. The size of the message body
- is determined by the semantics of the message and the special fields
- Content-Length and Transfer-Encoding.
- [@https://tools.ietf.org/html/rfc7230#section-3.3 rfc7230 section 3.3]
- provides a comprehensive description for how the body length is
- determined.
- [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 parsed in a message and also setting
- the fields if the caller requests it.
- [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 remove chunked
- encoding from parsed messages when present.
- ]
- ][
- [
- [@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]
|