// 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.element;

using fuchsia.sys;
using fuchsia.url;

@available(added=19)
const MANAGER_NAMESPACE string = "element_manager";

// The following annotation keys are all in the element manager namespace.

/// The name of the element in its collection. If not provided to `ProposeElement`, a random name is
/// chosen.
@available(added=19)
const ANNOTATION_KEY_NAME string = "name";

/// If present, the element will persist over a reboot.
@available(added=19)
const ANNOTATION_KEY_PERSIST_ELEMENT string = "persist_element";

/// The component URL of the element.
@available(added=19)
const ANNOTATION_KEY_URL string = "url";

/// An interface used to add elements to a session.
///
/// An *element* is a component that is expected to be instantiated as a child
/// of the session and (optionally) to interact with the user in some way.
///
/// The session will typically implement `Manager` and route it where needed.
/// For tools like `ffx session add` to work, the session must expose `Manager`
/// to its parent.
///
/// For example, a component in the session may be a non-interactive application that
/// listens to the network for a command to display an element to the user.
/// When it receives the command, the component calls `ProposeElement()`.
@discoverable
closed protocol Manager {
    /// Proposes to add an element to the session.
    ///
    /// If `ProposeElement` returns without error, the caller can assume
    /// the element is now part of the session. However, whether or not the
    /// element component is actively running, or not, depends on the session
    /// implementation. For example, a session may decide to conserve resources by
    /// suspending an element which is not visible, or delay the running of an
    /// element until a more appropriate time.
    ///
    /// ## Spec
    ///
    /// * `spec.component_url` is required
    /// + `spec` describes the element to add
    /// + `controller` can be used to observe and affect the lifecycle of the
    ///   element, and to set and get annotations on the element
    /// * error `ProposeElementError.NOT_FOUND` if `spec.component_url` could not be resolved
    /// * error `ProposeElementError.INVALID_ARGS` if a required field is not present or annotations
    ///   are invalid
    @available(replaced=19)
    strict ProposeElement(resource struct {
        spec Spec;
        controller server_end:<Controller, optional>;
    }) -> () error ProposeElementError;
    @available(added=19)
    strict ProposeElement(resource struct {
        spec Spec;
        controller server_end:<Controller, optional>;
    }) -> () error ManagerError;

    /// Removes the element identified by `name` from the session. If the element is a persistent
    /// element, it is removed permanently. Any persistent storage that the element might have used
    /// is left untouched.
    @available(added=19)
    strict RemoveElement(struct {
        name string:MAX;
    }) -> () error ManagerError;
};

/// Description of an element to be added to a session.
type Spec = resource table {
    /// The component URL of the element. Required.
    1: component_url fuchsia.url.Url;

    /// Initial annotations on the element. Required, but can be an empty vector. If the element
    /// manager URL annotation is included (which is allowed, but not necessary), then it *must*
    /// match `component_url`.
    2: annotations Annotations;

    @available(removed=12)
    3: additional_services fuchsia.sys.ServiceList;

    @available(removed=12)
    4: arguments vector<string:MAX>:MAX;
};

/// Errors that can be returned when using the Manager protocol.
@available(removed=19)
type ProposeElementError = strict enum {
    /// The element spec was malformed.
    INVALID_ARGS = 1;

    /// The element's component URL could not be resolved.
    NOT_FOUND = 2;
};

@available(added=19)
type ManagerError = strict enum {
    /// The element spec was malformed.
    INVALID_ARGS = 1;

    /// The element's component URL could not be resolved.
    NOT_FOUND = 2;

    /// Unable to persist a proposed element because there was an issue writing to persistent
    /// storage.  The proposed element will not have been started.
    UNABLE_TO_PERSIST = 3;
};

/// An interface that gives clients of `Manager` (element proposers) control
/// over the proposed element's lifecycle and annotations.
///
/// ## Lifecycle
///
/// The client must keep `Controller` connected to ensure the element
/// remains in the session and is not destroyed. Once `Controller` is closed,
/// the element and its component will be terminated. The element may also terminate
/// itself, which will cause `Controller` to close.
closed protocol Controller {
    compose AnnotationController;
};