Firebolt C++ Transport

A C++17 WebSocket + JSON-RPC 2.0 transport library shared by all Firebolt C++ SDKs. It handles connection management, request/response correlation, and event subscriptions — so higher-level SDKs only deal with typed method calls.

Architecture

Your App / Firebolt SDK
    │
    ▼
IHelper  (get<T> / set / invoke / subscribe)
    │
    ▼
IGateway  (JSON-RPC 2.0 framing over WebSocket)
    │
    ▼
ws://127.0.0.1:3474/jsonrpc  (Firebolt gateway daemon — out of process)

All production code is outbound-only. No listening sockets are opened by this library.

Public API

Result<T> — return type for all calls

auto result = helper.get<MyJsonType, std::string>("module.method");
if (result) {
    use(*result);          // has a value
} else {
    auto e = result.error(); // Firebolt::Error enum
    auto info = result.errorInfo(); // Firebolt::ErrorInfo (code + message)
    // info.error() gives the error code (int32_t)
    // info.message() gives the error message (std::string)
}

IGateway — low-level JSON-RPC transport

IGateway& gw = Firebolt::Transport::GetGatewayInstance();
gw.connect(config, onConnectionChange);
auto future = gw.request("module.method", params);
gw.subscribe("module.onEvent", callback, userdata);
gw.unsubscribe("module.onEvent", userdata);
gw.disconnect();

IHelper — typed wrapper over IGateway

IHelper& helper = Firebolt::Helpers::GetHelperInstance();
auto result = helper.get<DeviceIdJson, std::string>("device.id");
helper.set("device.name", params);
helper.invoke("lifecycle.ready", {});
SubscriptionId id = helper.subscribe<EventJson>("device.onNameChanged", callback, userdata);
helper.unsubscribe("device.onNameChanged", id);

Firebolt::Error — error codes

Value	Meaning
None	Success
NotConnected	No active WebSocket connection
Timedout	Request timed out
CapabilityNotPermitted	App lacks the required capability
InvalidRequest / InvalidParams	Bad JSON-RPC request

Building

Dependencies (GTest, nlohmann_json, websocketpp, gcovr) are only available inside the CI Docker image. Use the helper scripts:

./test.sh          # build + run unit tests  (like cargo test)
./fmt.sh           # check formatting        (like cargo fmt --check)
./fmt.sh --fix     # reformat in place

The image is built automatically from .github/Dockerfile on first run.

For cross-compilation against a sysroot (e.g. for device targets):

SYSROOT_PATH=/path/to/sysroot ./build.sh --release

Project Layout

include/firebolt/   public headers (gateway.h, helpers.h, json_types.h, types.h, logger.h)
src/                implementation
test/unit/          GTest unit tests (*Test.cpp)
.github/Dockerfile  CI image definition

License

Apache 2.0 — see LICENSE

Header Support

The transport layer supports custom HTTP headers during WebSocket connection setup and allows retrieval of response headers from the server.

Sending Custom Headers

You can specify custom headers in the Firebolt::Config struct:

Firebolt::Config config;
config.wsUrl = "ws://localhost:9002";
config.headers["Authorization"] = "Bearer <token>";
config.headers["X-Custom-Header"] = "value";

Pass the config to the gateway's connect method:

Firebolt::Transport::IGateway& gateway = Firebolt::Transport::GetGatewayInstance();
gateway.connect(config, onConnectionChange);

Retrieving Response Headers

After a successful connection, you can retrieve response headers sent by the server:

std::optional<std::string> value = gateway.getResponseHeader("Server");
if (value) {
    std::cout << "Server header: " << *value << std::endl;
}

• If the header is present, its value is returned.
• If the header is not present, std::nullopt is returned.

Thread Safety

Header operations are thread-safe. Access to response headers is protected by a mutex internally.

API Reference

• Config struct
• IGateway interface
• websocketpp connection API - get_response_header