From f8ff44d072803e8c193946818ee7d239c5834b10 Mon Sep 17 00:00:00 2001 From: Mohammad Nejati Date: Fri, 9 Feb 2024 15:41:50 +0000 Subject: [PATCH 1/5] Improve documentation of http::serializer Resolves #2221 --- include/boost/beast/http/serializer.hpp | 28 +++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/include/boost/beast/http/serializer.hpp b/include/boost/beast/http/serializer.hpp index c12bc172ac..229554ddb0 100644 --- a/include/boost/beast/http/serializer.hpp +++ b/include/boost/beast/http/serializer.hpp @@ -43,6 +43,14 @@ namespace http { the chunk buffer sequence types @ref chunk_body, @ref chunk_crlf, @ref chunk_header, and @ref chunk_last. + @note + + Moving or copying the serializer after the first call to + @ref serializer::next results in undefined behavior. Try to heap-allocate + the serializer object if you need to move the serializer between multiple + async operations (for example, between a call to `async_write_header` and + `async_write`). + @tparam isRequest `true` if the message is a request. @tparam Body The body type of the message. @@ -189,10 +197,26 @@ class serializer bool more_ = false; public: - /// Constructor + /** Move Constructor + @note + + Moving or copying the serializer after the first call to + @ref serializer::next results in undefined behavior. Try to heap-allocate + the serializer object if you need to move the serializer between multiple + async operations (for example, between a call to `async_write_header` and + `async_write`). + */ serializer(serializer&&) = default; - /// Constructor + /** Copy Constructor + @note + + Moving or copying the serializer after the first call to + @ref serializer::next results in undefined behavior. Try to heap-allocate + the serializer object if you need to move the serializer between multiple + async operations (for example, between a call to `async_write_header` and + `async_write`). + */ serializer(serializer const&) = default; /// Assignment From 7d4da621ac76d9720b3067f07a5cc6975085b0f8 Mon Sep 17 00:00:00 2001 From: Mohammad Nejati Date: Mon, 12 Feb 2024 10:30:26 +0000 Subject: [PATCH 2/5] Update bytes_transferred documentation for http reads operations --- include/boost/beast/http/read.hpp | 93 ++++++++++--------------------- 1 file changed, 30 insertions(+), 63 deletions(-) diff --git a/include/boost/beast/http/read.hpp b/include/boost/beast/http/read.hpp index bbd85a5d44..ec6ba06ffb 100644 --- a/include/boost/beast/http/read.hpp +++ b/include/boost/beast/http/read.hpp @@ -62,13 +62,9 @@ namespace http { @param parser The parser to use. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. @throws system_error Thrown on failure. - - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. */ template< class SyncReadStream, @@ -121,11 +117,7 @@ read_some( @param ec Set to the error, if any occurred. - @return The number of bytes transferred from the stream. - - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. + @return The number of bytes consumed by the parser. */ template< class SyncReadStream, @@ -189,7 +181,7 @@ read_some( @code void handler( error_code const& error, // result of operation - std::size_t bytes_transferred // the total number of bytes transferred from the stream + std::size_t bytes_transferred // the number of bytes consumed by the parser ); @endcode If the handler has an associated immediate executor, @@ -198,10 +190,6 @@ read_some( this function. Invocation of the handler will be performed in a manner equivalent to using `net::post`. - @note The completion handler will receive as a parameter the total number - of bytes transferred from the stream. This may be zero for the case where - there is sufficient pre-existing message data in the dynamic buffer. - @par Per-Operation Cancellation This asynchronous operation supports cancellation for the following @@ -270,14 +258,12 @@ async_read_some( @param parser The parser to use. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. @throws system_error Thrown on failure. - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. The implementation will call - @ref basic_parser::eager with the value `false` on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `false` on the parser passed in. */ template< class SyncReadStream, @@ -329,12 +315,10 @@ read_header( @param ec Set to the error, if any occurred. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. The implementation will call - @ref basic_parser::eager with the value `false` on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `false` on the parser passed in. */ template< class SyncReadStream, @@ -397,7 +381,7 @@ read_header( @code void handler( error_code const& error, // result of operation - std::size_t bytes_transferred // the total number of bytes transferred from the stream + std::size_t bytes_transferred // the number of bytes consumed by the parser ); @endcode If the handler has an associated immediate executor, @@ -406,11 +390,8 @@ read_header( this function. Invocation of the handler will be performed in a manner equivalent to using `net::post`. - @note The completion handler will receive as a parameter the total number - of bytes transferred from the stream. This may be zero for the case where - there is sufficient pre-existing message data in the dynamic buffer. The - implementation will call @ref basic_parser::eager with the value `false` - on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `false` on the parser passed in. @par Per-Operation Cancellation @@ -480,14 +461,12 @@ async_read_header( @param parser The parser to use. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. @throws system_error Thrown on failure. - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. The implementation will call - @ref basic_parser::eager with the value `true` on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `true` on the parser passed in. */ template< class SyncReadStream, @@ -539,12 +518,10 @@ read( @param ec Set to the error, if any occurred. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. The implementation will call - @ref basic_parser::eager with the value `true` on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `true` on the parser passed in. */ template< class SyncReadStream, @@ -607,7 +584,7 @@ read( @code void handler( error_code const& error, // result of operation - std::size_t bytes_transferred // the total number of bytes transferred from the stream + std::size_t bytes_transferred // the number of bytes consumed by the parser ); @endcode If the handler has an associated immediate executor, @@ -616,11 +593,8 @@ read( this function. Invocation of the handler will be performed in a manner equivalent to using `net::post`. - @note The completion handler will receive as a parameter the total number - of bytes transferred from the stream. This may be zero for the case where - there is sufficient pre-existing message data in the dynamic buffer. The - implementation will call @ref basic_parser::eager with the value `true` - on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `true` on the parser passed in. @par Per-Operation Cancellation @@ -693,14 +667,12 @@ async_read( is undefined. The type must be meet the MoveAssignable and MoveConstructible requirements. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. @throws system_error Thrown on failure. - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. The implementation will call - @ref basic_parser::eager with the value `true` on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `true` on the parser passed in. */ template< class SyncReadStream, @@ -755,12 +727,10 @@ read( @param ec Set to the error, if any occurred. - @return The number of bytes transferred from the stream. + @return The number of bytes consumed by the parser. - @note The function returns the total number of bytes transferred from the - stream. This may be zero for the case where there is sufficient pre-existing - message data in the dynamic buffer. The implementation will call - @ref basic_parser::eager with the value `true` on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `true` on the parser passed in. */ template< class SyncReadStream, @@ -826,7 +796,7 @@ read( @code void handler( error_code const& error, // result of operation - std::size_t bytes_transferred // the total number of bytes transferred from the stream + std::size_t bytes_transferred // the number of bytes consumed by the parser ); @endcode If the handler has an associated immediate executor, @@ -835,11 +805,8 @@ read( this function. Invocation of the handler will be performed in a manner equivalent to using `net::post`. - @note The completion handler will receive as a parameter the total number - of bytes transferred from the stream. This may be zero for the case where - there is sufficient pre-existing message data in the dynamic buffer. The - implementation will call @ref basic_parser::eager with the value `true` - on the parser passed in. + @note The implementation will call @ref basic_parser::eager with the value + `true` on the parser passed in. @par Per-Operation Cancellation From 40c22cbfa7aea25386f6f13967bbdd17da00657a Mon Sep 17 00:00:00 2001 From: Mohammad Nejati Date: Wed, 14 Feb 2024 07:34:23 +0000 Subject: [PATCH 3/5] Update documentation for websocket::permessage_deflate Resolves #962 --- include/boost/beast/websocket/option.hpp | 9 +++++++-- include/boost/beast/websocket/stream.hpp | 5 +++++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/include/boost/beast/websocket/option.hpp b/include/boost/beast/websocket/option.hpp index 817bf9110b..4c4e4ee68b 100644 --- a/include/boost/beast/websocket/option.hpp +++ b/include/boost/beast/websocket/option.hpp @@ -21,8 +21,13 @@ namespace websocket { These settings control the permessage-deflate extension, which allows messages to be compressed. - @note Objects of this type are used with - @ref beast::websocket::stream::set_option. + @note + + These settings should be configured before performing the WebSocket + handshake. + + Objects of this type are used with + @ref beast::websocket::stream::set_option. */ struct permessage_deflate { diff --git a/include/boost/beast/websocket/stream.hpp b/include/boost/beast/websocket/stream.hpp index 8dec12b146..0b9baf2b8f 100644 --- a/include/boost/beast/websocket/stream.hpp +++ b/include/boost/beast/websocket/stream.hpp @@ -398,6 +398,11 @@ class stream @throws invalid_argument if `deflateSupported == false`, and either `client_enable` or `server_enable` is `true`. + + @note + + These settings should be configured before performing the WebSocket + handshake. */ void set_option(permessage_deflate const& o); From dc154bc0bd86abdbb102ad23cf27659e8bb99142 Mon Sep 17 00:00:00 2001 From: Mohammad Nejati Date: Wed, 14 Feb 2024 15:20:31 +0000 Subject: [PATCH 4/5] Update host string after SSL_set_tlsext_host_name --- .../websocket_client_async_ssl_system_executor.cpp | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/example/websocket/client/async-ssl-system-executor/websocket_client_async_ssl_system_executor.cpp b/example/websocket/client/async-ssl-system-executor/websocket_client_async_ssl_system_executor.cpp index 02b6269248..f6af28d2f1 100644 --- a/example/websocket/client/async-ssl-system-executor/websocket_client_async_ssl_system_executor.cpp +++ b/example/websocket/client/async-ssl-system-executor/websocket_client_async_ssl_system_executor.cpp @@ -114,11 +114,6 @@ class session : public std::enable_shared_from_this if(ec) return fail(ec, "connect"); - // Update the host_ string. This will provide the value of the - // Host HTTP header during the WebSocket handshake. - // See https://tools.ietf.org/html/rfc7230#section-5.4 - host_ += ':' + std::to_string(ep.port()); - // Set a timeout on the operation beast::get_lowest_layer(ws_).expires_after(std::chrono::seconds(30)); @@ -132,6 +127,11 @@ class session : public std::enable_shared_from_this return fail(ec, "connect"); } + // Update the host_ string. This will provide the value of the + // Host HTTP header during the WebSocket handshake. + // See https://tools.ietf.org/html/rfc7230#section-5.4 + host_ += ':' + std::to_string(ep.port()); + // Perform the SSL handshake ws_.next_layer().async_handshake( ssl::stream_base::client, From e42cf8a1e4b75ee33210a20837d06887809b3c67 Mon Sep 17 00:00:00 2001 From: Mohammad Nejati Date: Wed, 14 Feb 2024 16:25:03 +0000 Subject: [PATCH 5/5] Remove BOOST_BEAST_USE_STD_STRING_VIEW deprecation warning Closes #2594 --- include/boost/beast/core/string_type.hpp | 5 ----- 1 file changed, 5 deletions(-) diff --git a/include/boost/beast/core/string_type.hpp b/include/boost/beast/core/string_type.hpp index bbb09db809..4bc6e5c67f 100644 --- a/include/boost/beast/core/string_type.hpp +++ b/include/boost/beast/core/string_type.hpp @@ -11,12 +11,7 @@ #define BOOST_BEAST_STRING_TYPE_HPP #include - #include -#if defined(BOOST_BEAST_USE_STD_STRING_VIEW) -#include -BOOST_PRAGMA_MESSAGE("BOOST_BEAST_USE_STD_STRING_VIEW is deprecated, use BOOST_NO_CXX17_HDR_STRING_VIEW instead"); -#endif namespace boost { namespace beast {