Skip to content

Firebolt CPP 2.0 API Headers

Jump to bottom
Sathishkumar edited this page Oct 12, 2026 · 2 revisions

Firebolt API Headers

Overview

Generated Firebolt APIs consist of:

  • Firebolt model definitions
  • Firebolt interface definitions

Each interface is generated as a lightweight header-only wrapper around FireboltClient.

The interface is responsible for:

  • Exposing strongly typed API methods
  • Declaring request and response models
  • Defining event signatures

FireboltClient provides the runtime execution infrastructure through:

  • send()
  • subscribe()
  • cancel()
  • unsubscribe()

Firebolt Operation and Subscription Model

Overview

Firebolt APIs are built on top of an asynchronous JSON-RPC transport. Public APIs expose asynchronous interactions through FireboltOperation<T> and event registrations through FireboltSubscription.

The generated Firebolt models and interfaces remain header-only, while the underlying request tracking, callback dispatching, transport communication, and correlation logic are implemented within the Firebolt runtime library.

To support this separation, the public API uses lightweight typed wrappers that reference internal runtime state through opaque interfaces.

Internal Runtime State

class IOperationState;
class ISubscriptionState;

IOperationState and ISubscriptionState are internal runtime abstractions used by the Firebolt client implementation.

These interfaces are not intended to be consumed directly by application developers.

Their responsibilities include:

  • Request lifecycle management
  • JSON-RPC correlation
  • Callback dispatching
  • Request cancellation
  • Request completion tracking
  • Event subscription tracking
  • Event unsubscription
  • Thread synchronization
  • Transport interaction

The runtime library owns these objects and manages their lifetimes.

Because these interfaces are non-template types, the runtime library remains independent of generated Firebolt API models.

FireboltOperation

template<typename T>
class FireboltOperation;

FireboltOperation<T> represents a pending Firebolt request that will eventually complete with a typed response model.

The template parameter T is typically a generated Firebolt model type such as:

  • LifecycleState
  • DeviceInfo
  • AccountProfile
  • CapabilityRole
  • FireboltVoid

A FireboltOperation<T> provides a strongly typed view over an underlying runtime request and allows applications to consume the response either asynchronously or synchronously.

Responsibilities

  • Represent a single request/response interaction
  • Provide access to a typed response model
  • Support callback-based consumption
  • Support blocking consumption with timeout
  • Support request cancellation
  • Hide transport and JSON-RPC implementation details
  • Maintain type safety for generated model responses

Characteristics

  • Represents a one-time operation
  • Completes exactly once
  • Can succeed or fail
  • May be cancelled
  • Does not expose JSON-RPC identifiers
  • Uses internal runtime state through IOperationState

Public Contract

template<typename T>
class FireboltOperation
{
public:
    bool IsValid() const;

    bool IsCompleted() const;

    bool Cancel();

    void Then(
        OperationCallback<T> callback);

    FireboltResult<T> Get(
        std::chrono::milliseconds timeout);
};

FireboltSubscription

class FireboltSubscription;

FireboltSubscription represents an active Firebolt event registration.

Unlike FireboltOperation<T>, a subscription does not complete after a single response. It remains active until explicitly or automatically unsubscribed.

A subscription is created together with a listener callback and acts exclusively as a lifetime management object.

Responsibilities

  • Represent an active event registration
  • Manage subscription lifetime
  • Support explicit unsubscription
  • Support automatic cleanup during destruction
  • Hide event correlation details
  • Hide transport implementation details

Characteristics

  • Represents a long-lived event registration
  • Remains active until unsubscribed
  • Does not contain a response payload
  • Does not expose JSON-RPC subscription identifiers
  • Uses internal runtime state through ISubscriptionState

Public Contract

class FireboltSubscription
{
public:
    bool IsValid() const;

    bool IsActive() const;

    bool Unsubscribe();
};

Separation Between Operations and Subscriptions

Firebolt distinguishes request/response interactions from event streams because they have fundamentally different lifecycles.

FireboltOperation

Represents:

Request
   ↓
Response
   ↓
Complete

Characteristics:

  • Single response
  • Single completion
  • Optional cancellation
  • Optional blocking wait
  • Typed result

FireboltSubscription

Represents:

Subscribe
     ↓
Event
     ↓
Event
     ↓
Event
     ↓
Unsubscribe

Characteristics:

  • Multiple events
  • Long-lived
  • Explicit lifetime management
  • No completion state
  • No blocking wait

Header-Only Model Compatibility

The Firebolt model architecture is designed so that generated API models remain entirely header-only.

Examples include:

LifecycleState
DeviceInfo
AccountProfile
FireboltVoid

The runtime library does not need knowledge of any generated model type.

Instead:

  • The runtime stores request data internally.
  • The runtime tracks request and subscription state through IOperationState and ISubscriptionState.
  • FireboltOperation<T> provides a typed facade over the runtime state.
  • Generated Firebolt models remain independent of the runtime implementation.

This architecture allows new generated Firebolt APIs and models to be introduced without requiring changes to the underlying runtime library.

Header-Only Generated Interface

Generated Firebolt API headers contain the models and interface definitions associated with an API module.

The generated header depends only on the public Firebolt framework types:

class IOperationState;
class ISubscriptionState;

template<typename T>
class FireboltOperation;

class FireboltSubscription;

The runtime implementation of operation and subscription state remains within the Firebolt Client library.

Lifecycle Header

#pragma once

#include <functional>
#include <string>
#include <utility>

#include <firebolt/FireboltClient.h>
#include <firebolt/FireboltModel.h>
#include <firebolt/FireboltObject.h>
#include <firebolt/FireboltOperation.h>
#include <firebolt/FireboltSubscription.h>
#include <firebolt/FireboltTypes.h>

namespace firebolt
{
namespace lifecycle
{

class LifecycleState final
    : public FireboltModel<LifecycleState>
{
public:
    FireboltString state;

    void Write(FireboltObject& object) const
    {
        object.Set("state", state);
    }

    void Read(const FireboltObject& object)
    {
        object.Get("state", state);
    }
};

class ILifecycle
{
public:
    virtual ~ILifecycle() = default;

    virtual FireboltOperation<LifecycleState>
    GetLifecycleState() = 0;

    virtual FireboltSubscription
    OnStateChanged(
        EventCallback<LifecycleState> listener) = 0;
};

class Lifecycle final : public ILifecycle
{
public:
    explicit Lifecycle(FireboltClient& client)
        : m_client(client)
    {
    }

    FireboltOperation<LifecycleState>
    GetLifecycleState() override
    {
        return m_client.Send<LifecycleState>(
            "lifecycle.state",
            FireboltObject{});
    }

    FireboltSubscription
    OnStateChanged(
        EventCallback<LifecycleState> listener) override
    {
        return m_client.Subscribe<LifecycleState>(
            "lifecycle.onStateChanged",
            std::move(listener));
    }

private:
    FireboltClient& m_client;
};

inline ILifecycle&
LifecycleInterface(FireboltClient& client)
{
    return client.GetInterface<Lifecycle>();
}

} // namespace lifecycle
} // namespace firebolt

Model Role

LifecycleState is a generated Firebolt response and event model.

It derives from:

FireboltModel<LifecycleState>

The generated model is responsible for translating between its typed C++ fields and FireboltObject.

The model remains header-only because its complete definition, including its field mappings, is available in the generated API header.

Interface Role

ILifecycle defines the public API contract for the Lifecycle capability.

A call response is represented by:

FireboltOperation<LifecycleState>

An event registration is represented by:

FireboltSubscription

The interface preserves strong typing while remaining independent of the underlying JSON-RPC implementation.

Operation Usage

The following call creates a Firebolt operation whose response will be converted into a LifecycleState model:

auto operation =
    lifecycle.GetLifecycleState();

The operation may be consumed asynchronously:

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

        const LifecycleState& lifecycleState =
            result.Value();
    });

The same operation may be consumed synchronously with a mandatory timeout:

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

The generated interface does not perform blocking transport communication. Get() waits on the internal IOperationState associated with the asynchronous request.

Subscription Usage

The listener is required when the subscription is created:

auto subscription =
    lifecycle.OnStateChanged(
        const LifecycleState& lifecycleState
        {
            const FireboltString& state =
                lifecycleState.state;
        });

The returned FireboltSubscription manages the lifetime of the event registration.

subscription.Unsubscribe();

The listener remains registered through the internal ISubscriptionState until the subscription is explicitly unsubscribed, destroyed, or invalidated by the Firebolt Client runtime.

Runtime Boundary

The generated header knows the following types:

LifecycleState
ILifecycle
Lifecycle
FireboltOperation<LifecycleState>
FireboltSubscription

The Firebolt Client runtime knows the following types:

IOperationState
ISubscriptionState
FireboltObject
JSON-RPC request identifiers
JSON-RPC subscription identifiers
Transport callbacks
Request and event correlation maps

The boundary between the generated header and the runtime is:

Generated Firebolt Model
          |
          | Read / Write
          v
    FireboltObject
          |
          | Stored and managed by
          v
IOperationState / ISubscriptionState

This separation allows generated models and interfaces to remain header-only while request tracking, synchronization, callback dispatch, cancellation, and transport behavior remain implemented by the Firebolt Client runtime library.

Clone this wiki locally