// 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
closed protocol CrashReporter {
    /// Files a crash `report` and gives the final result of the operation.
    ///
    /// 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.
    ///
    /// Warning: this could potentially take up to several minutes. Calling
    /// this function in a synchronous manner is not recommended.
    @available(added=11)
    strict FileReport(resource struct {
        report CrashReport;
    }) -> (struct {
        results FileReportResults;
    }) error FilingError;
};

const MAX_PROGRAM_NAME_LENGTH uint32 = 1024;
const MAX_NUM_ANNOTATIONS_PER_CRASH_REPORT uint32 = 32;
const MAX_NUM_ATTACHMENTS_PER_CRASH_REPORT uint32 = 16;
const MAX_EVENT_ID_LENGTH uint32 = 128;
const MAX_CRASH_SIGNATURE_LENGTH uint32 = 128;
@available(added=11)
const MAX_REPORT_ID_LENGTH uint32 = 64;

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

    /// How long the program was running before it crashed.
    6: program_uptime zx.Duration;

    /// The specific report that depends on the type of crashes.
    ///
    /// This field should be set if additional information about the crashing program needs to be
    /// sent, e.g., a minidump.
    2: specific_report SpecificCrashReport;

    /// A vector of key-value string pairs representing arbitrary data that should be attached to a
    /// crash report.
    ///
    /// Keys should be unique as only the latest value for a given key in the vector will be
    /// considered.
    3: annotations vector<Annotation>:MAX_NUM_ANNOTATIONS_PER_CRASH_REPORT;

    /// A vector of key-value string-to-VMO pairs representing arbitrary data that should be
    /// attached to a crash report.
    ///
    /// Keys should be unique as only the latest value for a given key in the vector will be
    /// considered.
    4: attachments vector<Attachment>:MAX_NUM_ATTACHMENTS_PER_CRASH_REPORT;

    /// 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: event_id string:MAX_EVENT_ID_LENGTH;

    /// A text signature that the crash server can use to track the same crash over time, e.g.,
    /// "kernel-panic" or "oom". This signature will take precedence over any automated signature
    /// derived from the rest of the data.
    ///
    /// 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.
    ///
    /// Must match [a-z][a-z\-]* i.e. only lowercase letters and hyphens or this will result in a
    /// ZX_ERR_INVALID_ARGS epitaph.
    7: crash_signature string:MAX_CRASH_SIGNATURE_LENGTH;

    /// Indicates whether the crash report is for the atypical stop of a running process, component,
    /// or the system itself.
    ///
    /// Examples of events that result in fatal crash reports are:
    ///  * an ELF process crashing
    ///  * the system rebooting because it ran out of memory.
    ///  * the system rebooting because a critical component crashed.
    ///  * the system rebooting because the device was too hot.
    ///
    /// Examples of events that result in non-fatal crash reports are:
    ///  * an uncaught exception in a Dart program with many execution contexts. The runtime may
    ///    chose to terminate that specific execution context and file a crash report for it instead
    ///    of the whole program.
    ///  * a component detecting a fatal event (like an OOM) may occur soon, but isn't guaranteed to
    ///    occur.
    ///
    /// This field is primarily used for grouping crashes by fatal, not fatal, and unknown,
    /// each corresponding to the field being set to true, set to false, or not set respectively.
    8: is_fatal bool;
};

/// 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.
type SpecificCrashReport = flexible resource union {
    /// Intended for a native exception.
    2: native NativeCrashReport;

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

const MAX_PROCESS_NAME_LENGTH uint32 = 64;
const MAX_THREAD_NAME_LENGTH uint32 = 64;

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

    /// The name of the crashed process.
    2: process_name string:MAX_PROCESS_NAME_LENGTH;

    /// The kernel object id of the crashed process.
    3: process_koid zx.Koid;

    /// The name of the crashed thread.
    4: thread_name string:MAX_THREAD_NAME_LENGTH;

    /// The kernel object id of the crashed thread.
    5: thread_koid zx.Koid;
};

const MAX_EXCEPTION_TYPE_LENGTH uint32 = 128;
@available(replaced=10)
const MAX_EXCEPTION_MESSAGE_LENGTH uint32 = 2048;
@available(added=10)
const MAX_EXCEPTION_MESSAGE_LENGTH uint32 = 4096;

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

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

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

@available(added=11)
type FileReportResults = table {
    /// The success type.
    1: result FilingSuccess;

    /// A non-empty value if |result| is FilingSuccess::REPORT_UPLOADED.
    2: report_id string:MAX_REPORT_ID_LENGTH;
};

/// "Memory" refers to a non-persistent location, e.g. a memory-backed
/// filesystem.
@available(added=11)
type FilingSuccess = flexible enum {
    @unknown
    UNKNOWN = 0;
    REPORT_UPLOADED = 1;
    REPORT_ON_DISK = 2;
    REPORT_IN_MEMORY = 3;
    REPORT_NOT_FILED_USER_OPTED_OUT = 4;
};

@available(added=11)
type FilingError = flexible enum {
    @unknown
    UNKNOWN = 0;
    INVALID_ARGS_ERROR = 1;
    SERVER_ERROR = 2;
    PERSISTENCE_ERROR = 3;
    QUOTA_REACHED_ERROR = 4;
};