// 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.
    ///
    /// A subsequent call to Upsert() for the same component URL overwrites the
    /// `CrashReportingProduct` for that component.
    ///
    /// Prefer UpsertWithAck() if the component also files crash reports itself, to avoid race
    /// conditions and mis-attribution.
    Upsert(struct {
        component_url fuchsia.sys.component_url;
        product CrashReportingProduct;
    });

    /// Upserts (see above) and notifies 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
    /// attributed to the wrong product, leading to potentially incorrect crash data.
    @transitional
    UpsertWithAck(struct {
        component_url fuchsia.sys.component_url;
        product CrashReportingProduct;
    }) -> ();
};

/// Product information to report to the crash server.
type CrashReportingProduct = table {
    /// The product name on the crash server.
    /// * The first character has to be alphanumeric. The remaining characters must be printable,
    ///   but cannot be a space, which leaves values 33 to 127 in the ASCII table. Any other
    ///   characters will result in a ZX_ERR_INVALID_ARGS epitaph.
    /// * Missing this required field will result in a ZX_ERR_INVALID_ARGS epitaph.
    1: name string:MAX;

    /// Optional product version of the component.
    /// * The first character has to be alphanumeric. The remaining characters must be printable,
    ///   but cannot be a space, which leaves values 33 to 127 in the ASCII table. Any other
    ///   characters will result in a ZX_ERR_INVALID_ARGS epitaph.
    ///
    /// If no version is specified then none is reported to the crash server.
    2: version string:MAX;

    /// 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: channel string:MAX;
};