236 lines
7.7 KiB
Plaintext
236 lines
7.7 KiB
Plaintext
[/
|
|
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 Message Containers]
|
|
|
|
Beast provides a single class template __message__ and some aliases which
|
|
model HTTP/1 and
|
|
[@https://tools.ietf.org/html/rfc7540 HTTP/2]
|
|
messages:
|
|
|
|
[table Message
|
|
[[Name][Description]]
|
|
[[
|
|
__message__
|
|
][
|
|
```
|
|
/// An HTTP message
|
|
template<
|
|
bool isRequest, // `true` for requests, `false` for responses
|
|
class Body, // Controls the container and algorithms used for the body
|
|
class Fields = fields> // The type of container to store the fields
|
|
class message;
|
|
```
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__request `request`]
|
|
][
|
|
```
|
|
/// A typical HTTP request
|
|
template<class Body, class Fields = fields>
|
|
using request = message<true, Body, Fields>;
|
|
```
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__response `response`]
|
|
][
|
|
```
|
|
/// A typical HTTP response
|
|
template<class Body, class Fields = fields>
|
|
using response = message<false, Body, Fields>;
|
|
```
|
|
]]
|
|
]
|
|
|
|
The container offers value semantics including move and copy if supported
|
|
by __Body__ and __Fields__. User defined template function parameters can
|
|
accept any message, or can use partial specialization to accept just
|
|
requests or responses. The default __fields__ is a provided associative
|
|
container using the standard allocator and supporting modification and
|
|
inspection of fields. As per __rfc7230__, a non-case-sensitive comparison
|
|
is used for field names. User defined types for fields are possible.
|
|
The `Body` type determines the type of the container used to represent the
|
|
body as well as the algorithms for transferring buffers to and from the
|
|
container. The library comes with a collection of common body types. As
|
|
with fields, user defined body types are possible.
|
|
|
|
Sometimes it is desired to only work with a header. Beast provides a single
|
|
class template __header__ and some aliases to model HTTP/1 and HTTP/2 headers:
|
|
|
|
[table Header
|
|
[[Name][Description]]
|
|
[[
|
|
__header__
|
|
][
|
|
```
|
|
/// An HTTP header
|
|
template<
|
|
bool isRequest, // `true` for requests, `false` for responses
|
|
class Fields = fields> // The type of container to store the fields
|
|
class header;
|
|
```
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__request_header `request_header`]
|
|
][
|
|
```
|
|
/// A typical HTTP request header
|
|
template<class Fields>
|
|
using request_header = header<true, Fields>;
|
|
```
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__response_header `response_header`]
|
|
][
|
|
```
|
|
/// A typical HTTP response header
|
|
template<class Fields>
|
|
using response_header = header<false, Fields>;
|
|
```
|
|
]]
|
|
]
|
|
|
|
Requests and responses share the version, fields, and body but have
|
|
a few members unique to the type. This is implemented by declaring the
|
|
header classes as partial specializations of `isRequest`. __message__
|
|
is derived from __header__; a message may be passed as an argument to
|
|
a function taking a suitably typed header as a parameter. Additionally,
|
|
`header` is publicly derived from `Fields`; a message inherits all the
|
|
member functions of `Fields`. This diagram shows the inheritance
|
|
relationship between header and message, along with some of the
|
|
notable differences in members in each partial specialization:
|
|
|
|
[$beast/images/message.png [width 730px] [height 459px]]
|
|
|
|
[heading:body Body Types]
|
|
|
|
Beast defines the __Body__ concept, which determines both the type of
|
|
the [link beast.ref.boost__beast__http__message.body `message::body`] member
|
|
(as seen in the diagram above) and may also include algorithms for
|
|
transferring buffers in and out. These algorithms are used during
|
|
parsing and serialization. Users may define their own body types which
|
|
meet the requirements, or use the ones that come with the library:
|
|
|
|
[table
|
|
[[Name][Description]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__buffer_body `buffer_body`]
|
|
][
|
|
A body whose
|
|
[link beast.ref.boost__beast__http__buffer_body__value_type `value_type`]
|
|
holds a raw pointer and size to a caller-provided buffer.
|
|
This allows for serialization of body data coming from
|
|
external sources, and incremental parsing of message body
|
|
content using a fixed size buffer.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__dynamic_body `dynamic_body`]
|
|
|
|
[link beast.ref.boost__beast__http__basic_dynamic_body `basic_dynamic_body`]
|
|
][
|
|
A body whose `value_type` is a __DynamicBuffer__. It inherits
|
|
the insertion complexity of the underlying choice of dynamic buffer.
|
|
Messages with this body type may be serialized and parsed.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__empty_body `empty_body`]
|
|
][
|
|
A special body with an empty `value_type` indicating that the
|
|
message has no body. Messages with this body may be serialized
|
|
and parsed; however, body octets received while parsing a message
|
|
with this body will generate a unique error.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__file_body `file_body`]
|
|
|
|
[link beast.ref.boost__beast__http__basic_file_body `basic_file_body`]
|
|
][
|
|
This body is represented by a file opened for either reading or
|
|
writing. Messages with this body may be serialized and parsed.
|
|
HTTP algorithms will use the open file for reading and writing,
|
|
for streaming and incremental sends and receives.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__span_body `span_body`]
|
|
][
|
|
A body whose `value_type` is a
|
|
[link beast.ref.boost__beast__span `span`],
|
|
a non-owning reference to a single linear buffer of bytes.
|
|
Messages with this body type may be serialized and parsed.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__string_body `string_body`]
|
|
|
|
[link beast.ref.boost__beast__http__basic_string_body `basic_string_body`]
|
|
][
|
|
A body whose `value_type` is `std::basic_string` or `std::string`.
|
|
Insertion complexity is amortized constant time, while capacity
|
|
grows geometrically. Messages with this body type may be serialized
|
|
and parsed. This is the type of body used in the examples.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__vector_body `vector_body`]
|
|
][
|
|
A body whose `value_type` is `std::vector`. Insertion complexity
|
|
is amortized constant time, while capacity grows geometrically.
|
|
Messages with this body type may be serialized and parsed.
|
|
]]
|
|
]
|
|
|
|
[heading Usage]
|
|
|
|
These examples show how to create and fill in request and response
|
|
objects: Here we build an
|
|
[@https://tools.ietf.org/html/rfc7231#section-4.3.1 HTTP GET]
|
|
request with an empty message body:
|
|
|
|
[table Create Request
|
|
[[Statements] [Serialized Result]]
|
|
[[
|
|
[http_snippet_2]
|
|
][
|
|
```
|
|
GET /index.htm HTTP/1.1\r\n
|
|
Accept: text/html\r\n
|
|
User-Agent: Beast\r\n
|
|
\r\n
|
|
```
|
|
]]
|
|
]
|
|
|
|
In this code we create an HTTP response with a status code indicating success.
|
|
This message has a body with a non-zero length. The function
|
|
[link beast.ref.boost__beast__http__message.prepare_payload `message::prepare_payload`]
|
|
automatically sets the Content-Length or Transfer-Encoding field
|
|
depending on the content and type of the `body` member. Use of this function
|
|
is optional; these fields may also be set explicitly.
|
|
|
|
[table Create Response
|
|
[[Statements] [Serialized Result]]
|
|
[[
|
|
[http_snippet_3]
|
|
][
|
|
```
|
|
HTTP/1.1 200 OK\r\n
|
|
Server: Beast\r\n
|
|
Content-Length: 13\r\n
|
|
\r\n
|
|
Hello, world!
|
|
```
|
|
]]
|
|
]
|
|
|
|
The implementation will automatically fill in the obsolete
|
|
[@https://tools.ietf.org/html/rfc7230#section-3.1.2 reason-phrase]
|
|
from the status code when serializing a message. Or it may
|
|
be set directly using
|
|
[link beast.ref.boost__beast__http__header.reason.overload2 `header::reason`].
|
|
|
|
[endsect]
|