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 intended to be a foundation for writing other
    interoperable libraries by providing HTTP vocabulary types and
    algorithms. The provided examples show how clients and servers
    might be built.
]

This library is designed for:

* [*Symmetry:] Interfaces 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 open-ended and
  suited for building higher level libraries.

[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
caused by the lack of a standardized C++ networking interface. This
will change soon with the Networking Technical Specification
(__N4588__): a uniform interface for networking 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 standardized C++
    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]