role_type is in boost/beast/core/role.hpp (API Change):

This enumeration is now part of the library core and
not specific to websocket.

CHANGELOG.md

@@ -1,6 +1,12 @@
 Version 221:
 
 * Rename to async_base, stable_async_base
+* role_type is in boost/beast/core/role.hpp (API Change)
+
+Actions Required:
+
+* Include <boost/beast/core/role.hpp> or
+  define BOOST_BEAST_ALLOW_DEPRECATED=1
 
 --------------------------------------------------------------------------------
 

doc/qbk/04_http/_http.qbk

@@ -7,7 +7,7 @@
     Official repository: https://github.com/boostorg/beast
 ]
 
-[section Using HTTP]
+[section:using_http HTTP]
 
 [warning
     Higher level functions such as Basic

doc/qbk/05_http_examples/_http_examples.qbk

@@ -7,7 +7,7 @@
     Official repository: https://github.com/boostorg/beast
 ]
 
-[section More Examples]
+[section:more_examples HTTP 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

doc/qbk/06_websocket/01_connecting.qbk

@@ -7,7 +7,7 @@
     Official repository: https://github.com/boostorg/beast
 ]
 
-[section Establishing Connections]
+[section:establishing_connections Connecting]
 
 Connections are established by invoking functions directly on the next layer
 object. For example, to make an outgoing connection using a standard TCP/IP

doc/qbk/06_websocket/01_streams.qbk

@@ -1,85 +0,0 @@
-[/
-    Copyright (c) 2016-2019 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
-]
-
-[section Creating Streams]
-
-The interface to the WebSocket implementation is a single template class
-[link beast.ref.boost__beast__websocket__stream `stream`]:
-
-[ws_snippet_26]
-
-An instance of the stream wraps an existing network transport object
-or other type of octet oriented stream. The wrapped object is called
-the "next layer" and must meet the requirements of __SyncStream__ if
-synchronous operations are performed, __AsyncStream__ if asynchronous
-operations are performed, or both. Any arguments supplied to the
-constructor of the stream wrapper are forwarded to next layer's constructor.
-
-The value of `deflateSupported` determines if the stream will support
-(but not require) the permessage-deflate extension
-([@https://tools.ietf.org/html/rfc7692 rfc7692])
-negotiation during handshaking. This extension allows messages to be
-optionally automatically compressed using the deflate algorithm prior
-to transmission. When this boolean value is `false`, the extension is
-disabled. Applications which do not intend to use the permessage-deflate
-extension may set the value to `false` to enjoy a reduction in the size
-of the compiled output, as the necessary compression code (included with
-Beast) will not be compiled in.
-
-Here we declare a websocket stream over a TCP/IP socket with ownership
-of the socket. The `io_context` argument is forwarded to the wrapped
-socket's constructor:
-
-[ws_snippet_2]
-
-[heading Using SSL]
-
-To use WebSockets over SSL, use an instance of the __ssl_stream__
-class template as the template type for the stream. The required
-__io_context__ and __ssl_context__ arguments are forwarded to the
-wrapped stream's constructor:
-
-[wss_snippet_1]
-[wss_snippet_2]
-
-[important
-    Code which declares websocket stream objects using Asio SSL types
-    must include the file [include_file boost/beast/websocket/ssl.hpp].
-]
-
-[heading Non-owning References]
-
-If a socket type supports move construction, a websocket stream may be
-constructed around the already existing socket by invoking the move
-constructor signature:
-
-[ws_snippet_3]
-
-Or, the wrapper can be constructed with a non-owning reference. In
-this case, the caller is responsible for managing the lifetime of the
-underlying socket being wrapped:
-
-[ws_snippet_4]
-
-Once the WebSocket stream wrapper is created, the wrapped object may be
-accessed by calling
-[link beast.ref.boost__beast__websocket__stream.next_layer.overload1 `stream::next_layer`]:
-
-[ws_snippet_5]
-
-[warning
-    Initiating operations on the next layer while websocket
-    operations are being performed may result in undefined behavior.
-]
-
-[heading Non-Blocking Mode]
-
-Please note that websocket streams do not support non-blocking modes.
-
-[endsect]

doc/qbk/06_websocket/0_websocket.qbk

@@ -1,42 +0,0 @@
-[/
-    Copyright (c) 2016-2019 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
-]
-
-[section Using WebSocket]
-
-The WebSocket Protocol enables two-way communication between a client
-running untrusted code in a controlled environment to a remote host that has
-opted-in to communications from that code. The protocol consists of an opening
-handshake followed by basic message framing, layered over TCP.  The goal of
-this technology is to provide a mechanism for browser-based applications
-needing two-way communication with servers without relying on opening multiple
-HTTP connections.
-
-Beast provides developers with a robust WebSocket implementation built on
-Boost.Asio with a consistent asynchronous model using a modern C++ approach.
-
-[note
-    This documentation assumes familiarity with __Asio__ and
-    the protocol specification described in __rfc6455__.
-    Sample code and identifiers appearing in this section is written
-    as if these declarations are in effect:
-
-    [ws_snippet_1]
-]
-
-[include 01_streams.qbk]
-[include 02_connect.qbk]
-[include 03_client.qbk]
-[include 04_server.qbk]
-[include 05_decorator.qbk]
-[include 06_messages.qbk]
-[include 07_control.qbk]
-[include 08_teardown.qbk]
-[include 09_notes.qbk]
-
-[endsect]

doc/qbk/06_websocket/_websocket.qbk

@@ -0,0 +1,155 @@
+[/
+    Copyright (c) 2016-2019 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
+]
+
+[section:using_websocket WebSocket __new__]
+
+[/-----------------------------------------------------------------------------]
+
+The WebSocket Protocol enables two-way communication between a client running
+untrusted code in a controlled environment to a remote host that has opted-in
+to communications from that code. The protocol consists of an opening handshake
+followed by basic message framing, layered over TCP.  The goal of this
+technology is to provide a mechanism for browser-based applications needing
+two-way communication with servers without relying on opening multiple HTTP
+connections.
+
+Beast provides developers with a robust WebSocket implementation
+built on Boost.Asio with a consistent asynchronous model using a modern C++
+approach.
+
+[note
+    This documentation assumes familiarity with __Asio__ and
+    the protocol specification described in __rfc6455__.
+    Sample code and identifiers appearing in this section is written
+    as if these declarations are in effect:
+
+    [code_websocket_1a]
+    '''<?linebreak?>'''
+    [code_websocket_1b]
+]
+
+[/-----------------------------------------------------------------------------]
+
+[heading Construction]
+
+A WebSocket connection requires a stateful object, represented in Beast by a
+single class template
+[link beast.ref.boost__beast__websocket__stream `websocket::stream`].
+The interface uses the layered stream model. A websocket stream object contains
+another stream object, called the "next layer", which it uses to perform I/O.
+Descriptions of each template parameter follow:
+
+[code_websocket_1h]
+
+[table WebSocket Stream Template Parameters
+[[Name][Description]]
+[
+    [`NextLayer`]
+    [
+      The type of the next layer. An object of this type will be constructed
+      and maintained for the lifetime of the stream. All reads and writes
+      will go through the next layer. This type must meet the requirements
+      of either __SyncStream__, __AsyncStream__, or both, depending on the
+      style of I/O that is to be performed.
+    ]
+][
+    [`deflateSupported`]
+    [
+      When this value is `true`, the stream will support (but not require)
+      the [@https://tools.ietf.org/html/rfc7692 permessage-deflate extension].
+      Whether or not the stream actually requests or accepts the extension
+      during a handshake depends on a separate configurable option.
+
+      When the value is `false` the extension is disabled. Streams will
+      never request the extension in the client role or accept a request
+      for the extension in the server role. An additional benefit of
+      disabling the extension is that compilation will be faster, and
+      the resulting program executable will contain less code.
+    ]
+]]
+
+When a stream is constructed, any arguments provided to the constructor are
+forwarded to the next layer object's constructor. This declares a stream
+over a plain TCP/IP socket using an I/O context:
+
+[code_websocket_1f]
+
+[tip
+    Websocket streams use their own protocol-specific timeout feature. When
+    using a websocket stream with the
+    [link beast.ref.boost__beast__tcp_stream `tcp_stream`] or
+    [link beast.ref.boost__beast__basic_stream `basic_stream`]
+    class template, timeouts should be disabled on the TCP or basic stream
+    after the connection is established, otherwise the behavior of the
+    stream is undefined.
+]
+
+As with most I/O objects, a websocket stream is [*not thread-safe]. Undefined
+behavior results if two different threads access the object concurrently.
+For multi-threaded programs, the `tcp_stream` can be constructed from an
+executor, in this case a strand. The stream declared below will use a
+strand to invoke all completion handlers:
+
+[code_websocket_2f]
+
+[heading Using SSL]
+
+To use WebSockets over SSL, use an instance of the __ssl_stream__
+class template as the template type for the stream. The required
+__io_context__ and __ssl_context__ arguments are forwarded to the
+wrapped stream's constructor:
+
+[code_websocket_3f]
+
+[important
+    Code which declares websocket stream objects using Asio SSL types
+    must include the file [include_file boost/beast/websocket/ssl.hpp].
+]
+
+[heading Non-owning References]
+
+If a socket type supports move construction, a websocket stream may be
+constructed around the already existing socket by invoking the move
+constructor signature:
+
+[ws_snippet_3]
+
+Or, the wrapper can be constructed with a non-owning reference. In
+this case, the caller is responsible for managing the lifetime of the
+underlying socket being wrapped:
+
+[ws_snippet_4]
+
+Once the WebSocket stream wrapper is created, the wrapped object may be
+accessed by calling
+[link beast.ref.boost__beast__websocket__stream.next_layer.overload1 `stream::next_layer`]:
+
+[ws_snippet_5]
+
+[warning
+    Initiating operations on the next layer while websocket
+    operations are being performed may result in undefined behavior.
+]
+
+[heading Non-Blocking Mode]
+
+Please note that websocket streams do not support non-blocking modes.
+
+
+
+[include 01_connecting.qbk]
+[include 03_client.qbk]
+[include 04_server.qbk]
+[include 05_decorator.qbk]
+[include 06_messages.qbk]
+[include 07_control.qbk]
+[include 08_teardown.qbk]
+[include 09_notes.qbk]
+
+[endsect]

doc/qbk/main.qbk

@@ -64,7 +64,7 @@
 [def __AsyncWriteStream__       [@boost:/doc/html/boost_asio/reference/AsyncWriteStream.html ['AsyncWriteStream]]]
 [def __CompletionCondition__    [@boost:/doc/html/boost_asio/reference/CompletionCondition.html ['CompletionCondition]]]
 [def __CompletionHandler__      [@boost:/doc/html/boost_asio/reference/CompletionHandler.html ['CompletionHandler]]]
-[def __CompletionToken__        [@boost:/doc/html/boost_asio/reference/asynchronous_operations#boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers ['CompletionToken]]]
+[def __CompletionToken__        [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html#boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers ['CompletionToken]]]
 [def __ConnectCondition__       [@boost:/doc/html/boost_asio/reference/ConnectCondition.html ['ConnectCondition]]]
 [def __ConnectHandler__         [@boost:/doc/html/boost_asio/reference/ConnectHandler.html ['ConnectHandler]]]
 [def __ConstBufferSequence__    [@boost:/doc/html/boost_asio/reference/ConstBufferSequence.html ['ConstBufferSequence]]]
@@ -133,6 +133,7 @@
 [import ../../example/websocket/client/sync/websocket_client_sync.cpp]
 
 [import ../../include/boost/beast/http/basic_file_body.hpp]
+[import ../../include/boost/beast/websocket/stream_fwd.hpp]
 
 [import ../../test/doc/exemplars.cpp]
 [import ../../test/doc/core_snippets.cpp]
@@ -143,6 +144,7 @@
 [import ../../test/doc/core_3_timeouts.cpp]
 [import ../../test/doc/core_4_layers.cpp]
 [import ../../test/doc/http_10_custom_parser.cpp]
+[import ../../test/doc/websocket.cpp]
 [import ../../test/doc/websocket_3_handshake.cpp]
 
 [import ../../include/boost/beast/core/detect_ssl.hpp]
@@ -171,11 +173,11 @@ __new__ indicates an item that is new in this version.
 [include 01_intro/_intro.qbk]
 [include 02_examples/_examples.qbk]
 [include 03_core/_core.qbk]
-[include 04_http/0_http.qbk]
+[include 04_http/_http.qbk]
-[include 05_http_examples/0_http_examples.qbk]
+[include 05_http_examples/_http_examples.qbk]
-[include 06_websocket/0_websocket.qbk]
+[include 06_websocket/_websocket.qbk]
-[include 07_concepts/0_concepts.qbk]
+[include 07_concepts/_concepts.qbk]
-[include 08_design/0_design.qbk]
+[include 08_design/_design.qbk]
 
 [section:moved1 Release Notes (Moved)]
 The Release Notes have been moved to the top of the table of contents.

doc/qbk/quickref.xml

@@ -58,6 +58,7 @@
           <member><link linkend="beast.ref.boost__beast__condition">condition</link>&nbsp;<emphasis role="green">&#9733;</emphasis></member>
           <member><link linkend="beast.ref.boost__beast__error">error</link>&nbsp;<emphasis role="green">&#9733;</emphasis></member>
           <member><link linkend="beast.ref.boost__beast__file_mode">file_mode</link></member>
+          <member><link linkend="beast.ref.boost__beast__role_type">role_type</link>&nbsp;<emphasis role="green">&#9733;</emphasis></member>
         </simplelist>
       </entry>
       <entry valign="top">
@@ -312,7 +313,6 @@
           <member><link linkend="beast.ref.boost__beast__websocket__condition">condition</link></member>
           <member><link linkend="beast.ref.boost__beast__websocket__error">error</link></member>
           <member><link linkend="beast.ref.boost__beast__websocket__frame_type">frame_type</link></member>
-          <member><link linkend="beast.ref.boost__beast__websocket__role_type">role_type</link></member>
         </simplelist>
       </entry>
     </row></tbody>

doc/qbk/release_notes.qbk

@@ -261,6 +261,8 @@
     `file_mode::append_existing`
     as needed.
 
+* `role_type` is moved from `websocket` to `beast`
+
 * `buffers_range_ref`
   is preferred to `std::reference_wrapper`.
   ['Actions Required]:

doc/source.dox

@@ -8,7 +8,7 @@ PROJECT_BRIEF          = C++ Networking Library
 PROJECT_LOGO           =
 OUTPUT_DIRECTORY       =
 CREATE_SUBDIRS         = NO
-ALLOW_UNICODE_NAMES    = NO
+#####ALLOW_UNICODE_NAMES    = NO
 OUTPUT_LANGUAGE        = English
 BRIEF_MEMBER_DESC      = YES
 REPEAT_BRIEF           = YES
@@ -39,7 +39,7 @@ CPP_CLI_SUPPORT        = NO
 SIP_SUPPORT            = NO
 IDL_PROPERTY_SUPPORT   = YES
 DISTRIBUTE_GROUP_DOC   = YES
-GROUP_NESTED_COMPOUNDS = NO
+#####GROUP_NESTED_COMPOUNDS = NO
 SUBGROUPING            = YES
 INLINE_GROUPED_CLASSES = NO
 INLINE_SIMPLE_STRUCTS  = NO
@@ -63,7 +63,7 @@ HIDE_IN_BODY_DOCS      = NO
 INTERNAL_DOCS          = NO
 CASE_SENSE_NAMES       = YES
 HIDE_SCOPE_NAMES       = NO
-HIDE_COMPOUND_REFERENCE= NO
+#####HIDE_COMPOUND_REFERENCE= NO
 SHOW_INCLUDE_FILES     = NO
 SHOW_GROUPED_MEMB_INC  = NO
 FORCE_LOCAL_INCLUDES   = NO
@@ -95,7 +95,7 @@ WARNINGS               = YES
 WARN_IF_UNDOCUMENTED   = YES
 WARN_IF_DOC_ERROR      = YES
 WARN_NO_PARAMDOC       = NO
-WARN_AS_ERROR          = NO
+#####WARN_AS_ERROR          = NO
 WARN_FORMAT            = "$file:$line: $text"
 WARN_LOGFILE           =
 
@@ -112,6 +112,7 @@ INPUT = \
         $(LIB_DIR)/include/boost/beast/websocket \
         $(LIB_DIR)/include/boost/beast/zlib
 
+
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          =
 RECURSIVE              = NO
@@ -210,47 +211,14 @@ SEARCHDATA_FILE        = searchdata.xml
 EXTERNAL_SEARCH_ID     =
 EXTRA_SEARCH_MAPPINGS  =
 
-#---------------------------------------------------------------------------
-# Configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
 GENERATE_LATEX         = NO
-LATEX_OUTPUT           = latex
-LATEX_CMD_NAME         = latex
-MAKEINDEX_CMD_NAME     = makeindex
-COMPACT_LATEX          = NO
-PAPER_TYPE             = a4
-EXTRA_PACKAGES         =
-LATEX_HEADER           =
-LATEX_FOOTER           =
-LATEX_EXTRA_STYLESHEET =
-LATEX_EXTRA_FILES      =
-PDF_HYPERLINKS         = YES
-USE_PDFLATEX           = YES
-LATEX_BATCHMODE        = NO
-LATEX_HIDE_INDICES     = NO
-LATEX_SOURCE_CODE      = NO
-LATEX_BIB_STYLE        = plain
-LATEX_TIMESTAMP        = NO
-
-#---------------------------------------------------------------------------
-# Configuration options related to the RTF output
-#---------------------------------------------------------------------------
 GENERATE_RTF           = NO
-RTF_OUTPUT             = rtf
-COMPACT_RTF            = NO
-RTF_HYPERLINKS         = NO
-RTF_STYLESHEET_FILE    =
-RTF_EXTENSIONS_FILE    =
-RTF_SOURCE_CODE        = NO
-
-#---------------------------------------------------------------------------
-# Configuration options related to the man page output
-#---------------------------------------------------------------------------
 GENERATE_MAN           = NO
-MAN_OUTPUT             = man
+GENERATE_DOCBOOK       = NO
-MAN_EXTENSION          = .3
+GENERATE_AUTOGEN_DEF   = NO
-MAN_SUBDIR             =
+GENERATE_PERLMOD       = NO
-MAN_LINKS              = NO
+CLASS_DIAGRAMS         = NO
+HAVE_DOT               = NO
 
 #---------------------------------------------------------------------------
 # Configuration options related to the XML output
@@ -259,22 +227,6 @@ GENERATE_XML           = YES
 XML_OUTPUT             = $(XML_OUTPUT)
 XML_PROGRAMLISTING     = YES
 
-#---------------------------------------------------------------------------
-# Configuration options related to the DOCBOOK output
-#---------------------------------------------------------------------------
-GENERATE_DOCBOOK       = NO
-DOCBOOK_OUTPUT         = docbook
-DOCBOOK_PROGRAMLISTING = NO
-
-#---------------------------------------------------------------------------
-# Configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-GENERATE_AUTOGEN_DEF   = NO
-GENERATE_PERLMOD       = NO
-PERLMOD_LATEX          = NO
-PERLMOD_PRETTY         = YES
-PERLMOD_MAKEVAR_PREFIX =
-
 #---------------------------------------------------------------------------
 # Configuration options related to the preprocessor
 #---------------------------------------------------------------------------
@@ -305,42 +257,3 @@ ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
 EXTERNAL_PAGES         = YES
 PERL_PATH              = /usr/bin/perl
-
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool
-#---------------------------------------------------------------------------
-CLASS_DIAGRAMS         = NO
-MSCGEN_PATH            =
-DIA_PATH               =
-HIDE_UNDOC_RELATIONS   = YES
-HAVE_DOT               = NO
-DOT_NUM_THREADS        = 0
-DOT_FONTNAME           = Helvetica
-DOT_FONTSIZE           = 10
-DOT_FONTPATH           =
-CLASS_GRAPH            = YES
-COLLABORATION_GRAPH    = YES
-GROUP_GRAPHS           = YES
-UML_LOOK               = NO
-UML_LIMIT_NUM_FIELDS   = 10
-TEMPLATE_RELATIONS     = NO
-INCLUDE_GRAPH          = YES
-INCLUDED_BY_GRAPH      = YES
-CALL_GRAPH             = NO
-CALLER_GRAPH           = NO
-GRAPHICAL_HIERARCHY    = YES
-DIRECTORY_GRAPH        = YES
-DOT_IMAGE_FORMAT       = png
-INTERACTIVE_SVG        = NO
-DOT_PATH               =
-DOTFILE_DIRS           =
-MSCFILE_DIRS           =
-DIAFILE_DIRS           =
-PLANTUML_JAR_PATH      =
-PLANTUML_INCLUDE_PATH  =
-DOT_GRAPH_MAX_NODES    = 50
-MAX_DOT_GRAPH_DEPTH    = 0
-DOT_TRANSPARENT        = NO
-DOT_MULTI_TARGETS      = NO
-GENERATE_LEGEND        = YES
-DOT_CLEANUP            = YES

example/advanced/server-flex/advanced_server_flex.cpp

@@ -268,7 +268,7 @@ public:
         // Set suggested timeout settings for the websocket
         derived().ws().set_option(
             websocket::stream_base::suggested_settings(
-                websocket::role_type::server));
+                beast::role_type::server));
 
         // Set a decorator to change the Server of the handshake
         derived().ws().set_option(

example/advanced/server/advanced_server.cpp

@@ -238,7 +238,7 @@ public:
         // Set suggested timeout settings for the websocket
         ws_.set_option(
             websocket::stream_base::suggested_settings(
-                websocket::role_type::server));
+                beast::role_type::server));
 
         // Set a decorator to change the Server of the handshake
         ws_.set_option(websocket::stream_base::decorator(

example/websocket/client/async-ssl/websocket_client_async_ssl.cpp

@@ -129,7 +129,7 @@ public:
         // Set suggested timeout settings for the websocket
         ws_.set_option(
             websocket::stream_base::suggested_settings(
-                websocket::role_type::client));
+                beast::role_type::client));
 
         // Set a decorator to change the User-Agent of the handshake
         ws_.set_option(websocket::stream_base::decorator(

example/websocket/client/async/websocket_client_async.cpp

@@ -106,7 +106,7 @@ public:
         // Set suggested timeout settings for the websocket
         ws_.set_option(
             websocket::stream_base::suggested_settings(
-                websocket::role_type::client));
+                beast::role_type::client));
 
         // Set a decorator to change the User-Agent of the handshake
         ws_.set_option(websocket::stream_base::decorator(

example/websocket/client/coro-ssl/websocket_client_coro_ssl.cpp

@@ -95,7 +95,7 @@ do_session(
     // Set suggested timeout settings for the websocket
     ws.set_option(
         websocket::stream_base::suggested_settings(
-            websocket::role_type::client));
+            beast::role_type::client));
 
     // Perform the websocket handshake
     ws.async_handshake(host, "/", yield[ec]);

example/websocket/client/coro/websocket_client_coro.cpp

@@ -71,7 +71,7 @@ do_session(
     // Set suggested timeout settings for the websocket
     ws.set_option(
         websocket::stream_base::suggested_settings(
-            websocket::role_type::client));
+            beast::role_type::client));
 
     // Set a decorator to change the User-Agent of the handshake
     ws.set_option(websocket::stream_base::decorator(

example/websocket/server/async-ssl/websocket_server_async_ssl.cpp

@@ -87,7 +87,7 @@ public:
         // Set suggested timeout settings for the websocket
         ws_.set_option(
             websocket::stream_base::suggested_settings(
-                websocket::role_type::server));
+                beast::role_type::server));
 
         // Set a decorator to change the Server of the handshake
         ws_.set_option(websocket::stream_base::decorator(

example/websocket/server/async/websocket_server_async.cpp

@@ -61,7 +61,7 @@ public:
         // Set suggested timeout settings for the websocket
         ws_.set_option(
             websocket::stream_base::suggested_settings(
-                websocket::role_type::server));
+                beast::role_type::server));
 
         // Set a decorator to change the Server of the handshake
         ws_.set_option(websocket::stream_base::decorator(

example/websocket/server/chat-multi/websocket_session.hpp

@@ -64,7 +64,7 @@ run(http::request<Body, http::basic_fields<Allocator>> req)
     // Set suggested timeout settings for the websocket
     ws_.set_option(
         websocket::stream_base::suggested_settings(
-            websocket::role_type::server));
+            beast::role_type::server));
 
     // Set a decorator to change the Server of the handshake
     ws_.set_option(websocket::stream_base::decorator(

example/websocket/server/coro-ssl/websocket_server_coro_ssl.cpp

@@ -69,7 +69,7 @@ do_session(
     // Set suggested timeout settings for the websocket
     ws.set_option(
         websocket::stream_base::suggested_settings(
-            websocket::role_type::server));
+            beast::role_type::server));
 
     // Set a decorator to change the Server of the handshake
     ws.set_option(websocket::stream_base::decorator(

example/websocket/server/coro/websocket_server_coro.cpp

@@ -51,7 +51,7 @@ do_session(
     // Set suggested timeout settings for the websocket
     ws.set_option(
         websocket::stream_base::suggested_settings(
-            websocket::role_type::server));
+            beast::role_type::server));
 
     // Set a decorator to change the Server of the handshake
     ws.set_option(websocket::stream_base::decorator(

example/websocket/server/fast/websocket_server_fast.cpp

@@ -159,7 +159,7 @@ public:
         // Set suggested timeout settings for the websocket
         ws_.set_option(
             websocket::stream_base::suggested_settings(
-                websocket::role_type::server));
+                beast::role_type::server));
 
         // Set a decorator to change the Server of the handshake
         ws_.set_option(websocket::stream_base::decorator(
@@ -339,7 +339,7 @@ do_coro_session(
     // Set suggested timeout settings for the websocket
     ws.set_option(
         websocket::stream_base::suggested_settings(
-            websocket::role_type::server));
+            beast::role_type::server));
 
     // Set a decorator to change the Server of the handshake
     ws.set_option(websocket::stream_base::decorator(

example/websocket/server/stackless-ssl/websocket_server_stackless_ssl.cpp

@@ -99,7 +99,7 @@ public:
             // Set suggested timeout settings for the websocket
             ws_.set_option(
                 websocket::stream_base::suggested_settings(
-                    websocket::role_type::server));
+                    beast::role_type::server));
 
             // Set a decorator to change the Server of the handshake
             ws_.set_option(websocket::stream_base::decorator(

example/websocket/server/stackless/websocket_server_stackless.cpp

@@ -76,7 +76,7 @@ public:
             // Set suggested timeout settings for the websocket
             ws_.set_option(
                 websocket::stream_base::suggested_settings(
-                    websocket::role_type::server));
+                    beast::role_type::server));
 
             // Set a decorator to change the Server of the handshake
             ws_.set_option(websocket::stream_base::decorator(

include/boost/beast/_experimental/test/impl/stream.hpp

@@ -392,7 +392,7 @@ async_write_some(
 template<class TeardownHandler>
 void
 async_teardown(
-    websocket::role_type,
+    role_type,
     stream& s,
     TeardownHandler&& handler)
 {

include/boost/beast/_experimental/test/impl/stream.ipp

@@ -255,7 +255,7 @@ close_remote()
 
 void
 teardown(
-    websocket::role_type,
+    role_type,
     stream& s,
     boost::system::error_code& ec)
 {

include/boost/beast/_experimental/test/stream.hpp

@@ -13,8 +13,8 @@
 #include <boost/beast/core/detail/config.hpp>
 #include <boost/beast/core/bind_handler.hpp>
 #include <boost/beast/core/flat_buffer.hpp>
+#include <boost/beast/core/role.hpp>
 #include <boost/beast/core/string.hpp>
-#include <boost/beast/websocket/role.hpp>
 #include <boost/beast/_experimental/test/fail_count.hpp>
 #include <boost/asio/async_result.hpp>
 #include <boost/asio/buffer.hpp>
@@ -494,7 +494,7 @@ public:
     BOOST_BEAST_DECL
     void
     teardown(
-        websocket::role_type,
+        role_type,
         stream& s,
         boost::system::error_code& ec);
 
@@ -503,7 +503,7 @@ public:
     BOOST_BEAST_DECL
     void
     async_teardown(
-        websocket::role_type role,
+        role_type role,
         stream& s,
         TeardownHandler&& handler);
 #endif

include/boost/beast/core/basic_stream.hpp

@@ -14,8 +14,8 @@
 #include <boost/beast/core/detail/stream_base.hpp>
 #include <boost/beast/core/error.hpp>
 #include <boost/beast/core/rate_policy.hpp>
+#include <boost/beast/core/role.hpp>
 #include <boost/beast/core/stream_traits.hpp>
-#include <boost/beast/websocket/role.hpp> // VFALCO This is unfortunate
 #include <boost/asio/async_result.hpp>
 #include <boost/asio/basic_stream_socket.hpp>
 #include <boost/asio/connect.hpp>

include/boost/beast/core/impl/basic_stream.hpp

@@ -972,7 +972,7 @@ template<
     class Protocol, class Executor, class RatePolicy>
 void
 teardown(
-    websocket::role_type role,
+    role_type role,
     basic_stream<Protocol, Executor, RatePolicy>& stream,
     error_code& ec)
 {
@@ -985,7 +985,7 @@ template<
     class TeardownHandler>
 void
 async_teardown(
-    websocket::role_type role,
+    role_type role,
     basic_stream<Protocol, Executor, RatePolicy>& stream,
     TeardownHandler&& handler)
 {

include/boost/beast/core/impl/flat_stream.hpp

@@ -255,7 +255,7 @@ async_write_some(
 template<class NextLayer>
 void
 teardown(
-    boost::beast::websocket::role_type role,
+    boost::beast::role_type role,
     flat_stream<NextLayer>& s,
     error_code& ec)
 {
@@ -266,7 +266,7 @@ teardown(
 template<class NextLayer, class TeardownHandler>
 void
 async_teardown(
-    boost::beast::websocket::role_type role,
+    boost::beast::role_type role,
     flat_stream<NextLayer>& s,
     TeardownHandler&& handler)
 {

include/boost/beast/core/role.hpp

@@ -0,0 +1,50 @@
+//
+// Copyright (c) 2016-2019 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
+//
+
+#ifndef BOOST_BEAST_ROLE_HPP
+#define BOOST_BEAST_ROLE_HPP
+
+#include <boost/beast/core/detail/config.hpp>
+
+namespace boost {
+namespace beast {
+
+/** The role of local or remote peer.
+
+    Whether the endpoint is a client or server affects the
+    behavior of teardown.
+    The teardown behavior also depends on the type of the stream
+    being torn down.
+    
+    The default implementation of teardown for regular
+    TCP/IP sockets is as follows:
+
+    @li In the client role, a TCP/IP shutdown is sent after
+    reading all remaining data on the connection.
+
+    @li In the server role, a TCP/IP shutdown is sent before
+    reading all remaining data on the connection.
+
+    When the next layer type is a `net::ssl::stream`,
+    the connection is closed by performing the SSL closing
+    handshake corresponding to the role type, client or server.
+*/
+enum class role_type
+{
+    /// The stream is operating as a client.
+    client,
+
+    /// The stream is operating as a server.
+    server
+};
+
+} // beast
+} // boost
+
+#endif

include/boost/beast/ssl/ssl_stream.hpp

@@ -658,7 +658,7 @@ public:
 template<class SyncStream>
 void
 teardown(
-    boost::beast::websocket::role_type role,
+    boost::beast::role_type role,
     ssl_stream<SyncStream>& stream,
     boost::system::error_code& ec)
 {
@@ -670,7 +670,7 @@ teardown(
 template<class AsyncStream, class TeardownHandler>
 void
 async_teardown(
-    boost::beast::websocket::role_type role,
+    boost::beast::role_type role,
     ssl_stream<AsyncStream>& stream,
     TeardownHandler&& handler)
 {

include/boost/beast/websocket.hpp

@@ -15,7 +15,6 @@
 #include <boost/beast/websocket/error.hpp>
 #include <boost/beast/websocket/option.hpp>
 #include <boost/beast/websocket/rfc6455.hpp>
-#include <boost/beast/websocket/role.hpp>
 #include <boost/beast/websocket/stream.hpp>
 #include <boost/beast/websocket/stream_fwd.hpp>
 #include <boost/beast/websocket/teardown.hpp>

include/boost/beast/websocket/detail/impl_base.hpp

@@ -10,14 +10,14 @@
 #ifndef BOOST_BEAST_WEBSOCKET_DETAIL_IMPL_BASE_HPP
 #define BOOST_BEAST_WEBSOCKET_DETAIL_IMPL_BASE_HPP
 
+#include <boost/beast/websocket/option.hpp>
+#include <boost/beast/websocket/detail/frame.hpp>
+#include <boost/beast/websocket/detail/pmd_extension.hpp>
 #include <boost/beast/core/buffer_size.hpp>
+#include <boost/beast/core/role.hpp>
 #include <boost/beast/http/empty_body.hpp>
 #include <boost/beast/http/message.hpp>
 #include <boost/beast/http/string_body.hpp>
-#include <boost/beast/websocket/option.hpp>
-#include <boost/beast/websocket/role.hpp>
-#include <boost/beast/websocket/detail/frame.hpp>
-#include <boost/beast/websocket/detail/pmd_extension.hpp>
 #include <boost/beast/zlib/deflate_stream.hpp>
 #include <boost/beast/zlib/inflate_stream.hpp>
 #include <boost/beast/core/buffers_suffix.hpp>

include/boost/beast/websocket/role.hpp

@@ -12,48 +12,24 @@
 
 #include <boost/beast/core/detail/config.hpp>
 
+#if ! BOOST_BEAST_ALLOW_DEPRECATED
+
+#error This file is deprecated interface, #define BOOST_BEAST_ALLOW_DEPRECATED to allow it
+
+#else
+
+#include <boost/beast/core/role.hpp>
+
 namespace boost {
 namespace beast {
 namespace websocket {
 
-/** The role of the websocket stream endpoint.
+using role_type = beast::role_type;
-
-    Whether the endpoint is a client or server affects the
-    behavior of the <em>Close the WebSocket Connection</em>
-    operation described in rfc6455 section 7.1.1.
-    The shutdown behavior depends on the type of the next
-    layer template parameter used to construct the @ref stream.
-    Other next layer types including user-defined types
-    may implement different role-based behavior when
-    performing the close operation.
-    
-    The default implementation for @ref stream when the next
-    layer type is a `net::ip::tcp::socket` behaves
-    as follows:
-
-    @li In the client role, a TCP/IP shutdown is sent after
-    reading all remaining data on the connection.
-
-    @li In the server role, a TCP/IP shutdown is sent before
-    reading all remaining data on the connection.
-
-    When the next layer type is a `net::ssl::stream`,
-    the connection is closed by performing the SSL closing
-    handshake corresponding to the role type, client or server.
-
-    @see https://tools.ietf.org/html/rfc6455#section-7.1.1
-*/
-enum class role_type
-{
-    /// The stream is operating as a client.
-    client,
-
-    /// The stream is operating as a server.
-    server
-};
 
 } // websocket
 } // beast
 } // boost
 
 #endif
+
+#endif

include/boost/beast/websocket/ssl.hpp

@@ -73,7 +73,6 @@ teardown(
 
 */
 template<class AsyncStream, class TeardownHandler>
-inline
 void
 async_teardown(
     role_type role,

include/boost/beast/websocket/stream.hpp

@@ -13,13 +13,13 @@
 #include <boost/beast/core/detail/config.hpp>
 #include <boost/beast/websocket/error.hpp>
 #include <boost/beast/websocket/option.hpp>
-#include <boost/beast/websocket/role.hpp>
 #include <boost/beast/websocket/rfc6455.hpp>
 #include <boost/beast/websocket/stream_base.hpp>
 #include <boost/beast/websocket/stream_fwd.hpp>
 #include <boost/beast/websocket/detail/hybi13.hpp>
 #include <boost/beast/websocket/detail/impl_base.hpp>
 #include <boost/beast/websocket/detail/pmd_extension.hpp>
+#include <boost/beast/core/role.hpp>
 #include <boost/beast/core/stream_traits.hpp>
 #include <boost/beast/core/string.hpp>
 #include <boost/beast/core/detail/type_traits.hpp>

include/boost/beast/websocket/stream_base.hpp

@@ -11,8 +11,8 @@
 #define BOOST_BEAST_WEBSOCKET_STREAM_BASE_HPP
 
 #include <boost/beast/core/detail/config.hpp>
-#include <boost/beast/websocket/role.hpp>
 #include <boost/beast/websocket/detail/decorator.hpp>
+#include <boost/beast/core/role.hpp>
 #include <chrono>
 
 namespace boost {

include/boost/beast/websocket/stream_fwd.hpp

@@ -12,6 +12,8 @@
 
 #include <boost/beast/core/detail/config.hpp>
 
+//[code_websocket_1h
+
 namespace boost {
 namespace beast {
 namespace websocket {
@@ -25,4 +27,6 @@ class stream;
 } // beast
 } // boost
 
+//]
+
 #endif

include/boost/beast/websocket/teardown.hpp

@@ -12,7 +12,7 @@
 
 #include <boost/beast/core/detail/config.hpp>
 #include <boost/beast/core/error.hpp>
-#include <boost/beast/websocket/role.hpp>
+#include <boost/beast/core/role.hpp>
 #include <boost/asio/basic_stream_socket.hpp>
 #include <type_traits>
 

test/beast/core/CMakeLists.txt

@@ -62,6 +62,7 @@ add_executable (tests-beast-core
     ostream.cpp
     rate_policy.cpp
     read_size.cpp
+    role.cpp
     saved_handler.cpp
     span.cpp
     static_buffer.cpp

test/beast/core/Jamfile

@@ -50,6 +50,7 @@ local SOURCES =
     ostream.cpp
     rate_policy.cpp
     read_size.cpp
+    role.cpp
     saved_handler.cpp
     span.cpp
     static_buffer.cpp

test/beast/core/basic_stream.cpp

@@ -1200,13 +1200,13 @@ public:
         {
             error_code ec;
             stream_type s(ioc);
-            teardown(websocket::role_type::client, s, ec);
+            teardown(role_type::client, s, ec);
         }
 
         {
             error_code ec;
             stream_type s(ioc);
-            async_teardown(websocket::role_type::server, s,
+            async_teardown(role_type::server, s,
                 [](error_code)
                 {
                 });

test/beast/core/flat_stream.cpp

@@ -14,7 +14,7 @@
 
 #include <boost/beast/_experimental/unit_test/suite.hpp>
 #include <boost/beast/_experimental/test/stream.hpp>
-#include <boost/beast/websocket/role.hpp>
+#include <boost/beast/core/role.hpp>
 #include <initializer_list>
 #include <vector>
 
@@ -162,14 +162,14 @@ public:
             flat_stream<test::stream> s(ioc);
             ts.connect(s.next_layer());
             error_code ec;
-            teardown(websocket::role_type::client, s, ec);
+            teardown(role_type::client, s, ec);
         }
 
         {
             test::stream ts(ioc);
             flat_stream<test::stream> s(ioc);
             ts.connect(s.next_layer());
-            async_teardown(websocket::role_type::client, s,
+            async_teardown(role_type::client, s,
                 [](error_code)
                 {
                 });

test/beast/core/role.cpp

@@ -8,4 +8,4 @@
 //
 
 // Test that header file is self-contained.
-#include <boost/beast/websocket/role.hpp>
+#include <boost/beast/core/role.hpp>

test/beast/websocket/CMakeLists.txt

@@ -32,7 +32,6 @@ add_executable (tests-beast-websocket
     read2.cpp
     read3.cpp
     rfc6455.cpp
-    role.cpp
     stream.cpp
     stream_base.cpp
     stream_explicit.cpp

test/beast/websocket/Jamfile

@@ -22,7 +22,6 @@ local SOURCES =
     read2.cpp
     read3.cpp
     rfc6455.cpp
-    role.cpp
     stream.cpp
     stream_base.cpp
     stream_explicit.cpp

test/doc/CMakeLists.txt

@@ -26,6 +26,7 @@ add_executable (tests-doc
     http_10_custom_parser.cpp
     http_examples.cpp
     http_snippets.cpp
+    websocket.cpp
     websocket_3_handshake.cpp
     websocket_snippets.cpp
     exemplars.cpp

test/doc/Jamfile

@@ -24,6 +24,7 @@ alias run-tests :
     [ run core_4_layers.cpp $(TEST_MAIN) ]
     [ run http_10_custom_parser.cpp $(TEST_MAIN) ]
     [ run http_examples.cpp $(TEST_MAIN) ]
+    [ run websocket.cpp $(TEST_MAIN) ]
     [ run websocket_3_handshake.cpp $(TEST_MAIN) ]
     ;
 
@@ -34,6 +35,7 @@ exe fat-tests :
     core_4_layers.cpp
     http_10_custom_parser.cpp
     http_examples.cpp
+    websocket.cpp
     websocket_3_handshake.cpp
     ;
 

test/doc/websocket.cpp

@@ -0,0 +1,97 @@
+//
+// Copyright (c) 2016-2019 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
+//
+
+#include "snippets.hpp"
+
+#include <boost/beast/_experimental/unit_test/suite.hpp>
+
+#ifdef BOOST_MSVC
+#pragma warning(push)
+#pragma warning(disable: 4459) // declaration hides global declaration
+#endif
+
+//[code_websocket_1a
+#include <boost/beast/core.hpp>
+#include <boost/beast/http.hpp>
+#include <boost/beast/ssl.hpp>
+#include <boost/beast/websocket.hpp>
+//]
+
+namespace {
+
+//[code_websocket_1b
+namespace net = boost::asio;
+using namespace boost::beast;
+using namespace boost::beast::websocket;
+
+net::io_context ioc;
+net::ssl::context ctx(net::ssl::context::sslv23);
+
+//]
+
+void
+websocket_snippets()
+{
+    {
+    //[code_websocket_1f
+
+        // This newly constructed WebSocket stream will use the specified
+        // I/O context and have support for the permessage-deflate extension.
+
+        stream<tcp_stream> ws(ioc);
+
+    //]
+    }
+
+    {
+    //[code_websocket_2f
+
+        // The `tcp_stream` will be constructed with a new strand which
+        // uses the specified I/O context.
+
+        stream<tcp_stream> ws(make_strand(ioc));
+
+    //]
+    }
+
+    {
+    //[code_websocket_3f
+
+        // The WebSocket stream will use SSL and a new strand
+        stream<ssl_stream<tcp_stream>> wss(make_strand(ioc), ctx);
+
+        //
+    //]
+    }
+}
+
+} // (anon)
+
+namespace boost {
+namespace beast {
+
+struct websocket_snippets_test
+    : public beast::unit_test::suite
+{
+    void
+    run() override
+    {
+        BEAST_EXPECT(&websocket_snippets);
+        pass();
+    }
+};
+
+BEAST_DEFINE_TESTSUITE(beast,doc,websocket_snippets);
+
+} // beast
+} // boost
+
+#ifdef BOOST_MSVC
+#pragma warning(pop)
+#endif

test/doc/websocket_snippets.cpp

@@ -10,18 +10,17 @@
 #include <boost/beast/core.hpp>
 #include <boost/asio.hpp>
 #include <boost/asio/spawn.hpp>
+#include <boost/asio/ssl.hpp>
 #include <boost/asio/use_future.hpp>
 #include <algorithm>
 #include <future>
 #include <iostream>
 #include <thread>
 
-//[ws_snippet_1
+using namespace boost::beast;
+
 #include <boost/beast/websocket.hpp>
 using namespace boost::beast::websocket;
-//]
-
-using namespace boost::beast;
 
 namespace doc_ws_snippets {
 
@@ -34,12 +33,6 @@ error_code ec;
 net::ip::tcp::socket sock{ioc};
 boost::ignore_unused(ec);
 
-{
-//[ws_snippet_2
-    stream<net::ip::tcp::socket> ws{ioc};
-//]
-}
-
 {
 //[ws_snippet_3
     stream<net::ip::tcp::socket> ws{std::move(sock)};
@@ -277,25 +270,10 @@ struct custom_wrapper
 
 //]
 
-//[ws_snippet_26
-
-// A WebSocket stream
-template<
-    class NextLayer,
-    bool deflateSupported = true>
-class stream;
-
-//]
-
 } // doc_ws_snippets
 
 //------------------------------------------------------------------------------
 
-//[wss_snippet_1
-#include <boost/beast/websocket/ssl.hpp>
-#include <boost/asio/ssl.hpp>
-//]
-
 namespace doc_wss_snippets {
 
 void fxx() {
@@ -306,13 +284,6 @@ std::thread t{[&](){ ioc.run(); }};
 error_code ec;
 net::ip::tcp::socket sock{ioc};
 
-{
-//[wss_snippet_2
-    net::ssl::context ctx{net::ssl::context::sslv23};
-    stream<net::ssl::stream<net::ip::tcp::socket>> wss{ioc, ctx};
-//]
-}
-
 {
 //[wss_snippet_3
     net::ip::tcp::endpoint ep;