dlcservice/dlc_manager.h

// Copyright 2019 The Chromium OS Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef DLCSERVICE_DLC_MANAGER_H_
#define DLCSERVICE_DLC_MANAGER_H_

#include <string>

#include <base/time/time.h>
#include <brillo/errors/error.h>
#include <brillo/message_loops/message_loop.h>
#include <gtest/gtest_prod.h>  // for FRIEND_TEST

#include "dlcservice/dlc.h"

namespace dlcservice {

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

  virtual DlcBase* GetDlc(const DlcId& id, brillo::ErrorPtr* err) = 0;
  virtual void Initialize() = 0;
  virtual DlcIdList GetInstalled() = 0;
  virtual DlcIdList GetExistingDlcs() = 0;
  virtual DlcIdList GetDlcsToUpdate() = 0;
  virtual DlcIdList GetSupported() = 0;
  virtual bool InstallCompleted(const DlcIdList& ids,
                                brillo::ErrorPtr* err) = 0;
  virtual bool UpdateCompleted(const DlcIdList& ids, brillo::ErrorPtr* err) = 0;
  virtual bool Install(const DlcId& id,
                       bool* external_install_needed,
                       brillo::ErrorPtr* err) = 0;
  virtual bool FinishInstall(const DlcId& id, brillo::ErrorPtr* err) = 0;
  virtual bool CancelInstall(const DlcId& id,
                             const brillo::ErrorPtr& err_in,
                             brillo::ErrorPtr* err) = 0;
  virtual bool Uninstall(const DlcId& id, brillo::ErrorPtr* err) = 0;
  virtual bool Purge(const DlcId& id, brillo::ErrorPtr* err) = 0;
  virtual void ChangeProgress(double progress) = 0;
};

class DlcManager : public DlcManagerInterface {
 public:
  DlcManager() = default;
  ~DlcManager();

  // Returns a reference to a DLC object given a DLC ID. If the ID is not
  // supported, it will set the error and return |nullptr|.
  DlcBase* GetDlc(const DlcId& id, brillo::ErrorPtr* err) override;

  // Initializes the state of DlcManager.
  void Initialize() override;

  // Returns the list of installed DLCs.
  DlcIdList GetInstalled() override;

  // Returns the list of DLCs with installed content.
  DlcIdList GetExistingDlcs() override;

  // Returns the list of DLCs that need to be updated.
  DlcIdList GetDlcsToUpdate() override;

  // Returns the list of all supported DLC(s).
  DlcIdList GetSupported() override;

  // Persists the verified pref for given DLC(s) on install completion.
  bool InstallCompleted(const DlcIdList& ids, brillo::ErrorPtr* err) override;

  // Persists the verified pref for given DLC(s) on update completion.
  bool UpdateCompleted(const DlcIdList& ids, brillo::ErrorPtr* err) override;

  // DLC Installation Flow

  // Install Step 1:
  // To start an install, the initial requirement is to call this function.
  // During this phase, all necessary setup for update_engine to successfully
  // install DLC(s) and other files that require creation are handled.
  // Args:
  //   id: The DLC ID that needs to be installed.
  //   external_install_needed: It is set to true if we need to actually install
  //     the DLC through update_engine.
  //   err: The error that's set when returned false.
  // Return:
  //   True on success, otherwise false.
  bool Install(const DlcId& id,
               bool* external_install_needed,
               brillo::ErrorPtr* err) override;

  // Install Step 2a:
  // Once the missing DLC(s) are installed or there were no missing DLC(s), this
  // call is still required to finish the installation.
  // If there were missing DLC(s) that were newly installed, this call will go
  // ahead and mount those DLC(s) to be ready for use.
  // Args:
  //   id: The DLC to finish the installation for.
  //   err: The error that's set when returned false.
  // Return:
  //   True on success, otherwise false.
  bool FinishInstall(const DlcId& id, brillo::ErrorPtr* err) override;

  // Install Step 2b:
  // If for any reason, the init'ed DLC(s) should not follow through with
  // mounting it can be cancelled by invoking this. The call may fail, in
  // which case the errors will reflect the causes and provide insight in ways
  // dlcservice can be put into a valid state again.
  // Args:
  //   id: The DLC to cancel the installation for.
  //   err_in: The error that caused the install to be cancelled.
  //   err: The error that's set when returned false.
  // Return:
  //   True on success, otherwise false.
  bool CancelInstall(const DlcId& id,
                     const brillo::ErrorPtr& err_in,
                     brillo::ErrorPtr* err) override;

  // DLC Deletion Flow

  // Delete Step 1:
  // To delete the DLC this can be invoked, no prior step is required.
  // Args:
  //   id: The DLC ID that is to be uninstalled.
  //   err: The error that's set when returned false.
  // Return:
  //   True if the DLC with the ID passed in is successfully uninstalled,
  //   otherwise false. Deleting a valid DLC that's not installed is considered
  //   successfully uninstalled, however uninstalling a DLC that's not supported
  //   is a failure. Uninstalling a DLC that is installing is also a failure.
  bool Uninstall(const DlcId& id, brillo::ErrorPtr* err) override;
  bool Purge(const DlcId& id, brillo::ErrorPtr* err) override;

  // Changes the progress on all DLCs being installed to |progress|.
  void ChangeProgress(double progress) override;

 private:
  FRIEND_TEST(DlcManagerTest, CleanupDanglingDlcs);

  // Removes all unsupported/deprecated DLC files and images.
  void CleanupUnsupportedDlcs();

  // Cleans up all DLCs that are dangling based on the ref count.
  void CleanupDanglingDlcs();

  // Posts the |CleanuupDanglingDlcs| as a delayed task with timeout |timeout|.
  void PostCleanupDanglingDlcs(const base::TimeDelta& timeout);

  DlcMap supported_;

  brillo::MessageLoop::TaskId cleanup_dangling_task_id_;

  DlcManager(const DlcManager&) = delete;
  DlcManager& operator=(const DlcManager&) = delete;
};

}  // namespace dlcservice

#endif  // DLCSERVICE_DLC_MANAGER_H_