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:using_http HTTP] 11 12[warning 13 Higher level functions such as Basic 14 Authentication, mime/multipart encoding, cookies, automatic handling 15 of redirects, gzipped transfer encodings, caching, or proxying (to name 16 a few) are not directly provided, but nothing stops users from creating 17 these features using Beast's HTTP message types. 18] 19 20This library offers programmers simple and performant models of HTTP messages 21and their associated operations including synchronous, asynchronous, and 22buffer-oriented parsing and serialization of messages in the HTTP/1 wire 23format using __Asio__. Specifically, the library provides: 24 25[variablelist 26[ 27 [Message Containers] 28 [ 29 Complete HTTP messages are modeled using the __message__ class, 30 with possible user customizations. 31 ] 32][ 33 [Stream Reading] 34 [ 35 The functions 36 [link beast.ref.boost__beast__http__read `read`], 37 [link beast.ref.boost__beast__http__read_header `read_header`], 38 [link beast.ref.boost__beast__http__read_some `read_some`], 39 [link beast.ref.boost__beast__http__async_read `async_read`], 40 [link beast.ref.boost__beast__http__async_read_header `async_read_header`], and 41 [link beast.ref.boost__beast__http__async_read_some `async_read_some`] 42 read HTTP/1 message data from a 43 [link beast.concepts.streams stream]. 44] 45][ 46 [Stream Writing] 47 [ 48 The functions 49 [link beast.ref.boost__beast__http__write `write`], 50 [link beast.ref.boost__beast__http__write_header `write_header`], 51 [link beast.ref.boost__beast__http__write_some `write_some`], 52 [link beast.ref.boost__beast__http__async_write `async_write`], 53 [link beast.ref.boost__beast__http__async_write_header `async_write_header`], and 54 [link beast.ref.boost__beast__http__async_write_some `async_write_some`] 55 write HTTP/1 message data to a 56 [link beast.concepts.streams stream]. 57 ] 58][ 59 [Serialization] 60 [ 61 The __serializer__ produces a series of octet buffers 62 conforming to the __rfc7230__ wire representation of 63 a __message__. 64 ] 65][ 66 [Parsing] 67 [ 68 The __parser__ attempts to convert a series of octet 69 buffers into a __message__. 70 ] 71] 72] 73 74Interfaces for operating on HTTP messages are structured into several 75layers. The highest level provides ease of use, while lower levels provide 76progressively more control, options, and flexibility. At the lowest level 77customization points are provided, where user defined types can replace 78parts of the implementation. The layers are arranged thusly: 79 80[table 81[[Level][Read/Write What][Description]] 82[ 83 [[*6]] 84 [ 85 __message__ 86 ][ 87 At the highest level, these free functions send or receive 88 a complete HTTP message in one call. They are designed for 89 ease of use: 90 [link beast.ref.boost__beast__http__read.overload4 `read`], 91 [link beast.ref.boost__beast__http__write.overload4 `write`], 92 [link beast.ref.boost__beast__http__async_read.overload2 `async_read`], and 93 [link beast.ref.boost__beast__http__async_write.overload2 `async_write`]. 94 ] 95][ 96 [[*5]] 97 [ 98 __parser__, __serializer__ 99 ][ 100 For more control, callers may take responsibility for managing the 101 required __parser__ or __serializer__ transient state objects. 102 This allows additional configuration such as limiting the number 103 of bytes for message components during parsing, or regulating the 104 size of buffers emitted during output. These functions send or 105 receive complete messages using a serializer or parser: 106 [link beast.ref.boost__beast__http__read.overload2 `read`], 107 [link beast.ref.boost__beast__http__write.overload2 `write`], 108 [link beast.ref.boost__beast__http__async_read.overload1 `async_read`], and 109 [link beast.ref.boost__beast__http__async_write.overload1 `async_write`]. 110 111 ] 112][ 113 [[*4]] 114 [ 115 __header__ 116 ][ 117 Sometimes it is necessary to first send or receive the HTTP 118 header. For example, to read the header and take action before 119 continuing to read the body. These functions use a __parser__ 120 or __serializer__ to read or write the header: 121 [link beast.ref.boost__beast__http__read_header.overload2 `read_header`], 122 [link beast.ref.boost__beast__http__write_header.overload2 `write_header`], 123 [link beast.ref.boost__beast__http__async_read_header `async_read_header`], and 124 [link beast.ref.boost__beast__http__async_write_header `async_write_header`]. 125 ] 126][ 127 [[*3]] 128 [ 129 partial __message__ 130 ][ 131 All of the stream operations at higher levels thus far have operated 132 on a complete header or message. At this level it is possible to 133 send and receive messages incrementally. This allows resource 134 constrained implementations to perform work bounded on storage, 135 or allows better control when setting timeouts for example. 136 These functions read or write bounded amounts of data and return 137 the number of bytes transacted: 138 [link beast.ref.boost__beast__http__read_some.overload2 `read_some`], 139 [link beast.ref.boost__beast__http__write_some.overload2 `write_some`], 140 [link beast.ref.boost__beast__http__async_read_some `async_read_some`], and 141 [link beast.ref.boost__beast__http__async_write_some `async_write_some`]. 142 ] 143][ 144 [[*2]] 145 [ 146 [@https://tools.ietf.org/html/rfc7230#section-4.1 ['chunked-body]] 147 ][ 148 Until now parse and serialize operations apply or remove the chunked 149 transfer coding as needed for message payloads whose size is not known 150 ahead of time. For some domain specific niches, it is necessary 151 to assume direct control over incoming or outgoing chunks in a chunk 152 encoded message payload. 153 For parsing this is achieved by setting hooks using the functions 154 [link beast.ref.boost__beast__http__parser.on_chunk_header `on_chunk_header`] and/or 155 [link beast.ref.boost__beast__http__parser.on_chunk_body `on_chunk_body`]. 156 For serializing callers may first emit the header, and then use 157 these buffer sequence adapters to control the contents of each chunk 158 including 159 [@https://tools.ietf.org/html/rfc7230#section-4.1.1 ['chunk extensions]] 160 and the 161 [@https://tools.ietf.org/html/rfc7230#section-4.1.2 ['trailer-part]]: 162 [link beast.ref.boost__beast__http__chunk_body `chunk_body`], 163 [link beast.ref.boost__beast__http__chunk_crlf `chunk_crlf`], 164 [link beast.ref.boost__beast__http__chunk_header `chunk_header`], and 165 [link beast.ref.boost__beast__http__chunk_last `chunk_last`]. 166 ] 167][ 168 [[*1]] 169 [ 170 buffers 171 ][ 172 For ultimate control, the use of library stream algorithms may 173 be bypassed entirely and instead work directly with buffers by 174 calling members of __parser__ or __serializer__. 175 ] 176][ 177 [[*0]] 178 [ 179 ['user-defined] 180 ][ 181 In addition to the typical customization points of __Stream__ 182 and __DynamicBuffer__, user-defined types may replace parts of 183 the library implementation at the lowest level. The customization 184 points include __Fields__ for creating a container to store HTTP 185 fields, __Body__ for defining containers and algorithms used for 186 HTTP message payloads, and user-defined subclasses of 187 __basic_parser__ for implementing custom message representation 188 strategies. 189 ] 190]] 191 192[note 193 This documentation assumes some familiarity with __Asio__ and 194 the HTTP protocol specification described in __rfc7230__. Sample 195 code and identifiers mentioned in this section is written as if 196 these declarations are in effect: 197 198 [http_snippet_1] 199] 200 201[include 01_primer.qbk] 202[include 02_message.qbk] 203[include 03_streams.qbk] 204[include 04_serializer_streams.qbk] 205[include 05_parser_streams.qbk] 206[include 06_serializer_buffers.qbk] 207[include 07_parser_buffers.qbk] 208[include 08_chunked_encoding.qbk] 209[include 09_custom_body.qbk] 210[include 10_custom_parsers.qbk] 211 212[endsect] 213