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

/// Declares an environment which configures a realm.
table EnvironmentDecl {
    /// The name of this environment.
    1: fuchsia.component.name name;

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

    /// 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: vector<RunnerRegistration>:MAX runners;

    /// 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: vector<ResolverRegistration>:MAX resolvers;

    /// Expose capabilties 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: vector<DebugRegistration>:MAX debug_capabilities;

    /// The duration in milliseconds that the component will have to stop before
    /// it is killed.
    6: uint32 stop_timeout_ms;
};

/// Specifies how a declared environment's initial set of properties are assigned.
enum EnvironmentExtends {
    /// 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.
table RunnerRegistration {
    /// The name of the runner capability as it's exposed to, offered, or
    /// defined by this component.
    1: fuchsia.component.name source_name;

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

    /// The name by which the runner is made available in this environment.
    3: fuchsia.component.name target_name;
};

/// A mapping of URL scheme to resolver name.
table ResolverRegistration {
    /// The name of the resolver.
    1: fuchsia.component.name resolver;

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

    /// 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: fuchsia.component.url_scheme scheme;
};

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

/// 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
table DebugProtocolRegistration {
    /// The provider of the capability relative to the component itself. Must be
    /// `parent`, `self`, or `child`.
    1: Ref source;

    /// Name identifying the protocol being offered.
    2: fuchsia.component.name source_name;

    /// The name by which the capability is being offered.
    3: fuchsia.component.name target_name;
};