HTTP and WebSocket built on Boost.Asio in C++11

Branch | Linux / Windows | Coverage | Documentation | Matrix | ----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| master | | | | | develop | | | | |

Introduction
Appearances
Description
Requirements
Git Branches
Building
Usage
License
Contact
Contributing

Introduction

Beast is a C++ header-only library serving as a foundation for writing interoperable networking libraries by providing low-level HTTP/1, WebSocket, and networking protocol vocabulary types and algorithms using the consistent asynchronous model of Boost.Asio.

This library is designed for:

Symmetry: Algorithms are role-agnostic; build clients, servers, or both.
Ease of Use: Boost.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.

Appearances

| <a href="https://github.com/vinniefalco/CppCon2018">CppCon 2018</a> | <a href="https://www.bishopfox.com/case_study/securing-beast/">Bishop Fox 2018</a> | | ------------ | ------------ | | <a href="https://www.youtube.com/watch?v=7FQwAjELMek"><img width="320" height = "180" alt="Beast" src="https://raw.githubusercontent.com/vinniefalco/CppCon2018/master/CppCon2018.png"></a> | <a href="https://youtu.be/4TtyYbGDAj0"><img width="320" height = "180" alt="Beast Security Review" src="https://raw.githubusercontent.com/vinniefalco/BeastAssets/master/BishopFox2018.png"></a> |

| <a href="https://github.com/vinniefalco/CppCon2018">CppCon 2017</a> | <a href="https://cppcast.com/vinnie-falco/">CppCast 2017</a> | <a href="https://raw.githubusercontent.com/vinniefalco/BeastAssets/master/CppCon2016.pdf">CppCon 2016</a> | | ------------ | ------------ | ----------- | | <a href="https://www.youtube.com/watch?v=WsUnnYEKPnI"><img width="320" height = "180" alt="Beast" src="https://raw.githubusercontent.com/vinniefalco/CppCon2017/master/CppCon2017.png"></a> | <a href="http://cppcast.com/2017/01/vinnie-falco/"><img width="180" height="180" alt="Vinnie Falco" src="https://avatars1.githubusercontent.com/u/1503976?v=3&u=76c56d989ef4c09625256662eca2775df78a16ad&s=180"></a> | <a href="https://www.youtube.com/watch?v=uJZgRcvPFwI"><img width="320" height = "180" alt="Beast" src="https://raw.githubusercontent.com/vinniefalco/BeastAssets/master/CppCon2016.png"></a> |

Description

This software is in its first official release. Interfaces may change in response to user feedback. For recent changes see the CHANGELOG.

Requirements

This library is for programmers familiar with Boost.Asio. Users who wish to use asynchronous interfaces should already know how to create concurrent network programs using callbacks or coroutines.

C++11: Robust support for most language features.
Boost: Boost.Asio and some other parts of Boost.
OpenSSL: Required for using TLS/Secure sockets and examples/tests

When using Microsoft Visual C++, Visual Studio 2017 or later is required.

One of these components is required in order to build the tests and examples:

Properly configured bjam/b2
CMake 3.5.1 or later (Windows only)

Building

Beast is header-only. To use it just add the necessary #include line to your source files, like this:

#include <boost/beast.hpp>

If you use coroutines you'll need to link with the Boost.Coroutine library. Please visit the Boost documentation for instructions on how to do this for your particular build system.

GitHub

To use the latest official release of Beast, simply obtain the latest Boost distribution and follow the instructions for integrating it into your development environment. If you wish to build the examples and tests, or if you wish to preview upcoming changes and features, it is suggested to clone the "Boost superproject" and work with Beast "in-tree" (meaning, the libs/beast subdirectory of the superproject).

The official repository contains the following branches:

master This holds the most recent snapshot with code that is known to be stable.
develop This holds the most recent snapshot. It may contain unstable code.

Each of these branches requires a corresponding Boost branch and all of its subprojects. For example, if you wish to use the master branch version of Beast, you should clone the Boost superproject, switch to the master branch in the superproject and acquire all the Boost libraries corresponding to that branch including Beast.

To clone the superproject locally, and switch into the main project's directory use:

git clone --recursive https://github.com/boostorg/boost.git
cd boost

"bjam" is used to build Beast and the Boost libraries. On a non-Windows system use this command to build bjam:

./bootstrap.sh

From a Windows command line, build bjam using this command:

.\BOOTSTRAP.BAT

Building tests and examples

Building tests and examples requires OpenSSL installed. If OpenSSL is installed in a non-system location, you will need to copy the user-config.jam file into your home directory and set the OPENSSL_ROOT environment variable to the path that contains an installation of OpenSSL.

Ubuntu/Debian

If installed into a system directory, OpenSSL will be automatically found and used.

sudo apt install libssl-dev

Windows

Replace path in the following code snippets with the path you installed vcpkg to. Examples assume a 32-bit build, if you build a 64-bit version replace x32-windows with x64-windows in the path.

Using vcpkg and CMD:

vcpkg install openssl --triplet x32-windows
SET OPENSSL_ROOT=path\installed\x32-windows

Using vcpkg and PowerShell:

vcpkg install openssl --triplet x32-windows
$env:OPENSSL_ROOT = "path\x32-windows"

Using vcpkg and bash:

vcpkg.exe install openssl --triplet x32-windows
export OPENSSL_ROOT=path/x32-windows

Mac OS

Using brew:

brew install openssl
export OPENSSL_ROOT=$(brew --prefix openssl)
# install bjam tool user specific configuration file to read OPENSSL_ROOT
# see https://www.bfgroup.xyz/b2/manual/release/index.html
cp ./libs/beast/tools/user-config.jam $HOME

Make sure the bjam tool (also called "b2") is available in the path your shell uses to find executables. The Beast project is located in "libs/beast" relative to the directory containing the Boot superproject. To build the Beast tests, examples, and documentation use these commands:

export PATH=$PWD:$PATH
b2 -j2 libs/beast/test cxxstd=11      # bjam must be in your $PATH
b2 -j2 libs

Beast

Install / Use

README