sdk/fidl/fuchsia.cobalt/cobalt.fidl

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

/// Channels should not be longer than this.
const MAX_CHANNEL_NAME_LENGTH uint32 = 256;

/// Realm names should not be longer than this.
const MAX_REALM_NAME_LENGTH uint32 = 256;

/// Response codes for Logger operations.
type Status = strict enum : int32 {
    OK = 0;

    /// For example the supplied metric id is invalid.
    INVALID_ARGUMENTS = 1;

    /// An attempt was made to log an Event whose serialized size exceeds
    /// MAX_BYTES_PER_EVENT.
    EVENT_TOO_BIG = 2;

    /// Cobalt's local buffer is temporarily full and cannot handle any more
    /// Events at this time. Try again later. This condition should be rare
    BUFFER_FULL = 3;

    // Cobalt has received a ShutDown signal and will not accept any more
    // events.
    SHUT_DOWN = 4;

    /// Catch-all for unexpected errors.
    INTERNAL_ERROR = -1;
};

/////////////////////////////////////////////////////////////////////
// SystemProfileUpdater Interface
/////////////////////////////////////////////////////////////////////

/// A collection of fields describing a system's software distribution.
type SoftwareDistributionInfo = table {
    /// The channel that the device last used as an update source. This value
    /// may be empty to indicate that the device is not currently associated
    /// with any channel.
    1: current_channel string:MAX_CHANNEL_NAME_LENGTH;
    /// The realm of the device represented by the Omaha App ID. This value
    /// may be empty to indicate that the device is not currently associated
    /// with any realm.
    2: current_realm string:MAX_REALM_NAME_LENGTH;
};

/// The SystemDataUpdater interface allows callers to update the state of
/// the SystemProfile in Cobalt. The changes are global and affect all loggers
/// running on the device.
@discoverable
protocol SystemDataUpdater {
    /// Sets Cobalt's view of the system-wide distribution information replacing the
    /// existing values.
    ///
    /// `info` The specifications of the current system's software distribution.
    SetSoftwareDistributionInfo(struct {
        info SoftwareDistributionInfo;
    }) -> (struct {
        status Status;
    });
};

/////////////////////////////////////////////////////////////////////
// AggregateAndUpload Interface
/////////////////////////////////////////////////////////////////////

/// Locally aggregates all collected metrics and uploads generated
/// observations immediately. This is only to be used for Recovery, and
/// should only be called once per Recovery attempt.
///
/// If AggregateAndUpload completes, then the collected metrics were uploaded
/// to Cobalt successfully. Otherwise, AggregateAndUpload may continue to run
/// until the calling service cancels the process when long running operation
/// exceeds the specified timeout. The reason this may occur, is that
/// AggregateAndUpload has a retry policy, and will retry any failures until
/// the operation succeeds or is cancelled due to exceeding a specified
/// timeout.
@discoverable
protocol AggregateAndUpload {
    AggregateAndUploadMetricEvents() -> ();
};