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