forked from boostorg/beast
Documentation work
This commit is contained in:
1 parent
d4ec693a61
commit
9d5d4d56a4
46 files changed
+1264
-153
No files matched your search
@@ -0,0 +1,161 @@
|
||||
[/
|
||||
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:message Message Containers]
|
||||
|
||||
Beast provides a single class template __message__ which models
|
||||
HTTP/1 and
|
||||
[@https://tools.ietf.org/html/rfc7540 HTTP/2]
|
||||
messages:
|
||||
```
|
||||
/// 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;
|
||||
```
|
||||
|
||||
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
|
||||
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__ to model HTTP/1 and HTTP/2 headers:
|
||||
```
|
||||
/// 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;
|
||||
```
|
||||
|
||||
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`. Furthermore,
|
||||
__message__ is derived from __header__; a message may be passed as an
|
||||
argument to a function taking a suitably typed header as a parameter.
|
||||
This diagram shows the inheritance relationship between header and message,
|
||||
along with the fields from the different partial specializations for each
|
||||
possible value of `isRequest`:
|
||||
|
||||
[$images/message.png [width 730px] [height 410px]]
|
||||
|
||||
The template type aliases
|
||||
[link beast.ref.http__request `request`] and
|
||||
[link beast.ref.http__response `response`]
|
||||
are provided for notational convenience. They also come with the default
|
||||
__fields__, a common choice.
|
||||
|
||||
```
|
||||
/// A typical HTTP request
|
||||
template<class Body, class Fields = fields>
|
||||
using request = message<true, Body, Fields>;
|
||||
|
||||
/// A typical HTTP response
|
||||
template<class Body, class Fields = fields>
|
||||
using response = message<false, Body, Fields>;
|
||||
```
|
||||
|
||||
[heading:body Body Types]
|
||||
|
||||
Beast defines the __Body__ concept, which determines both the type of
|
||||
the `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. These body types are available
|
||||
within the library, and users may define their own body types which meet
|
||||
the __Body__ requirements:
|
||||
|
||||
[table
|
||||
[[Name][Description]]
|
||||
[[
|
||||
[link beast.ref.http__buffer_body `buffer_body`]
|
||||
][
|
||||
A body whose `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.http__dynamic_body `dynamic_body`]
|
||||
|
||||
[link beast.ref.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.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.http__string_body `string_body`]
|
||||
][
|
||||
A body whose `value_type` is `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.
|
||||
]]
|
||||
]
|
||||
|
||||
[heading Usage]
|
||||
|
||||
The code examples below show how to create and fill in request and response
|
||||
objects: Here is simple example of building an
|
||||
[@https://tools.ietf.org/html/rfc7231#section-4.3.1 HTTP GET]
|
||||
request.
|
||||
|
||||
[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
|
||||
```
|
||||
]]
|
||||
]
|
||||
|
||||
Here we create an HTTP response indicating success. Note that this
|
||||
message has a body. The function
|
||||
[link beast.ref.http__message.prepare prepare]
|
||||
automatically sets the Content-Length or Transfer-Encoding field
|
||||
depending on the content and type of the `body` member. The use
|
||||
of prepare is optional; these fields may also be set.
|
||||
|
||||
[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!
|
||||
```
|
||||
]]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
Reference in new issue
Block a user