Repository navigation
RDKDEV-1794: Add firebolt-cpp-transport Documentation - #142
Open
gourivarma3 wants to merge 1 commit into
Open
gourivarma3 wants to merge 1 commit into
gourivarma3 wants to merge 1 commit into
Conversation
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Several documented connection, retry, callback-threading, and lifecycle behaviors do not match the implementation.
10 open findings
What changed in this PR
Adds comprehensive component documentation for the C++ transport library.
Changes:
- Documents architecture, threading, lifecycle, call flows, and configuration.
- Adds Mermaid diagrams and module interaction details.
| File | Description |
|---|---|
docs/README.md |
Adds component design and operational documentation. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| The library is structured as a layered stack. The outermost layer (`IHelper` / `SubscriptionManager`) provides a type-safe, RAII-managed interface that maps SDK-level operations to JSON-RPC method names and typed JSON deserializers. Beneath that, `IGateway` owns the JSON-RPC protocol logic: it generates message IDs, correlates responses to outstanding requests, manages event listener registration, and runs a watchdog thread that enforces request timeouts. The innermost layer (`Transport`) owns the WebSocket connection using `websocketpp` with an Asio event loop and decouples received message payloads from protocol processing through an internal message queue. | ||
|
|
||
| Northbound callers interact only through the `IGateway` and `IHelper` abstract interfaces. Implementation types are kept internal; `GetGatewayInstance()` and `GetHelperInstance()` return stable references scoped to the process lifetime. All data flow through these interfaces is outbound toward the Firebolt gateway daemon. |
|
|
||
| The southbound boundary is a single outbound WebSocket connection to the Firebolt gateway daemon. The connection URL, retry policy, and timeout parameters are all supplied through the `Firebolt::Config` struct passed to `IGateway::connect()`. | ||
|
|
||
| The library holds in-memory state: the current connection handle, the pending request map, and the registered event callback list. This state is reset on `disconnect()`. |
| #### Threading Model | ||
|
|
||
| - **Threading Architecture**: Multi-threaded — four distinct threads collaborate to decouple I/O, message processing, event dispatch, and timeout enforcement. | ||
| - **Connection Thread**: Runs the WebSocket Asio event loop and handles connection open, close, fail, and message events. Invokes the `ConnectionChangeCallback` on the calling thread for the initial result; subsequent callbacks fire on this thread. |
| #### Platform and Integration Requirements | ||
|
|
||
| - **Build Dependencies**: `nlohmann-json` (JSON serialization), `websocketpp` (WebSocket transport), `boost` (Asio backend for websocketpp). At runtime, `boost-system` is required. | ||
| - **Gateway Availability**: The Firebolt gateway daemon must be reachable at the configured WebSocket URL before `IGateway::connect()` returns. The configurable retry policy (`reconnect_max_attempts`, `reconnect_delay_ms`, `connect_attempt_timeout_ms`) supports environments where the gateway starts after the calling process. |
|
|
||
| #### Runtime State Changes | ||
|
|
||
| During normal operation the library reacts to WebSocket close or fail events delivered by the connection thread. These events trigger the registered `ConnectionChangeCallback` with `connected = false`. Pending requests are resolved with `Error::NotConnected`. The watchdog thread continues running until `disconnect()` is called explicitly. |
|
|
||
| ## Component Interactions | ||
|
|
||
| The library communicates with the Firebolt gateway daemon over a WebSocket connection. All interactions are client-initiated and outbound. |
|
|
||
| **Event Notification Flow:** | ||
|
|
||
| Incoming JSON-RPC notifications (messages without an `id` field) are matched by method name to registered callbacks. The matched callbacks are enqueued to the notification worker thread, which invokes them asynchronously. |
Comment on lines
+306
to
+308
| - **Error Handling Strategy**: All public API calls return `Firebolt::Error` or `Result<T>`. JSON-RPC error responses are parsed defensively, replacing missing or malformed fields with safe defaults. WebSocket transport errors are mapped to `Firebolt::Error` values. Timed-out requests are expired by the watchdog without disrupting the connection, and pending requests are cancelled gracefully on disconnect. | ||
| - Error mapping: `src/transport.cpp` | ||
| - Request timeout and disconnect cancellation: `src/gateway.cpp` |
Comment on lines
+337
to
+339
| | `reconnect_max_attempts` | `unsigned` | `0` | Number of additional connection attempts if the initial attempt fails. When set to `0`, a single connection attempt is made. Capped internally at 100. | | ||
| | `reconnect_delay_ms` | `unsigned` | `1000` | Delay in milliseconds between successive reconnect attempts. | | ||
| | `connect_attempt_timeout_ms` | `unsigned` | `10000` | Maximum time in milliseconds for a single connection attempt (DNS + TCP + WebSocket handshake) before it is aborted and counted as a failure. | |
|
|
||
| ## Build-Time Configurations | ||
|
|
||
| The following CMake options are exposed as Yocto `PACKAGECONFIG` entries in the bb file and control library behaviour at build time: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
RDKDEV-1794
Reason for Change: To add Component Documentation for firebolt-cpp-transport.
Fix: Added the README documentation
Test Procedure: None
I have read the CLA Document and I hereby sign the CLA
Signed-off-by: gourivarma3 gouri_varma@comcast.com