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 Message Containers] 11 12Beast provides a single class template __message__ and some aliases which 13model HTTP/1 and 14[@https://tools.ietf.org/html/rfc7540 HTTP/2] 15messages: 16 17[table Message 18[[Name][Description]] 19[[ 20 __message__ 21][ 22 ``` 23 /// An HTTP message 24 template< 25 bool isRequest, // `true` for requests, `false` for responses 26 class Body, // Controls the container and algorithms used for the body 27 class Fields = fields> // The type of container to store the fields 28 class message; 29 ``` 30]] 31[[ 32 [link beast.ref.boost__beast__http__request `request`] 33][ 34 ``` 35 /// A typical HTTP request 36 template<class Body, class Fields = fields> 37 using request = message<true, Body, Fields>; 38 ``` 39]] 40[[ 41 [link beast.ref.boost__beast__http__response `response`] 42][ 43 ``` 44 /// A typical HTTP response 45 template<class Body, class Fields = fields> 46 using response = message<false, Body, Fields>; 47 ``` 48]] 49] 50 51The container offers value semantics including move and copy if supported 52by __Body__ and __Fields__. User defined template function parameters can 53accept any message, or can use partial specialization to accept just 54requests or responses. The default __fields__ is a provided associative 55container using the standard allocator and supporting modification and 56inspection of fields. As per __rfc7230__, a non-case-sensitive comparison 57is used for field names. User defined types for fields are possible. 58The `Body` type determines the type of the container used to represent the 59body as well as the algorithms for transferring buffers to and from the 60container. The library comes with a collection of common body types. As 61with fields, user defined body types are possible. 62 63Sometimes it is desired to only work with a header. Beast provides a single 64class template __header__ and some aliases to model HTTP/1 and HTTP/2 headers: 65 66[table Header 67[[Name][Description]] 68[[ 69 __header__ 70][ 71 ``` 72 /// An HTTP header 73 template< 74 bool isRequest, // `true` for requests, `false` for responses 75 class Fields = fields> // The type of container to store the fields 76 class header; 77 ``` 78]] 79[[ 80 [link beast.ref.boost__beast__http__request_header `request_header`] 81][ 82 ``` 83 /// A typical HTTP request header 84 template<class Fields> 85 using request_header = header<true, Fields>; 86 ``` 87]] 88[[ 89 [link beast.ref.boost__beast__http__response_header `response_header`] 90][ 91 ``` 92 /// A typical HTTP response header 93 template<class Fields> 94 using response_header = header<false, Fields>; 95 ``` 96]] 97] 98 99Requests and responses share the version, fields, and body but have 100a few members unique to the type. This is implemented by declaring the 101header classes as partial specializations of `isRequest`. __message__ 102is derived from __header__; a message may be passed as an argument to 103a function taking a suitably typed header as a parameter. Additionally, 104`header` is publicly derived from `Fields`; a message inherits all the 105member functions of `Fields`. This diagram shows the inheritance 106relationship between header and message, along with some of the 107notable differences in members in each partial specialization: 108 109[$beast/images/message.png [width 730px] [height 459px]] 110 111[heading:body Body Types] 112 113Beast defines the __Body__ concept, which determines both the type of 114the [link beast.ref.boost__beast__http__message.body `message::body`] member 115(as seen in the diagram above) and may also include algorithms for 116transferring buffers in and out. These algorithms are used during 117parsing and serialization. Users may define their own body types which 118meet the requirements, or use the ones that come with the library: 119 120[table 121[[Name][Description]] 122[[ 123 [link beast.ref.boost__beast__http__buffer_body `buffer_body`] 124][ 125 A body whose 126 [link beast.ref.boost__beast__http__buffer_body__value_type `value_type`] 127 holds a raw pointer and size to a caller-provided buffer. 128 This allows for serialization of body data coming from 129 external sources, and incremental parsing of message body 130 content using a fixed size buffer. 131]] 132[[ 133 [link beast.ref.boost__beast__http__dynamic_body `dynamic_body`] 134 135 [link beast.ref.boost__beast__http__basic_dynamic_body `basic_dynamic_body`] 136][ 137 A body whose `value_type` is a __DynamicBuffer__. It inherits 138 the insertion complexity of the underlying choice of dynamic buffer. 139 Messages with this body type may be serialized and parsed. 140]] 141[[ 142 [link beast.ref.boost__beast__http__empty_body `empty_body`] 143][ 144 A special body with an empty `value_type` indicating that the 145 message has no body. Messages with this body may be serialized 146 and parsed; however, body octets received while parsing a message 147 with this body will generate a unique error. 148]] 149[[ 150 [link beast.ref.boost__beast__http__file_body `file_body`] 151 152 [link beast.ref.boost__beast__http__basic_file_body `basic_file_body`] 153][ 154 This body is represented by a file opened for either reading or 155 writing. Messages with this body may be serialized and parsed. 156 HTTP algorithms will use the open file for reading and writing, 157 for streaming and incremental sends and receives. 158]] 159[[ 160 [link beast.ref.boost__beast__http__span_body `span_body`] 161][ 162 A body whose `value_type` is a 163 [link beast.ref.boost__beast__span `span`], 164 a non-owning reference to a single linear buffer of bytes. 165 Messages with this body type may be serialized and parsed. 166]] 167[[ 168 [link beast.ref.boost__beast__http__string_body `string_body`] 169 170 [link beast.ref.boost__beast__http__basic_string_body `basic_string_body`] 171][ 172 A body whose `value_type` is `std::basic_string` or `std::string`. 173 Insertion complexity is amortized constant time, while capacity 174 grows geometrically. Messages with this body type may be serialized 175 and parsed. This is the type of body used in the examples. 176]] 177[[ 178 [link beast.ref.boost__beast__http__vector_body `vector_body`] 179][ 180 A body whose `value_type` is `std::vector`. Insertion complexity 181 is amortized constant time, while capacity grows geometrically. 182 Messages with this body type may be serialized and parsed. 183]] 184] 185 186[heading Usage] 187 188These examples show how to create and fill in request and response 189objects: Here we build an 190[@https://tools.ietf.org/html/rfc7231#section-4.3.1 HTTP GET] 191request with an empty message body: 192 193[table Create Request 194[[Statements] [Serialized Result]] 195[[ 196 [http_snippet_2] 197][ 198``` 199 GET /index.htm HTTP/1.1\r\n 200 Accept: text/html\r\n 201 User-Agent: Beast\r\n 202 \r\n 203``` 204]] 205] 206 207In this code we create an HTTP response with a status code indicating success. 208This message has a body with a non-zero length. The function 209[link beast.ref.boost__beast__http__message.prepare_payload `message::prepare_payload`] 210automatically sets the Content-Length or Transfer-Encoding field 211depending on the content and type of the `body` member. Use of this function 212is optional; these fields may also be set explicitly. 213 214[table Create Response 215[[Statements] [Serialized Result]] 216[[ 217 [http_snippet_3] 218][ 219``` 220 HTTP/1.1 200 OK\r\n 221 Server: Beast\r\n 222 Content-Length: 13\r\n 223 \r\n 224 Hello, world! 225``` 226]] 227] 228 229The implementation will automatically fill in the obsolete 230[@https://tools.ietf.org/html/rfc7230#section-3.1.2 reason-phrase] 231from the status code when serializing a message. Or it may 232be set directly using 233[link beast.ref.boost__beast__http__header.reason.overload2 `header::reason`]. 234 235[endsect] 236
