// 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.
type EnvironmentDecl = table {
    /// The name of this environment.
    1: name fuchsia.component.name;

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

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

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

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

    /// The duration in milliseconds that the component will have to stop before
    /// it is killed.
    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 {
    /// The name of the runner capability as it's exposed to, offered, or
    /// defined by this component.
    1: source_name fuchsia.component.name;

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

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

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

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

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

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

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