src/public/cobalt_service_interface.h

// Copyright 2020 The Fuchsia 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 COBALT_SRC_PUBLIC_COBALT_SERVICE_INTERFACE_H_
#define COBALT_SRC_PUBLIC_COBALT_SERVICE_INTERFACE_H_

#include "src/lib/util/clock.h"
#include "src/logger/logger_interface.h"
#include "src/logger/project_context.h"
#include "src/observation_store/observation_store.h"
#include "src/public/activity_listener_interface.h"
#include "src/system_data/system_data.h"

namespace cobalt {

using ReportSpec = observation_store::ReportSpec;

// CobaltService is the primary public interface for Cobalt on client platforms.
class CobaltServiceInterface {
 public:
  virtual ~CobaltServiceInterface() = default;

  // NewLogger returns a new instance of a Logger object based on the provided |project_context|.
  virtual std::unique_ptr<logger::LoggerInterface> NewLogger(
      std::unique_ptr<logger::ProjectContext> project_context) = 0;

  // NewLogger returns a new instance of a Logger object using the customer_id and project_id based
  // on the registry provided in the config. If the project is not found, this will return nullptr.
  // If no registry was provided, this will crash.
  virtual std::unique_ptr<logger::LoggerInterface> NewLogger(uint32_t customer_id,
                                                             uint32_t project_id) = 0;

  // SystemClockIsAccurate lets CobaltService know that it no longer needs to maintain an
  // UndatedEventManager, and can flush the data from it into the observation store.
  //
  // This method should be used at most once in the lifetime of a CobaltServiceInterface object.
  //
  // |system_clock|: An instance of SystemClockInterface that is used to add a timestamp to all of
  // the events that were received before the system clock was made accurate. It is then given to
  // the EventAggregator if |start_event_aggregator_worker| is true.
  virtual void SystemClockIsAccurate(std::unique_ptr<util::SystemClockInterface> system_clock,
                                     bool start_event_aggregator_worker) = 0;

  // system_data returns a pointer to the internal SystemDataInterface object. This should only be
  // used for updating the Experiment state or channel in the system data.
  virtual system_data::SystemDataInterface* system_data() = 0;

  enum class DataCollectionPolicy {
    // In COLLECT_AND_UPLOAD mode, we collect and upload data as normal.
    COLLECT_AND_UPLOAD,

    // In DO_NOT_UPLOAD mode, we collect data but do not upload it. This is intended to be a
    // temporary state, and should be followed by setting the policy to either COLLECT_AND_UPLOAD or
    // DO_NOT_COLLECT.
    DO_NOT_UPLOAD,

    // In DO_NOT_COLLECT mode, we silently drop all logged events. When switching to DO_NOT_COLLECT
    // mode, all stored device-specific data will be deleted.
    DO_NOT_COLLECT,
  };

  // Sets the data collection policy.
  virtual void SetDataCollectionPolicy(DataCollectionPolicy policy) = 0;

  // Triggers an out of schedule generation of aggregate observations for rolling windows ending
  // now.
  //
  // Returns the result of the generation.
  //
  // This method is intended for use in cobalt embeddings where running the local aggregation
  // background threads is undesirable. This should only be called if
  // CobaltConfig::start_worker_threads is false.
  //
  // This method should be called before attempting to read observations from the ObservationStore
  // for uploading, to make sure that the most up-to-date aggregated observations have been created.
  virtual logger::Status GenerateAggregatedObservations() = 0;

  // The remaining methods are mostly useful for testing the Cobalt system.
  //

  // Triggers an out of schedule generation of aggregate observations for rolling windows ending on
  // |final_day_index_utc|.
  //
  // Returns the result of the generation.
  //
  // This method is intended for use in the Cobalt testapps which require a single thread to
  // both log events to and generate Observations from an EventAggregator.
  virtual logger::Status GenerateAggregatedObservations(uint32_t final_day_index_utc) = 0;

  // Returns a count of the number of times the aggregation has occurred. This is likely
  // only useful in testing to verify that the worker thread is not running too frequently.
  [[nodiscard]] virtual uint64_t num_aggregator_runs() const = 0;

  // Returns the number of Observations that have been added to the ObservationStore.
  [[nodiscard]] virtual uint64_t num_observations_added() const = 0;

  // Returns a vector containing the number of Observations that have been added
  // to the ObservationStore for each specified report.
  [[nodiscard]] virtual std::vector<uint64_t> num_observations_added_for_reports(
      const std::vector<ReportSpec>& report_specs) const = 0;

  using SendCallback = std::function<void(bool)>;

  // Register a request for an expedited send of observations to the server. The
  // accumulated unsent Observations will be sent as soon as possible (with some rate limiting).
  //
  // |send_callback| will be invoked with the result of the requested send
  // attempt. More precisely, send_callback will be invoked after the
  // attempt to send all of the outstanding Observations. It will be invoked with true if all such
  // Observations were successfully sent. It will be invoked with false if some
  // Observations were not able to be sent, but the status of any particular
  // Observation may not be determined. This is useful mainly in tests.
  virtual void ShippingRequestSendSoon(const SendCallback& send_callback) = 0;

  // Blocks for |max_wait| seconds or until the sending of all previously added Observations is
  // complete.
  virtual void WaitUntilShippingIdle(std::chrono::seconds max_wait) = 0;

  // Courtesy signal for Cobalt to begin a graceful shutdown.
  //
  // Cobalt may be terminated before the shut down process is complete. The
  // amount of time before this occurs depends on caller. No metrics should be
  // logged after the shutdown signal is sent.
  virtual void ShutDown() = 0;

  // These diagnostic stats are mostly useful in a testing environment but
  // may possibly prove useful in production also.
  [[nodiscard]] virtual size_t num_shipping_send_attempts() const = 0;
  [[nodiscard]] virtual size_t num_shipping_failed_attempts() const = 0;
};

}  // namespace cobalt

#endif  // COBALT_SRC_PUBLIC_COBALT_SERVICE_INTERFACE_H_