blob: 9f944411faf0a05826ca9654659365664c1c3e1d [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.
type Annotation = resource struct {
/// An identfier for this annotation.
key AnnotationKey;
/// The contents of this annotation.
value AnnotationValue:optional;
};
/// Maximum number of annotations on a single story.
const MAX_ANNOTATIONS_PER_STORY uint32 = 100;
/// Maximum number of annotations on a single module.
const MAX_ANNOTATIONS_PER_MODULE uint32 = 100;
/// Maximum number of annotations that can be passed to either method
/// Annotate() AnnotateModule() in fuchsia.modular protocols that support
/// annotations.
const MAX_ANNOTATIONS_PER_UPDATE uint32 = 50;
/// Maximum length of [`fuchsia.modular/AnnotationKey`].
const MAX_ANNOTATION_KEY_LENGTH uint32 = 256;
/// Maximum length of [`fuchsia.modular/AnnotationValue`] fields:
/// `text` and `bytes`.
const MAX_ANNOTATION_VALUE_LENGTH uint32 = 1024;
/// Maximum length of the [`fuchsia.modular/AnnotationValue.buffer`] field, in
/// bytes.
///
/// Does not apply to other fields; see [`MAX_ANNOTATION_VALUE_LENGTH`].
const MAX_ANNOTATION_VALUE_BUFFER_LENGTH_BYTES uint32 = 102400;
/// An identifier for an [`fuchsia.modular/Annotation`].
alias 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.
type AnnotationValue = flexible resource union {
1: text string:MAX_ANNOTATION_VALUE_LENGTH;
2: bytes vector<uint8>:MAX_ANNOTATION_VALUE_LENGTH;
3: buffer fuchsia.mem.Buffer;
};
/// Error returned from calls to Annotate().
type AnnotationError = strict enum {
/// 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;
};