// 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.
type ReportSpec = table {
    /// The customer ID, as specified in Cobalt's metrics registry.
    1: customer_id uint32;

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

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

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

/// 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() -> (struct {
        success bool;
    });

    /// 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(struct {
        max_wait_seconds uint32;
    }) -> ();

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

    /// 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(struct {
        day_index uint32;
        report_specs vector<ReportSpec>:MAX;
    }) -> (struct {
        num_obs vector<uint64>:MAX;
    });

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