// Copyright 2018 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.sys2;

using fuchsia.io;

/// A protocol used by a component instance to manage its own realm, such as for
/// binding to its children.
///
/// The component manager provides this service to components that use
/// `/svc/fuchsia.sys2.Realm`.
[Discoverable]
protocol Realm {
    /// Binds to a child component instance, causing it to start running if it
    /// is not already. When this function successfully returns, |child| is
    /// running and |exposed_capabilities| is bound to a directory that contains
    /// the capabilities which the child exposed to its realm via
    /// |ComponentDecl.exposes| (specified via "expose" declarations in the
    /// component’s manifest).
    ///
    /// |exposed_capabilities| is a valid channel as long as |child| is running.
    /// |child| will remain running until it either stops on its own, or
    /// |DestroyChild| causes the child instance to be destroyed.
    ///
    /// For example, if the child exposes a service `/svc/example.Echo` then
    /// |exposed_capabilities| will contain that service at that path.
    ///
    /// NOTE: |BindChild| does not support pipelining with |CreateChild|. If
    /// |BindChild| is called on an instance before |CreateChild| successfully
    /// returns, it may return |INSTANCE_NOT_FOUND|.
    ///
    /// Errors:
    /// - INVALID_ARGUMENTS: |child| is not a valid child reference.  -
    /// - INSTANCE_NOT_FOUND: |child| does not exist.
    /// - INSTANCE_CANNOT_START: Instance was not running and there was an error
    ///   starting it.
    BindChild(ChildRef child, request<fuchsia.io.Directory>
              exposed_capabilities) -> () error Error;

    /// Creates a child component instance dynamically. When this function
    /// returns successfully, the instance exists, but it may not be running.
    ///
    /// Errors:
    /// - INVALID_ARGUMENTS: |collection| is not a valid reference or |child|
    ///   is not a valid declaration.
    /// - COLLECTION_NOT_FOUND: |collection| does not exist.
    /// - INSTANCE_ALREADY_EXISTS: |decl.name| already exists in |collection|.
    /// - NO_SPACE: Could not allocate storage for the new instance.
    CreateChild(CollectionRef collection, ChildDecl decl) -> () error Error;

    /// Destroys a dynamically-created component instance. When this function
    /// returns, the client should assume the instance no longer exists.
    /// However, some cleanup (such as stopping the component instance or
    /// freeing its storage) may be performed in the background after the
    /// function returns.
    ///
    /// Errors:
    /// - INVALID_ARGUMENTS: |child| is not a valid reference or does not refer
    ///   to a dynamic instance.
    /// - INSTANCE_NOT_FOUND: |child| does not exist.
    /// - COLLECTION_NOT_FOUND: |collection| does not exist.
    DestroyChild(ChildRef child) -> () error Error;

    /// Returns an iterator that lists all instances in a collection.
    ///
    /// NOTE: The results are not guaranteed to be consistent. Instances may be
    /// created or destroyed while the iterator is live, but those changes
    /// won't be observed by the iterator after this method returns.
    ///
    /// Errors:
    /// - INVALID_ARGUMENTS: |collection| is not a valid reference.
    /// - COLLECTION_NOT_FOUND: |collection| does not exist.
    ListChildren(CollectionRef collection, request<ChildIterator> iter) -> ()
        error Error;
};

/// A protocol to iterate over the list of children in a realm.
protocol ChildIterator {
    /// Advance the iterator and return the next batch of children.
    ///
    /// Returns a vector of |ChildRef|. Returns an empty vector when there are
    /// no more children.
    Next() -> (vector<ChildRef> children);
};