Firebolt CPP 2.0

Firebolt C++ 2.0 Architecture

The Firebolt native application ecosystem currently relies on two independent repositories that collectively provide Firebolt API access to C++ applications:

1. Firebolt C++ Client
2. Firebolt C++ Transport While this separation originally provided clear ownership boundaries between API consumption and transport functionality, the implementation has gradually evolved such that both repositories now contain overlapping responsibilities, resulting in tighter coupling, duplicated logic, and increased maintenance costs.

As adoption of Firebolt native applications expands across RDK platforms, a reassessment of repository boundaries and responsibilities is necessary to improve maintainability, enable architectural evolution, and reduce long-term operational overhead.

Overview

Firebolt CPP 2.0 defines the proposed refactoring of the Firebolt native C++ client ecosystem.

The goal is to separate responsibilities across three primary layers:

• Firebolt Model
• Firebolt Transport
• Firebolt Client

This structure reduces coupling between generated API models, runtime client behavior, and transport implementation details.

Goals

• Clarify ownership between client, model, and transport layers
• Remove dependency on a globally shared singleton model
• Enable explicit transport ownership
• Support custom transport implementations
• Improve scalability and testability
• Preserve strong typing for generated Firebolt APIs
• Support public and private API surfaces

Background

• Architectural Challenges
• Watchdog Cleanup Improvements

Architecture Vision

Vision

Firebolt CPP 2.0 separates Firebolt responsibilities into three distinct layers:

• The Model layer defines what Firebolt data looks like.
• The Transport layer defines how messages move.
• The Client layer binds models and transport together by managing runtime execution.

This separation creates a transport-agnostic, scalable, and extensible Firebolt programming model while maintaining strong type safety and minimizing framework overhead.

Design Principles

Explicit Ownership

Applications construct and own a FireboltClient instance. This replaces implicit access through a global singleton.

Transport Abstraction

The client depends on IFireboltTransport, allowing the default Firebolt transport or a custom application-provided transport to be used.

Strongly Typed Models

Generated Firebolt request, response, event, primitive, enum, and object models share a common model contract.

Compile-Time Model Behavior

Generated models use CRTP-based compile-time polymorphism to avoid unnecessary virtual interface overhead.

Runtime Transport Flexibility

Transport implementations use runtime polymorphism because transport selection is application-defined and may vary at runtime.

Strategic Outcome

Firebolt CPP 2.0 gives applications a clearer and more flexible integration model while preserving generated API usability and type-safe Firebolt data access.

Layered Architecture

Overview

Firebolt CPP 2.0 is organized around three primary layers:

+------------------------------------------------------+
|                  Firebolt Interfaces                 |
|     Public Headers            Private Headers        |
+------------------------+-----------------------------+
                         |
                         v
+------------------------------------------------------+
|                    Firebolt Client                   |
|  - Interface Access                                   |
|  - Request Correlation                                |
|  - Callback Dispatch                                  |
|  - Event Dispatch                                     |
|  - Uses IFireboltTransport                            |
+------------------------------------------------------+
                         |
                         v
+------------------------------------------------------+
|              Transport Implementation                |
|  - Firebolt Default Transport                         |
|  - Custom User Transport                              |
+------------------------------------------------------+
                         |
                         v
+------------------------------------------------------+
|                     App Gateway                      |
+------------------------------------------------------+

Example Code

Initialization

#include <firebolt/lifecycle.h>

std::shared_ptr<IFireboltTransport> transport =
    /* transport implementation */;

FireboltClient firebolt(transport);

auto& lifecycle =
    LifecycleInterface(firebolt);

---

Asynchronous Request

lifecycle.GetLifecycleState().Then(
    const FireboltResult<LifecycleState>& result
    {
        if (!result)
        {
            return;
        }

        const LifecycleState& state =
            result.Value();

        std::cout
           << state.state.value
           << std::endl;
    });

---

Synchronous Request

auto result =
    lifecycle.GetLifecycleState()
        .Get(std::chrono::seconds(5));

if (result)
{
  const LifecycleState& state =
       result.Value();

    std::cout
        << state.state.value
        << std::endl;
}

---

Event Subscription

auto subscription =
    lifecycle.OnStateChanged(
        const LifecycleState& state
        {
            std::cout
                << state.state.value
                << std::endl;
        });

---

Unsubscribe

subscription.Unsubscribe()

---

Layer Responsibilities

Firebolt Model

Defines generated Firebolt data contracts and conversion behavior. More details below. Firebolt CPP 2.0 Model

Firebolt Transport

Defines the transport contract and provides communication abstraction. More details below. Firebolt CPP 2.0 Transport

Firebolt Client

Binds generated interfaces and models to a specific transport context. More details below. Firebolt CPP 2.0 Client

API Interface Headers

Header-Only

• Public headers
• Private headers
• Firebolt models

Compiled Libraries

• libfirebolt-client.so
• libfirebolt-transport-default.so

More details below. Firebolt CPP 2.0 API Headers