ceph/src/Beast/doc/design.qbk

   1 [/
   2     Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
   3
   4     Distributed under the Boost Software License, Version 1.0. (See accompanying
   5     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6 ]
   7
   8 [section:design Design Choices]
   9
  10 [block '''
  11 <informaltable frame="all"><tgroup cols="1"><colspec colname="a"/><tbody><row><entry valign="top"><simplelist>
  12   <member><link linkend="beast.design.http">HTTP FAQ</link></member>
  13   <member><link linkend="beast.design.websocket">WebSocket FAQ</link></member>
  14   <member><link linkend="beast.design.websocketpp">Comparison to Zaphoyd Studios WebSocket++</link></member>
  15 </simplelist></entry></row></tbody></tgroup></informaltable>
  16 ''']
  17
  18 The implementations are driven by business needs of cryptocurrency server
  19 applications (e.g. [@https://ripple.com Ripple]) written in C++. These
  20 needs were not met by existing solutions so Beast was written from scratch
  21 as a solution. Beast's design philosophy avoids flaws exhibited by other
  22 libraries:
  23
  24 * Don't try to do too much.
  25
  26 * Don't sacrifice performance.
  27
  28 * Mimic Boost.Asio; familiarity breeds confidence.
  29
  30 * Role-symmetric interfaces; client and server the same (or close to it).
  31
  32 * Leave important decisions to the user, such as allocating memory or
  33   managing flow control.
  34
  35 Beast uses the __DynamicBuffer__ concept presented in the Networking TS
  36 (__N4588__), and relies heavily on the Boost.Asio __ConstBufferSequence__
  37 and __MutableBufferSequence__ concepts for passing buffers to functions.
  38 The authors have found the dynamic buffer and buffer sequence interfaces to
  39 be optimal for interacting with Asio, and for other tasks such as incremental
  40 parsing of data in buffers (for example, parsing websocket frames stored
  41 in a [link beast.ref.static_streambuf `static_streambuf`]).
  42
  43 During the development of Beast the authors have studied other software
  44 packages and in particular the comments left during the Boost Review process
  45 of other packages offering similar functionality. In this section and the
  46 FAQs that follow we attempt to answer those questions that are also applicable
  47 to Beast.
  48
  49 [variablelist
  50 [[
  51     "I would also like to see instances of this library being used
  52     in production. That would give some evidence that the design
  53     works in practice."
  54 ][
  55     Beast.HTTP and Beast.WebSocket are production ready and currently
  56     running on public servers receiving traffic and handling millions of
  57     dollars worth of financial transactions daily. The servers run [*rippled],
  58     open source software ([@https://github.com/ripple/rippled repository])
  59     implementing the
  60     [@https://ripple.com/files/ripple_consensus_whitepaper.pdf [*Ripple Consensus Protocol]],
  61     technology provided by [@http://ripple.com Ripple].
  62 ]]
  63
  64 ]
  65
  66
  67
  68 [section:http HTTP FAQ]
  69
  70 For HTTP we model the message to maximize flexibility of implementation
  71 strategies while allowing familiar verbs such as [*`read`] and [*`write`].
  72 The HTTP interface is further driven by the needs of the WebSocket module,
  73 as a WebSocket session requires a HTTP Upgrade handshake exchange at the
  74 start. Other design goals:
  75
  76 * Keep it simple.
  77
  78 * Stay low level; don't invent a whole web server or client.
  79
  80 * Allow for customizations, if the user needs it.
  81
  82 [variablelist
  83
  84 [[
  85     "Some more advanced examples, e.g. including TLS with client/server
  86     certificates would help."
  87 ][
  88     The HTTP interface doesn't try to reinvent the wheel, it just uses
  89     the `boost::asio::ip::tcp::socket` or `boost::asio::ssl::stream` that
  90     you set up beforehand. Callers use the interfaces already existing
  91     on those objects to make outgoing connections, accept incoming connections,
  92     or establish TLS sessions with certificates. We find the available Asio
  93     examples for performing these tasks sufficient.
  94 ]]
  95
  96 [[
  97     "A built-in router?"
  98 ][
  99     We presume this means a facility to match expressions against the URI
 100     in HTTP requests, and dispatch them to calling code. The authors feel
 101     that this is a responsibility of higher level code. Beast.HTTP does
 102     not try to offer a web server.
 103 ]]
 104
 105 [[
 106     "Cookies? Forms/File Uploads?"
 107 ][
 108     Cookies, or managing these types of HTTP headers in general, is the
 109     responsibility of higher levels. Beast.HTTP just tries to get complete
 110     messages to and from the calling code. It deals in the HTTP headers just
 111     enough to process the message body and leaves the rest to callers. However,
 112     for forms and file uploads the symmetric interface of the message class
 113     allows HTTP requests to include arbitrary body types including those needed
 114     to upload a file or fill out a form.
 115 ]]
 116
 117 [[
 118     "...supporting TLS (is this a feature? If not this would be a show-stopper),
 119     etc."
 120 ][
 121     Beast.HTTP does not provide direct facilities for implementing TLS
 122     connections; however, the interfaces already existing on the
 123     `boost::asio::ssl::stream` are available and can be used to establish
 124     secure connections. Then, functions like `http::read` or `http::async_write`
 125     can work with those encrypted connections with no problem.
 126 ]]
 127
 128 [[
 129     "There should also be more examples of how to integrate the http service
 130     with getting files from the file system, generating responses CGI-style"
 131 ][
 132     The design goal for the library is to not try to invent a web server.
 133     We feel that there is a strong need for a basic implementation that
 134     models the HTTP message and provides functions to send and receive them
 135     over Asio. Such an implementation should serve as a building block upon
 136     which higher abstractions such as the aforementioned HTTP service or
 137     cgi-gateway can be built.
 138
 139     One of the example programs implements a simple HTTP server that
 140     delivers files from the filesystem.
 141 ]]
 142
 143 [[
 144     "You should send a 100-continue to ask for the rest of the body if required."
 145 ][
 146     The Beast interface needs to support this functionality (by allowing this
 147     special case of partial message parsing and serialization). Specifically,
 148     it should let callers read the request up to just before the body,
 149     and let callers write the request up to just before the body. However,
 150     making use of this behavior should be up to callers (since Beast is low
 151     level).
 152 ]]
 153
 154 [[
 155     "What about HTTP/2?"
 156 ][
 157     Many reviewers feel that HTTP/2 support is an essential feature of
 158     a HTTP library. The authors agree that HTTP/2 is important but also
 159     feel that the most sensible implementation is one that does not re-use
 160     the same network reading and writing interface for 2 as that for 1.0
 161     and 1.1.
 162
 163     The Beast.HTTP message model is suitable for HTTP/2 and can be re-used.
 164     The IETF HTTP Working Group adopted message compatiblity with HTTP/1.x
 165     as an explicit goal. A parser can simply emit full headers after
 166     decoding the compressed HTTP/2 headers. The stream ID is not logically
 167     part of the message but rather message metadata and should be
 168     communicated out-of-band (see below). HTTP/2 sessions begin with a
 169     traditional HTTP/1.1 Upgrade similar in fashion to the WebSocket
 170     upgrade. An HTTP/2 implementation can use existing Beast.HTTP primitives
 171     to perform this handshake.
 172
 173     Free functions for HTTP/2 sessions are not possible because of the
 174     requirement to maintain per-session state. For example, to decode the
 175     compressed headers. Or to remember and respect the remote peer's window
 176     settings. The authors propose that a HTTP/2 implementation be written
 177     as a separate class template, similar to the `websocket::stream` but with
 178     additional interfaces to support version 2 features. We feel that
 179     Beast.HTTP offers enough useful functionality to justify inclusion,
 180     so that developers can take advantage of it right away instead of
 181     waiting.
 182 ]]
 183
 184 ]
 185
 186 [endsect]
 187
 188
 189
 190 [section:websocket WebSocket FAQ]
 191
 192 [variablelist
 193
 194 [[
 195     What about message compression?
 196 ][
 197     Beast WebSocket supports the permessage-deflate extension described in
 198     [@https://tools.ietf.org/html/draft-ietf-hybi-permessage-compression-00 draft-ietf-hybi-permessage-compression-00].
 199     The library comes with a header-only, C++11 port of ZLib's "deflate" codec
 200     used in the implementation of the permessage-deflate extension.
 201 ]]
 202
 203 [[
 204     Where is the TLS/SSL interface?
 205 ][
 206     The `websocket::stream` wraps the socket or stream that you provide
 207     (for example, a `boost::asio::ip::tcp::socket` or a
 208     `boost::asio::ssl::stream`). You establish your TLS connection using the
 209     interface on `ssl::stream` like shown in all of the Asio examples, then
 210     construct your `websocket::stream` around it. It works perfectly fine;
 211     Beast.WebSocket doesn't try to reinvent the wheel or put a fresh coat of
 212     interface paint on the `ssl::stream`.
 213
 214     The WebSocket implementation [*does] provide support for shutting down
 215     the TLS connection through the use of the ADL compile-time virtual functions
 216     [link beast.ref.websocket__teardown `teardown`] and
 217     [link beast.ref.websocket__async_teardown `async_teardown`]. These will
 218     properly close the connection as per rfc6455 and overloads are available
 219     for TLS streams. Callers may provide their own overloads of these functions
 220     for user-defined next layer types.
 221 ]]
 222
 223 ]
 224
 225 [endsect]
 226
 227
 228
 229 [section:websocketpp Comparison to Zaphoyd Studios WebSocket++]
 230
 231 [variablelist
 232
 233 [[
 234     How does this compare to [@https://www.zaphoyd.com/websocketpp websocketpp],
 235     an alternate header-only WebSocket implementation?
 236 ][
 237     [variablelist
 238
 239     [[1. Synchronous Interface][
 240
 241     Beast offers full support for WebSockets using a synchronous interface. It
 242     uses the same style of interfaces found in Boost.Asio: versions that throw
 243     exceptions, or versions that return the error code in a reference parameter:
 244
 245     [table
 246         [
 247             [[@https://github.com/vinniefalco/Beast/blob/6c8b4b2f8dde72b01507e4ac7fde4ffea57ebc99/include/beast/websocket/stream.hpp#L774 Beast]]
 248             [websocketpp]
 249         ][
 250             [```
 251                 template<class DynamicBuffer>
 252                 void
 253                 read(opcode& op, DynamicBuffer& dynabuf)
 254             ```]
 255             [
 256                 /<not available>/
 257             ]
 258     ]]]]
 259
 260     [[2. Connection Model][
 261
 262     websocketpp supports multiple transports by utilizing a trait, the `config::transport_type`
 263     ([@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/transport/asio/connection.hpp#L60 asio transport example])
 264     To get an idea of the complexity involved with implementing a transport,
 265     compare the asio transport to the
 266     [@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/transport/iostream/connection.hpp#L59 `iostream` transport]
 267     (a layer that allows websocket communication over a `std::iostream`).
 268
 269     In contrast, Beast abstracts the transport by defining just one [*`NextLayer`]
 270     template argument The type requirements for [*`NextLayer`] are
 271     already familiar to users as they are documented in Asio:
 272     __AsyncReadStream__, __AsyncWriteStream__, __SyncReadStream__, __SyncWriteStream__.
 273
 274     The type requirements for instantiating `beast::websocket::stream` versus
 275     `websocketpp::connection` with user defined types are vastly reduced
 276     (18 functions versus 2). Note that websocketpp connections are passed by
 277     `shared_ptr`. Beast does not use `shared_ptr` anywhere in its public interface.
 278     A `beast::websocket::stream` is constructible and movable in a manner identical
 279     to a `boost::asio::ip::tcp::socket`. Callers can put such objects in a
 280     `shared_ptr` if they want to, but there is no requirement to do so.
 281
 282     [table
 283         [
 284             [[@https://github.com/vinniefalco/Beast/blob/6c8b4b2f8dde72b01507e4ac7fde4ffea57ebc99/include/beast/websocket/stream.hpp Beast]]
 285             [[@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/connection.hpp#L234 websocketpp]]
 286         ][
 287             [```
 288                 template<class NextLayer>
 289                 class stream
 290                 {
 291                     NextLayer next_layer_;
 292                     ...
 293                 }
 294             ```]
 295             [```
 296                 template <typename config>
 297                 class connection
 298                 : public config::transport_type::transport_con_type
 299                 , public config::connection_base
 300                 {
 301                 public:
 302                     typedef lib::shared_ptr<type> ptr;
 303                     ...
 304                 }
 305             ```]
 306     ]]]]
 307
 308     [[3. Client and Server Role][
 309
 310     websocketpp provides multi-role support through a hierarchy of
 311     different classes. A `beast::websocket::stream` is role-agnostic, it
 312     offers member functions to perform both client and server handshakes
 313     in the same class. The same types are used for client and server
 314     streams.
 315
 316     [table
 317         [
 318             [Beast]
 319             [[@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/roles/server_endpoint.hpp#L39 websocketpp],
 320                 [@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/roles/client_endpoint.hpp#L42 also]]
 321         ][
 322             [
 323                 /<not needed>/
 324             ]
 325             [```
 326                 template <typename config>
 327                 class client : public endpoint<connection<config>,config>;
 328                 template <typename config>
 329                 class server : public endpoint<connection<config>,config>;
 330             ```]
 331     ]]]]
 332
 333     [[4. Thread Safety][
 334
 335     websocketpp uses mutexes to protect shared data from concurrent
 336     access. In contrast, Beast does not use mutexes anywhere in its
 337     implementation. Instead, it follows the Asio pattern. Calls to
 338     asynchronous initiation functions use the same method to invoke
 339     intermediate handlers as the method used to invoke the final handler,
 340     through the __asio_handler_invoke__ mechanism.
 341
 342     The only requirement in Beast is that calls to asynchronous initiation
 343     functions are made from the same implicit or explicit strand. For
 344     example, if the `io_service` associated with a `beast::websocket::stream`
 345     is single threaded, this counts as an implicit strand and no performance
 346     costs associated with mutexes are incurred.
 347
 348     [table
 349         [
 350             [[@https://github.com/vinniefalco/Beast/blob/6c8b4b2f8dde72b01507e4ac7fde4ffea57ebc99/include/beast/websocket/impl/read_frame_op.ipp#L118 Beast]]
 351             [[@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/transport/iostream/connection.hpp#L706 websocketpp]]
 352         ][
 353             [```
 354                 template <class Function>
 355                 friend
 356                 void asio_handler_invoke(Function&& f, read_frame_op* op)
 357                 {
 358                     return boost_asio_handler_invoke_helpers::invoke(f, op->d_->h);
 359                 }
 360             ```]
 361             [```
 362                 mutex_type m_read_mutex;
 363             ```]
 364     ]]]]
 365
 366     [[5. Callback Model][
 367
 368     websocketpp requires a one-time call to set the handler for each event
 369     in its interface (for example, upon message receipt). The handler is
 370     represented by a `std::function` equivalent. Its important to recognize
 371     that the websocketpp interface performs type-erasure on this handler.
 372
 373     In comparison, Beast handlers are specified in a manner identical to
 374     Boost.Asio. They are function objects which can be copied or moved but
 375     most importantly they are not type erased. The compiler can see
 376     through the type directly to the implementation, permitting
 377     optimization. Furthermore, Beast follows the Asio rules for treatment
 378     of handlers. It respects any allocation, continuation, or invocation
 379     customizations associated with the handler through the use of argument
 380     dependent lookup overloads of functions such as `asio_handler_allocate`.
 381
 382     The Beast completion handler is provided at the call site. For each
 383     call to an asynchronous initiation function, it is guaranteed that
 384     there will be exactly one final call to the handler. This functions
 385     exactly the same way as the asynchronous initiation functions found in
 386     Boost.Asio, allowing the composition of higher level abstractions.
 387
 388     [table
 389         [
 390             [[@https://github.com/vinniefalco/Beast/blob/6c8b4b2f8dde72b01507e4ac7fde4ffea57ebc99/include/beast/websocket/stream.hpp#L834 Beast]]
 391             [[@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/connection.hpp#L281 websocketpp],
 392                 [@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/connection.hpp#L473 also]]
 393         ][
 394             [```
 395                 template<class DynamicBuffer, class ReadHandler>
 396                 typename async_completion<ReadHandler, void(error_code)>::result_type
 397                 async_read(opcode& op, DynamicBuffer& dynabuf, ReadHandler&& handler);
 398             ```]
 399             [```
 400                 typedef lib::function<void(connection_hdl,message_ptr)> message_handler;
 401                 void set_message_handler(message_handler h);
 402             ```]
 403     ]]]]
 404
 405     [[6. Extensible Asynchronous Model][
 406
 407     Beast fully supports the
 408     [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3896.pdf Extensible Asynchronous Model]
 409     developed by Christopher Kohlhoff, author of Boost.Asio (see Section 8).
 410
 411     Beast websocket asynchronous interfaces may be used seamlessly with
 412     `std::future` stackful/stackless coroutines, or user defined customizations.
 413
 414     [table
 415         [
 416             [[@https://github.com/vinniefalco/Beast/blob/6c8b4b2f8dde72b01507e4ac7fde4ffea57ebc99/include/beast/websocket/impl/stream.ipp#L378 Beast]]
 417             [websocketpp]
 418         ][
 419             [```
 420                 beast::async_completion<ReadHandler, void(error_code)> completion(handler);
 421                 read_op<DynamicBuffer, decltype(completion.handler)>{
 422                     completion.handler, *this, op, streambuf};
 423                 return completion.result.get();
 424             ```]
 425             [
 426                 /<not available>/
 427             ]
 428     ]]]]
 429
 430     [[7. Message Buffering][
 431
 432     websocketpp defines a message buffer, passed in arguments by
 433     `shared_ptr`, and an associated message manager which permits
 434     aggregation and reuse of memory. The implementation of
 435     `websocketpp::message` uses a `std::string` to hold the payload. If an
 436     incoming message is broken up into multiple frames, the string may be
 437     reallocated for each continuation frame. The `std::string` always uses
 438     the standard allocator, it is not possible to customize the choice of
 439     allocator.
 440
 441     Beast allows callers to specify the object for receiving the message
 442     or frame data, which is of any type meeting the requirements of
 443     __DynamicBuffer__ (modeled after `boost::asio::streambuf`).
 444
 445     Beast comes with the class __basic_streambuf__, an efficient
 446     implementation of the __DynamicBuffer__ concept which makes use of multiple
 447     allocated octet arrays. If an incoming message is broken up into
 448     multiple pieces, no reallocation occurs. Instead, new allocations are
 449     appended to the sequence when existing allocations are filled. Beast
 450     does not impose any particular memory management model on callers. The
 451     __basic_streambuf__ provided by beast supports standard allocators through
 452     a template argument. Use the __DynamicBuffer__ that comes with beast,
 453     customize the allocator if you desire, or provide your own type that
 454     meets the requirements.
 455
 456     [table
 457         [
 458             [[@https://github.com/vinniefalco/Beast/blob/6c8b4b2f8dde72b01507e4ac7fde4ffea57ebc99/include/beast/websocket/stream.hpp#L774 Beast]]
 459             [[@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/message_buffer/message.hpp#L78 websocketpp]]
 460         ][
 461             [```
 462                 template<class DynamicBuffer>
 463                 read(opcode& op, DynamicBuffer& dynabuf);
 464             ```]
 465             [```
 466                 template <template<class> class con_msg_manager>
 467                 class message {
 468                 public:
 469                     typedef lib::shared_ptr<message> ptr;
 470                     ...
 471                     std::string m_payload;
 472                     ...
 473                 };
 474             ```]
 475     ]]]]
 476
 477     [[8. Sending Messages][
 478
 479     When sending a message, websocketpp requires that the payload is
 480     packaged in a `websocketpp::message` object using `std::string` as the
 481     storage, or it requires a copy of the caller provided buffer by
 482     constructing a new message object. Messages are placed onto an
 483     outgoing queue. An asynchronous write operation runs in the background
 484     to clear the queue. No user facing handler can be registered to be
 485     notified when messages or frames have completed sending.
 486
 487     Beast doesn't allocate or make copies of buffers when sending data. The
 488     caller's buffers are sent in-place. You can use any object meeting the
 489     requirements of
 490     [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConstBufferSequence.html ConstBufferSequence],
 491     permitting efficient scatter-gather I/O.
 492
 493     The [*ConstBufferSequence] interface allows callers to send data from
 494     memory-mapped regions (not possible in websocketpp). Callers can also
 495     use the same buffers to send data to multiple streams, for example
 496     broadcasting common subscription data to many clients at once. For
 497     each call to `async_write` the completion handler is called once when
 498     the data finishes sending, in a manner identical to `boost::asio::async_write`.
 499
 500     [table
 501         [
 502             [[@https://github.com/vinniefalco/Beast/blob/6c8b4b2f8dde72b01507e4ac7fde4ffea57ebc99/include/beast/websocket/stream.hpp#L1048 Beast]]
 503             [[@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/connection.hpp#L672 websocketpp]]
 504         ][
 505             [```
 506                 template<class ConstBufferSequence>
 507                 void
 508                 write(ConstBufferSequence const& buffers);
 509             ```]
 510             [```
 511                 lib::error_code send(std::string const & payload,
 512                     frame::opcode::value op = frame::opcode::text);
 513                 ...
 514                 lib::error_code send(message_ptr msg);
 515             ```]
 516     ]]]]
 517
 518     [[9. Streaming Messages][
 519
 520     websocketpp requires that the entire message fit into memory, and that
 521     the size is known ahead of time.
 522
 523     Beast allows callers to compose messages in individual frames. This is
 524     useful when the size of the data is not known ahead of time or if it
 525     is not desired to buffer the entire message in memory at once before
 526     sending it. For example, sending periodic output of a database query
 527     running on a coroutine. Or sending the contents of a file in pieces,
 528     without bringing it all into memory.
 529
 530     [table
 531         [
 532             [[@https://github.com/vinniefalco/Beast/blob/6c8b4b2f8dde72b01507e4ac7fde4ffea57ebc99/include/beast/websocket/stream.hpp#L1151 Beast]]
 533             [websocketpp]
 534         ][
 535             [```
 536                 template<class ConstBufferSequence>
 537                 void
 538                 write_frame(bool fin,
 539                     ConstBufferSequence const& buffers);
 540             ```]
 541             [
 542                 /<not available>/
 543             ]
 544     ]]]]
 545
 546     [[10. Flow Control][
 547
 548     The websocketpp read implementation continuously reads asynchronously
 549     from the network and buffers message data. To prevent unbounded growth
 550     and leverage TCP/IP's flow control mechanism, callers can periodically
 551     turn this 'read pump' off and back on.
 552
 553     In contrast a `beast::websocket::stream` does not independently begin
 554     background activity, nor does it buffer messages. It receives data only
 555     when there is a call to an asynchronous initiation function (for
 556     example `beast::websocket::stream::async_read`) with an associated handler.
 557     Applications do not need to implement explicit logic to regulate the
 558     flow of data. Instead, they follow the traditional model of issuing a
 559     read, receiving a read completion, processing the message, then
 560     issuing a new read and repeating the process.
 561
 562     [table
 563         [
 564             [Beast]
 565             [[@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/connection.hpp#L728 websocketpp]]
 566         ][
 567             [
 568                 /<implicit>/
 569             ]
 570             [```
 571                 lib::error_code pause_reading();
 572                 lib::error_code resume_reading();
 573             ```]
 574     ]]]]
 575
 576     [[11. Connection Establishment][
 577
 578     websocketpp offers the `endpoint` class which can handle binding and
 579     listening to a port, and spawning connection objects.
 580
 581     Beast does not reinvent the wheel here, callers use the interfaces
 582     already in `boost::asio` for receiving incoming connections resolving
 583     host names, or establishing outgoing connections. After the socket (or
 584     `boost::asio::ssl::stream`) is connected, the `beast::websocket::stream`
 585     is constructed around it and the WebSocket handshake can be performed.
 586
 587     Beast users are free to implement their own "connection manager", but
 588     there is no requirement to do so.
 589
 590     [table
 591         [
 592             [[@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/async_connect.html Beast],
 593                 [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/basic_socket_acceptor/async_accept.html also]]
 594             [[@https://github.com/zaphoyd/websocketpp/blob/378437aecdcb1dfe62096ffd5d944bf1f640ccc3/websocketpp/transport/asio/endpoint.hpp#L52 websocketpp]]
 595         ][
 596             [```
 597                 #include <boost/asio.hpp>
 598             ```]
 599             [```
 600                 template <typename config>
 601                 class endpoint : public config::socket_type;
 602             ```]
 603     ]]]]
 604
 605     [[12. WebSocket Handshaking][
 606
 607     Callers invoke `beast::websocket::accept` to perform the WebSocket
 608     handshake, but there is no requirement to use this function. Advanced
 609     users can perform the WebSocket handshake themselves. Beast WebSocket
 610     provides the tools for composing the request or response, and the
 611     Beast HTTP interface provides the container and algorithms for sending
 612     and receiving HTTP/1 messages including the necessary HTTP Upgrade
 613     request for establishing the WebSocket session.
 614
 615     Beast allows the caller to pass the incoming HTTP Upgrade request for
 616     the cases where the caller has already received an HTTP message.
 617     This flexibility permits novel and robust implementations. For example,
 618     a listening socket that can handshake in multiple protocols on the
 619     same port.
 620
 621     Sometimes callers want to read some bytes on the socket before reading
 622     the WebSocket HTTP Upgrade request. Beast allows these already-received
 623     bytes to be supplied to an overload of the accepting function to permit
 624     sophisticated features. For example, a listening socket that can
 625     accept both regular WebSocket and Secure WebSocket (SSL) connections.
 626
 627     [table
 628         [
 629             [[@https://github.com/vinniefalco/Beast/blob/6c8b4b2f8dde72b01507e4ac7fde4ffea57ebc99/include/beast/websocket/stream.hpp#L501 Beast],
 630                 [@https://github.com/vinniefalco/Beast/blob/6c8b4b2f8dde72b01507e4ac7fde4ffea57ebc99/include/beast/websocket/stream.hpp#L401 also]]
 631             [websocketpp]
 632         ][
 633             [```
 634                 template<class ConstBufferSequence>
 635                 void
 636                 accept(ConstBufferSequence const& buffers);
 637
 638                 template<class Body, class Headers>
 639                 void
 640                 accept(http::request_v1<Body, Headers> const& request);
 641             ```]
 642             [
 643                 /<not available>/
 644             ]
 645     ]]]]
 646
 647     ]
 648 ]]
 649
 650 ]
 651
 652 [endsect]
 653
 654 [endsect]