README

This repository contains the cross-platform C++ tubus library, which implements a streaming transport protocol based on UDP. The protocol was originally developed as part of the wormhole utility. It can be used in cases where the use of TCP is difficult, for example, for applications running over NAT. Optionally, to increase connection security, tubus packets can be obfuscated by a pre-shared key.

For the convenience of developing applications based on boost::asio, the asio-like primitives tubus::socket and tubus::acceptor are offered. The tubus::socket primitive implements AsyncReadStream, AsyncWriteStream, Stream, SyncReadStream and SyncWriteStream concepts, so it can be used as the lower layer of boost::asio::ssl::stream.

Core

Tubus сhannel interface.

namespace tubus {
...
struct channel
{
    virtual ~channel() noexcept(true) {}
    virtual void close() noexcept(true) = 0;
    virtual void open(const endpoint& local) noexcept(false) = 0;
    virtual void connect(const endpoint& remote, const callback& handle) noexcept(true) = 0;
    virtual void accept(const endpoint& remote, const callback& handle) noexcept(true) = 0;
    virtual void read(const mutable_buffer& buffer, const io_callback& handle) noexcept(true) = 0;
    virtual void write(const const_buffer& buffer, const io_callback& handle) noexcept(true) = 0;
    virtual void shutdown(const callback& handle) noexcept(true) = 0;
    virtual size_t writable() const noexcept(true) = 0;
    virtual size_t readable() const noexcept(true) = 0;
    virtual endpoint host() const noexcept(false) = 0;
    virtual endpoint peer() const noexcept(false) = 0;
};
...
channel_ptr create_channel(boost::asio::io_context& io, uint64_t /*pre-shared key*/ secret = 0) noexcept(true);
}

open - opens a channel at the specified endpoint
close - closes the channel without notifying the remote side, interrupts all pended asynchronous operations
shutdown - closes the channel with the notification of the remote side, interrupts all pended asynchronous operations
accept - waits asynchronously for connection from the specified peer
connect - starts asynchronously connecting to the specified peer
read - appends asynchronous read operation, calls back when the passed buffer is full or an error has occurred
write - appends asynchronous write operation, calls back when the passed buffer is transmitted or an error has occurred
writable - returns the number of bytes that can be transmitted immediately
readable - returns number of bytes available for reading
host - returns local endpoint of the channel
peer - returns remote endpoint of the channel

Examples

Data consumer implemented using tubus::channel.

#include <tubus/channel.h>
...
auto consumer = tubus::create_channel(io_service, key);
consumer->open(local_endpoint);
consumer->connect(remote_endpoint, [&](const boost::system::error_code& error)
{
    ...
    tubus::mutable_buffer buffer(consumer->readable()); 
    
    // if the buffer is empty, the callback will be called when all previously
    // pended read operations are completed and more data can be read
    
    consumer->read(buffer, [&](const boost::system::error_code& error, size_t size)
    {
        ...
        consumer->shutdown();
    };
});

Data producer implemented using tubus::socket.

#include <tubus/socket.h>
...
tubus::socket producer(io_service, key);
producer.open(local_endpoint);
producer.async_accept(remote_endpoint, [&](const boost::system::error_code& error)
{
    ...
    tubus::const_buffer buffer("hello, world!");
    producer.async_write_some(buffer, [&](const boost::system::error_code& error, size_t size)
    {
        ...
        producer.shutdown();
    };
});

Server implemented using tubus::acceptor (Linux only).

#include <tubus/acceptor.h>
...
tubus::acceptor server(io_service, key);
server.open(local_endpoint);

tubus::socket peer1(io_service);
server.accept(peer1);

peer1.read_some(...);
peer1.write_some(...);

tubus::socket peer2(io_service);
server.accept(peer2);

peer2.read_some(...);
peer2.write_some(...);

peer1.shutdown();
peer2.shutdown();

server.close();

Encrypted stream implemented using boost::asio::ssl::stream and tubus::socket.

#include <boost/asio/ssl.hpp>
#include <tubus/socket.h>
...
boost::asio::ssl::stream<tubus::socket> client(tubus::socket(io_service, key), ssl_ctx);

client.lowest_layer().open(local_endpoint);
client.lowest_layer().connect(remote_endpoint);
client.handshake(boost::asio::ssl::stream_base::client);

boost::asio::read(client, ...);
boost::asio::write(client, ...);

client.shutdown();

Build

You can download prebuild packages for Debian and Windows platforms.

The library depends on the boost. To build tests, the openssl is required.

cd ~
git clone https://github.com/novemus/tubus.git
cd ~/tubus
cmake -B ./build [-DBOOST_ROOT=...] [-DBUILD_TESTING=ON [-DOPENSSL_ROOT_DIR=...]]
cmake --build ./build --config Release --target tubus_shared tubus_static [tubus_ut]
cmake --build ./build --target install

CMake import variables.

tubus_USE_SHARED_LIB=ON - import dynamic library to your CMake project, searches for a static library by default
tubus_INCLUDE_DIR - tubus header files directory
tubus_LIBRARY_DIR - tubus library directory
tubus_DLL - the path to the tubus.dll library file
tubus_LIB - the path to the tubus-static.lib, tubus.lib, libtubus.a or libtubus.so library file

Collaboration

Report bugs and suggest improvements.

License

Tubus is licensed under the Apache License 2.0, which means that you are free to get and use it for commercial and non-commercial purposes as long as you fulfill its conditions. See the LICENSE.txt file for more details.