forked from boostorg/beast
ff15cf8688
New buffer sequence classes are provided to allow full
control over the serialization of chunk-encoded message
payloads:
* chunk_header
A ConstBufferSequence representing the chunk header.
It includes a hexadecimal-encoded size, an optional
set of chunk extensions, and the trailing CRLF
required to denote the end of the chunk header.
This allows the caller to manually serialize the chunk
body in one or more calls to a stream output function.
The caller must also output an object of type `chunk_crlf`
to the stream to indicate the end of the chunk body.
* chunk_crlf
A small ConstBufferSequence that simply represents
the two character sequence "\r\n" (CRLF). This is needed
for the case where the caller wants to output a chunk
body as a series of buffers (i.e. "chunking a chunk").
* chunk_body
A ConstBufferSequence representing a complete chunk.
This includes the size, an optional set of chunk extensions,
a caller provided buffer containing the body, and the
required CRLF that follows.
* chunk_final
A ConstBufferSequence representing a final chunk. It
includes an optional set of caller-provided field trailers
* chunk_extensions
A container for building a set of chunk extensions to use
during serialization. The use of the container is optional,
callers may provide their own buffer containing a correctly
formatted set of chunk extensions, or they may use their
own convenience container which meets the requirements.
The basic_fields container is modified to allow construction
outside the context of a message. The container can be used
to provide trailers to `chunk_final`.
Actions Required:
* Remove references to ChunkDecorators. Use the new chunk-encoding
buffer sequences to manually produce a chunked payload body in
the case where control over the chunk-extensions and/or trailers
is required.
144 lines
5.0 KiB
Plaintext
144 lines
5.0 KiB
Plaintext
[/
|
|
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 More 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.beast__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:
|
|
|
|
[example_http_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:
|
|
|
|
[example_http_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:
|
|
|
|
[example_http_receive_expect_100_continue]
|
|
|
|
[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.
|
|
|
|
[example_http_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.
|
|
|
|
[example_http_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:
|
|
|
|
[example_http_relay]
|
|
|
|
[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:
|
|
|
|
[example_http_send_cgi_response]
|
|
|
|
[endsect]
|
|
|
|
|
|
|
|
[endsect]
|