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

/// Declares an environment which configures a realm.
type Environment = table {
    /// (Required) The name of this environment.
    1: name name;

    /// (Required) Specifies how the initial state of this environment is
    /// constructed.
    2: extends EnvironmentExtends;

    /// (Optional) List of runners available in this environment.
    ///
    /// This list determines the total set of runners that are available for any
    /// component in the environment to use.
    3: runners vector<RunnerRegistration>:MAX;

    /// (Optional) List of component resolvers and the URL schemes they are
    /// registered to resolve. These registrations determine how components are
    /// resolved in the realm. If the component URL scheme does not match any of
    /// these resolvers, URL resolution is delegated to the parent environment,
    /// if this environment `extends` from `REALM`.
    4: resolvers vector<ResolverRegistration>:MAX;

    /// (Optional) Expose capabilities to debug section when component manager
    /// allows it.
    ///
    /// These capabilities are accessible to any component in the environment
    /// with a `use` declaration with `source == debug`.  Only capabilities
    /// intended to support development should be declared here, and they are
    /// only allowed if explicitly included in the component manager allowlist.
    5: debug_capabilities vector<DebugRegistration>:MAX;

    /// (Optional) The duration in milliseconds that the component will have to
    /// stop before it is killed. Required if this environment `extends` from
    /// `NONE`.
    6: stop_timeout_ms uint32;
};

/// Specifies how a declared environment's initial set of properties are assigned.
type EnvironmentExtends = strict enum {
    /// The environment has no initial set of properties.
    NONE = 0;
    /// The environment's initial set of properties are inherited from its realm.
    /// Inherited properties include any fields defined in `EnvironmentDecl`.
    REALM = 1;
};

/// A repository of the runners available in an environment.
type RunnerRegistration = table {
    /// (Required) The name of the runner capability as it's exposed to,
    /// offered, or defined by this component.
    1: source_name name;

    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `parent`, `self`, or `child`.
    2: source Ref;

    /// (Required) The name by which the runner is made available in this
    /// environment.
    3: target_name name;
};

/// A mapping of URL scheme to resolver name.
type ResolverRegistration = table {
    /// (Required) The name of the resolver.
    1: resolver name;

    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `parent`, `self`, or `child`.
    2: source Ref;

    /// (Required) The URL scheme the resolver is registered to handle. Only one
    /// resolver may be registered to a particular URL scheme. The URL scheme
    /// must start with a lowercase ASCII letter (a-z), and may contain
    /// lowercase ASCII letters, digits, `+`, `-`, and `.`.
    3: scheme url_scheme;
};

/// Declares a capability registered in the debug section of an environment.
type DebugRegistration = flexible union {
    1: protocol DebugProtocolRegistration;
};

/// Registers a protocol in the environment as a debug capability. This makes
/// it available to any component in the environment that uses it with
/// `source == debug`.
///
/// To learn more about protocols, see:
/// https://fuchsia.dev/fuchsia-src/glossary#protocol
type DebugProtocolRegistration = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `parent`, `self`, or `child`.
    1: source Ref;

    /// (Required) Name identifying the protocol being offered.
    2: source_name name;

    /// (Required) The name by which the capability is being offered.
    3: target_name name;
};