feedc0de/boost_beast
1
0 Fork 0
forked from boostorg/beast
Code Pull Requests Activity

Refactor HTTP serialization (API Change):

Browse Source 
A new class `serializer` is introduced to permit incremental
serialization of HTTP messages. Existing free functions are
re-implemented in terms of this new class.

* The BodyReader concept is refined to support a greater variety
of strategies for providing buffers representing the body to
the serialization algorithms.

* Added buffer_body, a new model of Body which allows the caller
to provide a series of owned buffers using their own serialization
loop.

* Added empty_body, a model of Body which is for serialization only,
to represent HTTP messages with no content body.

* Removed overloads of write and async_write which send only
the HTTP header.

* Removed public interfaces for performing low-level chunk encoding.
This commit is contained in:
Vinnie Falco committed 2017-07-20 08:12:17 -07:00
1 parent b9bdb1bbbc
commit 3664329ea7
44 files changed
+2540 -1104
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

include/beast/http/write.hpp
+380 -83
View File
@@ -9,127 +9,424 @@
#define BEAST_HTTP_WRITE_HPP
#include <beast/config.hpp>
#include <beast/core/buffer_cat.hpp>
#include <beast/core/consuming_buffers.hpp>
#include <beast/core/multi_buffer.hpp>
#include <beast/http/message.hpp>
#include <beast/http/detail/chunk_encode.hpp>
#include <beast/core/error.hpp>
#include <beast/core/async_result.hpp>
#include <beast/core/string_view.hpp>
#include <boost/variant.hpp>
#include <limits>
#include <memory>
#include <ostream>
#include <type_traits>
#include <utility>
namespace beast {
namespace http {
/** Write a HTTP/1 header to a stream.
/** A chunk decorator which does nothing.
This function is used to synchronously write a header to
a stream. The call will block until one of the following
conditions is true:
When selected as a chunk decorator, objects of this type
affect the output of messages specifying chunked
transfer encodings as follows:
@li The entire header is written.
@li chunk headers will have empty chunk extensions, and
@li An error occurs.
@li final chunks will have an empty set of trailers.
This operation is implemented in terms of one or more calls
to the stream's `write_some` function.
Regardless of the semantic meaning of the header (for example,
specifying "Content-Length: 0" and "Connection: close"),
this function will not return `boost::asio::error::eof`.
@param stream The stream to which the data is to be written.
The type must support the @b SyncWriteStream concept.
@param msg The header to write.
@throws system_error Thrown on failure.
@see @ref serializer
*/
template<class SyncWriteStream,
bool isRequest, class Fields>
void
write(SyncWriteStream& stream,
header<isRequest, Fields> const& msg);
struct empty_decorator
{
template<class ConstBufferSequence>
string_view
operator()(ConstBufferSequence const&) const
{
return {"\r\n"};
}
/** Write a HTTP/1 header to a stream.
string_view
operator()(boost::asio::null_buffers) const
{
return {};
}
};
This function is used to synchronously write a header to
a stream. The call will block until one of the following
conditions is true:
/** Provides stream-oriented HTTP message serialization functionality.
@li The entire header is written.
Objects of this type may be used to perform synchronous or
asynchronous serialization of an HTTP message on a stream.
Unlike functions such as @ref write or @ref async_write,
the stream operations provided here guarantee that bounded
work will be performed. This is accomplished by making one
or more calls to the underlying stream's `write_some` or
`async_write_some` member functions. In order to fully
serialize the message, multiple calls are required.
@li An error occurs.
The ability to incrementally serialize a message, peforming
bounded work at each iteration is useful in many scenarios,
such as:
This operation is implemented in terms of one or more calls
to the stream's `write_some` function.
@li Setting consistent, per-call timeouts
Regardless of the semantic meaning of the header (for example,
specifying "Content-Length: 0" and "Connection: close"),
this function will not return `boost::asio::error::eof`.
@li Efficiently relaying body content from another stream
@param stream The stream to which the data is to be written.
The type must support the @b SyncWriteStream concept.
@li Performing application-layer flow control
@param msg The header to write.
To use this class, construct an instance with the message
to be sent. To make it easier to declare the type, the
helper function @ref make_write_stream is provided:
@param ec Set to the error, if any occurred.
The implementation will automatically perform chunk encoding
if the contents of the message indicate that chunk encoding
is required. If the semantics of the message indicate that
the connection should be closed after the message is sent,
the error delivered from stream operations will be
`boost::asio::error::eof`.
@code
template<class Stream>
void send(Stream& stream, request<string_body> const& msg)
{
serializer<true, string_body, fields> w{msg};
do
{
w.write_some();
}
while(! w.is_done());
}
@endcode
Upon construction, an optional chunk decorator may be
specified. This decorator is a function object called with
each buffer sequence of the body when the chunked transfer
encoding is indicate in the message header. The decorator
will be called with an empty buffer sequence (actually
the type `boost::asio::null_buffers`) to indicate the
final chunk. The decorator may return a string which forms
the chunk extension for chunks, and the field trailers
for the final chunk.
In C++11 the decorator must be declared as a class or
struct with a templated operator() thusly:
@code
// The implementation guarantees that operator()
// will be called only after the view returned by
// any previous calls to operator() are no longer
// needed. The decorator instance is intended to
// manage the lifetime of the storage for all returned
// views.
//
struct decorator
{
// Returns the chunk-extension for each chunk.
// The buffer returned must include a trailing "\r\n",
// and the leading semicolon (";") if one or more
// chunk extensions are specified.
//
template<class ConstBufferSequence>
string_view
operator()(ConstBufferSequence const&) const;
// Returns a set of field trailers for the final chunk.
// Each field should be formatted according to rfc7230
// including the trailing "\r\n" for each field. If
// no trailers are indicated, an empty string is returned.
//
string_view
operator()(boost::asio::null_buffers) const;
};
@endcode
@par Thread Safety
@e Distinct @e objects: Safe.@n
@e Shared @e objects: Unsafe.
@tparam isRequest `true` if the message is a request.
@tparam Body The body type of the message.
@tparam Fields The type of fields in the message.
@tparam Decorator The type of chunk decorator to use.
@tparam Allocator The type of allocator to use.
@see @ref make_write_stream
*/
template<class SyncWriteStream,
bool isRequest, class Fields>
void
write(SyncWriteStream& stream,
header<isRequest, Fields> const& msg,
error_code& ec);
template<
bool isRequest, class Body, class Fields,
class Decorator = empty_decorator,
class Allocator = std::allocator<char>
>
class serializer
{
template<class Stream, class Handler>
class async_op;
/** Write a HTTP/1 header asynchronously to a stream.
enum
{
do_init = 0,
do_header_only = 10,
do_header = 20,
do_body = 40,
do_init_c = 50,
do_header_only_c = 60,
do_header_c = 70,
do_body_c = 90,
do_final_c = 100,
This function is used to asynchronously write a header to
a stream. The function call always returns immediately. The
asynchronous operation will continue until one of the following
conditions is true:
do_complete = 110
};
@li The entire header is written.
void split(bool, std::true_type) {}
void split(bool v, std::false_type) { split_ = v; }
@li An error occurs.
using buffer_type =
basic_multi_buffer<Allocator>;
This operation is implemented in terms of one or more calls to
the stream's `async_write_some` functions, and is known as a
<em>composed operation</em>. The program must ensure that the
stream performs no other write operations until this operation
completes.
using is_deferred =
typename Body::writer::is_deferred;
Regardless of the semantic meaning of the header (for example,
specifying "Content-Length: 0" and "Connection: close"),
this function will not return `boost::asio::error::eof`.
using cb0_t = consuming_buffers<buffers_view<
typename buffer_type::const_buffers_type, // header
typename Body::writer::const_buffers_type>>;// body
@param stream The stream to which the data is to be written.
The type must support the @b AsyncWriteStream concept.
using cb1_t = consuming_buffers<
typename Body::writer::const_buffers_type>; // body
@param msg The header to write. The object must remain valid
at least until the completion handler is called; ownership is
not transferred.
using ch0_t = consuming_buffers<buffers_view<
typename buffer_type::const_buffers_type, // header
detail::chunk_header, // chunk-header
boost::asio::const_buffers_1, // chunk-ext+\r\n
typename Body::writer::const_buffers_type, // body
boost::asio::const_buffers_1>>; // crlf
using ch1_t = consuming_buffers<buffers_view<
detail::chunk_header, // chunk-header
boost::asio::const_buffers_1, // chunk-ext+\r\n
typename Body::writer::const_buffers_type, // body
boost::asio::const_buffers_1>>; // crlf
@param handler The handler to be called when the operation
completes. Copies will be made of the handler as required.
The equivalent function signature of the handler must be:
@code void handler(
error_code const& error // result of operation
); @endcode
Regardless of whether the asynchronous operation completes
immediately or not, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
manner equivalent to using `boost::asio::io_service::post`.
*/
template<class AsyncWriteStream,
bool isRequest, class Fields,
class WriteHandler>
using ch2_t = consuming_buffers<buffers_view<
boost::asio::const_buffers_1, // chunk-final
boost::asio::const_buffers_1, // trailers
boost::asio::const_buffers_1>>; // crlf
message<isRequest, Body, Fields> const& m_;
Decorator d_;
std::size_t limit_ =
(std::numeric_limits<std::size_t>::max)();
boost::optional<typename Body::writer> wr_;
buffer_type b_;
boost::variant<boost::blank,
cb0_t, cb1_t, ch0_t, ch1_t, ch2_t> v_;
int s_;
bool split_ = is_deferred::value;
bool header_done_ = false;
bool chunked_;
bool close_;
bool more_;
public:
/** Constructor
@param msg The message to serialize. The message object
must remain valid for the lifetime of the write stream.
@param decorator An optional decorator to use.
@param alloc An optional allocator to use.
*/
explicit
serializer(message<isRequest, Body, Fields> const& msg,
Decorator const& decorator = Decorator{},
Allocator const& alloc = Allocator{});
/// Returns the maximum number of bytes that will be written in each operation
std::size_t
limit() const
{
return limit_;
}
/** Returns `true` if we will pause after writing the header.
*/
bool
split() const
{
return split_;
}
/** Set whether the header and body are written separately.
When the split feature is enabled, the implementation will
write only the octets corresponding to the serialized header
first. If the header has already been written, this function
will have no effect on output. This function should be called
before any writes take place, otherwise the behavior is
undefined.
*/
void
split(bool v)
{
split(v, is_deferred{});
}
/** Set the maximum number of bytes that will be written in each operation.
By default, there is no limit on the size of writes.
@param n The byte limit. This must be greater than zero.
*/
void
limit(std::size_t n)
{
limit_ = n;
}
/** Return `true` if serialization of the header is complete.
This function indicates whether or not all octets
corresponding to the serialized representation of the
header have been successfully delivered to the stream.
*/
bool
is_header_done() const
{
return header_done_;
}
/** Return `true` if serialization is complete
The operation is complete when all octets corresponding
to the serialized representation of the message have been
successfully delivered to the stream.
*/
bool
is_done() const
{
return s_ == do_complete;
}
/** Write some serialized message data to the stream.
This function is used to write serialized message data to the
stream. The function call will block until one of the following
conditions is true:
@li One or more bytes have been transferred.
@li An error occurs on the stream.
In order to completely serialize a message, this function
should be called until @ref is_done returns `true`. If the
semantics of the message indicate that the connection should
be closed after the message is sent, the error delivered from
this call will be `boost::asio::error::eof`.
@param stream The stream to write to. This type must
satisfy the requirements of @b SyncWriteStream.
@throws system_error Thrown on failure.
*/
template<class SyncWriteStream>
void
write_some(SyncWriteStream& stream);
/** Write some serialized message data to the stream.
This function is used to write serialized message data to the
stream. The function call will block until one of the following
conditions is true:
@li One or more bytes have been transferred.
@li An error occurs on the stream.
In order to completely serialize a message, this function
should be called until @ref is_done returns `true`. If the
semantics of the message indicate that the connection should
be closed after the message is sent, the error delivered from
this call will be `boost::asio::error::eof`.
@param stream The stream to write to. This type must
satisfy the requirements of @b SyncWriteStream.
@param ec Set to indicate what error occurred, if any.
*/
template<class SyncWriteStream>
void
write_some(SyncWriteStream& stream, error_code &ec);
/** Start an asynchronous write of some serialized message data.
This function is used to asynchronously write serialized
message data to the stream. The function call always returns
immediately. The asynchronous operation will continue until
one of the following conditions is true:
@li One or more bytes have been transferred.
@li An error occurs on the stream.
In order to completely serialize a message, this function
should be called until @ref is_done returns `true`. If the
semantics of the message indicate that the connection should
be closed after the message is sent, the error delivered from
this call will be `boost::asio::error::eof`.
@param stream The stream to write to. This type must
satisfy the requirements of @b SyncWriteStream.
@param handler The handler to be called when the request
completes. Copies will be made of the handler as required. The
equivalent function signature of the handler must be:
@code void handler(
error_code const& ec // Result of operation
); @endcode
Regardless of whether the asynchronous operation completes
immediately or not, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
manner equivalent to using `boost::asio::io_service::post`.
*/
template<class AsyncWriteStream, class WriteHandler>
#if BEAST_DOXYGEN
void_or_deduced
#else
async_return_type<
WriteHandler, void(error_code)>
async_return_type<WriteHandler, void(error_code)>
#endif
async_write(AsyncWriteStream& stream,
header<isRequest, Fields> const& msg,
async_write_some(AsyncWriteStream& stream,
WriteHandler&& handler);
};
/** Return a stateful object to serialize an HTTP message.
This convenience function makes it easier to declare
the variable for a given message.
*/
template<
bool isRequest, class Body, class Fields,
class Decorator = empty_decorator,
class Allocator = std::allocator<char>>
inline
serializer<isRequest, Body, Fields,
typename std::decay<Decorator>::type,
typename std::decay<Allocator>::type>
make_write_stream(message<isRequest, Body, Fields> const& m,
Decorator const& decorator = Decorator{},
Allocator const& allocator = Allocator{})
{
return serializer<isRequest, Body, Fields,
typename std::decay<Decorator>::type,
typename std::decay<Allocator>::type>{
m, decorator, allocator};
}
//------------------------------------------------------------------------------