Table of Contents

1. Objective

1.1 What is Ripple?

Ripple is derived from Firebolt Reference implementation, it is a Rust-based Application gateway that provides support for System, Native, and 3rd party applications for Video-based devices. Ripple will provide a Firebolt Gateway which will be used by Distributors and App Developers to interact with the Application platform to discover, launch, and manage video streaming applications.

Image Added

1.2 Why do we need Ripple?

...

Definition

Purpose

Usage

Onboarding

Repository

Development

Contribution

Architecture

HLA

Why Rust?

Why Extensions?

Standardization: Ripple provides a secure and standardized Firebolt API gateway for 3rd party applications to communicate with the underlying platform. 

Certification: Ripple versions are certified using a stringent set of Firebolt Certification suites and it can be tested across multiple platforms. This offers increased quality control which can be scaled across devices and operators.

Abstraction: Ripple abstracts the applications from the underlying platform such that the platform can be upgraded or changed altogether.

Extensible: Ripple can extend to multiple device types and platforms through Extensions more about it here. // insert link

Configurable: Ripple uses Manifests, RFC(thunder), Contracts, and best of all Extensions to offer configurations for Operators and App developers.

Secure: Ripple uses Firebolt capabilities and defines multiple layers of checks like Supported, Availablity, Permitted, and User Grants to ensure Consumer Privacy and App Security.

Portable: Ripple is small in size and can be easily bundled into the device. App Platform developers can build Extensions by fulfilling the contracts defined in the Ripple SDK.

How is Ripple used right now?

RDK-M Video Accelerator Devices

Video Accelerator device uses Navigator UI to offer a Video Platform experience on these devices.

 Video Accelerator UI version 4 will use Ripple to offer support for Firebolt applications which are part of the catalog.

Image Added

Onboarding

Repository

Ripple can be found in Github Repo https://github.com/rdkcentral/Ripple

Development

The preferred developer environment would include

1. VsCode or Neo Vim
2. Rust Analyzer
3. Precommit 
4. Rust Clippy
5. Rust format

More instructions here

Commit Hooks

Pre-commit is the preferred tool used for setting up the git hook for local development.

Ripple uses Clippy for local git hooks to do format and static analysis on the code before it is committed. So always run precommit install  on a new workspace.

Detailed instructions are provided here

Contribution

CI/CD

Architecture

Reasoning

Why Rust?

Rust was chosen as the programming language for Ripple for mainly below reasons

1. Memory Safety: Rust is a compiler that transforms the code to a target platform using the LLVM linker similar to libc++. Memory safety is offered out of the box by the compiler, unlike other system programming languages.
2. No Runtime: Rust compiles the application or library to the intended target platform without additional server or runtime offering itself as a candidate with less footprint.
3. Rust Community: Rust brings along with it a powerful packager called Cargo. Cargo is empowered by a registry called crates.io providing an NPM-like development environment where dependencies can be easily addressed.
4. Opensource Tooling and Infrastructure: Rust offers more options in terms of Tooling and infrastructure compared to other traditional System languages making it a far more productive option.

Rust in itself offers many idiomatic principles which makes it unique

1. Sum Types: Ability to add structures and enumeration as variants inside a parent Enum.
2. Traits: Offers Polymorphism-like characteristics provided in traditional OOP languages.
3. Destructive Move: Each block of code can own the object inside the block making it safer and also easily garbage collected. Rust also offers memory safety for pass-by references and enforces strong compiler validations to prevent memory errors.
4. Predictable Error handling: Rust allows you to return Result type objects which can contain either an OK (success object) or an Error(object). This makes the code more predictable and also reduces the scope of unpredictable errors.
5. Optional Value: Rust allows values to be built ergonomically using Options, in many cases values are built over a lifetime or in some cases not at all. Rust solves this problem using the Option type which can be initialized to None and when the option value gets filled it becomes a Some(Value).
6. Pattern Matching: Rust offers strong Match  pattern syntax which places Arms for a given value. It can use regular datatypes(str, u32, bool), Result, and Options making it more readable for even complex conditions.

Why Extensions?

Extensions in Ripple offer extensibility and faster migration. Below are some of the good use cases where an extension is necessary

1. Firebolt API requests and responses are not readily available in a Thunder Plugin or an external service.
2. Firebolt API requires multiple Thunder calls and events to provide the API response as defined in the Firebolt OpenRPC schema.
3. Firebolt API requires proprietary API calls either within the device or to a backend service for a given operator.
4. Firebolt API is supported only for a given device and it is not required for another device(s).
5. Non-Firebolt API is supported by the existing Application which needs backward compatibility.

Each of these use cases expects something more from each platform when we try to scale across other global partners.

The foundational code required to build extensions is provided by the Ripple SDK to easily help App Platform developers to easily build and test Extensions. 

Extensions offer that extra leverage to easily migrate and offer support for these platforms as they try to fully adopt the Firebolt Architecture.

What is a Ripple Contract?

A contract is a concrete unit of work expected to be fulfilled by a Ripple extension.

Each contract maps to a Request, Response, or Event structure or enumeration defined mostly by Firebolt Openrpc Schema. 

An Extension implements a request processor based on the Request structure thereby providing fulfillment of the given contract.

Ripple Main uses the contract definition in the Extn manifest to create a map for Inter Extension Communication.

Image Added

Why do we need a Ripple Contract?

Ripple SDK defines the contracts and deeply integrates them with the IEC(Inter Extension Communication) with the ExtnClient .  

Standardization: Similar to Ripple offering Firebolt capabilities contracts offer definition and control over the extensions. This provides a layer of abstraction that can be configured by each operator.

Below are some examples

1. Operator A can use a Mac address for a unique Device ID and Operator B can use a backend system to define a Device ID.
2. Operator A can use the local device persistent storage and Operator B can use a cloud persistence to store the same data. 

Authorization: The extension manifest has a fulfills  field that lists the contracts expected to be fulfilled by the extension. Extensions do not even register a processor for which a contract is not expected to be fulfilled by the manifest.

Permissions: Manifests also has a uses  field for each extension which decides the permissions for each extension in terms of calling other contracts. Using Contracts thus provides added layers of security for a given App Platform developer to build a complex and secure extension-based ecosystem.

Mapping: Each extension contains a list of contracts that it is expected to fulfill these are clearly defined in the Extension Manifests. Main uses this mapping to redirect the incoming Extn requests to the right extension so they can be correctly processed.

Abstraction: Using Extension Manifests operators can swap processors easily for eg let's say we have a backend service A which is getting deprecated and service B is its replacement.  The operator can create a new extension while using the same contract request and response structure defined in the SDK and switch easily to service B without impacting other sections of the platform.

HLA

Below is the High-Level architecture defined for Ripple used by the Video Accelerator device.

Image Added

Manifests

Ripple bootstraps three configuration json files during startup these files are referred to as manifests.

There are three types of manifests in Ripple

Device manifest

This manifest contains the below configurations

1. Websocket configuration for internal and 3rd party app secure connections
2. Device platform information
3. Distributor platform information
4. Distributor cloud services configurations
5. Privacy and data governance settings
6. Default values for settings and other known configurations
7. Permission Exclusory
8. Supported Capabilties
9. User grant policies
10. App lifecycle properties
11. Application properties

Sample Firebolt-device-manifest can be found here

App Library

List of applications that are launchable by Ripple. This app library can be empty if the launcher app wants to handle the catalog expectation for this implementation is to use Lifecyclemanagement API(s) provided by the Ripple RPC api(s) defined here.

Sample App library can be found here

Extension Manifest

Extension Manifest defines the list of Extensions needed to be loaded by Ripple to fulfill its contracts. A given Extension manifest contains

1. The default path for all extensions
2. Default extension type for the given platform (.so/.dll/.dylib)
3. An array of extensions each having an id, uses, fulfills, and config fields
4. Required contracts expected by the platform
5. RPC aliases for legacy and other extension support.

Sample Extension manifest can be found here

Ripple SDK

Ripple Main

IEC

Extensions

Bootstrap

Firebolt App Lifecycle 1.0

A Firebolt application needs to comply with the Application Lifecycle policies defined by the schema. 

...

ADRs

Links and Stuff

TBA