blob: c9f56c858f613d19512e115396a89ca8ebc3e24e [file] [log] [blame]
// 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.modular;
using fuchsia.mem;
/// A user-defined annotation for a story or module.
struct Annotation {
/// An identfier for this annotation.
AnnotationKey key;
/// The contents of this annotation.
AnnotationValue? value;
};
/// Maximum number of annotations on a single story.
const uint32 MAX_ANNOTATIONS_PER_STORY = 100;
/// Maximum number of annotations on a single module.
const uint32 MAX_ANNOTATIONS_PER_MODULE = 100;
/// Maximum number of annotations that can be passed to either method
/// Annotate() AnnotateModule() in fuchsia.modular protocols that support
/// annotations.
const uint32 MAX_ANNOTATIONS_PER_UPDATE = 50;
/// Maximum length of [`fuchsia.modular/AnnotationKey`].
const uint32 MAX_ANNOTATION_KEY_LENGTH = 256;
/// Maximum length of [`fuchsia.modular/AnnotationValue`] fields:
/// `text` and `bytes`.
const uint32 MAX_ANNOTATION_VALUE_LENGTH = 1024;
/// Maximum length of the [`fuchsia.modular/AnnotationValue.buffer`] field, in
/// bytes.
///
/// Does not apply to other fields; see [`MAX_ANNOTATION_VALUE_LENGTH`].
const uint32 MAX_ANNOTATION_VALUE_BUFFER_LENGTH_BYTES = 102400;
/// An identifier for an [`fuchsia.modular/Annotation`].
using AnnotationKey = string:MAX_ANNOTATION_KEY_LENGTH;
/// The value of a [`fuchsia.modular/Annotation`].
///
/// The actual field used depends on the type of annotation, which is
/// user-defined, and not enforced by the framework.
///
/// The size of `buffer` is limited to
/// `MAX_ANNOTATION_VALUE_BUFFER_LENGTH_BYTES` bytes.
flexible union AnnotationValue {
1: string:MAX_ANNOTATION_VALUE_LENGTH text;
2: vector<uint8>:MAX_ANNOTATION_VALUE_LENGTH bytes;
3: fuchsia.mem.Buffer buffer;
};
/// Error returned from calls to Annotate().
enum AnnotationError {
/// The `AnnotationValue.buffer` size exceeds the maximum length,
/// `MAX_ANNOTATION_VALUE_BUFFER_LENGTH_BYTES`.
VALUE_TOO_BIG = 1;
/// The total number of annotations on the story or module being annotated
/// exceeds `MAX_ANNOTATIONS_PER_STORY` or `MAX_ANNOTATIONS_PER_MODULE`.
TOO_MANY_ANNOTATIONS = 2;
/// The resource to be annotated was not found and could not be resolved
/// by, for example, waiting, or creating the missing resource automatically.
/// This error may be returned by StoryPuppetMaster.AnnotateModule(), which
/// can wait for a missing Module, but requires the Module's Story exist.
NOT_FOUND = 3;
};