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

/// A component declaration.
///
/// This information is typically encoded in the component manifest (.cm file)
/// if it has one or may be generated at runtime by a component resolver for
/// those that don't.
table ComponentDecl {
    /// Information about the program to run when the component is executed.
    ///
    /// The component manager provides the contents of this dictionary to the
    /// component runner when executing the program. Each component runner can
    /// freely define the contents of this dictionary as needed.
    ///
    /// The system's default runner understands the following entries:
    ///
    /// - "binary": string
    ///   The path of the executable relative to the root of the package.
    ///   Typically an ELF binary.
    ///
    /// - "args": vector of strings
    ///   The command-line arguments to provide to the executable at runtime.
    ///
    /// - "env": dictionary of strings
    ///   The environment variables to provide to the executable at runtime.
    ///
    /// Other runners may define different entries.
    1: fuchsia.data.Dictionary program;

    /// List of capabilities used by the component. These consist of
    /// capabilities offered to the component that are installed in its incoming
    /// namespace.
    ///
    /// The used capabilities must be unique and non-overlapping.
    2: vector<UseDecl> uses;

    /// List of capabilities exposed by the component. These consist of
    /// capabilities that are made visible to the containing realm. The parent
    /// may `offer` these capabilities to its children, but not `use` them.
    ///
    /// The exposed capabilities must be unique and non-overlapping.
    3: vector<ExposeDecl> exposes;

    /// List of capabilities offered to the component’s children. These consist
    /// of capabilities that the given children may `use`, which may come from a
    /// child, the containing realm, or the component's own outgoing namespace.
    ///
    /// The offered capabilities must be unique and non-overlapping.
    4: vector<OfferDecl> offers;

    /// Additional metadata about the component.
    5: Object facets;

    /// The component's statically instantiated children. The children must have
    /// unique names.
    6: vector<ChildDecl> children;

    /// The component's collections. The collections must have unique names.
    7: vector<CollectionDecl> collections;

    /// List of storage capabilities created by this component.
    /// Storage capabilities can be offered to children.
    8: vector<StorageDecl> storage;

    /// List of runner capabilities created by this component.
    /// Runner capabilities can be exposed to the parent's realm or offered to children.
    9: vector<RunnerDecl> runners;

    /// List of environments created by this component.
    /// Environments are assigned to children and control aspects of a child component's
    /// runtime.
    10: vector<EnvironmentDecl> environments;

    /// List of resolver capabilities created by this component.
    ///
    /// A component can:
    ///
    /// - "expose" a resolver capability to its realm,
    /// - "offer" a resolver capability to its children,
    /// - register a resolver in an environment.
    ///
    /// A component cannot "use" a resolver capability directly. Component manager uses
    /// a resolver capability on behalf of a component when that component's environment
    /// contains the resolver capability.
    11: vector<ResolverDecl> resolvers;
};