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

using fuchsia.url;

/// Statically declares a child component instance.
type Child = table {
    /// (Required) The name assigned to the child by its parent.
    ///
    /// Must be non-empty, unique among all siblings, and contain only the
    /// following characters: [a-z0-9-_.].
    1: name child_name;

    /// (Required) The child component's URL.
    ///
    /// Must be non-empty and a well-formed URL.
    2: url fuchsia.url.Url;

    /// (Required) The startup mode for the component instance.
    ///
    /// Must be set.
    3: startup StartupMode;

    /// (Optional) The environment assigned to this child.
    ///
    /// May be unset, in which case the child will inherit the parent component's
    /// environment. If set, the name must reference an environment defined in
    /// the `ComponentDecl` and it must contain only the following characters:
    /// [a-z0-9-_.].
    4: environment name;

    /// (Optional, defaults to `NONE`) The action to take if this component
    /// instance terminates unexpectedly.
    5: on_terminate OnTerminate;

    /// Configuration overrides to apply to the child's base configuration.
    ///
    /// For a configuration field to be overridden it must be marked as mutable by parent.
    ///
    /// Parents must pass `ConfigOverride` values which match the child's declared schema types
    /// exactly.
    @available(added=12)
    6: config_overrides vector<ConfigOverride>:MAX;
};

/// Describes under what conditions the component may be started.
type StartupMode = strict enum {
    /// Start component instance only when another instance binds to it.
    LAZY = 0;
    /// Start component instance as soon as parent starts. This mode is only
    /// supported for statically declared children -- a dynamic instance may only be
    /// started by binding to it.
    EAGER = 1;
};

/// Describes the action to take if this component instance terminates
/// unexpectedly.
type OnTerminate = strict enum {
    /// No action, the default
    NONE = 0;

    /// Trigger a graceful system reboot if the component terminates for any
    /// reason. This is a specialized feature gated by Component Framework
    /// security policy.
    REBOOT = 1;
};

/// A directive to override the value of a particular configuration field in the child.
@available(added=12)
type ConfigOverride = table {
    1: key ConfigKey;
    2: value ConfigValue;
};