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

/// A specification to identify a single Cobalt report.
table ReportSpec {
    /// The customer ID, as specified in Cobalt's metrics registry.
    1: uint32 customer_id;

    /// The ID of the project, as specified in Cobalt's metrics registry.
    2: uint32 project_id;

    /// The ID of the metric, as specified in Cobalt's metrics registry.
    3: uint32 metric_id;

    /// The ID of the report, as specified in Cobalt's metrics registry.
    4: uint32 report_id;
};

/// 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_specs` A vector of specifications identifying the reports to
    ///                return the number of observations for.
    ///
    /// Returns a vector whose k-th element is the number of observations
    /// generated for the k-th element of `report_specs`. If `report_specs`
    /// is the empty vector, then an empty vector is returned.
    GenerateAggregatedObservations(uint32 day_index,
                                   vector<ReportSpec>:MAX report_specs)
        -> (vector<uint64>:MAX num_obs);

    /// Requests that the caller be notified after the Cobalt FIDL service
    /// is in the fully-initialized state.
    ///
    /// Cobalt starts serving requests before it is fully initialized. In this
    /// pre-initialized state it will buffer incoming log events in memory
    /// but not complete their processing. After Cobalt becomes fully
    /// initialized the events in the bufer are fully processed.
    ///
    /// A partial list of things that must happen before Cobalt enters the
    /// fully-initialized state are:
    ///
    /// - Cobalt must by notified by the timekeeper service that the system
    ///   clock has become accurate--usually because the time has been
    ///   fetched from a trusted network resource.
    ///
    /// The callback to this method will be invoked after Cobalt transistions
    // to the fully-initialized state. This may never happen.
    ListenForInitialized() -> ();
};