C++ SDK

The C++ SDK targets native environments where performance, runtime control, and deep integration with existing networking stacks matter.

Repository: github.com/rstreamlabs/rstream-cpp

This page focuses on the C++ SDK surface. For raw HTTP routes, see APIs. For event-stream semantics, see Signaling.

Its implementation focus differs from the Go SDK. The C++ surface is built for native integration inside an existing process, for Boost.Asio and Boost.Beast friendly async APIs, for long-lived bytestream tunnel workflows, and for compatibility with the same config and project model as the CLI. The Go SDK remains the reference SDK and covers the broadest surface today, while the C++ SDK is intended for native services, gateways, appliances, and device software.

Current focus

rstream-cpp is centered on bytestream tunnel workflows and operational connectivity inside C++ processes. Typical use cases include native HTTP services exposed through rstream, embedded agents and gateways, private bytestream connectivity between native components, and integrations that already use Boost.Asio or Beast.

Published and private tunnels

The SDK supports the two main tunnel patterns used by rstream: published tunnels, which expose a forwarding address through the edge, and private tunnels, which are consumed by tunnel id or name through rstream-native dialing. Tunnel properties still carry policy-related configuration such as labels and publication mode, while enforcement remains the responsibility of the rstream edge.

Async model

The SDK follows the Boost.Asio asynchronous model. Core objects use executors, strands, and async_initiate, which makes integration natural in codebases that already use Asio.

If your code already uses Beast, Asio coroutines, or executor-based networking components, rstream-cpp fits that style directly.

Build prerequisites

A typical source build uses a C++20 compiler, CMake, Conan 2.x, Python 3.x, and usually Ninja as the build generator. Dependencies are resolved through Conan/CMake integration and include Boost, OpenSSL or LibreSSL, yaml-cpp, nlohmann_json, and spdlog.

Build from source

Local CMake build:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --build build --target check
cmake --install build --prefix ./build/release

Conan package build:

conan profile detect --force
conan config install conan/config
conan create . -u --build=missing -pr:b default -pr:h default

The repository also provides packaging helpers such as build-conan-cross.sh, build-docker-conan.sh, and deploy.py for producing distributable artifacts.

Using the SDK in CMake

After installation or Conan consumption, integrate through find_package and link rstream::rstream.

find_package(rstream CONFIG REQUIRED)
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE rstream::rstream)

Authentication and project setup

The C++ SDK uses the same runtime config model as the rstream CLI.

Typical developer-machine setup:

rstream login
rstream project use <project-endpoint> --default

The SDK then reads the same ~/.rstream/config.yaml file and context selection model as the CLI.

Useful overrides include RSTREAM_CONFIG, RSTREAM_CONTEXT, RSTREAM_API_URL, RSTREAM_ENGINE_ADDRESS, RSTREAM_ENGINE, and RSTREAM_AUTHENTICATION_TOKEN.

Minimal published HTTP server example

The example below creates a published HTTP tunnel and serves a simple Beast response through an io-rstrm socket.

#include <csignal>
#include <iostream>
#include <boost/asio.hpp>
#include <boost/beast/core.hpp>
#include <boost/beast/http.hpp>
#include <rstream/io-rstrm/client.hpp>
#include <rstream/io-rstrm/io-rstrm.hpp>
#include <rstream/io-rstrm/socket.hpp>
 
namespace asio = boost::asio;
namespace http = boost::beast::http;
namespace rstrm = rstream::io_rstrm;
 
asio::awaitable<void> session(rstrm::socket socket) {
  http::request<http::string_body> req;
  boost::beast::flat_buffer buffer;
  co_await http::async_read(socket, buffer, req, asio::use_awaitable);
  http::response<http::string_body> res{http::status::ok, req.version()};
  res.set(http::field::content_type, "text/plain");
  res.body() = "Hello from rstream-cpp";
  res.prepare_payload();
  co_await http::async_write(socket, res, asio::use_awaitable);
}
 
asio::awaitable<void> listener() {
  auto executor = co_await asio::this_coro::executor;
  rstrm::client client(executor);
  co_await client.async_connect(asio::use_awaitable);
  rstrm::tunnel_properties properties = {
    .m_publish = true,
    .m_protocol = rstrm::protocol::http,
  };
  auto tunnel = co_await client.async_create_tunnel(
    properties,
    asio::use_awaitable,
  );
  while (true) {
    rstrm::socket socket(executor);
    rstrm::endpoint peer;
    co_await tunnel.async_accept(socket, peer, asio::use_awaitable);
    asio::co_spawn(executor, session(std::move(socket)), asio::detached);
  }
}

Private-tunnel pattern

The repository also includes examples for private tunnel patterns, including programmatic dial flows that avoid a published forwarding address. Those examples are a good starting point when you want native service-to-service connectivity rather than public exposure.

Examples

The main repository includes examples for published HTTP servers, private bytestream tunnels, Boost/Asio integration patterns, and packaging and Conan usage.