// 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.
@available(added=7)
library fuchsia.sys2;

using fuchsia.component;
using fuchsia.component.decl;

// Errors that can occur from resolving a component instance
@available(added=11)
type ResolveError = flexible enum {
    // An unexpected error occurred.
    INTERNAL = 1;
    // The instance identified by the given moniker could not be found.
    INSTANCE_NOT_FOUND = 2;
    // The given moniker is invalid.
    BAD_MONIKER = 3;
    // The package containing the component manifest could not be found.
    PACKAGE_NOT_FOUND = 4;
    // The component manifest could not be found in the package.
    MANIFEST_NOT_FOUND = 5;
    // The component failed a policy check.
    @available(added=19)
    POLICY_ERROR = 6;
};

// Errors that can occur from starting a component instance
@available(added=11)
type StartError = flexible enum {
    // An unexpected error occurred.
    INTERNAL = 1;
    // The instance identified by the given moniker could not be found.
    INSTANCE_NOT_FOUND = 2;
    // The given moniker is invalid.
    BAD_MONIKER = 3;
    // The package containing the component manifest could not be found.
    PACKAGE_NOT_FOUND = 4;
    // The component manifest could not be found in the package.
    MANIFEST_NOT_FOUND = 5;
    // The component failed a policy check.
    @available(added=19)
    POLICY_ERROR = 6;
};

// Errors that can occur from stopping a component instance
@available(added=11)
type StopError = flexible enum {
    // An unexpected error occurred.
    INTERNAL = 1;
    // The instance identified by the given moniker could not be found.
    INSTANCE_NOT_FOUND = 2;
    // The given moniker is invalid.
    BAD_MONIKER = 3;
};

// Errors that can occur from destroying a component instance
@available(added=11)
type DestroyError = flexible enum {
    // An unexpected error occurred.
    INTERNAL = 1;
    // The instance identified by the given moniker could not be found.
    INSTANCE_NOT_FOUND = 2;
    // The given moniker is invalid.
    BAD_MONIKER = 3;
    // The given child reference is invalid.
    BAD_CHILD_REF = 4;
    // The instance identified by the given moniker exists but has not been
    // resolved.
    @available(added=20)
    INSTANCE_NOT_RESOLVED = 5;
};

// Errors that can occur from unresolving a component instance
@available(added=11)
type UnresolveError = flexible enum {
    // An unexpected error occurred.
    INTERNAL = 1;
    // The instance identified by the given moniker could not be found.
    INSTANCE_NOT_FOUND = 2;
    // The given moniker is invalid.
    BAD_MONIKER = 3;
};

// Errors that can occur from creating a component instance
@available(added=11)
type CreateError = flexible enum {
    // An unexpected error occurred.
    INTERNAL = 1;
    // The instance identified by the given moniker could not be found.
    INSTANCE_NOT_FOUND = 2;
    // The instance identified by the given moniker already exists.
    INSTANCE_ALREADY_EXISTS = 3;
    // The given moniker is invalid.
    BAD_MONIKER = 4;
    // The given child declaration is invalid.
    BAD_CHILD_DECL = 5;
    // The parent instance does not have a collection with the given name.
    COLLECTION_NOT_FOUND = 6;
    // A given dynamic offer is invalid.
    BAD_DYNAMIC_OFFER = 7;
    // The specified collection does not allow dynamic offers.
    DYNAMIC_OFFERS_FORBIDDEN = 8;
    // The specified collection does not allow eager startup.
    @available(removed=19)
    EAGER_STARTUP_FORBIDDEN = 9;
    // The specified collection does not allow numbered handles.
    NUMBERED_HANDLES_FORBIDDEN = 10;
};

/// Mutates the component instance state in a realm.
@discoverable
closed protocol LifecycleController {
    /// Starts the instance identified by the given moniker. Relative
    /// monikers must start with "./".
    ///
    /// The client can pass in the server end of a channel
    /// for the fuchsia.component.Binder protocol. This protocol
    /// will notify the client when the instance has stopped.
    ///
    /// The function returns once the instance has been started. Calling
    /// StartInstance() when the instance is already running is a no-op, but
    /// it will connect the Binder channel if a valid handle is provided.
    @available(added=11)
    strict StartInstance(resource struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        binder server_end:fuchsia.component.Binder;
    }) -> () error StartError;

    /// Stops the instance identified by the given moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the instance has been stopped.
    @available(added=11)
    strict StopInstance(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> () error StopError;

    /// Resolves the instance identified by the given moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the instance has been resolved.
    @available(added=11)
    strict ResolveInstance(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> () error ResolveError;

    /// Unresolves the component designated by the provided moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the instance has been unresolved.
    @available(added=11)
    strict UnresolveInstance(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> () error UnresolveError;

    /// Creates a new child instance identified by the given moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the child instance has been added to the topology.
    @available(added=11)
    strict CreateInstance(resource struct {
        parent_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        collection fuchsia.component.decl.CollectionRef;
        decl fuchsia.component.decl.Child;
        args fuchsia.component.CreateChildArgs;
    }) -> () error CreateError;

    /// Destroys the instance identified by the given moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the child instance no longer exists in the topology.
    @available(added=11)
    strict DestroyInstance(struct {
        parent_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        child fuchsia.component.decl.ChildRef;
    }) -> () error DestroyError;

    // ---------------------------------------------------------------
    // The methods below are considered deprecated and will be removed
    // in an upcoming API release.
    // ---------------------------------------------------------------

    /// Starts the instance identified by the given moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the instance has been started.
    @available(added=7, deprecated=11, removed=12, note="Use StartInstance instead")
    strict Start(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> (struct {
        result StartResult;
    }) error fuchsia.component.Error;

    /// Stops the instance identified by the given moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the instance has been stopped.
    ///
    /// Note: `is_recursive` is no longer supported by component manager.
    ///       Setting it to true will return Error::Unsupported.
    @available(added=7, deprecated=11, removed=12, note="Use StopInstance instead")
    strict Stop(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        is_recursive bool;
    }) -> () error fuchsia.component.Error;

    /// Resolves the instance identified by the given moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the instance has been resolved
    @available(added=7, deprecated=11, removed=12, note="Use ResolveInstance instead")
    strict Resolve(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> () error fuchsia.component.Error;

    /// Unresolves the component designated by the provided moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the component successfully unresolves, or the
    /// operation fails.
    @available(added=7, deprecated=11, removed=12, note="Use UnresolveInstance instead")
    strict Unresolve(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> () error fuchsia.component.Error;

    /// Creates a new child instance under a collection. This method is similar to
    /// [`fuchsia.component/Realm.CreateChild`].
    ///
    /// `parent_moniker` is the moniker of the instance that owns the collection.
    ///
    /// The function returns once the child instance has been added to the topology.
    @available(added=7, deprecated=11, removed=12, note="Use CreateInstance instead")
    strict CreateChild(resource struct {
        parent_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        collection fuchsia.component.decl.CollectionRef;
        decl fuchsia.component.decl.Child;
        args fuchsia.component.CreateChildArgs;
    }) -> () error fuchsia.component.Error;

    /// Destroys a child instance under a collection. This method is similar to
    /// [`fuchsia.component/Realm.DestroyChild`].
    ///
    /// `parent_moniker` is the moniker of the instance that owns the collection.
    ///
    /// The function returns once the child instance no longer exists in the topology.
    @available(added=7, deprecated=11, removed=12, note="Use DestroyInstance instead")
    strict DestroyChild(struct {
        parent_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        child fuchsia.component.decl.ChildRef;
    }) -> () error fuchsia.component.Error;

    /// Opens a [`fuchsia.sys2/StorageAdmin`] protocol for the exposed storage capability of an
    /// instance identified by its moniker. This protocol is served by component manager.
    ///
    /// TODO(https://fxbug.dev/42180039): Move this function to [`fuchsia.sys2/RealmQuery`]
    @available(added=11, deprecated=11, removed=12)
    strict GetStorageAdmin(resource struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        capability string:fuchsia.component.MAX_CAPABILITY_ID_LENGTH;
        admin_server server_end:StorageAdmin;
    }) -> () error fuchsia.component.Error;
};

/// Describes the result of the Start command.
@available(added=7, deprecated=11, removed=12, note="Use StartInstance instead")
type StartResult = strict enum {
    /// The instance was started.
    STARTED = 0;

    /// The instance was already running.
    ALREADY_STARTED = 1;
};