// Copyright 2022 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;
using fuchsia.component;
using fuchsia.component.decl;
using fuchsia.component.config;
using fuchsia.url;

/// The maximum length of an instance ID.
/// An instance ID is a 256-bit identifier, which when encoded
/// in hex notation is 64 characters long.
const MAX_INSTANCE_ID_LENGTH uint32 = 64;

/// Describes the current state of instance
type InstanceState = strict enum {
    /// The component is created, but has not been resolved by component manager.
    /// Most information about this component is unknown.
    UNRESOLVED = 0;

    /// The component has been resolved by component manager but is not currently running.
    RESOLVED = 1;

    /// The component has been resolved and started by component manager.
    STARTED = 2;
};

/// Basic information about a component instance.
/// This object contains information that is readily available to component manager.
type InstanceInfo = struct {
    /// The path to this instance relative to the scope root.
    moniker string:fuchsia.component.MAX_MONIKER_LENGTH;

    /// The URL of the component manifest for this instance.
    url fuchsia.url.Url;

    /// The stable identifier for this instance.
    instance_id string:<MAX_INSTANCE_ID_LENGTH, optional>;

    /// The current state of this instance.
    state InstanceState;
};

/// The detailed resolved state of a component instance
type ResolvedState = resource struct {
    /// All `use` declarations as defined in the component manifest.
    uses vector<fuchsia.component.decl.Use>:MAX;

    /// All `expose` declarations as defined in the component manifest.
    exposes vector<fuchsia.component.decl.Expose>:MAX;

    /// The resolved structured configuration of this component instance.
    config box<fuchsia.component.config.ResolvedConfig>;

    /// The package directory containing the component manifest, if one exists.
    /// This directory has the same permissions given by the package resolver
    /// (most likely RO permissions).
    pkg_dir client_end:<fuchsia.io.Directory, optional>;

    /// The execution state of this instance.
    started box<StartedState>;

    /// The directory containing all capabilities exposed by the component.
    /// This directory has RW permissions.
    exposed_dir client_end:<fuchsia.io.Directory>;

    /// The directory representing the component's namespace.
    /// This directory has RW permissions.
    ns_dir client_end:<fuchsia.io.Directory>;
};

/// The detailed started state of a component instance
type StartedState = resource struct {
    /// The outgoing directory of this instance, if one exists.
    out_dir client_end:<fuchsia.io.Directory, optional>;

    /// The debug directory served by the runner of this instance, if one exists.
    runtime_dir client_end:<fuchsia.io.Directory, optional>;

    /// The human-readable explanation for why this instance is running.
    start_reason string:MAX;
};

/// An iterator over basic information of all instances in the realm
protocol InstanceInfoIterator {
    Next() -> (struct {
        infos vector<InstanceInfo>:MAX;
    });
};

/// Offers detailed introspection into component instances under a realm.
@discoverable
protocol RealmQuery {
    /// Gets the detailed information of a particular instance identified by its moniker.
    /// This response contains handles to resources of the instance. As a result, component manager
    /// pays a non-trivial cost when this method is invoked.
    ///
    /// Errors:
    /// * INVALID_ARGUMENTS: The given moniker is not valid.
    /// * INSTANCE_NOT_FOUND: No instance was found matching the given moniker.
    GetInstanceInfo(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> (resource struct {
        /// Basic information about the component instance.
        info InstanceInfo;

        /// Detailed information about the resolved component instance.
        /// If this object does not exist, the instance is not resolved.
        resolved box<ResolvedState>;
    }) error fuchsia.component.Error;
};

/// Offers basic introspection into component instances under a realm.
@discoverable
protocol RealmExplorer {
    /// Returns an iterator over basic information of each instance scoped to this realm.
    /// When the server receives this call, it will take a snapshot of the current component
    /// topology and relays that over the iterator. Any changes to the topology *after* this method
    /// call is received by the server will not be shown by the iterator.
    ///
    /// Errors:
    /// * INSTANCE_NOT_FOUND: The instance at the scope root cannot be found.
    GetAllInstanceInfos() -> (resource struct {
        iterator client_end:InstanceInfoIterator;
    }) error fuchsia.component.Error;
};