GODT-1676: developer documentation. [skip ci]

Other: bridge-gui readme. [skip ci]
This commit is contained in:
Xavier Michelon
2022-08-15 19:35:13 +02:00
committed by Jakub
parent af51018e02
commit f221fead4a
12 changed files with 5437 additions and 75 deletions

View File

@ -0,0 +1,54 @@
# bridge-gui
bridge-gui is the graphical user interface for Bridge. It's a C++ [Qt](https://www.qt.io) application that
communicates with the bridge executable via gRPC remote procedure call, on a local-only TLS-secured connection.
For more technical details ,see this [RFC](https://confluence.protontech.ch/x/diWHBQ).
# Components
bridge-gui consists in 3 components:
- **bridge-gui**: The Bridge-GUI application itself. It's a QML Qt application that implements the bridge
[gRPC](https://www.grpc.io) service to communicate and interact with the bridge application written in
[Go](https://go.dev).
- **bridge-gui-tester**: A Qt widgets test application that offers a dummy gRPC server implementing the Bridge gRPC
service. It can be used as a debugging and development tool, as it can simulate the server side (bridge) portion of
the gRPC service.
- **bridgepp**: bridgepp (for bridge++) is a C++ static library that contains the code shared by bridge-gui and
bridge-gui-tester.
# Bridge gRPC service
The bridge gRPC service that allows communications between bridge-gui, and the bridge Go application (or
bridge-gui-tester) is defined in `../grpc/bridge.proto`.
# Supported platforms
bridge-gui runs on the same platforms as the bridge app:
- Linux x64.
- macOS x64 and Apple Silicon.
- Windows x64.
# Requirements:
- A C++ development toolchain ([GCC](https://gcc.gnu.org)/[Clang](https://clang.llvm.org)/
[MSVC](https://docs.microsoft.com/en-us/cpp/?view=msvc-170), [CMake](https://cmake.org),
[Ninja](https://ninja-build.org)). An easy way to get all the needed tools is to use a modern IDE such
as [CLion](https://www.jetbrains.com/clion/), [Qt Creator](https://www.qt.io/product/development-tools) or
[Visual Studio Code](https://code.visualstudio.com) that will check and install or use their bundled versions
of the tools.
- [Qt 6](https://www.qt.io/download-open-source). Use the online installer to install the latest stable
release of Qt for your platform and compiler.
# First build
bridge-gui uses [vcpkg](https://vcpkg.io/en/index.html), Microsoft multi-platform C/C++ dependency manager to get
the source code and build gRPC and its dependencies (protobuf, zlib, ...). vcpkg is managed as a git submodule
in `extern/vcpkg`,relative to the root of the bridge source tree. A pair of scripts is provided to perform
the initialization of vcpkg, the retrieval and compilation of gRPC and a first build of the bridge-gui project
components:
- `build.sh`: a shell script to use on macOS and Linux.
- `build.ps1`: a [PowerShell](https://docs.microsoft.com/en-us/powershell/) script for Windows.

File diff suppressed because it is too large Load Diff

View File

@ -316,7 +316,7 @@ Status GRPCService::CurrentEmailClient(ServerContext *, Empty const *, StringVal
//****************************************************************************************************************************************************
/// \param[in] response The request.
/// \param[in] request The request.
/// \return The status for the call.
//****************************************************************************************************************************************************
Status GRPCService::ForceLauncher(ServerContext *, StringValue const *request, Empty *)
@ -660,7 +660,8 @@ Status GRPCService::ChangePorts(ServerContext *, ChangePortsRequest const *reque
//****************************************************************************************************************************************************
/// \param[out] response the response.
/// \param[in] request The request.
/// \param[out] response The response.
/// \return The status for the call.
//****************************************************************************************************************************************************
Status GRPCService::IsPortFree(ServerContext *, Int32Value const *request, BoolValue *response)

View File

@ -41,61 +41,61 @@ public: // member functions.
void connectProxySignals(); ///< Connect the signals of the Qt Proxy to the GUI components
bool isStreaming() const; ///< Check if the service is currently streaming events.
grpc::Status AddLogEntry(::grpc::ServerContext *context, ::grpc::AddLogEntryRequest const *request, ::google::protobuf::Empty *response) override;
grpc::Status GuiReady(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::Empty *response) override;
grpc::Status Quit(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::Empty *response) override;
grpc::Status Restart(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::Empty *response) override;
grpc::Status ShowOnStartup(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::BoolValue *response) override;
grpc::Status ShowSplashScreen(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::BoolValue *response) override;
grpc::Status IsFirstGuiStart(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::BoolValue *response) override;
grpc::Status SetIsAutostartOn(::grpc::ServerContext *context, ::google::protobuf::BoolValue const *request, ::google::protobuf::Empty *response) override;
grpc::Status IsAutostartOn(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::BoolValue *response) override;
grpc::Status SetIsBetaEnabled(::grpc::ServerContext *context, ::google::protobuf::BoolValue const *request, ::google::protobuf::Empty *response) override;
grpc::Status IsBetaEnabled(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::BoolValue *response) override;
grpc::Status GoOs(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::StringValue *response) override;
grpc::Status TriggerReset(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::Empty *response) override;
grpc::Status Version(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::StringValue *response) override;
grpc::Status LogsPath(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::StringValue *response) override;
grpc::Status LicensePath(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::StringValue *response) override;
grpc::Status ReleaseNotesPageLink(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::StringValue *response) override;
grpc::Status DependencyLicensesLink(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::StringValue *response) override;
grpc::Status LandingPageLink(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::StringValue *response) override;
grpc::Status SetColorSchemeName(::grpc::ServerContext *context, ::google::protobuf::StringValue const *request, ::google::protobuf::Empty *response) override;
grpc::Status ColorSchemeName(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::StringValue *response) override;
grpc::Status CurrentEmailClient(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::StringValue *response) override;
grpc::Status ReportBug(::grpc::ServerContext *context, ::grpc::ReportBugRequest const *request, ::google::protobuf::Empty *response) override;
grpc::Status ForceLauncher(::grpc::ServerContext *context, ::google::protobuf::StringValue const *request, ::google::protobuf::Empty *response) override;
grpc::Status Login(::grpc::ServerContext *context, ::grpc::LoginRequest const *request, ::google::protobuf::Empty *response) override;
grpc::Status Login2FA(::grpc::ServerContext *context, ::grpc::LoginRequest const *request, ::google::protobuf::Empty *response) override;
grpc::Status Login2Passwords(::grpc::ServerContext *context, ::grpc::LoginRequest const *request, ::google::protobuf::Empty *response) override;
grpc::Status LoginAbort(::grpc::ServerContext *context, ::grpc::LoginAbortRequest const *request, ::google::protobuf::Empty *response) override;
grpc::Status CheckUpdate(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::Empty *response) override;
grpc::Status InstallUpdate(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::Empty *response) override;
grpc::Status SetIsAutomaticUpdateOn(::grpc::ServerContext *context, ::google::protobuf::BoolValue const *request, ::google::protobuf::Empty *response) override;
grpc::Status IsAutomaticUpdateOn(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::BoolValue *response) override;
grpc::Status IsCacheOnDiskEnabled(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::BoolValue *response) override;
grpc::Status DiskCachePath(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::StringValue *response) override;
grpc::Status ChangeLocalCache(::grpc::ServerContext *context, ::grpc::ChangeLocalCacheRequest const *request, ::google::protobuf::Empty *response) override;
grpc::Status SetIsDoHEnabled(::grpc::ServerContext *context, ::google::protobuf::BoolValue const *request, ::google::protobuf::Empty *response) override;
grpc::Status IsDoHEnabled(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::BoolValue *response) override;
grpc::Status SetUseSslForSmtp(::grpc::ServerContext *context, ::google::protobuf::BoolValue const *request, ::google::protobuf::Empty *response) override;
grpc::Status UseSslForSmtp(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::BoolValue *response) override;
grpc::Status Hostname(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::StringValue *response) override;
grpc::Status ImapPort(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::Int32Value *response) override;
grpc::Status SmtpPort(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::Int32Value *response) override;
grpc::Status ChangePorts(::grpc::ServerContext *context, ::grpc::ChangePortsRequest const *request, ::google::protobuf::Empty *response) override;
grpc::Status IsPortFree(::grpc::ServerContext *context, ::google::protobuf::Int32Value const *request, ::google::protobuf::BoolValue *response) override;
grpc::Status AvailableKeychains(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::grpc::AvailableKeychainsResponse *response) override;
grpc::Status SetCurrentKeychain(::grpc::ServerContext *context, ::google::protobuf::StringValue const *request, ::google::protobuf::Empty *response) override;
grpc::Status CurrentKeychain(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::StringValue *response) override;
grpc::Status GetUserList(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::grpc::UserListResponse *response) override;
grpc::Status GetUser(::grpc::ServerContext *context, ::google::protobuf::StringValue const *request, ::grpc::User *response) override;
grpc::Status SetUserSplitMode(::grpc::ServerContext *context, ::grpc::UserSplitModeRequest const *request, ::google::protobuf::Empty *response) override;
grpc::Status LogoutUser(::grpc::ServerContext *context, ::google::protobuf::StringValue const *request, ::google::protobuf::Empty *response) override;
grpc::Status RemoveUser(::grpc::ServerContext *context, ::google::protobuf::StringValue const *request, ::google::protobuf::Empty *response) override;
grpc::Status ConfigureUserAppleMail(::grpc::ServerContext *context, ::grpc::ConfigureAppleMailRequest const *request, ::google::protobuf::Empty *response) override;
grpc::Status StartEventStream(::grpc::ServerContext *context, ::grpc::EventStreamRequest const *request, ::grpc::ServerWriter<::grpc::StreamEvent> *writer) override;
grpc::Status StopEventStream(::grpc::ServerContext *context, ::google::protobuf::Empty const *request, ::google::protobuf::Empty *response) override;
grpc::Status AddLogEntry(::grpc::ServerContext *, ::grpc::AddLogEntryRequest const *request, ::google::protobuf::Empty *) override;
grpc::Status GuiReady(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::Empty *) override;
grpc::Status Quit(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::Empty *) override;
grpc::Status Restart(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::Empty *) override;
grpc::Status ShowOnStartup(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::BoolValue *response) override;
grpc::Status ShowSplashScreen(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::BoolValue *response) override;
grpc::Status IsFirstGuiStart(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::BoolValue *response) override;
grpc::Status SetIsAutostartOn(::grpc::ServerContext *, ::google::protobuf::BoolValue const *request, ::google::protobuf::Empty *) override;
grpc::Status IsAutostartOn(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::BoolValue *response) override;
grpc::Status SetIsBetaEnabled(::grpc::ServerContext *, ::google::protobuf::BoolValue const *request, ::google::protobuf::Empty *) override;
grpc::Status IsBetaEnabled(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::BoolValue *response) override;
grpc::Status GoOs(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::StringValue *response) override;
grpc::Status TriggerReset(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::Empty *) override;
grpc::Status Version(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::StringValue *response) override;
grpc::Status LogsPath(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::StringValue *response) override;
grpc::Status LicensePath(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::StringValue *response) override;
grpc::Status ReleaseNotesPageLink(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::StringValue *response) override;
grpc::Status DependencyLicensesLink(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::StringValue *response) override;
grpc::Status LandingPageLink(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::StringValue *response) override;
grpc::Status SetColorSchemeName(::grpc::ServerContext *, ::google::protobuf::StringValue const *request, ::google::protobuf::Empty *) override;
grpc::Status ColorSchemeName(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::StringValue *response) override;
grpc::Status CurrentEmailClient(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::StringValue *response) override;
grpc::Status ReportBug(::grpc::ServerContext *, ::grpc::ReportBugRequest const *request, ::google::protobuf::Empty *) override;
grpc::Status ForceLauncher(::grpc::ServerContext *, ::google::protobuf::StringValue const *request, ::google::protobuf::Empty *) override;
grpc::Status Login(::grpc::ServerContext *, ::grpc::LoginRequest const *request, ::google::protobuf::Empty *) override;
grpc::Status Login2FA(::grpc::ServerContext *, ::grpc::LoginRequest const *request, ::google::protobuf::Empty *) override;
grpc::Status Login2Passwords(::grpc::ServerContext *, ::grpc::LoginRequest const *request, ::google::protobuf::Empty *) override;
grpc::Status LoginAbort(::grpc::ServerContext *, ::grpc::LoginAbortRequest const *request, ::google::protobuf::Empty *) override;
grpc::Status CheckUpdate(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::Empty *) override;
grpc::Status InstallUpdate(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::Empty *) override;
grpc::Status SetIsAutomaticUpdateOn(::grpc::ServerContext *, ::google::protobuf::BoolValue const *request, ::google::protobuf::Empty *) override;
grpc::Status IsAutomaticUpdateOn(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::BoolValue *response) override;
grpc::Status IsCacheOnDiskEnabled(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::BoolValue *response) override;
grpc::Status DiskCachePath(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::StringValue *response) override;
grpc::Status ChangeLocalCache(::grpc::ServerContext *, ::grpc::ChangeLocalCacheRequest const *request, ::google::protobuf::Empty *) override;
grpc::Status SetIsDoHEnabled(::grpc::ServerContext *, ::google::protobuf::BoolValue const *request, ::google::protobuf::Empty *) override;
grpc::Status IsDoHEnabled(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::BoolValue *response) override;
grpc::Status SetUseSslForSmtp(::grpc::ServerContext *, ::google::protobuf::BoolValue const *request, ::google::protobuf::Empty *) override;
grpc::Status UseSslForSmtp(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::BoolValue *response) override;
grpc::Status Hostname(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::StringValue *response) override;
grpc::Status ImapPort(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::Int32Value *response) override;
grpc::Status SmtpPort(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::Int32Value *response) override;
grpc::Status ChangePorts(::grpc::ServerContext *, ::grpc::ChangePortsRequest const *request, ::google::protobuf::Empty *) override;
grpc::Status IsPortFree(::grpc::ServerContext *, ::google::protobuf::Int32Value const *request, ::google::protobuf::BoolValue *response) override;
grpc::Status AvailableKeychains(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::grpc::AvailableKeychainsResponse *response) override;
grpc::Status SetCurrentKeychain(::grpc::ServerContext *, ::google::protobuf::StringValue const *request, ::google::protobuf::Empty *) override;
grpc::Status CurrentKeychain(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::StringValue *response) override;
grpc::Status GetUserList(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::grpc::UserListResponse *response) override;
grpc::Status GetUser(::grpc::ServerContext *, ::google::protobuf::StringValue const *request, ::grpc::User *response) override;
grpc::Status SetUserSplitMode(::grpc::ServerContext *, ::grpc::UserSplitModeRequest const *request, ::google::protobuf::Empty *) override;
grpc::Status LogoutUser(::grpc::ServerContext *, ::google::protobuf::StringValue const *request, ::google::protobuf::Empty *) override;
grpc::Status RemoveUser(::grpc::ServerContext *, ::google::protobuf::StringValue const *request, ::google::protobuf::Empty *) override;
grpc::Status ConfigureUserAppleMail(::grpc::ServerContext *, ::grpc::ConfigureAppleMailRequest const *request, ::google::protobuf::Empty *) override;
grpc::Status StartEventStream(::grpc::ServerContext *, ::grpc::EventStreamRequest const *request, ::grpc::ServerWriter<::grpc::StreamEvent> *writer) override;
grpc::Status StopEventStream(::grpc::ServerContext *, ::google::protobuf::Empty const*, ::google::protobuf::Empty *) override;
bool sendEvent(bridgepp::SPStreamEvent const &event); ///< Queue an event for sending through the event stream.

View File

@ -146,7 +146,7 @@ bool SettingsTab::isFirstGUIStart() const
//****************************************************************************************************************************************************
/// \return true iff the 'Show Splash Screen' check box is checked.
/// \return true iff autosart is on.
//****************************************************************************************************************************************************
bool SettingsTab::isAutostartOn() const
{
@ -155,7 +155,7 @@ bool SettingsTab::isAutostartOn() const
//****************************************************************************************************************************************************
/// \return true iff the 'Show Splash Screen' check box is checked.
/// \param[in] on Should autostart be turned on?
//****************************************************************************************************************************************************
void SettingsTab::setIsAutostartOn(bool on)
{
@ -376,6 +376,7 @@ bool SettingsTab::isCacheOnDiskEnabled() const
//****************************************************************************************************************************************************
/// \param[in] enabled Is the cache on disk enabled?
/// \param[in] path The path of the local cache.
//****************************************************************************************************************************************************
void SettingsTab::changeLocalCache(bool enabled, QString const &path)
{

View File

@ -51,7 +51,9 @@ int UserTable::columnCount(QModelIndex const &) const
//****************************************************************************************************************************************************
/// \param[in]
/// \param[in] index The model index.
/// \param[in] role The role to retrieve data for.
/// \return The data for the role at the given index.
//****************************************************************************************************************************************************
QVariant UserTable::data(QModelIndex const &index, int role) const
{

View File

@ -57,7 +57,7 @@ DOXYFILE_ENCODING = UTF-8
# title of most generated pages and in a few other places.
# The default value is: My Project.
PROJECT_NAME = "Proton Mail Bridge Qt6"
PROJECT_NAME = "Proton Mail Bridge GUI"
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
# could be handy for archiving the generated documentation or if some version

View File

@ -83,18 +83,6 @@ int UserList::rowOfUserID(QString const &userID) const
}
//****************************************************************************************************************************************************
//
//****************************************************************************************************************************************************
void UserList::reset()
{
this->beginResetModel();
users_.clear();
this->endResetModel();
emit countChanged(0);
}
//****************************************************************************************************************************************************
/// \param[in] users The new user list.
//****************************************************************************************************************************************************

View File

@ -39,7 +39,6 @@ public: // member functions.
void connectGRPCEvents() const; ///< Connects gRPC event to the model.
int rowCount(QModelIndex const &parent) const override; ///< Return the number of row in the model
QVariant data(QModelIndex const &index, int role) const override; ///< Retrieve model data.
void reset(); ///< Reset the user list.
void reset(QList<bridgepp::SPUser> const &users); ///< Replace the user list.
int rowOfUserID(QString const &userID) const;
void removeUserAt(int row); ///< Remove the user at a given row

File diff suppressed because it is too large Load Diff

View File

@ -127,7 +127,7 @@ Log::Level logLevelFromGRPC(grpc::LogLevel level)
//****************************************************************************************************************************************************
/// \param[in] grpcUser The gRPC user.
/// \param[in] user The user.
/// \return user The user.
//****************************************************************************************************************************************************
SPUser userFromGRPC(grpc::User const &grpcUser)
{

View File

@ -26,6 +26,7 @@ namespace bridgepp
//****************************************************************************************************************************************************
/// \param[in] exePath The path of the executable.
/// \param[in] args The list of command-line arguments.
/// \param[in] parent The parent object of the worker.
//****************************************************************************************************************************************************
ProcessMonitor::ProcessMonitor(QString const &exePath, QStringList const &args, QObject *parent)