blob: 0f87bf3adf8f291d8361b183b0efbb55c8efa87b [file] [log] [blame]
// 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;
};