forked from boostorg/beast
Documentation work
This commit is contained in:
1 parent
d4ec693a61
commit
9d5d4d56a4
46 files changed
+1264
-153
No files matched your search
@@ -0,0 +1,187 @@
|
||||
[/
|
||||
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]
|
||||
|
||||
These examples in this section are working functions that may be found
|
||||
in the examples directory. They demonstrate the usage of the library for
|
||||
a variety of scenarios.
|
||||
|
||||
|
||||
|
||||
[section Change Body Type]
|
||||
|
||||
Sophisticated servers may wish to defer the choice of the Body template type
|
||||
until after the header is available. Then, a body type may be chosen
|
||||
depending on the header contents. For example, depending on the verb,
|
||||
target path, or target query parameters. To accomplish this, a parser
|
||||
is declared to read in the header only, using a trivial body type such as
|
||||
[link beast.ref.http__empty_body `empty_body`]. Then, a new parser is constructed
|
||||
from this existing parser where the body type is conditionally determined
|
||||
by information from the header or elsewhere.
|
||||
|
||||
This example illustrates how a server may make the commitment of a body
|
||||
type depending on the method verb:
|
||||
|
||||
[http_sample_defer_body]
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
|
||||
[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]
|
||||
|
||||
|
||||
|
||||
[include 6_1_file_body.qbk]
|
||||
|
||||
|
||||
|
||||
[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 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]
|
||||
|
||||
|
||||
|
||||
[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 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 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]
|
||||
|
||||
|
||||
|
||||
[endsect]
|
||||
Reference in new issue
Block a user