// Copyright 2019 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.mem;
using zx;

/// Provides the ability to file crash reports.
[Discoverable]
protocol CrashReporter {
    /// Files a crash `report`.
    ///
    /// This could mean generating a crash report in a local crash report database or uploading the
    /// crash report to a remote crash server depending on the FIDL server's configuration.
    File(CrashReport report) -> () error zx.status;
};

/// Represents a crash report.
table CrashReport {
    /// The name of the program that crashed, e.g., the process or component's name.
    1: string:1024 program_name;

    /// The specific report that depends on the type of crashes.
    2: SpecificCrashReport specific_report;

    /// A vector of key-value string pairs representing arbitrary data that should be attached to a
    /// crash report. Keys should be unique.
    3: vector<Annotation>:32 annotations;

    /// A vector of key-value string-to-VMO pairs representing arbitrary data that should be
    /// attached to a crash report. Keys should be unique.
    4: vector<Attachment>:16 attachments;

    /// A text ID that the crash server can use to group multiple crash reports related to the
    /// same event.
    ///
    /// Unlike the crash signature, crash reports sharing the same ID correspond to different
    /// crashes, but can be considered as belonging to the same event, e.g., a crash in a low-level
    /// server causing a crash in a high-level UI widget.
    5: string:128 event_id;
};

/// Represents a specific crash report.
///
/// Add a new member when the server needs to special case how it handles certain annotations and
/// attachments for a given type of crashes, e.g., a `RuntimeCrashReport` for Javascript.
xunion SpecificCrashReport {
    /// Intended for arbitrary crashes, e.g., OOM, out-of-disk.
    GenericCrashReport generic;

    /// Intended for a native exception.
    NativeCrashReport native;

    /// Intended for a Dart exception.
    RuntimeCrashReport dart;
};

/// Represents a generic crash report.
table GenericCrashReport {
    /// A text signature that the crash server can use to track the same crash over time, e.g.,
    /// "kernel-panic" or "oom".
    ///
    /// Unlike the event ID, crash reports sharing the same signature correspond to the same crash,
    /// but happening over multiple events, e.g., a null pointer exception in a server whenever
    /// asked the same request.
    1: string:128 crash_signature;
};

/// Represents a crash report for a native exception out of which the client has built a minidump.
table NativeCrashReport {
    /// The core dump in the Minidump format.
    1: fuchsia.mem.Buffer minidump;
};

/// Represents a crash report for a runtime exception, applicable to most languages.
table RuntimeCrashReport {
    /// The exception type, e.g., "FileSystemException".
    1: string:128 exception_type;

    /// The exception message, e.g., "cannot open file".
    2: string:1024 exception_message;

    /// The text representation of the exception stack trace.
    3: fuchsia.mem.Buffer exception_stack_trace;
};