// Copyright 2021 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.component;

using fuchsia.io;
using fuchsia.process;
using fuchsia.component.decl;
using fuchsia.component.sandbox;

/// The maximum number of handles that can be passed to a created component.
const MAX_HANDLE_COUNT uint32 = 128;

/// The maximum number of dynamic offers that can target a created component.
const MAX_DYNAMIC_OFFER_COUNT uint32 = 128;

// The maximum number of configuration capabilities that can target a created component.
@available(added=HEAD)
const MAX_CONFIG_COUNT uint32 = 128;

/// The maximum number of children that the a call `ChildIterator.Next`
/// can return.
/// Note, this is not a limit on the number of children that can be added
/// to a component. This is merely a limit for a single invocation of the
/// `Next` method.
const MAX_CHILD_COUNT uint32 = 128;

/// A protocol used by a component instance to manage its own realm, such as for
/// binding to its children.
///
/// Requests to this protocol are processed in the order they are received.
/// Clients that wish to send requests in parallel should open multiple
/// connections.
///
/// The component framework provides this service to components that use
/// `fuchsia.component.Realm`.
@discoverable
closed protocol Realm {
    /// Opens the exposed directory of a child component instance. When this
    /// function successfully returns, `exposed_dir` 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). The child component will not start as a
    /// result of this call. Instead, starting will occur iff the parent binds
    /// to one of the capabilities contained within `exposed_dir`.
    ///
    /// `exposed_dir` is open as long as `child` exists.
    ///
    /// Errors:
    /// - `INVALID_ARGUMENTS`: `child` is not a valid child reference.
    /// - `INSTANCE_NOT_FOUND`: `child` does not exist.
    /// - `INSTANCE_CANNOT_RESOLVE`: `child`'s component declaration failed to resolve.
    /// - `INSTANCE_DIED`: This realm no longer exists.
    strict OpenExposedDir(resource struct {
        child fuchsia.component.decl.ChildRef;
        exposed_dir server_end:fuchsia.io.Directory;
    }) -> () error Error;

    /// Creates a child component instance dynamically. When this function
    /// returns successfully, the instance exists, but it may not be running.
    ///
    /// The environment of the child instance is determined by the environment
    /// of the collection. `decl` must not set `environment`.
    ///
    /// If `decl.startup == EAGER`, or `collection.durability == SINGLE_RUN`,
    /// [CreateChild] will start the component and return once the component is
    /// started. Otherwise, [CreateChild] will return immediately after creating
    /// the component and will not start or resolve it.
    ///
    /// 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`.
    /// - `INSTANCE_CANNOT_RESOLVE`: `child`'s component declaration failed to resolve
    ///   in a `SingleRun` collection.
    /// - `NO_SPACE`: Could not allocate storage for the new instance.
    /// - `INSTANCE_DIED`: This realm no longer exists.
    strict CreateChild(resource struct {
        collection fuchsia.component.decl.CollectionRef;
        decl fuchsia.component.decl.Child;
        args CreateChildArgs;
    }) -> () error Error;

    /// Destroys a dynamically-created component instance. When this function
    /// returns, the instance is destroyed and has stopped running.  However,
    /// cleanup of the component's resources (such as its isolated storage) may
    /// happen in the background after this 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.
    /// - `INSTANCE_DIED`: This realm no longer exists.
    strict DestroyChild(struct {
        child fuchsia.component.decl.ChildRef;
    }) -> () 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 or `iter`
    /// does not have `ZX_RIGHT_WAIT`.
    /// - `COLLECTION_NOT_FOUND`: `collection` does not exist.
    /// - `INSTANCE_DIED`: This realm no longer exists.
    /// - If `iter` does not have standard channel rights, this function may
    ///   return `ACCESS_DENIED` or component manager may close `iter`.
    strict ListChildren(resource struct {
        collection fuchsia.component.decl.CollectionRef;
        iter server_end:ChildIterator;
    }) -> () error Error;
};

type CreateChildArgs = resource table {
    /// The numbered handles to pass to the component instance.
    ///
    /// If the runner for the component does not support the numbered handles it is
    /// expected to close the handles.
    1: numbered_handles vector<fuchsia.process.HandleInfo>:MAX_HANDLE_COUNT;

    /// Dynamic offers that will target the component instance.
    ///
    /// Including `OfferDecl`s in this vector will cause additional capabilities
    /// to be offered to the newly created child, beyond the `OfferDecl`s in the
    /// parent's `ComponentDecl` that target the collection.
    ///
    /// Any kind of offer (e.g., protocol, directory) can be used as a dynamic
    /// offer. Any source that would be valid for a static offer is also valid
    /// for a dynamic offer. Additionally, unlike static offers, dynamic offers
    /// can use a "sibling" dynamic child component as a source by setting the
    /// source to a `ChildRef` that sets the `collection` field.
    ///
    /// Dynamic offers always target the newly created child component. As a
    /// result, `OfferDecl`s in `dynamic_offers` must not set the `target`
    /// field, as its value is implied.
    ///
    /// If either the source (that is, the component named in the `source` field
    /// of the `OfferDecl`) or the target of a dynamic offer is destroyed, the
    /// offer itself is destroyed simultaneously.
    ///
    /// In order to set this field to a non-empty value, the collection in which
    /// the child component is being created must specify
    /// `ComponentDecl.allowed_offers = STATIC_AND_DYNAMIC`.
    2: dynamic_offers vector<fuchsia.component.decl.Offer>:MAX_DYNAMIC_OFFER_COUNT;

    /// The controller for this component, which may be used to influence the
    /// component's lifecycle.
    @available(added=14)
    3: controller server_end:Controller;

    /// Configuration Capabilities that will target the component instance.
    ///
    /// Including a Configuration in this list will add the Configuration Capability
    /// as a dynamic capability in the current realm. It will also create a dynamic
    /// offer for this capability to the child.
    ///
    /// The dynamic offer that is created is from `self` to the newly created child.
    ///
    /// If the newly created child is destroyed, both the configuration capability and
    /// its resulting dynamic offer will be destroyed.
    ///
    /// In order to set this field to a non-empty value, the collection in which
    /// the child component is being created must specify
    /// `ComponentDecl.allowed_offers = STATIC_AND_DYNAMIC`.
    @available(added=HEAD)
    4: config_capabilities vector<fuchsia.component.decl.Configuration>:MAX_CONFIG_COUNT;

    /// A dictionary that contains extra capabilities for the component instance.
    @available(added=HEAD)
    5: dictionary client_end:fuchsia.component.sandbox.Dictionary;
};

/// A protocol to iterate over the list of children in a realm.
closed 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.
    strict Next() -> (struct {
        children vector<fuchsia.component.decl.ChildRef>:MAX_CHILD_COUNT;
    });
};