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

/// 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 to interact with the user in some way. An *element proposer*
/// is a component that calls `ProposeElement` to add an element to the session.
///
/// The session will typically implement `Manager` and provide it
/// to its child element proposers.
///
/// For example, an element proposer 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 element proposer proposes to add an
/// element to the session via the `Manager` protocol. Similarly,
/// the element proposer may be part of an interactive user interface that
/// proposes elements based on user input.
[Discoverable]
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
    ///
    /// If `spec.additional_services` is specified,
    ///
    /// * `spec.component_url` must point to a CFv1 component
    ///   (`additional_services` is not supported for CFv2 components)
    ///
    /// * The [`fuchsia.sys/ServiceList.host_directory`] field in
    ///   `spec.additional_services` must be set to a channel to a directory hosting
    ///   the services ([`fuchsia.sys/ServiceList.provider`] is not supported
    ///   and must be null)
    ///
    /// + `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` is missing or
    ///   could not be resolved
    /// * error `ProposeElementError.INVALID_ARGS`
    ///   if `spec.additional_services`:
    ///   - is specified for a CFv2 `spec.component_url`, or
    ///   - does not have a valid [`fuchsia.sys/ServiceList.host_directory`], or
    ///   - contains a non-null [`fuchsia.sys/ServiceList.provider`]
    ProposeElement(Spec spec, request<Controller>? controller)
        -> () error ProposeElementError;
};

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

    /// Initial annotations on the element. Required, but can be an empty vector.
    2: Annotations annotations;

    /// A list of services passed to the Element. Optional.
    3: fuchsia.sys.ServiceList additional_services;
};

/// Errors that can be returned when attempting to add elements to a session.
enum ProposeElementError {
    /// The element spec was malformed.
    INVALID_ARGS = 1;

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

/// 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.
protocol Controller {
    compose AnnotationController;
};