123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235 |
- [/
- 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]
|