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