Home

Awesome

Build Status <span class="badge-paypal"><a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=GME2V7WLLFRT2" title="Donate to this project using Paypal"><img src="https://img.shields.io/badge/paypal-donate-yellow.svg" alt="PayPal donate button" /></a></span> <span class="badge-bitcoin"><a href="https://www.coinbase.com/checkouts/95751916234a5d59b197d8ef1916cfe6" title="Donate once-off to this project using Bitcoin"><img src="https://img.shields.io/badge/bitcoin-donate-yellow.svg" alt="Bitcoin donate button" /></a></span>

Club

A lightweight Peer-to-Peer networking engine for real time applications written in C++14.

Motivation

Real time applications such as Online games, VoIP, Instant Messaging or Videoconference apps need a way to communicate and synchronize state among interested peers. The traditional way of doing so is to have a dedicated server that receives commands from clients while assigning an implicit order (order in which messages are received) to those commands.

Such centralized structure is relatively easy to implement and works great for many aplications, but comes with drawbacks in the form of server bandwidth, maintenance and attack protection costs. This renders the centralized approach infeasible for applications with a smaller budget.

On the other hand, decentralization adds another layers of complexity on top of already complex matter. There are problems such as not every node can connect to every other node directly, packets from different sources may be received by other nodes in different order, and in cases of network partition, there is no central authority that says who is in the game and who is not.

Club implements solutions to such problems and hides this complexity behind a simple to use API.

Dependencies

Build & run

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release
# To make everything (the library, tests, benchmark and a demo) run
# make without arguments. Alternatively use these targets:
#  club                  : Builds the libclub.a library
#  club-tests            : Builds tests
#  transport-speed-bench : Builds a not-so-complete transport benchmark
#  rendezvous-server     : Builds the rendezvous server
make

Run tests

# The stun_client test expects stun servers (not part of Club) to run on localhost.
stunserver --primaryport=3478 &
stunserver --primaryport=3480 &
stunserver --primaryport=3482 &
stunserver --primaryport=3484 &
stunserver --primaryport=3486 &
./club-tests --run_test="*" --log_level=test_suite

Run chat demo

To run the club-chat demo, invoke ./club-chat from multiple teminals. The terminals need not be on the same PC nor LAN but the app does need an internet acess.

API Description

There are essentially only two classes that developers need to know about: Socket and Hub. Socket can be seen as a cross between the traditional TCP and UDP socket, in that it is connection oriented, provides both reliable and unreliable message delivery and congestion control.

Hub is an interface to the network of connected nodes. It provides an interface to send messages and merge networks together. Hub currently provides two types of send operations.

The total-order property makes this guarantee: If a node received a message M1 before a message M2, then every node that received both of those messages shall receive them in the same order.

Demos

Features