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

/// Declares a capability exposed to either a component's containing realm or to
/// the framework. For example, a legacy service exposed by the component at
/// runtime.
type Expose = flexible union {
    1: service ExposeService;
    2: protocol ExposeProtocol;
    3: directory ExposeDirectory;
    4: runner ExposeRunner;
    5: resolver ExposeResolver;
    @available(removed=13)
    6: event_stream ExposeEventStream;
    @available(added=HEAD)
    7: dictionary ExposeDictionary;
    @available(added=HEAD)
    8: config ExposeConfiguration;
};

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

    /// (Required) Name identifying the service, by which it was presented to
    /// this component.
    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)
    6: source_dictionary string:MAX_PATH_LENGTH;

    /// (Required) The destination to which the service is exposed: either the
    /// component's realm or the framework.
    3: target Ref;

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

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// See [`Availability`].
    @available(added=11)
    5: availability Availability;
};

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

    /// (Required) Name identifying the protocol, by which it was presented to
    /// this component.
    2: source_name name;

    /// (Optional) Path in a dictionary offered by `ref` 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 a
    /// dictionary. The name of the top-level dictionary is given by the first path
    /// segment of `source_dictionary`, and `source` is expected to route a
    /// dictionary capability with this name. The rest of the path (possibly empty)
    /// represents the path to a dictionary nested in the top-level dictionary which
    /// is expected to contain `source_name`.
    @available(added=HEAD)
    6: source_dictionary string:MAX_PATH_LENGTH;

    /// (Required) The destination to which the protocol is exposed: either the
    /// component's realm or the framework.
    3: target Ref;

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

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// See [`Availability`].
    @available(added=11)
    5: availability Availability;
};

/// Declares a directory exposed to a component's containing realm, such as a
/// directory exposed by the component or one of its children at runtime.
type ExposeDirectory = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `self` or `child`, or `void`. If set to `void`, then the
    /// target must expose, offer, or use the capability with `OPTIONAL` or
    /// `TRANSITIONAL` availability.
    1: source Ref;

    /// (Required) Name identifying the directory, by which it was presented to
    /// this component.
    2: source_name name;

    /// (Optional) Path in a dictionary offered by `ref` 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 a
    /// dictionary. The name of the top-level dictionary is given by the first path
    /// segment of `source_dictionary`, and `source` is expected to route a
    /// dictionary capability with this name. The rest of the path (possibly empty)
    /// represents the path to a dictionary nested in the top-level dictionary which
    /// is expected to contain `source_name`.
    @available(added=HEAD)
    8: source_dictionary string:MAX_PATH_LENGTH;

    /// (Required) The destination to which the directory is exposed: either the
    /// component's realm or the framework.
    3: target Ref;

    /// (Required) The name by which the capability is being exposed.
    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 expose instead of the
    /// root.
    6: subdir string:MAX_PATH_LENGTH;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// See [`Availability`].
    @available(added=11)
    7: availability Availability;
};

/// Declares a runner exposed to a component's containing realm, such as a
/// runner exposed by the component or one of its children at runtime.
type ExposeRunner = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `self` or `child`.
    1: source Ref;

    /// (Required) The name of the runner, by which it was presented to this
    /// component.
    2: source_name name;

    /// (Optional) Path in a dictionary offered by `ref` 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 a
    /// dictionary. The name of the top-level dictionary is given by the first path
    /// segment of `source_dictionary`, and `source` is expected to route a
    /// dictionary capability with this name. The rest of the path (possibly empty)
    /// represents the path to a dictionary nested in the top-level dictionary which
    /// is expected to contain `source_name`.
    @available(added=HEAD)
    6: source_dictionary string:MAX_PATH_LENGTH;

    /// (Required) The destination to which the runner is exposed: either the
    /// component's realm or the framework.
    3: target Ref;

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

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// See [`Availability`].
    @available(added=11, removed=12)
    5: availability Availability;
};

/// Declares a resolver exposed to a component's containing realm, such as a
/// resolver exposed by the component or one of its children at runtime.
type ExposeResolver = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `self` or `child`.
    1: source Ref;

    /// (Required) The name of the resolver, by which it was presented to this
    /// component.
    2: source_name name;

    /// (Optional) Path in a dictionary offered by `ref` 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 a
    /// dictionary. The name of the top-level dictionary is given by the first path
    /// segment of `source_dictionary`, and `source` is expected to route a
    /// dictionary capability with this name. The rest of the path (possibly empty)
    /// represents the path to a dictionary nested in the top-level dictionary which
    /// is expected to contain `source_name`.
    @available(added=HEAD)
    6: source_dictionary string:MAX_PATH_LENGTH;

    /// (Required) The destination to which the resolver is exposed
    3: target Ref;

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

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// See [`Availability`].
    @available(added=11, removed=12)
    5: availability Availability;
};

/// Declares an event stream exposed to a component's containing realm, such as
/// an event stream exposed by the component or one of its children at runtime.
@available(removed=13)
type ExposeEventStream = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `child`, or `framework`.
    1: source Ref;

    /// (Required) The name of the event stream
    2: source_name name;

    /// (Required) When an event is exposed from framework, the scope is
    /// required and allows one to define the child (or array of children) which
    /// the event is about.
    3: scope vector<Ref>:MAX;

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

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

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// See [`Availability`].
    @available(added=11)
    6: availability Availability;
};

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

    /// (Required) Name identifying the dictionary, by which it was presented to
    /// this component.
    2: source_name name;

    /// (Optional) Path in a dictionary offered by `ref` 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 a
    /// dictionary. The name of the top-level dictionary is given by the first path
    /// segment of `source_dictionary`, and `source` is expected to route a
    /// dictionary capability with this name. The rest of the path (possibly empty)
    /// represents the path to a dictionary nested in the top-level dictionary which
    /// is expected to contain `source_name`.
    @available(added=HEAD)
    6: source_dictionary string:MAX_PATH_LENGTH;

    /// (Required) The destination to which the dictionary is exposed: either the
    /// component's realm or the framework.
    3: target Ref;

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

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// See [`Availability`].
    5: availability Availability;
};

/// Declares a configuration capability exposed to a component's containing realm, such as
/// a capability exposed by the component or one of its children at runtime.
@available(added=HEAD)
type ExposeConfiguration = table {
    /// (Required) The provider of the capability relative to the component
    /// itself. Must be `self` or `child`, or `void`. If set to `void`, then the
    /// target must expose, offer, or use the capability with `OPTIONAL` or
    /// `TRANSITIONAL` availability.
    1: source Ref;

    /// (Required) Name identifying the configuration, by which it was presented to
    /// this component.
    2: source_name name;

    /// (Required) The destination to which the capability is exposed.
    3: target Ref;

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

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// See [`Availability`].
    5: availability Availability;
};