boost_beast/doc/1_overview.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:overview Introduction]

[important
    Beast is a cross-platform, header-only C++11 library for
    [*low-level HTTP/1, WebSocket, and network protocol] programming
    using the consistent asynchronous model of __Asio__. Beast is
    not an HTTP client or HTTP server, but it can be used to build
    those things. It is a foundation for writing interoperable
    libraries by providing HTTP vocabulary types and algorithms. The
    examples show how client and server applications might be built.
]

This library is designed for:

* [*Symmetry:] Algorithms are role-agnostic; build clients, servers, or both.

* [*Ease of Use:] __Asio__ users will immediately understand Beast.

* [*Flexibility:] Users make the important decisions such as buffer or
  thread management.

* [*Performance:] Build applications handling thousands of connections or more.

* [*Basis for Further Abstraction.] Components are well-suited for building upon.

[heading Audience]

Beast is for network programmers who have some familiarity with
__Asio__. In particular, users who wish to write asynchronous programs
with Beast should already know how to use Asio sockets and streams,
and should know how to create concurrent network programs using
Asio callbacks or coroutines.

[heading Motivation]

An absence of high quality C++ network protocol libraries has led
to a patchwork of open-source solutions lacking suitable conciseness
and expressive power for standardization. Part of this problem is a
lack of common C++ networking interfaces. This is changing soon with
the Networking Technical Specification (__N4588__): a uniform interface
on track to become standardized. This technical specification is modeled
closely after Boost.Asio.
The HTTP and WebSocket protocols drive most of the World Wide Web.
Every web browser implements these protocols to load webpages and
to enable client side programs (often written in JavaScript) to
communicate interactively. C++ benefits greatly from having a
standardized implementation of these protocols.

[note
    The Beast roadmap includes a port to the networking
    interface based on __N4588__.
]

[heading Requirements]

Beast requires:

* [*C++11:] Robust support for most language features.
* [*Boost:] Boost.Asio and some other parts of Boost.
* [*OpenSSL:] Optional, for using TLS/Secure sockets.

[note Supported compilers: msvc-14+, gcc 4.8+, clang 3.6+]

This library is [*header-only]. To link a program using Beast
successfully, add the
[@http://www.boost.org/libs/system/doc/reference.html Boost.System]
library to the list of linked libraries. If you use coroutines
you'll also need the
[@http://www.boost.org/libs/coroutine/doc/html/index.html Boost.Coroutine]
library. Please visit the
[@http://www.boost.org/doc/ Boost documentation]
for instructions on how to do this for your particular build system.

[note
    Beast does not compile using the
    [@https://github.com/chriskohlhoff/asio stand-alone Asio],
    since it relies on other Boost parts. There are no immediate
    plans to offer a version that works with stand-alone Asio.
]

[heading Credits]

Boost.Asio is the inspiration behind which all of the interfaces and
implementation strategies are built. Some parts of the documentation are
written to closely resemble the wording and presentation of Boost.Asio
documentation. Credit goes to
[@https://github.com/chriskohlhoff Christopher Kohlhoff]
for his wonderful Asio library and the ideas in __N4588__ which power Beast.

Beast would not be possible without the support of
[@https://www.ripple.com Ripple]
during the library's early development, or the ideas, time and patience
contributed by
[@https://github.com/JoelKatz David Schwartz],
[@https://github.com/ximinez Edward Hennis],
[@https://github.com/howardhinnant Howard Hinnant],
[@https://github.com/miguelportilla Miguel Portilla],
[@https://github.com/nbougalis Nik Bougalis],
[@https://github.com/seelabs Scott Determan],
[@https://github.com/scottschurr Scott Schurr],
Many thanks to
[@https://github.com/K-ballo Agustín Bergé],
[@http://www.boost.org/users/people/glen_fernandes.html Glen Fernandes],
and
[@https://github.com/pdimov Peter Dimov]
for tirelessly answering questions on
[@https://cpplang.slack.com/ Cpplang-Slack].

[endsect]