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

/// Registers data useful to attach in feedback reports (crash, user feedback or bug reports).
///
/// This can be used by components to augment the data attached to all feedback reports. By default
/// the Feedback service attaches data exposed to the platform. This protocol is  useful for data
/// known by certain components in certain products, but that is not exposed to the platform.
///
/// The epitaph ZX_ERR_INVALID_ARGS indicates that the client is sending invalid requests. See
/// below for each request why they might be invalid.
///
/// The epitaph ZX_ERR_NO_RESOURCES indicates that the server can no longer store additional
/// component data and will not service new connections.
@discoverable
protocol ComponentDataRegister {
    /// Upserts, i.e. updates or inserts, extra component data to be included in feedback reports.
    ///
    /// The namespace and each annotation key are used to decide whether to update or insert an
    /// annotation. If an annotation is already present for a given key within the same namespace,
    /// update the value, otherwise insert the annotation with that key under that namespace.
    ///
    /// For instance, assuming these are the data already held by the server (from previous calls
    /// to Upsert()):
    /// ```
    /// {
    ///   "bar": { # namespace
    ///     "channel": "stable",
    ///   },
    ///   "foo": { # namespace
    ///     "version": "0.2",
    ///   }
    /// }
    /// ```
    /// then:
    /// ```
    /// Upsert({
    ///   "namespace": "bar",
    ///   "annotations": [
    ///     "version": "1.2.3.45",
    ///     "channel": "beta",
    ///   ]
    /// })
    /// ```
    /// would result in the server now holding:
    /// ```
    /// {
    ///   "bar": { # namespace
    ///     "channel": "beta", # updated
    ///     "version": "1.2.3.45" # inserted
    ///   },
    ///   "foo": { # namespace
    ///     "version": "0.2", # untouched
    ///   }
    /// }
    /// ```
    ///
    /// Note that the server will only hold at most MAX_NUM_ANNOTATIONS_PER_NAMESPACE distinct
    /// annotation keys per namespace, picking up the latest values.
    Upsert(struct {
        data ComponentData;
    }) -> ();
};

const MAX_NAMESPACE_LENGTH uint32 = 32;
const MAX_NUM_ANNOTATIONS_PER_NAMESPACE uint32 = 16;

/// Data known to a component, but not exposed to the platform, to attach to feedback reports.
type ComponentData = table {
    /// The top-level namespace associated with the data:
    /// * Is intended to group related data together and reduce data key collisions across
    ///   namespaces.
    /// * May be shared by multiple clients, e.g., there could be multiple clients within the same
    ///   component or across components that want to expose related data and they would all use
    ///   the same namespace.
    /// * Will be prefixed to every data key passed within that namespace in all feedback reports,
    ///   e.g., the annotation "version" would appear as "foo.version" in all feedback reports if
    ///   the namespace is "foo".
    /// * Must match [a-z\-]+, i.e. only lowercase letters and hyphens or this will result in a
    ///   ZX_ERR_INVALID_ARGS epitaph.
    /// * Must not match a reserved namespace used internally for platform data, e.g., "build", or
    ///   this will result in a ZX_ERR_INVALID_ARGS epitaph. The list of reserved namespaces is
    ///   internal and subject to change for now.
    1: namespace string:MAX_NAMESPACE_LENGTH;

    /// A vector of key-value string pairs, e.g., `<"version", "1.2.3.45">`.
    ///
    /// Keys:
    /// * Should be unique as only the latest value for a given key in the vector will be
    ///   considered.
    /// * Must match [a-z\-\.]+, i.e. only lowercase letters, hyphens and periods. Use periods for
    ///   sub-namespacing, e.g., "build.label" and "build.type", so that related annotations are
    ///   grouped together (here related to "build") when sorted lexicographically.
    2: annotations vector<Annotation>:MAX_NUM_ANNOTATIONS_PER_NAMESPACE;
};