// 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);

    // 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.
    //
    // Returns the number of Observations which were generated.
    GenerateAggregatedObservations(uint32 day_index) -> (int64 num);
};