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

/// Statically declares a component instance collection.
type Collection = table {
    /// (Required) The name of the collection. Instances created in the
    /// collection are scoped to this name.
    1: name name;

    /// (Required) The durability of instances in the collection.
    2: durability Durability;

    /// (Optional) The environment assigned to child instances in this
    /// collection.
    ///
    /// May be unset, in which case children in this collection 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-_.].
    3: environment name;

    /// (Optional, defaults to `STATIC_ONLY`) The kinds of offers that can
    /// target the child instances in this collection.
    ///
    /// Only components using the `dynamic_offers` restricted feature may set
    /// this field.
    4: allowed_offers AllowedOffers;

    /// (Optional, defaults to `false`) Whether child instances in this
    /// collection can have names longer than the default length limit of 100.
    ///
    /// Only components using the `allow_long_names` restricted feature may set
    /// this field.
    5: allow_long_names bool;

    /// (Optional) Whether the data in isolated storage used by dynamic child
    /// instances and their descendants will persist after the instances are
    /// destroyed. New dynamic instances inherit the previous instances' data
    /// stores.
    ///
    /// This setting can be overridden by a lower-level collection that is a
    /// descendant of a collection that enables/disables this setting.
    ///
    /// This setting applies to all storage capabilities consumed by the
    /// collection components and their descendants.
    ///
    /// The default is the value inherited from an ancestral collection if set,
    /// otherwise `false`.
    6: persistent_storage bool;
};

/// The durability of component instances created in a collection.
@strict_audit(bug="https://fxbug.dev/467128242", state="PENDING_REVIEW")
type Durability = strict enum {
    /// An instance exists until either its parent instance is stopped
    /// or it is explicitly destroyed.
    TRANSIENT = 2;
    /// An instance is started upon creation and is immediately destroyed when
    /// it stops.
    SINGLE_RUN = 3;
};

/// The kinds of offers that can target the children in a collection.
@strict_audit(bug="https://fxbug.dev/467128242", state="PENDING_REVIEW")
type AllowedOffers = strict enum {
    /// Only static offers may target components in the collection. "Static
    /// offers" are the offers in the `ComponentDecl` that target the collection
    /// itself.
    ///
    /// This is the default behavior.
    STATIC_ONLY = 1;

    /// Both static offers and dynamic offers may target components in the
    /// collection. "Static offers" are the offers in the `ComponentDecl` that
    /// target the collection itself. "Dynamic offers" are additional offers
    /// that are passed to `CreateChild` at runtime.
    STATIC_AND_DYNAMIC = 2;
};