boost_beast/doc/design.qbk

[/
    Copyright (c) 2013-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)
]

[section:design Design Choices]

[block '''
<informaltable frame="all"><tgroup cols="1"><colspec colname="a"/><tbody><row><entry valign="top"><simplelist>
  <member><link linkend="beast.design.http_message">HTTP Message Container</link></member>
  <member><link linkend="beast.design.http_comparison">HTTP Comparison to Other Libraries</link></member>
  <member><link linkend="beast.design.websocket_zaphoyd">Comparison to Zaphoyd Studios WebSocket++</link></member>
  <member><link linkend="beast.design.review">Boost Formal Review FAQ</link></member>
</simplelist></entry></row></tbody></tgroup></informaltable>
''']

The implementations are driven by business needs of cryptocurrency server
applications (e.g. [@https://ripple.com Ripple]) written in C++. These
needs were not met by existing solutions so Beast was written from scratch
as a solution. Beast's design philosophy avoids flaws exhibited by other
libraries:

* Don't try to do too much.

* Don't sacrifice performance.

* Mimic Boost.Asio; familiarity breeds confidence.

* Role-symmetric interfaces; client and server the same (or close to it).

* Leave important decisions to the user, such as allocating memory or
  managing flow control.

Beast uses the __DynamicBuffer__ concept presented in the Networking TS
(__N4588__), and relies heavily on the Boost.Asio __ConstBufferSequence__
and __MutableBufferSequence__ concepts for passing buffers to functions.
The authors have found the dynamic buffer and buffer sequence interfaces to
be optimal for interacting with Asio, and for other tasks such as incremental
parsing of data in buffers (for example, parsing websocket frames stored
in a [link beast.ref.static_buffer `static_buffer`]).

During the development of Beast the authors have studied other software
packages and in particular the comments left during the Boost Review process
of other packages offering similar functionality. In this section and the
FAQs that follow we attempt to answer those questions that are also applicable
to Beast.

For HTTP we model the message to maximize flexibility of implementation
strategies while allowing familiar verbs such as [*`read`] and [*`write`].
The HTTP interface is further driven by the needs of the WebSocket module,
as a WebSocket session requires a HTTP Upgrade handshake exchange at the
start. Other design goals:

* Keep it simple.

* Stay low level; don't invent a whole web server or client.

* Allow for customizations, if the user needs it.

[include design/http_message.qbk]
[include design/http_comparison.qbk]
[include design/websocket_zaphoyd.qbk]
[include design/review.qbk]

[endsect]