// Copyright 2017 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.

library fuchsia.cobalt;

/// The Controller is primarily useful for testing the Cobalt service.
/// Cobalt clients should use the Logger.
[Discoverable]
protocol Controller {
    /// Requests that the collection of Observations that are currently cached
    /// locally be sent to the Cobalt server soon. Cobalt will send the
    /// Observations in one or more batches and will retry several times upon
    /// failure. The response occurs only after that procedure is completed. A
    /// return value of true indicates that all Observations were successfully
    /// sent. A return value of false indicates otherwise.
    RequestSendSoon() -> (bool success);

    /// The Cobalt FIDL service will block, not processing any further FIDL
    /// requests or responses, on either this interface or the Logger interface,
    /// until either `max_wait_seconds` have elapsed or the Cobalt service's
    /// worker thread has successfully sent all previously added Observations to
    /// the Shuffler. The response will be returned after the blocking period has
    /// ended. Note that this method does not request an expedited send and so it
    /// is possible that the worker thread is currently waiting for the next
    /// scheduled send time and so the empty state will not be achieved prior
    /// that time.
    BlockUntilEmpty(uint32 max_wait_seconds) -> ();

    /// These diagnostic stats are mostly useful in a testing environment but
    /// may possibly prove useful in production also.
    GetNumSendAttempts() -> (uint32 num);
    GetFailedSendAttempts() -> (uint32 num);
    GetNumObservationsAdded() -> (uint64 num_obs);
    GetNumEventAggregatorRuns() -> (uint64 num_runs);

    /// Triggers Cobalt to generate Observations based on locally aggregated
    /// event data and write them to the local ObservationStore. In a non-test
    /// environment this would normally be done periodically by a background
    /// thread. In a test environment this method should be invoked against an
    /// instance of the Cobalt FIDL service that was passed the flag
    /// --start_event_aggregator_worker=false.
    ///
    /// `day_index` The index of the day for which locally aggregated
    ///             Observations should be generated.
    ///
    /// `report_ids` A vector of report IDs.
    ///
    /// Returns a vector whose k-th element is the number of observations
    /// generated for the k-th element of `report_ids`. If `report_ids`
    /// is the empty vector, then an empty vector is returned.
    GenerateAggregatedObservations(uint32 day_index, vector<uint32>:MAX report_ids)
        -> (vector<uint64>:MAX num_obs);
};