[/ 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] Beast is a header-only, cross-platform C++ library built on Boost.Asio and parts of Boost, containing two modules implementing widely used network protocols. Beast offers a universal HTTP message model, plus algorithms for parsing and serializing HTTP/1 messages. Beast.WebSocket provides a complete implementation of the WebSocket protocol. Their design achieves these goals: * [*Symmetry.] Interfaces are role-agnostic; the same interfaces can be used to build clients, servers, or both. * [*Ease of Use.] HTTP messages are modeled using simple, readily accessible objects. Functions and classes used to send and receive HTTP or WebSocket messages are designed to resemble Boost.Asio as closely as possible. Users familiar with Boost.Asio will be immediately comfortable using this library. * [*Flexibility.] Interfaces do not mandate specific implementation strategies; important decisions such as buffer or thread management are left to users of the library. * [*Performance.] The implementation performs competitively, making it a realistic choice for building high performance network servers. * [*Scalability.] Development of network applications that scale to thousands of concurrent connections is possible with the implementation. * [*Basis for further abstraction.] The interfaces facilitate the development of other libraries that provide higher levels of abstraction. [heading Requirements] Beast requires: * [*C++11.] A minimum of C++11 is needed. * [*Boost.] Beast is built on Boost, especially Boost.Asio. * [*OpenSSL.] If using TLS/Secure sockets (optional). [note Tested compilers: msvc-14+, gcc 4.8+, clang 3.6+] The library is [*header-only]. It is not necessary to add any .cpp files, or to add commands to your build script for building Beast. To link your program successfully, you'll need to add the Boost.System library to link with. If you use coroutines you'll also need the Boost.Coroutine library. Please visit the Boost documentation for instructions on how to do this for your particular build system. There are no provisions for enabling Beast to compile using the stand-alone version of Asio. Beast relies on other parts of Boost in addition to Asio. There are no immediate plans to offer a version of Beast that works with the stand-alone Asio. [heading Audience] Beast is aimed at network programmers who have know some Boost.Asio. While experience is not strictly necessary, the documentation and interfaces assume a reasonable grasp of how Asio works. In particular, users who wish to write asynchronous programs with Beast should already have knowledge and experience of Asio's asynchronous interfaces and general style of asynchronous programming using callbacks or coroutines. The supplied WebSocket and HTTP interfaces are low-level. The library does not provide out of the box solutions for implementing clients or servers. For example, users must provide their own code to make connections, handle timeouts, reconnect a dropped connection, accept incoming connections, or manage connection resources on a server. Beast's HTTP interfaces are similarly low level, providing functionality only for modelling HTTP messages and reading and writing them to sockets or streams. Higher level functions such as HTTP Basic Authentication, mime/multipart encoding, cookies, automatic handling of redirects, gzipped transfer encodings, caching, or proxying (to name a few) are not directly provided, but nothing stops users from creating these features using Beast's HTTP message types. Instead, the library is intended to be a building block for creating higher level libraries. It implements just enough of the HTTP and WebSocket protocol to allow users to create useful objects and algorithms which may then be composed to produce useful applications. It is the desire of the author that this library will become the foundation for a new generation of network libraries. [heading Motivation] Beast is built on Boost.Asio. A proposal to add networking functionality to the C++ standard library, based on Boost.Asio, is under consideration by the committee and on track for standardization. Since the final approved networking interface for the C++ standard library will likely closely resemble the current interface of Boost.Asio, the choice of Boost.Asio as the network transport layer is prudent. The HTTP protocol is pervasive in network applications. As C++ is a logical choice for high performance network servers, there is great utility in solid building blocks for manipulating, sending, and receiving HTTP messages compliant with the Hypertext Transfer Protocol and the supplements that follow. Unfortunately reliable implementations or industry standards do not exist in C++. The development of higher level libraries is stymied by the lack of a common set of low-level algorithms and types for interacting with the HTTP protocol. Today's web applications increasingly rely on alternatives to standard HTTP to achieve performance and/or responsiveness. While WebSocket implementations are widely available in common web development languages such as Javascript, good implementations in C++ are scarce. A survey of existing C++ WebSocket solutions reveals interfaces which lack symmetry, impose performance penalties, and needlessly restrict implementation strategies. Beast.WebSocket takes advantage of Boost.Asio's extensible asynchronous model, handler allocation, and handler invocation hooks. Calls to Beast.WebSocket asynchronous initiation functions allow callers the choice of using a completion handler, stackful or stackless coroutines, futures, or user defined customizations (for example, Boost.Fiber). The implementation uses handler invocation hooks (__asio_handler_invoke__), providing execution guarantees on composed operations in a manner identical to Boost.Asio. The implementation also uses handler allocation hooks (__asio_handler_allocate__) when allocating memory internally for composed operations. There is no need for inheritance or virtual members in a [link beast.ref.websocket__stream `websocket::stream`]. All operations are templated and transparent to the compiler, allowing for maximum inlining and optimization. [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 Christopher Kohlhoff for the wonderful Asio library and the ideas upon which Beast is built. Beast would not be possible without the considerable time and patience contributed by David Schwartz, Edward Hennis, Howard Hinnant, Miguel Portilla, Nikolaos Bougalis, Scott Determan, Scott Schurr, and Ripple Labs for supporting its early development. Also thanks to Agustín Bergé, Glen Fernandes and Peter Dimov for putting up with my endless C++ questions on Slack. [endsect]