awaitable examples.

Closes #2104.

doc/qbk/02_examples/_examples.qbk

@@ -40,6 +40,10 @@ used to evaluate robustness. All asynchronous clients support timeouts.
         [HTTP, coroutine]
         [[path_link example/http/client/coro/http_client_coro.cpp http_client_coro.cpp]]
         [[path_link example/http/client/coro-ssl/http_client_coro_ssl.cpp http_client_coro_ssl.cpp]]
+][
+        [WebSocket, C++20 coroutine]
+        [[path_link example/http/client/awaitable/http_client_awaitable.cpp http_client_awaitable.cpp]]
+        []
 ][
         [HTTP crawl (asynchronous)]
         [[path_link example/http/client/crawl/http_crawl.cpp http_crawl.cpp]]
@@ -72,6 +76,10 @@ before disconnecting. All asynchronous clients support timeouts.
         [WebSocket, coroutine]
         [[path_link example/websocket/client/coro/websocket_client_coro.cpp websocket_client_coro.cpp]]
         [[path_link example/websocket/client/coro-ssl/websocket_client_coro_ssl.cpp websocket_client_coro_ssl.cpp]]
+][
+        [WebSocket, C++20 coroutine]
+        [[path_link example/websocket/client/awaitable/websocket_client_awaitable.cpp websocket_client_awaitable.cpp]]
+        []
 ]]
 
 [endsect]
@@ -101,6 +109,9 @@ command line. All asynchronous servers support timeouts.
         [HTTP, stackless coroutine]
         [[path_link example/http/server/stackless/http_server_stackless.cpp http_server_stackless.cpp]]
         [[path_link example/http/server/stackless-ssl/http_server_stackless_ssl.cpp http_server_stackless_ssl.cpp]]
+][
+        [HTTP, C++ 20 coroutine]
+        [[path_link example/http/server/awaitable/http_server_awaitable.cpp http_server_awaitable.cpp]]
 ][
         [HTTP, fast (optimized for speed)]
         [[path_link example/http/server/fast/http_server_fast.cpp http_server_fast.cpp]]
@@ -137,6 +148,10 @@ support timeouts.
         [WebSocket, stackless coroutine]
         [[path_link example/websocket/server/stackless/websocket_server_stackless.cpp websocket_server_stackless.cpp]]
         [[path_link example/websocket/server/stackless-ssl/websocket_server_stackless_ssl.cpp websocket_server_stackless_ssl.cpp]]
+][
+        [HTTP, C++ 20 coroutine]
+        [[path_link example/websocket/server/awaitable/websocket_server_awaitable.cpp websocket_server_awaitable.cpp]]
+        []
 ][
         [WebSocket, fast (suited for benchmarks)]
         [[path_link example/websocket/server/fast/websocket_server_fast.cpp websocket_server_fast.cpp]]
@@ -178,6 +193,19 @@ and illustrate the implementation of advanced features.
         ]]
         [[path_link example/advanced/server-flex/advanced_server_flex.cpp advanced_server_flex.cpp]]
 ][
+         [Advanced, flex (plain + SSL) with awaitable]
+         [[itemized_list
+             [Timeouts]
+             [Multi-threaded]
+             [HTTP pipelining]
+             [Parser-oriented HTTP reading]
+             [Dual protocols: HTTP and WebSocket]
+             [Flexible ports: plain and SSL on the same port]
+             [Clean exit via SIGINT (CTRL+C) or SIGTERM (kill)]
+             [Usage of cancellation_signals]
+         ]]
+         [[path_link example/advanced/server-flex-awaitable/advanced_server_flex_awaitable.cpp advanced_server_flex_awaitable.cpp]]
+ ][
         [Chat Server, multi-threaded]
         [[itemized_list
             [Multi-threaded]

example/advanced/CMakeLists.txt

@@ -9,3 +9,4 @@
 
 add_subdirectory (server)
 add_subdirectory (server-flex)
+add_subdirectory (server-flex-awaitable)

example/advanced/Jamfile

@@ -11,3 +11,6 @@ build-project server ;
 
 # SSL
 build-project server-flex ;
+
+# C++20
+build-project server-flex-awaitable ;

example/advanced/server-flex-awaitable/CMakeLists.txt

@@ -0,0 +1,31 @@
+#
+# Copyright (c) 2016-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)
+#
+# Official repository: https://github.com/boostorg/beast
+#
+
+if (OPENSSL_FOUND)
+    GroupSources(include/boost/beast beast)
+    GroupSources(example/common common)
+    GroupSources(example/advanced/server-flex-awaitable "/")
+
+    add_executable (advanced-server-flex-awaitable
+        ${BOOST_BEAST_FILES}
+        ${PROJECT_SOURCE_DIR}/example/common/server_certificate.hpp
+        Jamfile
+            advanced_server_flex_awaitable.cpp
+    )
+
+    set_property(TARGET advanced-server-flex-awaitable PROPERTY FOLDER "example-advanced-server")
+    
+    target_link_libraries (advanced-server-flex-awaitable
+        OpenSSL::SSL OpenSSL::Crypto
+        lib-asio
+        lib-asio-ssl
+        lib-beast
+        )
+
+endif()

example/advanced/server-flex-awaitable/Jamfile

@@ -0,0 +1,22 @@
+#
+# Copyright (c) 2016-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)
+#
+# Official repository: https://github.com/boostorg/beast
+#
+
+import ac ;
+
+project
+    : requirements
+        [ ac.check-library /boost/beast//lib-asio-ssl : <library>/boost/beast//lib-asio-ssl/<link>static : <build>no ]
+    ;
+
+exe advanced-server-flex-awaitable :
+    advanced_server_flex_awaitable.cpp
+    :
+    <variant>coverage:<build>no
+    <variant>ubasan:<build>no
+    ;

example/http/client/CMakeLists.txt

@@ -8,6 +8,7 @@
 #
 
 add_subdirectory (async)
+add_subdirectory (awaitable)
 add_subdirectory (coro)
 add_subdirectory (crawl)
 add_subdirectory (sync)

example/http/client/Jamfile

@@ -11,6 +11,7 @@ build-project async ;
 build-project coro ;
 build-project crawl ;
 build-project sync ;
+build-project awaitable ;
 
 # SSL
 build-project async-ssl ;

example/http/client/awaitable/CMakeLists.txt

@@ -0,0 +1,23 @@
+#
+# Copyright (c) 2016-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)
+#
+# Official repository: https://github.com/boostorg/beast
+#
+
+GroupSources(include/boost/beast beast)
+GroupSources(example/http/client/awaitable "/")
+
+add_executable (http-client-awaitable
+    ${BOOST_BEAST_FILES}
+    Jamfile
+        http_client_awaitable.cpp
+    )
+
+target_link_libraries(http-client-awaitable
+    lib-asio
+    lib-beast)
+
+set_property(TARGET http-client-awaitable PROPERTY FOLDER "example-http-client")

example/http/client/awaitable/Jamfile

@@ -0,0 +1,15 @@
+#
+# Copyright (c) 2016-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)
+#
+# Official repository: https://github.com/boostorg/beast
+#
+
+exe http-client-awaitable :
+    http_client_awaitable.cpp
+    :
+    <variant>coverage:<build>no
+    <variant>ubasan:<build>no
+    ;

example/http/client/awaitable/http_client_awaitable.cpp

@@ -0,0 +1,158 @@
+//
+// Copyright (c) 2022 Klemens D. Morgenstern (klemens dot morgenstern at gmx dot net)
+//
+// 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)
+//
+// Official repository: https://github.com/boostorg/beast
+//
+
+//------------------------------------------------------------------------------
+//
+// Example: HTTP client, coroutine
+//
+//------------------------------------------------------------------------------
+
+
+
+#include <boost/beast/core.hpp>
+#include <boost/beast/http.hpp>
+#include <boost/beast/version.hpp>
+#include <boost/asio/awaitable.hpp>
+#include <boost/asio/co_spawn.hpp>
+#include <boost/asio/detached.hpp>
+#include <boost/asio/use_awaitable.hpp>
+
+#if defined(BOOST_ASIO_HAS_CO_AWAIT)
+
+#include <cstdlib>
+#include <functional>
+#include <iostream>
+#include <string>
+
+namespace beast = boost::beast;         // from <boost/beast.hpp>
+namespace http = beast::http;           // from <boost/beast/http.hpp>
+namespace net = boost::asio;            // from <boost/asio.hpp>
+using tcp = boost::asio::ip::tcp;       // from <boost/asio/ip/tcp.hpp>
+
+//------------------------------------------------------------------------------
+
+// Report a failure
+void
+fail(beast::error_code ec, char const* what)
+{
+    std::cerr << what << ": " << ec.message() << "\n";
+}
+
+// Performs an HTTP GET and prints the response
+net::awaitable<void>
+do_session(
+    std::string host,
+    std::string port,
+    std::string target,
+    int version)
+{
+    // These objects perform our I/O
+
+    auto resolver = net::use_awaitable.as_default_on(tcp::resolver(co_await net::this_coro::executor));
+    auto stream = net::use_awaitable.as_default_on(beast::tcp_stream(co_await net::this_coro::executor));
+
+    // Look up the domain name
+    auto const results = co_await resolver.async_resolve(host, port);
+
+    // Set the timeout.
+    stream.expires_after(std::chrono::seconds(30));
+
+    // Make the connection on the IP address we get from a lookup
+    co_await stream.async_connect(results);
+
+    // Set up an HTTP GET request message
+    http::request<http::string_body> req{http::verb::get, target, version};
+    req.set(http::field::host, host);
+    req.set(http::field::user_agent, BOOST_BEAST_VERSION_STRING);
+
+    // Set the timeout.
+    stream.expires_after(std::chrono::seconds(30));
+
+    // Send the HTTP request to the remote host
+    co_await http::async_write(stream, req);
+
+    // This buffer is used for reading and must be persisted
+    beast::flat_buffer b;
+
+    // Declare a container to hold the response
+    http::response<http::dynamic_body> res;
+
+    // Receive the HTTP response
+    co_await http::async_read(stream, b, res);
+
+    // Write the message to standard out
+    std::cout << res << std::endl;
+
+    // Gracefully close the socket
+    beast::error_code ec;
+    stream.socket().shutdown(tcp::socket::shutdown_both, ec);
+
+    // not_connected happens sometimes
+    // so don't bother reporting it.
+    //
+    if(ec && ec != beast::errc::not_connected)
+        throw boost::system::system_error(ec, "shutdown");
+
+    // If we get here then the connection is closed gracefully
+}
+
+//------------------------------------------------------------------------------
+
+int main(int argc, char** argv)
+{
+    // Check command line arguments.
+    if(argc != 4 && argc != 5)
+    {
+        std::cerr <<
+            "Usage: http-client-awaitable <host> <port> <target> [<HTTP version: 1.0 or 1.1(default)>]\n" <<
+            "Example:\n" <<
+            "    http-client-awaitable www.example.com 80 /\n" <<
+            "    http-client-awaitable www.example.com 80 / 1.0\n";
+        return EXIT_FAILURE;
+    }
+    auto const host = argv[1];
+    auto const port = argv[2];
+    auto const target = argv[3];
+    int version = argc == 5 && !std::strcmp("1.0", argv[4]) ? 10 : 11;
+
+    // The io_context is required for all I/O
+    net::io_context ioc;
+
+    // Launch the asynchronous operation
+    net::co_spawn(ioc,
+                  do_session(host, port, target, version),
+                  [](std::exception_ptr e)
+                  {
+                    if (e)
+                    try
+                    {
+                        std::rethrow_exception(e);
+                    }
+                    catch(std::exception & e)
+                    {
+                        std::cerr << "Error: " << e.what() << "\n";
+                    }
+                  });
+
+    // Run the I/O service. The call will return when
+    // the get operation is complete.
+    ioc.run();
+
+    return EXIT_SUCCESS;
+}
+
+#else
+
+int main(int, char * [])
+{
+    std::printf("awaitables require C++20\n");
+    return 1;
+}
+
+#endif

example/http/server/CMakeLists.txt

@@ -8,6 +8,7 @@
 #
 
 add_subdirectory (async)
+add_subdirectory (awaitable)
 add_subdirectory (coro)
 add_subdirectory (fast)
 add_subdirectory (small)

example/http/server/Jamfile

@@ -13,6 +13,7 @@ build-project fast ;
 build-project small ;
 build-project stackless ;
 build-project sync ;
+build-project awaitable ;
 
 # SSL
 build-project async-ssl ;

example/http/server/awaitable/CMakeLists.txt

@@ -0,0 +1,23 @@
+#
+# Copyright (c) 2016-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)
+#
+# Official repository: https://github.com/boostorg/beast
+#
+
+GroupSources(include/boost/beast beast)
+GroupSources(example/http/server/awaitable "/")
+
+add_executable (http-server-awaitable
+    ${BOOST_BEAST_FILES}
+    Jamfile
+        http_server_awaitable.cpp
+)
+
+target_link_libraries(http-server-awaitable
+    lib-asio
+    lib-beast)
+
+set_property(TARGET http-server-awaitable PROPERTY FOLDER "example-http-server")

example/http/server/awaitable/Jamfile

@@ -0,0 +1,16 @@
+#
+# Copyright (c) 2016-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)
+#
+# Official repository: https://github.com/boostorg/beast
+#
+
+exe http-server-awaitable :
+    http_server_awaitable.cpp
+    :
+    <variant>coverage:<build>no
+    <variant>ubasan:<build>no
+    <build>no
+    ;

example/http/server/awaitable/http_server_awaitable.cpp

@@ -0,0 +1,358 @@
+//
+// Copyright (c) 2022 Klemens D. Morgenstern (klemens dot morgenstern at gmx dot net)
+//
+// 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)
+//
+// Official repository: https://github.com/boostorg/beast
+//
+
+//------------------------------------------------------------------------------
+//
+// Example: HTTP server, coroutine
+//
+//------------------------------------------------------------------------------
+
+#include <boost/beast/core.hpp>
+#include <boost/beast/http.hpp>
+#include <boost/beast/version.hpp>
+#include <boost/asio/ip/tcp.hpp>
+#include <boost/asio/awaitable.hpp>
+#include <boost/asio/co_spawn.hpp>
+#include <boost/asio/use_awaitable.hpp>
+#include <boost/config.hpp>
+#include <algorithm>
+#include <cstdlib>
+#include <iostream>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+#if defined(BOOST_ASIO_HAS_CO_AWAIT)
+
+namespace beast = boost::beast;         // from <boost/beast.hpp>
+namespace http = beast::http;           // from <boost/beast/http.hpp>
+namespace net = boost::asio;            // from <boost/asio.hpp>
+using tcp = boost::asio::ip::tcp;       // from <boost/asio/ip/tcp.hpp>
+
+using tcp_stream = typename beast::tcp_stream::rebind_executor<
+        net::use_awaitable_t<>::executor_with_default<net::any_io_executor>>::other;
+
+// Return a reasonable mime type based on the extension of a file.
+beast::string_view
+mime_type(beast::string_view path)
+{
+    using beast::iequals;
+    auto const ext = [&path]
+    {
+        auto const pos = path.rfind(".");
+        if(pos == beast::string_view::npos)
+            return beast::string_view{};
+        return path.substr(pos);
+    }();
+    if(iequals(ext, ".htm"))  return "text/html";
+    if(iequals(ext, ".html")) return "text/html";
+    if(iequals(ext, ".php"))  return "text/html";
+    if(iequals(ext, ".css"))  return "text/css";
+    if(iequals(ext, ".txt"))  return "text/plain";
+    if(iequals(ext, ".js"))   return "application/javascript";
+    if(iequals(ext, ".json")) return "application/json";
+    if(iequals(ext, ".xml"))  return "application/xml";
+    if(iequals(ext, ".swf"))  return "application/x-shockwave-flash";
+    if(iequals(ext, ".flv"))  return "video/x-flv";
+    if(iequals(ext, ".png"))  return "image/png";
+    if(iequals(ext, ".jpe"))  return "image/jpeg";
+    if(iequals(ext, ".jpeg")) return "image/jpeg";
+    if(iequals(ext, ".jpg"))  return "image/jpeg";
+    if(iequals(ext, ".gif"))  return "image/gif";
+    if(iequals(ext, ".bmp"))  return "image/bmp";
+    if(iequals(ext, ".ico"))  return "image/vnd.microsoft.icon";
+    if(iequals(ext, ".tiff")) return "image/tiff";
+    if(iequals(ext, ".tif"))  return "image/tiff";
+    if(iequals(ext, ".svg"))  return "image/svg+xml";
+    if(iequals(ext, ".svgz")) return "image/svg+xml";
+    return "application/text";
+}
+
+// Append an HTTP rel-path to a local filesystem path.
+// The returned path is normalized for the platform.
+std::string
+path_cat(
+    beast::string_view base,
+    beast::string_view path)
+{
+    if(base.empty())
+        return std::string(path);
+    std::string result(base);
+#ifdef BOOST_MSVC
+    char constexpr path_separator = '\\';
+    if(result.back() == path_separator)
+        result.resize(result.size() - 1);
+    result.append(path.data(), path.size());
+    for(auto& c : result)
+        if(c == '/')
+            c = path_separator;
+#else
+    char constexpr path_separator = '/';
+    if(result.back() == path_separator)
+        result.resize(result.size() - 1);
+    result.append(path.data(), path.size());
+#endif
+    return result;
+}
+
+// Return a response for the given request.
+//
+// The concrete type of the response message (which depends on the
+// request), is type-erased in message_generator.
+template <class Body, class Allocator>
+http::message_generator
+handle_request(
+    beast::string_view doc_root,
+    http::request<Body, http::basic_fields<Allocator>>&& req)
+{
+    // Returns a bad request response
+    auto const bad_request =
+    [&req](beast::string_view why)
+    {
+        http::response<http::string_body> res{http::status::bad_request, req.version()};
+        res.set(http::field::server, BOOST_BEAST_VERSION_STRING);
+        res.set(http::field::content_type, "text/html");
+        res.keep_alive(req.keep_alive());
+        res.body() = std::string(why);
+        res.prepare_payload();
+        return res;
+    };
+
+    // Returns a not found response
+    auto const not_found =
+    [&req](beast::string_view target)
+    {
+        http::response<http::string_body> res{http::status::not_found, req.version()};
+        res.set(http::field::server, BOOST_BEAST_VERSION_STRING);
+        res.set(http::field::content_type, "text/html");
+        res.keep_alive(req.keep_alive());
+        res.body() = "The resource '" + std::string(target) + "' was not found.";
+        res.prepare_payload();
+        return res;
+    };
+
+    // Returns a server error response
+    auto const server_error =
+    [&req](beast::string_view what)
+    {
+        http::response<http::string_body> res{http::status::internal_server_error, req.version()};
+        res.set(http::field::server, BOOST_BEAST_VERSION_STRING);
+        res.set(http::field::content_type, "text/html");
+        res.keep_alive(req.keep_alive());
+        res.body() = "An error occurred: '" + std::string(what) + "'";
+        res.prepare_payload();
+        return res;
+    };
+
+    // Make sure we can handle the method
+    if( req.method() != http::verb::get &&
+        req.method() != http::verb::head)
+        return bad_request("Unknown HTTP-method");
+
+    // Request path must be absolute and not contain "..".
+    if( req.target().empty() ||
+        req.target()[0] != '/' ||
+        req.target().find("..") != beast::string_view::npos)
+        return bad_request("Illegal request-target");
+
+    // Build the path to the requested file
+    std::string path = path_cat(doc_root, req.target());
+    if(req.target().back() == '/')
+        path.append("index.html");
+
+    // Attempt to open the file
+    beast::error_code ec;
+    http::file_body::value_type body;
+    body.open(path.c_str(), beast::file_mode::scan, ec);
+
+    // Handle the case where the file doesn't exist
+    if(ec == beast::errc::no_such_file_or_directory)
+        return not_found(req.target());
+
+    // Handle an unknown error
+    if(ec)
+        return server_error(ec.message());
+
+    // Cache the size since we need it after the move
+    auto const size = body.size();
+
+    // Respond to HEAD request
+    if(req.method() == http::verb::head)
+    {
+        http::response<http::empty_body> res{http::status::ok, req.version()};
+        res.set(http::field::server, BOOST_BEAST_VERSION_STRING);
+        res.set(http::field::content_type, mime_type(path));
+        res.content_length(size);
+        res.keep_alive(req.keep_alive());
+        return res;
+    }
+
+    // Respond to GET request
+    http::response<http::file_body> res{
+        std::piecewise_construct,
+        std::make_tuple(std::move(body)),
+        std::make_tuple(http::status::ok, req.version())};
+    res.set(http::field::server, BOOST_BEAST_VERSION_STRING);
+    res.set(http::field::content_type, mime_type(path));
+    res.content_length(size);
+    res.keep_alive(req.keep_alive());
+    return res;
+}
+
+//------------------------------------------------------------------------------
+
+
+// Handles an HTTP server connection
+net::awaitable<void>
+do_session(
+    tcp_stream stream,
+    std::shared_ptr<std::string const> doc_root)
+{
+    beast::error_code ec;
+
+    // This buffer is required to persist across reads
+    beast::flat_buffer buffer;
+
+    // This lambda is used to send messages
+    for(;;)
+    try
+    {
+        // Set the timeout.
+        stream.expires_after(std::chrono::seconds(30));
+
+        // Read a request
+        http::request<http::string_body> req;
+        co_await http::async_read(stream, buffer, req);
+
+        // Handle the request
+        http::message_generator msg =
+            handle_request(*doc_root, std::move(req));
+
+        // Determine if we should close the connection
+        bool keep_alive = msg.keep_alive();
+
+        // Send the response
+        co_await beast::async_write(stream, std::move(msg), net::use_awaitable);
+
+        if(! keep_alive)
+        {
+            // This means we should close the connection, usually because
+            // the response indicated the "Connection: close" semantic.
+            break;
+        }
+    }
+    catch (boost::system::system_error & se)
+    {
+        if (se.code() != http::error::end_of_stream )
+            throw ;
+    }
+
+    // Send a TCP shutdown
+    stream.socket().shutdown(tcp::socket::shutdown_send, ec);
+
+    // At this point the connection is closed gracefully
+}
+
+//------------------------------------------------------------------------------
+
+// Accepts incoming connections and launches the sessions
+net::awaitable<void>
+do_listen(
+    tcp::endpoint endpoint,
+    std::shared_ptr<std::string const> doc_root)
+{
+    // Open the acceptor
+    auto acceptor = net::use_awaitable.as_default_on(tcp::acceptor(co_await net::this_coro::executor));
+    acceptor.open(endpoint.protocol());
+
+    // Allow address reuse
+    acceptor.set_option(net::socket_base::reuse_address(true));
+
+    // Bind to the server address
+    acceptor.bind(endpoint);
+
+    // Start listening for connections
+    acceptor.listen(net::socket_base::max_listen_connections);
+
+    for(;;)
+        boost::asio::co_spawn(
+            acceptor.get_executor(),
+                do_session(tcp_stream(co_await acceptor.async_accept()), doc_root),
+                [](std::exception_ptr e)
+                {
+                    try
+                    {
+                        std::rethrow_exception(e);
+                    }
+                    catch (std::exception &e) {
+                        std::cerr << "Error in session: " << e.what() << "\n";
+                    }
+                });
+
+}
+
+int main(int argc, char* argv[])
+{
+    // Check command line arguments.
+    if (argc != 5)
+    {
+        std::cerr <<
+            "Usage: http-server-awaitable <address> <port> <doc_root> <threads>\n" <<
+            "Example:\n" <<
+            "    http-server-awaitable 0.0.0.0 8080 . 1\n";
+        return EXIT_FAILURE;
+    }
+    auto const address = net::ip::make_address(argv[1]);
+    auto const port = static_cast<unsigned short>(std::atoi(argv[2]));
+    auto const doc_root = std::make_shared<std::string>(argv[3]);
+    auto const threads = std::max<int>(1, std::atoi(argv[4]));
+
+    // The io_context is required for all I/O
+    net::io_context ioc{threads};
+
+    // Spawn a listening port
+    boost::asio::co_spawn(ioc,
+                          do_listen(tcp::endpoint{address, port}, doc_root),
+                          [](std::exception_ptr e)
+                          {
+                              if (e)
+                                  try
+                                  {
+                                      std::rethrow_exception(e);
+                                  }
+                                  catch(std::exception & e)
+                                  {
+                                      std::cerr << "Error in acceptor: " << e.what() << "\n";
+                                  }
+                          });
+
+    // Run the I/O service on the requested number of threads
+    std::vector<std::thread> v;
+    v.reserve(threads - 1);
+    for(auto i = threads - 1; i > 0; --i)
+        v.emplace_back(
+        [&ioc]
+        {
+            ioc.run();
+        });
+    ioc.run();
+
+    return EXIT_SUCCESS;
+}
+
+#else
+
+int main(int, char * [])
+{
+    std::printf("awaitables require C++20\n");
+    return 1;
+}
+
+#endif

example/websocket/client/CMakeLists.txt

@@ -8,6 +8,7 @@
 #
 
 add_subdirectory (async)
+add_subdirectory (awaitable)
 add_subdirectory (coro)
 add_subdirectory (sync)
 

example/websocket/client/Jamfile

@@ -8,6 +8,7 @@
 #
 
 build-project async ;
+build-project awaitable ;
 build-project coro ;
 build-project sync ;
 

example/websocket/client/awaitable/CMakeLists.txt

@@ -0,0 +1,23 @@
+#
+# Copyright (c) 2016-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)
+#
+# Official repository: https://github.com/boostorg/beast
+#
+
+GroupSources(include/boost/beast beast)
+GroupSources(example/websocket/client/awaitable "/")
+
+add_executable (websocket-client-awaitable
+    ${BOOST_BEAST_FILES}
+    Jamfile
+        websocket_client_awaitable.cpp
+)
+
+target_link_libraries(websocket-client-awaitable
+    lib-asio
+    lib-beast)
+
+set_property(TARGET websocket-client-awaitable PROPERTY FOLDER "example-websocket-client")

example/websocket/client/awaitable/Jamfile

@@ -0,0 +1,15 @@
+#
+# Copyright (c) 2016-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)
+#
+# Official repository: https://github.com/boostorg/beast
+#
+
+exe websocket-client-awaitable :
+    websocket_client_awaitable.cpp
+    :
+    <variant>coverage:<build>no
+    <variant>ubasan:<build>no
+    ;

example/websocket/client/awaitable/websocket_client_awaitable.cpp

@@ -0,0 +1,162 @@
+//
+// Copyright (c) 2022 Klemens D. Morgenstern (klemens dot morgenstern at gmx dot net)
+//
+// 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)
+//
+// Official repository: https://github.com/boostorg/beast
+//
+
+//------------------------------------------------------------------------------
+//
+// Example: WebSocket client, coroutine
+//
+//------------------------------------------------------------------------------
+
+#include <boost/beast/core.hpp>
+#include <boost/beast/websocket.hpp>
+#include <cstdlib>
+#include <functional>
+#include <iostream>
+#include <string>
+#include <boost/asio/awaitable.hpp>
+#include <boost/asio/co_spawn.hpp>
+#include <boost/asio/detached.hpp>
+#include <boost/asio/use_awaitable.hpp>
+
+#if defined(BOOST_ASIO_HAS_CO_AWAIT)
+
+
+namespace beast = boost::beast;         // from <boost/beast.hpp>
+namespace http = beast::http;           // from <boost/beast/http.hpp>
+namespace websocket = beast::websocket; // from <boost/beast/websocket.hpp>
+namespace net = boost::asio;            // from <boost/asio.hpp>
+using tcp = boost::asio::ip::tcp;       // from <boost/asio/ip/tcp.hpp>
+
+//------------------------------------------------------------------------------
+
+// Report a failure
+void
+fail(beast::error_code ec, char const* what)
+{
+    std::cerr << what << ": " << ec.message() << "\n";
+}
+
+// Sends a WebSocket message and prints the response
+net::awaitable<void>
+do_session(
+    std::string host,
+    std::string port,
+    std::string text)
+{
+    // These objects perform our I/O
+    auto resolver = net::use_awaitable.as_default_on(
+            tcp::resolver(co_await net::this_coro::executor));
+    auto ws = net::use_awaitable.as_default_on(
+            websocket::stream<beast::tcp_stream>(co_await net::this_coro::executor));
+
+    // Look up the domain name
+    auto const results = co_await resolver.async_resolve(host, port);
+
+    // Set a timeout on the operation
+    beast::get_lowest_layer(ws).expires_after(std::chrono::seconds(30));
+
+    // Make the connection on the IP address we get from a lookup
+    auto ep = co_await beast::get_lowest_layer(ws).async_connect(results);
+
+    // 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());
+
+    // Turn off the timeout on the tcp_stream, because
+    // the websocket stream has its own timeout system.
+    beast::get_lowest_layer(ws).expires_never();
+
+    // Set suggested timeout settings for the websocket
+    ws.set_option(
+        websocket::stream_base::timeout::suggested(
+            beast::role_type::client));
+
+    // Set a decorator to change the User-Agent of the handshake
+    ws.set_option(websocket::stream_base::decorator(
+        [](websocket::request_type& req)
+        {
+            req.set(http::field::user_agent,
+                std::string(BOOST_BEAST_VERSION_STRING) +
+                    " websocket-client-coro");
+        }));
+
+    // Perform the websocket handshake
+    co_await ws.async_handshake(host, "/");
+
+    // Send the message
+    co_await ws.async_write(net::buffer(std::string(text)));
+
+    // This buffer will hold the incoming message
+    beast::flat_buffer buffer;
+
+    // Read a message into our buffer
+    co_await ws.async_read(buffer);
+
+    // Close the WebSocket connection
+    co_await ws.async_close(websocket::close_code::normal);
+
+    // If we get here then the connection is closed gracefully
+
+    // The make_printable() function helps print a ConstBufferSequence
+    std::cout << beast::make_printable(buffer.data()) << std::endl;
+}
+
+//------------------------------------------------------------------------------
+
+int main(int argc, char** argv)
+{
+    // Check command line arguments.
+    if(argc != 4)
+    {
+        std::cerr <<
+            "Usage: websocket-client-awaitable <host> <port> <text>\n" <<
+            "Example:\n" <<
+            "    websocket-client-awaitable echo.websocket.org 80 \"Hello, world!\"\n";
+        return EXIT_FAILURE;
+    }
+    auto const host = argv[1];
+    auto const port = argv[2];
+    auto const text = argv[3];
+
+    // The io_context is required for all I/O
+    net::io_context ioc;
+
+    // Launch the asynchronous operation
+    net::co_spawn(ioc,
+                  do_session(host, port, text),
+                  [](std::exception_ptr e)
+                  {
+                      if (e)
+                          try
+                          {
+                              std::rethrow_exception(e);
+                          }
+                          catch(std::exception & e)
+                          {
+                              std::cerr << "Error: " << e.what() << "\n";
+                          }
+                  });
+
+    // Run the I/O service. The call will return when
+    // the socket is closed.
+    ioc.run();
+
+    return EXIT_SUCCESS;
+}
+
+#else
+
+int main(int, char * [])
+{
+    std::printf("awaitables require C++20\n");
+    return 1;
+}
+
+#endif

example/websocket/server/CMakeLists.txt

@@ -8,6 +8,7 @@
 #
 
 add_subdirectory (async)
+add_subdirectory (awaitable)
 add_subdirectory (chat-multi)
 add_subdirectory (coro)
 add_subdirectory (fast)

example/websocket/server/Jamfile

@@ -8,6 +8,7 @@
 #
 
 build-project async ;
+build-project awaitable ;
 build-project chat-multi ;
 build-project coro ;
 build-project fast ;

example/websocket/server/awaitable/CMakeLists.txt

@@ -0,0 +1,23 @@
+#
+# Copyright (c) 2016-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)
+#
+# Official repository: https://github.com/boostorg/beast
+#
+
+GroupSources(include/boost/beast beast)
+GroupSources(example/websocket/server/awaitable "/")
+
+add_executable (websocket-server-awaitable
+    ${BOOST_BEAST_FILES}
+    Jamfile
+        websocket_server_awaitable.cpp
+)
+
+target_link_libraries(websocket-server-awaitable
+    lib-asio
+    lib-beast)
+
+set_property(TARGET websocket-server-awaitable PROPERTY FOLDER "example-websocket-server")

example/websocket/server/awaitable/Jamfile

@@ -0,0 +1,15 @@
+#
+# Copyright (c) 2016-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)
+#
+# Official repository: https://github.com/boostorg/beast
+#
+
+exe websocket-server-awaitable :
+    websocket_server_awaitable.cpp
+    :
+    <variant>coverage:<build>no
+    <variant>ubasan:<build>no
+    ;

example/websocket/server/awaitable/websocket_server_awaitable.cpp

@@ -0,0 +1,181 @@
+//
+// Copyright (c) 2022 Klemens D. Morgenstern (klemens dot morgenstern at gmx dot net)
+//
+// 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)
+//
+// Official repository: https://github.com/boostorg/beast
+//
+
+//------------------------------------------------------------------------------
+//
+// Example: WebSocket server, coroutine
+//
+//------------------------------------------------------------------------------
+
+#include <boost/beast/core.hpp>
+#include <boost/beast/websocket.hpp>
+#include <boost/asio/awaitable.hpp>
+#include <boost/asio/co_spawn.hpp>
+#include <boost/asio/detached.hpp>
+#include <boost/asio/use_awaitable.hpp>
+#include <algorithm>
+#include <cstdlib>
+#include <functional>
+#include <iostream>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+#if defined(BOOST_ASIO_HAS_CO_AWAIT)
+
+namespace beast = boost::beast;         // from <boost/beast.hpp>
+namespace http = beast::http;           // from <boost/beast/http.hpp>
+namespace websocket = beast::websocket; // from <boost/beast/websocket.hpp>
+namespace net = boost::asio;            // from <boost/asio.hpp>
+using tcp = boost::asio::ip::tcp;       // from <boost/asio/ip/tcp.hpp>
+
+using stream = websocket::stream<
+        typename beast::tcp_stream::rebind_executor<
+            typename net::use_awaitable_t<>::executor_with_default<net::any_io_executor>>::other>;
+
+//------------------------------------------------------------------------------
+
+// Echoes back all received WebSocket messages
+net::awaitable<void>
+do_session(stream ws)
+{
+    // Set suggested timeout settings for the websocket
+    ws.set_option(
+        websocket::stream_base::timeout::suggested(
+            beast::role_type::server));
+
+    // Set a decorator to change the Server of the handshake
+    ws.set_option(websocket::stream_base::decorator(
+        [](websocket::response_type& res)
+        {
+            res.set(http::field::server,
+                std::string(BOOST_BEAST_VERSION_STRING) +
+                    " websocket-server-coro");
+        }));
+
+    // Accept the websocket handshake
+    co_await ws.async_accept();
+
+    for(;;)
+        try {
+            // This buffer will hold the incoming message
+            beast::flat_buffer buffer;
+
+            // Read a message
+            co_await ws.async_read(buffer);
+
+            // Echo the message back
+            ws.text(ws.got_text());
+            co_await ws.async_write(buffer.data());
+
+        }
+        catch(boost::system::system_error & se)
+        {
+            if (se.code() != websocket::error::closed)
+                throw;
+
+        }
+}
+
+//------------------------------------------------------------------------------
+
+// Accepts incoming connections and launches the sessions
+net::awaitable<void>
+do_listen(
+    tcp::endpoint endpoint)
+{
+
+    // Open the acceptor
+    auto acceptor = net::use_awaitable.as_default_on(tcp::acceptor(co_await net::this_coro::executor));
+    acceptor.open(endpoint.protocol());
+
+    // Allow address reuse
+    acceptor.set_option(net::socket_base::reuse_address(true));
+
+    // Bind to the server address
+    acceptor.bind(endpoint);
+
+    // Start listening for connections
+    acceptor.listen(net::socket_base::max_listen_connections);
+
+    for(;;)
+        boost::asio::co_spawn(
+                acceptor.get_executor(),
+                do_session(stream(co_await acceptor.async_accept())),
+                [](std::exception_ptr e)
+                {
+                    try
+                    {
+                        std::rethrow_exception(e);
+                    }
+                    catch (std::exception &e) {
+                        std::cerr << "Error in session: " << e.what() << "\n";
+                    }
+                });
+}
+
+int main(int argc, char* argv[])
+{
+    // Check command line arguments.
+    if (argc != 4)
+    {
+        std::cerr <<
+            "Usage: websocket-server-awaitable <address> <port> <threads>\n" <<
+            "Example:\n" <<
+            "    websocket-server-awaitable 0.0.0.0 8080 1\n";
+        return EXIT_FAILURE;
+    }
+    auto const address = net::ip::make_address(argv[1]);
+    auto const port = static_cast<unsigned short>(std::atoi(argv[2]));
+    auto const threads = std::max<int>(1, std::atoi(argv[3]));
+
+    // The io_context is required for all I/O
+    net::io_context ioc(threads);
+
+    // Spawn a listening port
+    boost::asio::co_spawn(
+              ioc,
+              do_listen(tcp::endpoint{address, port}),
+              [](std::exception_ptr e)
+              {
+                  if (e)
+                      try
+                      {
+                          std::rethrow_exception(e);
+                      }
+                      catch(std::exception & e)
+                      {
+                          std::cerr << "Error: " << e.what() << "\n";
+                      }
+            });
+
+    // Run the I/O service on the requested number of threads
+    std::vector<std::thread> v;
+    v.reserve(threads - 1);
+    for(auto i = threads - 1; i > 0; --i)
+        v.emplace_back(
+        [&ioc]
+        {
+            ioc.run();
+        });
+    ioc.run();
+
+    return EXIT_SUCCESS;
+}
+
+#else
+
+int main(int, char * [])
+{
+    std::printf("awaitables require C++20\n");
+    return 1;
+}
+
+#endif