]>
Commit | Line | Data |
---|---|---|
1 | <img width="880" height = "80" alt = "Beast" | |
2 | src="https://raw.githubusercontent.com/vinniefalco/Beast/master/doc/images/readme.png"> | |
3 | ||
4 | [![Join the chat at https://gitter.im/vinniefalco/Beast](https://badges.gitter.im/vinniefalco/Beast.svg)](https://gitter.im/vinniefalco/Beast?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) | |
5 | [![Build Status](https://travis-ci.org/vinniefalco/Beast.svg?branch=master)](https://travis-ci.org/vinniefalco/Beast) | |
6 | [![Build status](https://ci.appveyor.com/api/projects/status/g0llpbvhpjuxjnlw?svg=true)](https://ci.appveyor.com/project/vinniefalco/beast) | |
7 | [![codecov](https://codecov.io/gh/vinniefalco/Beast/branch/master/graph/badge.svg)](https://codecov.io/gh/vinniefalco/Beast) | |
8 | [![coveralls](https://coveralls.io/repos/github/vinniefalco/Beast/badge.svg?branch=master)](https://coveralls.io/github/vinniefalco/Beast?branch=master) | |
9 | [![Documentation](https://img.shields.io/badge/documentation-master-brightgreen.svg)](http://vinniefalco.github.io/beast/) | |
10 | [![License](https://img.shields.io/badge/license-boost-brightgreen.svg)](LICENSE_1_0.txt) | |
11 | ||
12 | # HTTP and WebSocket built on Boost.Asio in C++11 | |
13 | ||
14 | --- | |
15 | ||
16 | ## Appearances | |
17 | ||
18 | | <a href="http://cppcast.com/2017/01/vinnie-falco/">CppCast 2017</a> | <a href="https://raw.githubusercontent.com/vinniefalco/Beast/master/doc/images/CppCon2016.pdf">CppCon 2016</a> | | |
19 | | ------------ | ----------- | | |
20 | | <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/Beast/master/doc/images/CppCon2016.png"></a> | | |
21 | ||
22 | --- | |
23 | ||
24 | ## Contents | |
25 | ||
26 | - [Introduction](#introduction) | |
27 | - [Description](#description) | |
28 | - [Requirements](#requirements) | |
29 | - [Building](#building) | |
30 | - [Usage](#usage) | |
31 | - [Licence](#licence) | |
32 | - [Contact](#contact) | |
33 | ||
34 | ## Introduction | |
35 | ||
36 | Beast is a header-only, cross-platform C++ library built on Boost.Asio and | |
37 | Boost, containing two modules implementing widely used network protocols. | |
38 | Beast.HTTP offers a universal model for describing, sending, and receiving | |
39 | HTTP messages while Beast.WebSocket provides a complete implementation of | |
40 | the WebSocket protocol. Their design achieves these goals: | |
41 | ||
42 | * **Symmetry.** Interfaces are role-agnostic; the same interfaces can be | |
43 | used to build clients, servers, or both. | |
44 | ||
45 | * **Ease of Use.** HTTP messages are modeled using simple, readily | |
46 | accessible objects. Functions and classes used to send and receive HTTP | |
47 | or WebSocket messages are designed to resemble Boost.Asio as closely as | |
48 | possible. Users familiar with Boost.Asio will be immediately comfortable | |
49 | using this library. | |
50 | ||
51 | * **Flexibility.** Interfaces do not mandate specific implementation | |
52 | strategies; important decisions such as buffer or thread management are | |
53 | left to users of the library. | |
54 | ||
55 | * **Performance.** The implementation performs competitively, making it a | |
56 | realistic choice for building high performance network servers. | |
57 | ||
58 | * **Scalability.** Development of network applications that scale to thousands | |
59 | of concurrent connections is possible with the implementation. | |
60 | ||
61 | * **Basis for further abstraction.** The interfaces facilitate the | |
62 | development of other libraries that provide higher levels of abstraction. | |
63 | ||
64 | Beast is used in [rippled](https://github.com/ripple/rippled), an | |
65 | open source server application that implements a decentralized | |
66 | cryptocurrency system. | |
67 | ||
68 | ## Description | |
69 | ||
70 | This software is currently in beta: interfaces may change. | |
71 | For recent changes see the [CHANGELOG](CHANGELOG.md). | |
72 | The library has been submitted to the | |
73 | [Boost Library Incubator](http://rrsd.com/blincubator.com/bi_library/beast-2/?gform_post_id=1579) | |
74 | ||
75 | * [Project Site](http://vinniefalco.github.io/) | |
76 | * [Repository](https://github.com/vinniefalco/Beast) | |
77 | * [Project Documentation](http://vinniefalco.github.io/beast/) | |
78 | * [Autobahn.testsuite results](http://vinniefalco.github.io/autobahn/index.html) | |
79 | ||
80 | ## Requirements | |
81 | ||
82 | * Boost 1.58 or later | |
83 | * C++11 or later | |
84 | ||
85 | When using Microsoft Visual C++, Visual Studio 2015 Update 3 or later is required. | |
86 | ||
87 | These components are optionally required in order to build the | |
88 | tests and examples: | |
89 | ||
90 | * OpenSSL (optional) | |
91 | * CMake 3.7.2 or later (optional) | |
92 | * Properly configured bjam/b2 (optional) | |
93 | ||
94 | ## Building | |
95 | ||
96 | Beast is header-only so there are no libraries to build or link with. | |
97 | To use Beast in your project, simply copy the Beast sources to your | |
98 | project's source tree (alternatively, bring Beast into your Git repository | |
99 | using the `git subtree` or `git submodule` commands). Then, edit your | |
100 | build scripts to add the `include/` directory to the list of paths checked | |
101 | by the C++ compiler when searching for includes. Beast `#include` lines | |
102 | will look like this: | |
103 | ```C++ | |
104 | #include <beast/http.hpp> | |
105 | #include <beast/websocket.hpp> | |
106 | ``` | |
107 | ||
108 | To link your program successfully, you'll need to add the Boost.System | |
109 | library to link with. If you use coroutines you'll also need the | |
110 | Boost.Coroutine library. Please visit the Boost documentation for | |
111 | instructions on how to do this for your particular build system. | |
112 | ||
113 | For the examples and tests, Beast provides build scripts for Boost.Build (bjam) | |
114 | and CMake. It is possible to generate Microsoft Visual Studio or Apple | |
115 | Xcode project files using CMake by executing these commands from | |
116 | the root of the repository: | |
117 | ||
118 | ``` | |
119 | cd bin | |
120 | cmake .. # for 32-bit Windows builds | |
121 | cmake -G Xcode .. # for Apple Xcode builds | |
122 | ||
123 | cd ../bin64 | |
124 | cmake -G"Visual Studio 14 2015 Win64" .. # for 64-bit Windows builds (VS2015) | |
125 | cmake -G"Visual Studio 15 2017 Win64" .. # for 64-bit Windows builds (VS2017) | |
126 | ||
127 | ``` | |
128 | ||
129 | To build with Boost.Build, it is necessary to have the bjam executable | |
130 | in your path. And bjam needs to know how to find the Boost sources. The | |
131 | easiest way to do this is make sure that the version of bjam in your path | |
132 | is the one at the root of the Boost source tree, which is built when | |
133 | running `bootstrap.sh` (or `bootstrap.bat` on Windows). | |
134 | ||
135 | Once bjam is in your path, simply run bjam in the root of the Beast | |
136 | repository to automatically build the required Boost libraries if they | |
137 | are not already built, build the examples, then build and run the unit | |
138 | tests. | |
139 | ||
140 | The files in the repository are laid out thusly: | |
141 | ||
142 | ``` | |
143 | ./ | |
144 | bin/ Holds executables and project files | |
145 | bin64/ Holds 64-bit Windows executables and project files | |
146 | doc/ Source code and scripts for the documentation | |
147 | include/ Add this to your compiler includes | |
148 | beast/ | |
149 | extras/ Additional APIs, may change | |
150 | examples/ Self contained example programs | |
151 | test/ Unit tests and benchmarks | |
152 | ``` | |
153 | ||
154 | ||
155 | ## Usage | |
156 | ||
157 | These examples are complete, self-contained programs that you can build | |
158 | and run yourself (they are in the `examples` directory). | |
159 | ||
160 | Example WebSocket program: | |
161 | ```C++ | |
162 | #include <beast/core/to_string.hpp> | |
163 | #include <beast/websocket.hpp> | |
164 | #include <boost/asio.hpp> | |
165 | #include <iostream> | |
166 | #include <string> | |
167 | ||
168 | int main() | |
169 | { | |
170 | // Normal boost::asio setup | |
171 | std::string const host = "echo.websocket.org"; | |
172 | boost::asio::io_service ios; | |
173 | boost::asio::ip::tcp::resolver r{ios}; | |
174 | boost::asio::ip::tcp::socket sock{ios}; | |
175 | boost::asio::connect(sock, | |
176 | r.resolve(boost::asio::ip::tcp::resolver::query{host, "80"})); | |
177 | ||
178 | // WebSocket connect and send message using beast | |
179 | beast::websocket::stream<boost::asio::ip::tcp::socket&> ws{sock}; | |
180 | ws.handshake(host, "/"); | |
181 | ws.write(boost::asio::buffer(std::string("Hello, world!"))); | |
182 | ||
183 | // Receive WebSocket message, print and close using beast | |
184 | beast::streambuf sb; | |
185 | beast::websocket::opcode op; | |
186 | ws.read(op, sb); | |
187 | ws.close(beast::websocket::close_code::normal); | |
188 | std::cout << beast::to_string(sb.data()) << "\n"; | |
189 | } | |
190 | ``` | |
191 | ||
192 | Example HTTP program: | |
193 | ```C++ | |
194 | #include <beast/http.hpp> | |
195 | #include <boost/asio.hpp> | |
196 | #include <boost/lexical_cast.hpp> | |
197 | #include <iostream> | |
198 | #include <string> | |
199 | ||
200 | int main() | |
201 | { | |
202 | // Normal boost::asio setup | |
203 | std::string const host = "boost.org"; | |
204 | boost::asio::io_service ios; | |
205 | boost::asio::ip::tcp::resolver r{ios}; | |
206 | boost::asio::ip::tcp::socket sock{ios}; | |
207 | boost::asio::connect(sock, | |
208 | r.resolve(boost::asio::ip::tcp::resolver::query{host, "http"})); | |
209 | ||
210 | // Send HTTP request using beast | |
211 | beast::http::request<beast::http::string_body> req; | |
212 | req.method = "GET"; | |
213 | req.url = "/"; | |
214 | req.version = 11; | |
215 | req.fields.replace("Host", host + ":" + | |
216 | boost::lexical_cast<std::string>(sock.remote_endpoint().port())); | |
217 | req.fields.replace("User-Agent", "Beast"); | |
218 | beast::http::prepare(req); | |
219 | beast::http::write(sock, req); | |
220 | ||
221 | // Receive and print HTTP response using beast | |
222 | beast::streambuf sb; | |
223 | beast::http::response<beast::http::streambuf_body> resp; | |
224 | beast::http::read(sock, sb, resp); | |
225 | std::cout << resp; | |
226 | } | |
227 | ``` | |
228 | ||
229 | ## License | |
230 | ||
231 | Distributed under the Boost Software License, Version 1.0. | |
232 | (See accompanying file [LICENSE_1_0.txt](LICENSE_1_0.txt) or copy at | |
233 | http://www.boost.org/LICENSE_1_0.txt) | |
234 | ||
235 | ## Contact | |
236 | ||
237 | Please report issues or questions here: | |
238 | https://github.com/vinniefalco/Beast/issues |