* Revise stream algorithm javadocs
* HTTP stream algorithms now use beast::read and
beast::async_read with a custom completion condition.
API Changes:
* HTTP stream algorithms return the number of bytes transferred
from the stream. Previously, they returned the number of bytes
consumed by the parser.
Actions Required:
* Callers depending on the return value of http::read or
http::async_read overloads should adjust the usage of
the returned value as needed.
This works similarly to bind_handler, and can help with reducing
template instantiations and compiler memory usage (since it does
not need to support placeholders).
A specialization for the most common case `void(error_code, size_t)`
is provided to minimize instantiation cost.
fix#1270
basic_fields::value_type uses base hooks instead of member hooks,
otherwise MSVC can sometimes produce undefined behavior when
attempting to recover the base class from a data member in
certain build configurations.
fix#1133, fix#1241
When the macro BOOST_BEAST_USE_STD_STRING_VIEW is defined,
Beast will use std::string_view instead of boost::string_view.
The name boost::beast::string_view is a type alias for the
chosen view type.
fix#1237
HTTP client examples now verify the server's certificate
and generate an error if the certificate is invalid or
expired:
* Set certificate verify mode
* Remove duplicate root certificate
fix#1245, fix#1249
The value used to fill the incomplete code point buffer is
changed to a character which no longer causes
utf8_checker::valid() to incorrectly return false.
This resolves a medium vulnerability described in the
Beast Hybrid Assessment Report by Bishop Fox, where masks generated
for use with outgoing WebSocket client frames use an insufficient
source of entropy and a non-cryptographically secure pseudo-random
number generator.
By default, all newly constructed WebSocket streams will use a
uniquely seeded secure PRNG (ChaCha20 in counter mode). As this may
result in increased CPU resource consumption, the function
websocket::stream::secure_prng() may be used to select a faster but
less secure PRNG, for the case where the caller knows that the secure
generator is not necessary.
On some systems, std::random_device may produce insufficient entropy
to securely seed the PRNG. As this condition cannot be detected by
Beast, callers may use the function websocket::seed_prng() called
once at startup to provide at least 256 bits of entropy which will
be used to uniquely seed all subsequent PRNGs.
The ssl_stream wrapper provides C++11 move semantics for ssl::stream,
as well as incorporating the flat_stream workaround for a performance
problem with ssl::stream writes and buffer sequences having length
greater than one.
fix#1108
The `flat_stream` is a stream wrapper designed to overcome a
performance limitation of the `boost::asio::ssl::stream`
implementation. Specifically, when writing buffer sequences having
length greater than one, the `ssl::stream` implementation does
not use scatter-gather I/O and instead performs a kernel transition
for every buffer in the sequence.
The wrapper addresses this problem by allocating memory and
presenting the buffer sequence into a single buffer, using
some logic to determine when this allocation is advantageous
versus simply passing the buffers through as-is.
See Also:
https://github.com/boostorg/asio/issues/100https://stackoverflow.com/questions/50026167/performance-drop-on-port-from-beast-1-0-0-b66-to-boost-1-67-0-beast
fix#1076
As per Asio and Networking TS requirements, composed operations must
maintain an object of type executor_work_guard for the executor associated
with the I/O object, for the lifetime of the asynchronous operation.
This is in addition to the requirement for maintaining an object of type
executor_work_guard for the executor associated with the handler.
fix#941, fix#1016
`get_lowest_layer` is now a type alias for the
lowest layer instead of a struct with a nested type.
Actions required:
* Replace instances of `typename get_lowest_layer<T>::type`
with `get_lowest_layer<T>`.
fix#949
* New error codes are introduced for WebSocket failures
* More verbose messages for error codes
* Error codes are mapped to conditions for ease of testing
* error::failed and error::handshake_failed are deprecated (don't use)
Actions Required:
* Code which explicitly compares error_code values against the
constant `websocket::error::handshake_failed` should compare
against `websocket::condition::handshake_failed` instead.
* Code which explicitly compares error_code values against the
constant `websocket::error::failed` should compare
against `websocket::condition::protocol_violation` instead.
fix#849
This adds an additional `bool` template parameter to
`websocket::stream`:
* When deflateSupported is `true`, the stream will be capable
of negotiating the permessage-deflate websocket extension per
the configured run-time settings.
* When deflateSupported is `false`, the stream will never negotiate
the permessage-deflate websocket extension. Furthermore, all of the
code necessary for implementing the permessage-deflate extension
will be excluded from function instantiations. The resulting emitted
object code should be smaller.
fix#884
* BodyReader and BodyWriter constructors now require the header and
body elements to be passed as distinct header and value_type objects.
This enables the composition of body types, for example:
http::response<compressed_body<http::string_body>> res;
* The previous single-argument constructors are deprecated and will be
removed in a subsequent version.
Actions Required:
* Change user-defined instances of BodyReader or BodyWriter constructor
signatures to the two-argument form.
OR
* Define the macro BOOST_BEAST_ALLOW_DEPRECATED in the project (which
will accept both the new and the deprecated signatures).
Body::reader and Body::writer meanings are reversed, for
consistency with the names of the stream operations:
* Body::reader is used for read, read_some, async_read, async_read_some
* Body::writer is used for write, write_some, async_write, async_write_some
Actions Required:
* Swap the reader and writer names for user defined Body types
* Swap use of is_body_reader and is_body_writer
* Fields::writer replaces Fields::reader
* The FieldsWriter concept is renamed from FieldsReader
Actions Required:
* Rename reader to writer for user defined Fields
* The function has_content_length_impl is added to the
requirements of Fields.
Actions Required:
* Implement has_content_length_impl for user-defined Fields
fix#769
The following classes are removed:
* handler_type
* async_result
* async_completion
* is_dynamic_buffer
* is_const_buffer_sequence
* is_mutable_buffer_sequence
* handler_alloc
Actions Required:
* Use BOOST_ASIO_HANDLER_TYPE instead of handler_type
* Use BOOST_ASIO_INITFN_RESULT_TYPE instead of async_result
* Use boost::asio::async_completion
* Use boost::asio::is_dynamic_buffer
* Use boost::asio::is_const_buffer_sequence
* Use boost::asio::is_mutable_buffer_sequence
* boost::asio::associated_allocator_t replaces handler_alloc
fix#773
* buffer_cat is renamed to buffers_cat
* buffer_cat_view is renamed to buffers_cat_view
Actions Required:
* Use buffers_cat instead of buffer_cat
* Use buffers_cat_view instead of buffer_cat_view
fix#773
* buffer_prefix is renamed to buffers_prefix
* buffer_prefix_view is renamed to buffers_prefix_view
Actions Required:
* Use buffers_prefix instead of buffer_prefix
* Use buffers_prefix_view instead of buffer_prefix_view
fix#778
* The version data member is replaced with accessor
member functions.
Actions Required:
* Call member function message::version instead of accessing
the version member at call sites.
* HTTP read and write operations now return the
number of bytes transferred to or from the stream.
Actions Required:
* Modify HTTP read and/or write completion handlers to receive
the extra std::size_t bytes_transferred parameter.
fix#575, fix#604, fix#608, fix#634, fix#712
All examples are rewritten:
* Using Best Practices
* Mostly self-contained
* New examples to complete the feature matrix
* The server-framework example is removed
* teardown_tag is replaced with teardown_role, a client/server
flag used to determine whether the shutdown is performed
before or after reading the EOF. This is in accordance with
RFC6455 7.1.1:
https://tools.ietf.org/html/rfc6455#section-7.1.1
Actions Required:
* Modify signatures of teardown and async_teardown to use
teardown_role instead of teardown_tag
* Change calls to teardown and async_teardown to pass the
correct role: client or server depending on context.
* The drain_buffer dynamic buffer is no longer a public interface.
Actions Required:
* Replace code which uses drain_buffer. For websocket::stream,
it is no longer necessary to manually drain the connection
after closing.
The websocket stream is optimized to contain a small
circular static buffer, reducing the number of I/O calls when
reading data. The size of the buffer is tuned for maximum
performance with TCP/IP and no long needs configuration:
* read_some replaces read_frame
* write_some replaces write_Frame
* async_read_some replaces async_read_frame
* async_write_some replaces async_write_frame
* websocket::stream::read_buffer_size is removed
Actions Required:
* Remove calls websocket::stream::read_buffer_size
* Use read_some and write_some instead of read_frame and write_frame
* static_buffer is added
Note this is the same name from two versions ago, when
static_buffer was renamed to flat_static_buffer for
consistency and to clear the name for a circular static
buffer.
Actions Required:
* Callers who depend on static_buffer returning sequences of
exactly length one should switch to flat_static_buffer.
* parser now has a callback feature for intercepting chunk headers
and chunk bodies
* The names for basic_parser derived class callbacks have been
refactored
* basic_parser offers an additional callback for distinguishing
chunk body data.
Actions Required:
* Adjust signatures for required members of user-defined
subclasses of basic_parser
* Use the new basic_parser chunk callbacks for accessing
chunk extensions and chunk bodies.
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.
These types now perform error-based initialization in
a separate init() functions instead of in the constructor.
Actions Required:
* Modify instances of user-defined BodyReader and BodyWriter
types to perfrom two-phase initialization, as per the
updated documented type requirements.
