// Copyright 2020 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.feedback;

using fuchsia.sys;

/// Allows a component to choose a different crash reporting product to file crashes for that
/// component under.
///
/// By default, all crashes detected by the platform are filed under a single product on the crash
/// server. This API allows components to choose their own product while still benefiting from the
/// platform's exception handling and crash reporting.
[Discoverable]
protocol CrashReportingProductRegister {
    /// Upserts, i.e. updates or inserts, a crash reporting product for a given component URL.
    ///
    /// Upsert() may be called multiple times for the same `component_url`, e.g., once for each
    /// launch of the component, in which case only the most recent call's product information
    /// will be used in crash reports.
    ///
    /// UpsertWithAck should be preferred if the client manually files crash reports because a
    /// fire-and-forget is racy and client cannot know if their crash reports will successfully be
    /// attributed to the product they specify.
    Upsert(fuchsia.sys.component_url component_url, CrashReportingProduct product);

    /// Upsert and notify the client when the operation is complete.
    ///
    /// This allows clients to prevent races between filing crash reports and calls to Upsert.
    /// Otherwise if a crash report is filed before the upsert completes, the crash report will be
    /// attriburted to the wrong product, leading to potentially incorrect crash data.
    [Transitional]
    UpsertWithAck(fuchsia.sys.component_url component_url, CrashReportingProduct product) -> ();
};

/// Product release information to report to the crash server.
table CrashReportingProduct {
    /// The product name on the crash server.
    /// * Missing this required field will result in a ZX_ERR_INVALID_ARGS epitaph.
    1: string:MAX name;

    /// Optional product version of the component.
    ///
    /// If no version is specified then none is reported to the crash server.
    2: string:MAX version;

    /// Optional product release channel for the component, e.g., "canary", "beta", "stable".
    ///
    /// If no channel is specified then none is reported to the crash server.
    3: string:MAX channel;
};