belle
/
README.md
An HTTP / Websocket library in C++17 using Boost.Beast and Boost.ASIO.
Belle enables C++ programs to communicate asynchronously over HTTP and Websockets. It aims to have an intuitive API, reasonable defaults, and great performance.
An HTTP server listening on 127.0.0.1:8080 that responds to a POST request to the path '/'.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22#include "belle.hh"
namespace Belle = OB::Belle;
#include <string>
int main()
{
// init the server with local address and port
Belle::Server app {"127.0.0.1", 8080};
// handle route POST '/'
app.on_http("/", Belle::Method::post, [](auto& ctx)
{
// echo back the request body
ctx.res.body() = ctx.req.body();
});
// start the server
app.listen();
return 0;
}An HTTP client connecting to 127.0.0.1:8080 that sends a POST request to the path '/'.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23#include "belle.hh"
namespace Belle = OB::Belle;
#include <string>
#include <iostream>
int main()
{
// init the client with remote address and port
Belle::Client app {"127.0.0.1", 8080};
// request parameters and response handler
app.on_http(Belle::Method::post, "/", "Hello, Belle!", [](auto& ctx)
{
// print the response body
std::cout << ctx.res.body() << "\n";
});
// start the client
app.connect();
return 0;
}Belle is a single header C++17 library for working with HTTP and Websockets. It utilizes the HTTP and Websocket functionalities of Boost.Beast, along with the asynchronous networking capabilities of Boost.ASIO.
The design goals for Belle are the following:
There are many HTTP and Websocket libraries currently available, each with their own goals and advantages. As the networking layer is often a crucial component in your program, make sure to browse around and select a library that is going to be the most beneficial for you.
This library is undergoing active development and is working its way towards a 1.0.0 release. Be aware that while the major version is zero, 0.y.z, the public API should not be considered stable, and is subject to change at any time.
Belle welcomes and encourages your thoughts and feedback!
The following lists describe an overview of the current implemented features, along with the planned future features:
Belle is a single header file. It can either be installed into your systems include directory, or copied directly into your projects directory.
The default install location is /usr/local/include/ob/belle.hh.
To install on your system:
$ ./install.sh
To copy to your project:
$ cp ./include/belle.hh ./<project>
Use the following define flags at compile time to alter the library:
If Belle is installed on your system:
1
2#include <ob/belle.hh>
namespace Belle = OB::Belle;If Belle is copied to your project directory:
1
2#include "belle.hh"
namespace Belle = OB::Belle;Make sure to link the Dependencies, along with meeting the Requirements listed above.
The source code contains helpful comments and explanations. A detailed set of documentation and guides are planned for the future.
Basic documentation can be generated using Doxygen:
$ doxygen ./.doxyfile
There are several examples located in the ./example directory.
Each example has its own CMake build file, and can be built in either Debug or Release mode by passing the appropriate CMake flag, -DCMAKE_BUILD_TYPE=Debug or -DCMAKE_BUILD_TYPE=Release.
Several examples rely on relative paths, therefore, they expect to be executed
from a specific path. The example programs should be executed in their respective build directory.
Within an examples directory, the following will build and run it in Debug mode.
$ mkdir -p ./build
$ cd ./build
$ cmake ../ -DCMAKE_BUILD_TYPE=Debug
$ make
$ ./app
The examples depend on the Belle source file in the ./include directory.
To use one of the examples as a starting point, copy the selected example
to a new directory, and then follow the Install and Build
instructions listed above.
There are currently no tests at this time, but there are plans to add them in the future.
There are currently no benchmarks at this time, but there are plans to add them in the future.
This project uses Semantic Versioning.
This project is licensed under the MIT License.
Copyright (c) 2018 Brett Robinson
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.