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:more_examples HTTP Examples] 11 12These examples in this section are working functions that may be found 13in the examples directory. They demonstrate the usage of the library for 14a variety of scenarios. 15 16 17 18[section:change_body_type Change Body Type __example__] 19 20Sophisticated servers may wish to defer the choice of the Body template type 21until after the header is available. Then, a body type may be chosen 22depending on the header contents. For example, depending on the verb, 23target path, or target query parameters. To accomplish this, a parser 24is declared to read in the header only, using a trivial body type such as 25[link beast.ref.boost__beast__http__empty_body `empty_body`]. Then, a new parser is constructed 26from this existing parser where the body type is conditionally determined 27by information from the header or elsewhere. 28 29This example illustrates how a server may make the commitment of a body 30type depending on the method verb: 31 32[example_http_defer_body] 33 34[endsect] 35 36 37 38[section:expect_100_continue_client Expect 100-continue (Client) __example__] 39 40The Expect field with the value "100-continue" in a request is special. It 41indicates that the after sending the message header, a client desires an 42immediate informational response before sending the message body, which 43presumably may be expensive to compute or large. This behavior is described in 44[@https://tools.ietf.org/html/rfc7231#section-5.1.1 rfc7231 section 5.1.1]. 45Invoking the 100-continue behavior is implemented easily in a client by 46constructing a __serializer__ to send the header first, then receiving 47the server response, and finally conditionally send the body using the same 48serializer instance. A synchronous, simplified version (no timeout) of 49this client action looks like this: 50 51[example_http_send_expect_100_continue] 52 53[endsect] 54 55 56 57[section:expect_100_continue_server Expect 100-continue (Server) __example__] 58 59The Expect field with the value "100-continue" in a request is special. It 60indicates that the after sending the message header, a client desires an 61immediate informational response before sending the message body, which 62presumably may be expensive to compute or large. This behavior is described in 63[@https://tools.ietf.org/html/rfc7231#section-5.1.1 rfc7231 section 5.1.1]. 64Handling the Expect field can be implemented easily in a server by constructing 65a __parser__ to read the header first, then send an informational HTTP 66response, and finally read the body using the same parser instance. A 67synchronous version of this server action looks like this: 68 69[example_http_receive_expect_100_continue] 70 71[endsect] 72 73 74 75[section:head_request_client HEAD request (Client) __example__] 76 77The 78[@https://tools.ietf.org/html/rfc7231#section-4.3.2 HEAD request] 79method indicates to the server that the client wishes to receive the 80entire header that would be delivered if the method was GET, except 81that the body is omitted. When a client wishes to receive the response 82to a HEAD request, it is necessary to inform the parser not to expect 83a body. This is done by calling 84[link beast.ref.boost__beast__http__basic_parser.skip `basic_parser::skip`] 85with the value `true`, as shown in this example: 86 87[example_http_do_head_request] 88 89[endsect] 90 91 92 93[section:head_response_server HEAD response (Server) __example__] 94 95When a server receives a 96[@https://tools.ietf.org/html/rfc7231#section-4.3.2 HEAD request], 97the response should contain the entire header that would be delivered 98if the method was GET, except that the body is omitted. 99 100[example_http_do_head_response] 101 102[endsect] 103 104 105 106[section:http_relay HTTP Relay __example__] 107 108An HTTP proxy acts as a relay between client and server. The proxy reads a 109request from the client and sends it to the server, possibly adjusting some 110of the headers and representation of the body along the way. Then, the 111proxy reads a response from the server and sends it back to the client, 112also with the possibility of changing the headers and body representation. 113 114The example that follows implements a synchronous HTTP relay. It uses a 115fixed size buffer, to avoid reading in the entire body so that the upstream 116connection sees a header without unnecessary latency. This example brings 117together all of the concepts discussed so far, it uses both a __serializer__ 118and a __parser__ to achieve its goal: 119 120[example_http_relay] 121 122[endsect] 123 124 125 126[section:send_child_process_output Send Child Process Output __example__] 127 128Sometimes it is necessary to send a message whose body is not conveniently 129described by a single container. For example, when implementing an HTTP relay 130function a robust implementation needs to present body buffers individually 131as they become available from the downstream host. These buffers should be 132fixed in size, otherwise creating the unnecessary and inefficient burden of 133reading the complete message body before forwarding it to the upstream host. 134 135To enable these use-cases, the body type __buffer_body__ is provided. This 136body uses a caller-provided pointer and size instead of an owned container. 137To use this body, instantiate an instance of the serializer and fill in 138the pointer and size fields before calling a stream write function. 139 140This example reads from a child process and sends the output back in an 141HTTP response. The output of the process is sent as it becomes available: 142 143[example_http_send_cgi_response] 144 145[endsect] 146 147 148 149[endsect] 150