// 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.data;
using fuchsia.io;

/// Declares a capability offered by a component to one of its children, which
/// may have been offered by the component's containing realm, the component
/// itself, or one of its other children.
type Offer = flexible union {
    1: service OfferService;
    2: protocol OfferProtocol;
    3: directory OfferDirectory;
    4: storage OfferStorage;
    5: runner OfferRunner;
    6: resolver OfferResolver;
    @available(removed=14)
    7: event OfferEvent;
    8: event_stream OfferEventStream;
    @available(added=HEAD)
    9: dictionary OfferDictionary;
    @available(added=HEAD)
    10: config OfferConfiguration;
};

/// Describes the type of dependency implied by the capability.
type DependencyType = strict enum {
    /// A strong dependency which may be required by components that use it.
    STRONG = 1;
    /// A weak dependency which is allowed to form a cycle. Components that use
    /// a weak dependency must support the dependency being unavailable at
    /// arbitrary times.
    WEAK = 2;

    @available(deprecated=14, removed=15)
    WEAK_FOR_MIGRATION = 3;
};


/// Type used to create a mapping between 2 names. Used to rename service or component instances
/// in FIDL declarations.
type NameMapping = struct {
    /// Name used in the source instance.
    source_name name;

    /// Name used in the target instance.
    target_name name;
};

/// Describes the expected availability of the capability.
///
/// Some capabilities may not be present on all system configurations. In those
/// cases, the availability will be declared as `OPTIONAL` along the chains of
/// exposes/offers/uses, and the capability would be routed from `void` on
/// system configurations where it does not make sense to route or provide a
/// particular capability (e.g. graphical capabilities on a headless system).
type Availability = strict enum {
    /// The capability must be available. Failure to route the capability is an
    /// error.
    REQUIRED = 1;

    /// Inside a use declaration: the component can function if it fails to
    /// obtain the capability.
    ///
    /// Inside an offer/expose declaration: the capability may not be available
    /// in some system configurations. As a corollary, the target component must
    /// not have a required dependency on the capability.
    OPTIONAL = 2;

    /// If the target of the corresponding offer or expose declaration requires
    /// the capability, then the behavior is equivalent to required. If the
    /// target has an optional dependency on the capability, then the behavior
    /// is equivalent to optional. This is useful for container components that
    /// would like to change their routing availability based on ones inside.
    ///
    /// This value is not allowed inside a use declaration.
    SAME_AS_TARGET = 3;

    /// The source may omit the route completely without even having to route
    /// from `void`.
    ///
    /// [`TRANSITIONAL`] is used for soft transitions that introduce new
    /// capabilities.
    @available(added=9)
    TRANSITIONAL = 4;
};

/// Declares a service offered by a component to one of its children, which may
/// have been offered by the component's containing realm, the component itself,
/// or one of its other children.
///
/// To learn more about services, see:
/// https://fuchsia.dev/fuchsia-src/glossary#service
type OfferService = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `parent`, `self`, `child`, or `void`.
    /// If set to `void`, then the target must offer or use the capability with
    /// `OPTIONAL` or `TRANSITIONAL` availability.
    1: source Ref;

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

    /// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
    /// If this field is absent, `source_name` identifies a capability directly routed
    /// by `source`. If set, `source_name` identifies a capability nested inside this
    /// dictionary.
    @available(added=HEAD)
    8: source_dictionary dictionary_path;

    /// (Required) Reference to the target. Must be `child`, `collection`, or
    /// a dictionary `capability`.
    3: target Ref;

    /// (Required) The name under which the capability is being offered.
    4: target_name name;

    /// (Optional) The list of allowlisted instances to be offered. Instances
    /// of the service not in this list will not be accessible by the target
    /// component. If this is not set that means all instances from the source
    /// service are offered.
    5: source_instance_filter vector<string:MAX_NAME_LENGTH>:MAX;

    /// (Optional) The list of allowlisted instances to be offered, with
    /// renames.
    ///
    /// If this is set and nonempty, the set of instances in the target service
    /// will be restricted to the instances in this list, renaming `source_name`
    /// to `target_name`.
    ///
    /// If it is set and nonempty, `source_instance_filter` will further
    /// restrict the set of instances to those whose `target_name` appears in
    /// that list. There is generally no reason to set both, but we support it
    /// for compatibility.
    6: renamed_instances vector<NameMapping>:MAX;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the target may use or offer the capability with
    /// either `required` or `optional` availability. If set to `optional`, the
    /// target must use or offer the capability with `optional` availability.
    /// The `same_as_target` value causes this offer's availability to match the
    /// availability set in the target.
    7: availability Availability;
};

/// Declares a protocol offered by a component to one of its children,
/// which may have been offered by the component's containing realm, the
/// component itself, or one of its other children.
///
/// To learn more about protocols, see:
/// https://fuchsia.dev/fuchsia-src/glossary#protocol
type OfferProtocol = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `parent`, `self`, `child`, or `void`.
    /// If set to `void`, then the target must offer or use the capability with
    /// `OPTIONAL` or `TRANSITIONAL` availability.
    1: source Ref;

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

    /// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
    /// If this field is absent, `source_name` identifies a capability directly routed
    /// by `source`. If set, `source_name` identifies a capability nested inside this
    /// dictionary.
    @available(added=HEAD)
    7: source_dictionary dictionary_path;

    /// (Required) Reference to the target. Must be `child`, `collection`, or
    /// a dictionary `capability`.
    3: target Ref;

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

    /// (Required) The dependency type this offer represents. A component which
    /// receives a weak offer must support the offered capability being
    /// unavailable at any point.
    5: dependency_type DependencyType;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the target may use or offer the capability with
    /// either `required` or `optional` availability. If set to `optional`, the
    /// target must use or offer the capability with `optional` availability.
    /// The `same_as_target` value causes this offer's availability to match the
    /// availability set in the target.
    6: availability Availability;
};

/// Declares a directory offered by a component to one of its children, which
/// may have been offered by the component's containing realm, the component
/// itself, or one of its other children.
type OfferDirectory = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `parent`, `self`, `child`, or `void`.
    /// If set to `void`, then the target must offer or use the capability with
    /// `OPTIONAL` or `TRANSITIONAL` availability.
    1: source Ref;

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

    /// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
    /// If this field is absent, `source_name` identifies a capability directly routed
    /// by `source`. If set, `source_name` identifies a capability nested inside this
    /// dictionary.
    @available(added=HEAD)
    9: source_dictionary dictionary_path;

    /// (Required) Reference to the target. Must be `child`, `collection`, or
    /// a dictionary `capability`.
    3: target Ref;

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

    /// (Optional) The maximum rights that can be set by a component using this
    /// directory. IF unset, the rights are inherited from `source`.
    5: rights fuchsia.io.Rights;

    /// (Optional) The subdirectory of this directory to offer instead of the
    /// root. Optional.
    6: subdir string:MAX_PATH_LENGTH;

    /// (Required) The dependency type this offer represents. A component which
    /// receives a weak offer must support the offered capability being
    /// unavailable at any point.
    7: dependency_type DependencyType;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the target may use or offer the capability with
    /// either `required` or `optional` availability. If set to `optional`, the
    /// target must use or offer the capability with `optional` availability.
    /// The `same_as_target` value causes this offer's availability to match the
    /// availability set in the target.
    8: availability Availability;
};

/// Declares a storage capability offered by a component to one of its children,
/// such as meta storage offered by the component's containing realm or cache
/// storage offered by the component itself.
type OfferStorage = table {
    /// (Required) The name of the storage capability being offered
    1: source_name name;

    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `parent`, `self`, `child`, or `void`.
    /// If set to `void`, then the target must offer or use the capability with
    /// `OPTIONAL` or `TRANSITIONAL` availability.
    2: source Ref;

    /// (Required) Reference to the target. Must be `child`, `collection`, or
    /// a dictionary `capability`.
    3: target Ref;

    /// (Required) The name the storage capability is being offered as
    4: target_name name;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the target may use or offer the capability with
    /// either `required` or `optional` availability. If set to `optional`, the
    /// target must use or offer the capability with `optional` availability.
    /// The `same_as_target` value causes this offer's availability to match the
    /// availability set in the target.
    5: availability Availability;
};

/// Declares a runner offered by a component to one of its children, which may
/// have been offered by the component's containing realm, the component itself,
/// or one of its other children.
type OfferRunner = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `parent`, `self`, `child`, or `void`.
    /// If set to `void`, then the target must offer or use the capability with
    /// `OPTIONAL` or `TRANSITIONAL` availability.
    1: source Ref;

    /// (Required) Name of the runner being offered.
    2: source_name name;

    /// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
    /// If this field is absent, `source_name` identifies a capability directly routed
    /// by `source`. If set, `source_name` identifies a capability nested inside this
    /// dictionary.
    @available(added=HEAD)
    5: source_dictionary dictionary_path;

    /// (Required) Reference to the target. Must be `child`, `collection`, or
    /// a dictionary `capability`.
    3: target Ref;

    /// (Required) Name under which the capability is being offered.
    4: target_name name;
};

/// Declares a resolver capability offered by a component to one of its children, which
/// may have been offered by the component's containing realm, the component itself,
/// or one of its other children.
type OfferResolver = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `parent`, `self`, `child`, or `void`.
    /// If set to `void`, then the target must offer or use the capability with
    /// `OPTIONAL` or `TRANSITIONAL` availability.
    1: source Ref;

    /// (Required) Name of the resolver being offered.
    2: source_name name;

    /// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
    /// If this field is absent, `source_name` identifies a capability directly routed
    /// by `source`. If set, `source_name` identifies a capability nested inside this
    /// dictionary.
    @available(added=HEAD)
    5: source_dictionary dictionary_path;

    /// (Required) Reference to the target. Must be `child`, `collection`, or
    /// a dictionary `capability`.
    3: target Ref;

    /// (Required) Name under which the capability is being offered.
    4: target_name name;
};

/// Declares an event offered by a component.
@available(removed=14)
type OfferEvent = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `parent` or `void`. If set to `void`, then the target
    /// must offer or use the capability with `optional` availability.
    1: source Ref;

    /// (Required) Name of the event being offered.
    2: source_name name;

    /// (Required) Reference to the target. Must be `child`, `collection`, or
    /// a dictionary `capability`.
    3: target Ref;

    /// (Required) Name under which the event is being offered.
    4: target_name name;

    /// (Optional) Filter for the event. The structure of the filter depends on
    /// the event type. May be absent for some events. (TODO: which ones?)
    5: filter fuchsia.data.Dictionary;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the target may use or offer the capability with
    /// either `required` or `optional` availability. If set to `optional`, the
    /// target must use or offer the capability with `optional` availability.
    /// The `same_as_target` value causes this offer's availability to match the
    /// availability set in the target.
    6: availability Availability;
};

/// Declares an event stream offered by a component.
type OfferEventStream = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `parent`, `framework`, `child`, or `void`. If set to
    /// `void`, then the target must offer or use the capability with `OPTIONAL`
    /// or `TRANSITIONAL` availability.
    1: source Ref;

    /// (Required) Name of the event being offered.
    2: source_name name;

    /// (Optional) When an event is offered from framework, the scope is
    /// required and allows one to define the child (or array of children) which
    /// the event is about. When the event is offered from parent, the scope can
    /// be used to downscope the event to a certain child scope, otherwise the
    /// event will carry the scope coming from the parent.
    3: scope vector<Ref>:MAX;

    /// (Required) The destination to which the event stream is offered.
    4: target Ref;

    /// (Required) Name under which the event stream is being offered.
    5: target_name name;

    /// (Optional) Filter for the event stream. Only present for DirectoryReady
    /// events and CapabilityRequested events
    @available(removed=14)
    6: filter fuchsia.data.Dictionary;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the target may use or offer the capability with
    /// either `required` or `optional` availability. If set to `optional`, the
    /// target must use or offer the capability with `optional` availability.
    /// The `same_as_target` value causes this offer's availability to match the
    /// availability set in the target.
    7: availability Availability;
};

/// Declares a dictionary offered by a component to one of its children,
/// which may have been offered by the component's containing realm, the
/// component itself, or one of its other children.
///
/// To learn more about dictionaries, see:
/// https://fuchsia.dev/fuchsia-src/glossary#dictionary
@available(added=HEAD)
type OfferDictionary = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `parent`, `self`, `child`, or `void`.
    /// If set to `void`, then the target must offer or use the capability with
    /// `OPTIONAL` or `TRANSITIONAL` availability.
    1: source Ref;

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

    /// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
    /// If this field is absent, `source_name` identifies a capability directly routed
    /// by `source`. If set, `source_name` identifies a capability nested inside this
    /// dictionary.
    @available(added=HEAD)
    7: source_dictionary dictionary_path;

    /// (Required) Reference to the target. Must be `child`, `collection`, or
    /// a dictionary `capability`.
    3: target Ref;

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

    /// (Required) The dependency type this offer represents. A component which
    /// receives a weak offer must support the offered capability being
    /// unavailable at any point.
    5: dependency_type DependencyType;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the target may use or offer the capability with
    /// either `required` or `optional` availability. If set to `optional`, the
    /// target must use or offer the capability with `optional` availability.
    /// The `same_as_target` value causes this offer's availability to match the
    /// availability set in the target.
    6: availability Availability;
};

/// Declares a configuration capability offered by a component to one of its children,
/// which may have been offered by the component's containing realm, the
/// component itself, or one of its other children.
@available(added=HEAD)
type OfferConfiguration = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `parent`, `self`, `child`, or `void`.
    /// If set to `void`, then the target must offer or use the capability with
    /// `OPTIONAL` or `TRANSITIONAL` availability.
    1: source Ref;

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

    /// (Required) Reference to the target. Must be `child`, or `collection`.
    3: target Ref;

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

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the target may use or offer the capability with
    /// either `required` or `optional` availability. If set to `optional`, the
    /// target must use or offer the capability with `optional` availability.
    /// The `same_as_target` value causes this offer's availability to match the
    /// availability set in the target.
    5: availability Availability;
};