[/
    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 HTTP Examples]

[section Expect 100-continue (Client)]

The Expect field with the value "100-continue" in a request is special. It
indicates that the after sending the message header, a client desires an
immediate informational response before sending the the message body, which
presumably may be expensive to compute or large. This behavior is described in
[@https://tools.ietf.org/html/rfc7231#section-5.1.1 rfc7231 section 5.1.1].
Invoking the 100-continue behavior is implemented easily in a client by
constructing a __serializer__ to send the header first, then receiving
the server response, and finally conditionally send the body using the same
serializer instance. A synchronous, simplified version (no timeout) of
this client action looks like this:

[http_sample_send_expect_100_continue]

[endsect]



[section Expect 100-continue (Server)]

The Expect field with the value "100-continue" in a request is special. It
indicates that the after sending the message header, a client desires an
immediate informational response before sending the the message body, which
presumably may be expensive to compute or large. This behavior is described in
[@https://tools.ietf.org/html/rfc7231#section-5.1.1 rfc7231 section 5.1.1].
Handling the Expect field can be implemented easily in a server by constructing
a __parser__ to read the header first, then send an informational HTTP
response, and finally read the body using the same parser instance. A
synchronous version of this server action looks like this:

[http_sample_receive_expect_100_continue]

[endsect]



[section Send Child Process Output]

Sometimes it is necessary  to send a message whose body is not conveniently
described by a single container. For example, when implementing an HTTP relay
function a robust implementation needs to present body buffers individually
as they become available from the downstream host. These buffers should be
fixed in size, otherwise creating the unnecessary and inefficient burden of
reading the complete message body before forwarding it to the upstream host.

To enable these use-cases, the body type __buffer_body__ is provided. This
body uses a caller-provided pointer and size instead of an owned container.
To use this body, instantiate an instance of the serializer and fill in
the pointer and size fields before calling a stream write function.

This example reads from a child process and sends the output back in an
HTTP response. The output of the process is sent as it becomes available:

[http_sample_send_cgi_response]

[endsect]



[section HEAD request (Client)]

The
[@https://tools.ietf.org/html/rfc7231#section-4.3.2 HEAD request]
method indicates to the server that the client wishes to receive the
entire header that would be delivered if the method was GET, except
that the body is omitted.

[http_sample_do_head_request]

[endsect]



[section HEAD response (Server)]

When a server receives a
[@https://tools.ietf.org/html/rfc7231#section-4.3.2 HEAD request],
the response should contain the entire header that would be delivered
if the method was GET, except that the body is omitted.

[http_sample_do_head_response]

[endsect]



[section Write To std::ostream]

The standard library provides the type `std::ostream` for performing high
level write operations on character streams. The variable `std::cout` is
based on this output stream. In this example, we build a stream operation
which serializes an HTTP message to a `std::ostream`:

[http_sample_write_ostream]

[tip
    Serializing to a `std::ostream` could be implemented using an alternate
    strategy: adapt the `std::ostream` interface to a __SyncWriteStream__.
    This lets all the library's existing algorithms work on `std::ostream`.
    We leave this as an exercise for the reader.
]

[endsect]



[section Read From std::istream]

The standard library provides the type `std::istream` for performing high
level read operations on character streams. The variable `std::cin` is based
on this input stream. In this example, we build a stream operation which
parses an HTTP message from a `std::istream`:

[http_sample_read_istream]

[tip
    Parsing from a `std::istream` could be implemented using an alternate
    strategy: adapt the `std::istream` interface to a __SyncReadStream__.
    This lets all the library's existing algorithms work on `std::istream`.
    We leave this as an exercise for the reader.
]

[endsect]



[section HTTP Relay]

An HTTP proxy acts as a relay between client and server. The proxy reads a
request from the client and sends it to the server, possibly adjusting some
of the headers and representation of the body along the way. Then, the
proxy reads a response from the server and sends it back to the client,
also with the possibility of changing the headers and body representation.

The example that follows implements a synchronous HTTP relay. It uses a
fixed size buffer, to avoid reading in the entire body so that the upstream
connection sees a header without unnecessary latency. This example brings
together all of the concepts discussed so far, it uses both a __serializer__
and a __parser__ to achieve its goal:

[http_sample_relay]

[endsect]



[endsect]