(DOCSP-36597): C++ Template App, MVC style (#197)

Add a C++ template app using FTXUI and the C++ SDK.

Ignore the C++ directory when running the Bluehawk copy script. Bluehawk
has a problem with using `::state:` in C++ code. For more details, refer
to this issue on the Bluehawk repo:
mongodb-university/Bluehawk#145

I used Bluehawk copy for all other files and manually copied the
`database_manager.cpp` where the code triggering this issue is located.

---------

Co-authored-by: Chris Bush <[email protected]>

manifest.json

@@ -5,6 +5,16 @@
  "repo_name": "realm-template-apps",
  "backend_path": "sync-todo/v2/backend"
  },
+ "cpp.todo.flex": {
+ "name": "C++ Todo App",
+ "repo_owner": "mongodb-university",
+ "repo_name": "realm-template-apps",
+ "backend_path": "sync-todo/v2/backend",
+ "client_path": "sync-todo/v2/generated/cpp",
+ "metadata_path": "sync-todo/v2/generated/cpp",
+ "metadata_filename": "atlasConfig",
+ "file_format": "json"
+ },
  "react-native.todo.flex": {
  "name": "React Native Todo App (TypeScript)",
  "repo_owner": "mongodb-university",

sync-todo/v2/bluehawk.sh

@@ -2,10 +2,13 @@
 
 pushd "$(dirname "$0")"
 
-rm -r generated
-
 for client in client/*; do
+ # Can't Bluehawk copy the cpp client because of `:state:` in the code
+ # Can remove if block when this issue is resolved: https://github.com/mongodb-university/Bluehawk/issues/145
+ if [[ "$client" != "client/cpp"* ]]; then
+ rm -r generated/$(basename $client)
  npx bluehawk copy -o generated/$(basename $client) $client/;
+ fi
 done
 
 cp template-atlasConfig.json generated/flutter/assets/config/atlasConfig.json

sync-todo/v2/client/cpp/.gitignore

@@ -0,0 +1,3 @@
+build/
+.idea/
+cmake-build-debug/

sync-todo/v2/client/cpp/CMakeLists.txt

@@ -0,0 +1,61 @@
+cmake_minimum_required(VERSION 3.25)
+
+project(sync_todo)
+
+set(CMAKE_CXX_STANDARD 17)
+
+Include(FetchContent)
+
+FetchContent_Declare(cpprealm
+ GIT_REPOSITORY https://github.com/realm/realm-cpp.git
+ GIT_TAG v1.0.0
+)
+
+FetchContent_Declare(ftxui
+ GIT_REPOSITORY https://github.com/ArthurSonzogni/ftxui
+ GIT_TAG v5.0.0
+)
+
+FetchContent_Declare(nlohmann_json
+ GIT_REPOSITORY https://github.com/nlohmann/json.git
+ GIT_TAG v3.11.3
+)
+
+FetchContent_GetProperties(ftxui)
+if(NOT ftxui_POPULATED)
+ FetchContent_Populate(ftxui)
+ add_subdirectory(${ftxui_SOURCE_DIR} ${ftxui_BINARY_DIR} EXCLUDE_FROM_ALL)
+endif()
+
+FetchContent_MakeAvailable(cpprealm ftxui nlohmann_json)
+
+add_executable(sync_todo
+ main.cpp
+ ss.hpp
+ controllers/app_controller.hpp
+ controllers/app_controller.cpp
+ controllers/controller.hpp
+ controllers/home_controller.hpp
+ controllers/home_controller.cpp
+ controllers/login_controller.hpp
+ controllers/login_controller.cpp
+ controllers/navigation.hpp
+ controllers/navigation.cpp
+ managers/auth_manager.hpp
+ managers/auth_manager.cpp
+ managers/database_manager.hpp
+ managers/database_manager.cpp
+ managers/error_manager.hpp
+ managers/error_manager.cpp
+ state/app_config_metadata.hpp
+ state/app_config_metadata.cpp
+ state/app_state.hpp
+ state/home_controller_state.hpp
+ state/item.hpp
+ views/scroller.hpp
+ views/scroller.cpp
+)
+
+target_link_libraries(sync_todo PRIVATE cpprealm)
+target_link_libraries(sync_todo PRIVATE ftxui::component)
+target_link_libraries(sync_todo PRIVATE nlohmann_json::nlohmann_json)

sync-todo/v2/client/cpp/README.md

@@ -0,0 +1,133 @@
+# C++ Template App
+
+> [!NOTE] 
+> This is a Preview release of the C++ template app.
+
+A todo list application built with the [Atlas Device SDK for C++](https://www.mongodb.com/docs/realm/sdk/cpp/) and [Atlas Device Sync](https://www.mongodb.com/docs/atlas/app-services/sync/).
+
+This app uses a terminal UI built with [FTXUI](https://github.com/ArthurSonzogni/FTXUI).
+
+## Configuration
+
+For this template app to work, you must ensure that `atlasConfig.json` exists and contains the following properties:
+
+- **appId:** your Atlas App Services App ID.
+- **appUrl:** the URL to browse directly to your App Services App.
+- **baseUrl:** the App Services backend URL. This should be https://services.cloud.mongodb.com in most cases.
+- **clientApiBaseUrl:** the deployment region and baseURL a client application can use to connect to a specific regional 
+ deployment. This information is not used by this template app.
+- **dataApiBaseUrl:** the deployment region and Data API baseURL a client application can use to connect to a specific 
+ Data API app in a given region. This information is not used by this template app.
+- **dataExplorerLink:** the URL to browse to your collections in Atlas. Go here to see data syncing from your app.
+- **dataSourceName:** the name of the data source in Atlas. This information is not used by this template app.
+
+## Create an Atlas Device Sync Template App
+
+### Create the Template App using App Services CLI
+
+The easiest way to work with this client is to create the template app using App Services CLI. If you use the CLI to
+create the template app, or if you use the CLI to pull the C++ client you created from the App Services UI, you'll get
+a version of this client with the `atlasConfig.json` pre-populated with the appropriate values for your application.
+
+For more information, refer to the [Template App documentation](https://www.mongodb.com/docs/atlas/app-services/reference/template-apps/).
+
+### Cloning from GitHub
+
+If you have cloned this repository from the GitHub
+[mongodb/template-app-cpp-todo](https://github.com/mongodb/template-app-cpp-todo.git)
+repository, you must create a separate App Services App with Device Sync
+enabled to use this client. You can find information about how to do this
+in the Atlas App Services documentation page:
+[Template Apps -> Create a Template App](https://www.mongodb.com/docs/atlas/app-services/reference/template-apps/)
+
+Once you have created the App Services App, replace the value in this client's `appId` field 
+in the `atlasConfig.json` file with your App Services App ID. For help finding this ID, refer
+to: [Find Your Project or App ID](https://www.mongodb.com/docs/atlas/app-services/reference/find-your-project-or-app-id/)
+
+### Making a Template App in the App Services UI
+
+You can create a template app by logging on to [Atlas App Services](https://services.cloud.mongodb.com) and click the
+**Create App From Template** button. Choose **Real Time Sync**, and then follow the prompts.
+
+You can download some of the Sync clients from the UI as a .zip file. That is not possible at this time for the C++ client.
+To get a copy of the C++ client with `atlasConfig.json` values pre-populated with the data for your app, pull a copy of
+the template app client using App Services CLI. For more information, refer to the Atlas App Services documentation page:
+[Template Apps -> Get a Template App Client](https://www.mongodb.com/docs/atlas/app-services/reference/template-apps/#get-a-template-app-client).
+
+## Run the app
+
+This app uses CMake to manage dependencies. You must have CMake installed to use this template app.
+
+- Make a `/build` directory inside this client directory, and `cd` into it.
+
+ ```shell
+ mkdir build && cd build
+ ```
+
+- Use CMake to create the Makefile
+
+ ```shell
+ cmake ../
+ ```
+
+- Use CMake to build the app executable.
+
+ ```shell
+ cmake --build .
+ ```
+
+- Run the executable. Pass the path to the `atlasConfig.json` as an argument when you run the application.
+
+ ```shell
+ ./sync_todo /path-to-file/atlasConfig.json
+ ```
+
+## Issues
+
+Please report issues with the template at https://github.com/mongodb-university/realm-template-apps/issues/new
+
+## Structure
+
+To see the code examples concerned with Atlas Device SDK for C++, these files are the most relevant:
+
+- Controllers:
+ - `app_controller.cpp`: Set up app state, including reading the `atlasConfig.json` and setting up the Atlas App connection.
+ - `home_controller.cpp`: Create the task list, add new items, and let the user change app state.
+- Managers
+ - `auth_manager.cpp`: Authenticate users with the Atlas Device Sync app.
+ - `database_manager.cpp`: Handle Device Sync client configuration, Sync subscriptions, Sync sessions, and database CRUD operations.
+- State
+ - `item.hpp`: The Atlas Device SDK data model.
+
+```
+├── controllers
+│   ├── app_controller.cpp
+│   ├── app_controller.hpp
+│   ├── controller.hpp
+│   ├── home_controller.cpp
+│   ├── home_controller.hpp
+│   ├── login_controller.cpp
+│   ├── login_controller.hpp
+│   ├── navigation.cpp
+│   └── navigation.hpp
+├── main.cpp
+├── managers
+│   ├── auth_manager.cpp
+│   ├── auth_manager.hpp
+│   ├── database_manager.cpp
+│   ├── database_manager.hpp
+│   ├── error_manager.cpp
+│   └── error_manager.hpp
+├── ss.hpp
+├── state
+│   ├── app_config_metadata.cpp
+│   ├── app_config_metadata.hpp
+│   ├── app_state.hpp
+│   ├── home_controller_state.hpp
+│   ├── item.hpp
+│   ├── offline_mode_selection.hpp
+│   └── subscription_selection.hpp
+└── views
+ ├── scroller.cpp
+ └── scroller.hpp
+```

sync-todo/v2/client/cpp/atlasConfig.json

@@ -0,0 +1,9 @@
+{
+ "appId": "INSERT-YOUR-APP-ID-HERE",
+ "appUrl": "https://services.cloud.mongodb.com/groups/6388cb218e4d865c34158da5/apps/65f46bd16a5a245b65769e5d",
+ "baseUrl": "https://services.cloud.mongodb.com",
+ "clientApiBaseUrl": "https://us-east-1.aws.services.cloud.mongodb.com",
+ "dataApiBaseUrl": "https://us-east-1.aws.data.mongodb-api.com",
+ "dataExplorerLink": "https://cloud.mongodb.com/links/6388cb218e4d865c34158da5/explorer/Cluster0/database/collection/find",
+ "dataSourceName": "mongodb-atlas"
+}

sync-todo/v2/client/cpp/controllers/app_controller.cpp

@@ -0,0 +1,62 @@
+#include "app_controller.hpp"
+
+void AppController::onFrame() {
+ _navigation.onFrame();
+}
+
+AppController::AppController(ftxui::ScreenInteractive *screen, std::string const& pathToAtlasConfig) {
+ _appState.screen = screen;
+
+ // Read the contents of the atlasConfig.json to get the metadata for the App Services App.
+ std::ifstream f(pathToAtlasConfig);
+ nlohmann::json data = nlohmann::json::parse(f);
+ auto appConfigMetadata = data.template get<AppConfigMetadata>();
+ f.close();
+
+ auto appConfig = realm::App::configuration {
+ .app_id = appConfigMetadata.appId
+ };
+ _appState.app = std::make_unique<realm::App>(appConfig);
+ _appState.authManager = std::make_unique<AuthManager>(this, _appState.app.get());
+ _appState.errorManager = std::make_unique<ErrorManager>(this);
+ _appState.appConfigMetadata = appConfigMetadata;
+
+ // Lay out and style the error modal.
+ auto dismissButton = ftxui::Button("Dismiss", [this]{ _appState.errorManager->clearError(); });
+ auto buttonLayout = ftxui::Container::Horizontal({ dismissButton });
+
+ _errorModal = Renderer(buttonLayout, [=] {
+ auto content = ftxui::vbox({
+ ftxui::hbox(ftxui::text(_appState.errorManager->getError().value()) | ftxui::hcenter),
+ ftxui::hbox(dismissButton->Render()) | ftxui::hcenter
+ }) | ftxui::center | size(ftxui::HEIGHT, ftxui::GREATER_THAN, 10);
+ return window(
+ ftxui::text(L" Error "), content) | ftxui::clear_under | ftxui::center | size(ftxui::WIDTH, ftxui::GREATER_THAN, 80);
+ });
+
+ component()->Add(_navigation.component());
+
+ if (_appState.app->get_current_user()) {
+ _navigation.goTo(std::make_unique<HomeController>(&_appState));
+ } else {
+ _navigation.goTo(std::make_unique<LoginController>(&_appState));
+ }
+}
+
+void AppController::onLoggedIn() {
+ _navigation.goTo(std::make_unique<HomeController>(&_appState));
+}
+
+void AppController::onLoggedOut() {
+ _navigation.goTo(std::make_unique<LoginController>(&_appState));
+}
+
+void AppController::onError(ErrorManager &error) {
+ _errorModal->Detach();
+ component()->Add(_errorModal);
+ _errorModal->TakeFocus();
+}
+
+void AppController::onErrorCleared(ErrorManager &error) {
+ _errorModal->Detach();
+}

sync-todo/v2/client/cpp/controllers/app_controller.hpp

@@ -0,0 +1,41 @@
+#ifndef APP_CONTROLLER_HPP
+#define APP_CONTROLLER_HPP
+
+#include <nlohmann/json.hpp>
+#include <cpprealm/sdk.hpp>
+#include <fstream>
+
+#include "ftxui/component/component.hpp"
+#include "controller.hpp"
+#include "home_controller.hpp"
+#include "login_controller.hpp"
+#include "navigation.hpp"
+#include "../managers/auth_manager.hpp"
+#include "../managers/error_manager.hpp"
+#include "../state/app_config_metadata.hpp"
+#include "../state/app_state.hpp"
+#include "../state/home_controller_state.hpp"
+#include "../ss.hpp"
+
+class AppController final : public Controller, public AuthManager::Delegate, public ErrorManager::Delegate {
+ private:
+ AppState _appState;
+ Navigation _navigation;
+ ftxui::Component _errorModal;
+
+ public:
+ explicit AppController(ftxui::ScreenInteractive *screen, std::string const& pathToAtlasConfig);
+
+ void onFrame() override;
+
+ private:
+ void onLoggedIn() override;
+
+ void onLoggedOut() override;
+
+ void onError(ErrorManager &error) override;
+
+ void onErrorCleared(ErrorManager &error) override;
+};
+
+#endif

sync-todo/v2/client/cpp/controllers/controller.hpp

@@ -0,0 +1,23 @@
+#ifndef CONTROLLER_HPP
+#define CONTROLLER_HPP
+
+#include "ftxui/component/component.hpp"
+
+class Controller {
+ private:
+ ftxui::Component _component;
+
+ public:
+ Controller(): Controller(ftxui::Container::Stacked({})) {}
+ Controller(ftxui::Component component): _component(component) {}
+ virtual ~Controller() = 0;
+ virtual void onFrame() {}
+
+ ftxui::Component component() {
+ return _component;
+ }
+};
+
+inline Controller::~Controller() = default;
+
+#endif