Note

This is a cleanup and modernization of the belle http/websocket library using CMake and modern Boost library.

Belle

An HTTP / Websocket library in C++20 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.

A Brief Tour

An HTTP server listening on 127.0.0.1:8080 that responds to a POST request to the path '/'.

#include <belle/server.hpp>

#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 '/'.

#include <belle/client.hpp>

#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;
}

About

Belle is a single header C++20 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:

• Intuitive API: Interactions with the library should be as straightforward and concise as that of a modern scripting language.
• Reasonable Defaults: The default state of data and behaviour should be logical and expected, allowing customization when needed.
• Great Performance: Speed and memory usage is important and sought after, but not at the cost of diminishing the goals listed above.

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.

Warning

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:

Server Features

• HTTP 1.0 / 1.1 server (async, SSL / TLS, multithreaded)
• Websocket server (async, SSL / TLS)
• Serve static content
• Serve dynamic content
• Use lambdas as handlers
• Routes can match a single, multiple, or all HTTP methods
• Use regular expressions with capture groups to match and tokenize routes
• Parse query parameters
• URL percent-decode query parameters
• Handle HTTP and Websocket on the same port
• Group Websocket connections into channels for broadcasting

Client Features

• HTTP 1.0 / 1.1 client (async, SSL / TLS)
• Use lambdas as handlers
• Serialize query parameters
• URL percent-encode query parameters

Future Features

• Add an async, SSL / TLS Websocket client
• add Websocket ping, pong, and timeout
• Add an interface for a custom logger
• Add connection manager for clean shutdown
• Chunked encoding support
• Request and response streaming support
• General optimizations to improve performance

Install

This library now uses CMake and installs to the system as follows:

# configure the library.
cmake -B ${BUILD_DIR} -S .

# Install the library
sudo cmake --install build # default location '/usr/local/
# If you wish to install the library to a custom location:
sudo cmake --install build --prefix ${LOCATION}

Requirements

• A C++ compiler supporting std=C++20
• OpenSSL >= v1.1.0 (if SSL is enabled)
• CMake >= v3.16
• boost libs >= v1.88
• libpthread

Flags

Use the following define flags at compile time to alter the library:

• -D OB_BELLE_CONFIG_SSL_OFF - Disable SSL support.
• -D OB_BELLE_CONFIG_CLIENT_OFF - Disable client support.
• -D OB_BELLE_CONFIG_SERVER_OFF - Disable server support

Usage

#include <belle/belle.hpp>

Make sure to link the Requirements listed above.

Documentation

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

Examples

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 build
$ cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
$ cmake --build build --parallel
$ cd build
$ ./app

Server

• hello: an HTTP server with a get endpoint, post endpoint, and static file handling
• http: a multithreaded HTTP server with multiple endpoints, static file handling, signal handling, and error handling
• https: a multithreaded HTTPS server with multiple endpoints, static file handling, signal handling, and error handling
• chat: a single threaded HTTP / Websocket chat room server with multiple endpoints, static file handling, signal handling, and error handling, with a basic html/css/js client interface
• chat-ssl: a single threaded HTTPS / Websocket Secure chat room server with multiple endpoints, static file handling, signal handling, -nd error handling, with a basic html/css/js client interface
• file_upload: a single-threaded http server that can directly stream files from disk into the response body, ideal for large-file uploads.

Client

• http: an HTTP client that makes multiple requests to a remote endpoint
• https: an HTTPS client that makes multiple requests to a remote endpoint

Tests

There are currently no tests at this time, but there are plans to add them in the future.

Benchmarks

There are currently no benchmarks at this time, but there are plans to add them in the future.

Versioning

This project uses Semantic Versioning.