blob: 1944ebfe5d9514cd03cbf6b03deb212712ad43bf [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.
/// 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.
protocol ComponentDataRegister {
/// 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": "",
/// "channel": "beta",
/// ]
/// }) would result in the server now holding:
/// {
/// "bar": { # namespace
/// "channel": "beta", # updated
/// "version": "" # 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(ComponentData data) -> ();
const uint32 MAX_NAMESPACE_LENGTH = 32;
/// Data known to a component, but not exposed to the platform, to attach to feedback reports.
table ComponentData {
/// 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: string:MAX_NAMESPACE_LENGTH namespace;
/// A vector of key-value string pairs, e.g., `<"version", "">`.
/// 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: vector<Annotation>:MAX_NUM_ANNOTATIONS_PER_NAMESPACE annotations;