// 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 used by a component, which was offered to it.
type Use = flexible union {
    1: service UseService;
    2: protocol UseProtocol;
    3: directory UseDirectory;
    4: storage UseStorage;
    @available(removed=14)
    5: event UseEvent;
    @available(removed=14)
    6: event_stream_deprecated UseEventStreamDeprecated;
    7: event_stream UseEventStream;
    @available(added=HEAD)
    8: runner UseRunner;
    @available(added=20)
    9: config UseConfiguration;
};

/// Declares a service used by a component, which was offered to it.
///
/// To learn more about services, see:
/// https://fuchsia.dev/fuchsia-src/glossary#service
type UseService = table {
    /// (Required) The provider of the protocol relative to the component
    /// itself. Must be `parent`, `framework`, `self`, or `child`.
    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 dictionary_path;

    /// (Required) The path where the capability should be installed in the
    /// component's namespace.
    ///
    /// Must be an absolute path starting with /.
    3: target_path string:MAX_PATH_LENGTH;

    /// (Required) The dependency type this use represents.
    ///
    /// A component which offers a capability to a child from itself and uses a
    /// capability from the same child, must mark the dependency as `weak`.  A
    /// `weak` dependency implies that the capability may become unavailable at
    /// any point. Taking a strong dependency on a child's capability will
    /// cause this the child to shut down before its parent. When using a weak
    /// dependency, the parent shuts down before the child.
    4: dependency_type DependencyType;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the component is likely to malfunction if this
    /// capability is not provided. If set to `optional`, the component can
    /// handle the capability's absence.
    5: availability Availability;
};

/// Declares a protocol used by a component, which was offered to it.
///
/// A protocol is a service with a single instance, provided by a single FIDL
/// protocol.
type UseProtocol = table {
    /// (Required) The provider of the protocol relative to the component
    /// itself. Must be `parent`, `framework`, `debug`, `capability` or `child`.
    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 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 dictionary_path;

    /// (Required) The path where the capability should be installed in the component's
    /// namespace.
    ///
    /// Must be an absolute path starting with /.
    3: target_path string:MAX_PATH_LENGTH;

    /// (Required) The dependency type this use represents.
    ///
    /// A component which offers a capability to a child from itself and uses a
    /// capability from the same child, must mark the dependency as `weak`.  A
    /// `weak` dependency implies that the capability may become unavailable at
    /// any point. Taking a strong dependency on a child's capability will
    /// cause this the child to shut down before its parent. When using a weak
    /// dependency, the parent shuts down before the child.
    4: dependency_type DependencyType;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the component is likely to malfunction if this
    /// capability is not provided. If set to `optional`, the component can
    /// handle the capability's absence.
    5: availability Availability;
};

/// Declares a directory used by a component, which was offered to it.
type UseDirectory = table {
    /// (Required) The provider of the directory relative to the component
    /// itself. Must be `parent`, `framework`,  or `child`.
    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 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) The path where the capability should be installed in the
    /// component's namespace.
    ///
    /// Must be an absolute path starting with /.
    3: target_path string:MAX_PATH_LENGTH;

    /// (Required) The rights required by the component to use this directory.
    4: rights fuchsia.io.Rights;

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

    /// (Required) The dependency type this use represents.
    ///
    /// A component which offers a capability to a child from itself and uses a
    /// capability from the same child, must mark the dependency as `weak`.  A
    /// `weak` dependency implies that the capability may become unavailable at
    /// any point. Taking a strong dependency on a child's capability will
    /// cause this the child to shut down before its parent. When using a weak
    /// dependency, the parent shuts down before the child.
    6: dependency_type DependencyType;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the component is likely to malfunction if this
    /// capability is not provided. If set to `optional`, the component can
    /// handle the capability's absence.
    7: availability Availability;
};

/// Declares storage used by a component, which was offered to it.
type UseStorage = table {
    /// (Required) Name identifying the storage, by which it was presented to
    /// this component.
    1: source_name name;

    /// (Required) The path where the capability should be installed in the
    /// component's namespace.
    ///
    /// Must be an absolute path starting with /.
    2: target_path string:MAX_PATH_LENGTH;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the component is likely to malfunction if this
    /// capability is not provided. If set to `optional`, the component can
    /// handle the capability's absence.
    3: availability Availability;
};

/// Declares an event used by a component, which was offered to it.
@available(removed=14)
type UseEvent = table {
    /// (Required) The provider of the event. Must be `realm` or `framework`. If
    /// the availability is set to `optional`, then this must be set to
    /// `parent`.
    1: source Ref;

    /// (Required) Name identifying the event which was presented to this
    /// component.
    2: source_name name;

    /// (Required) The name which the component will use to refer to this event.
    3: 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?)
    4: filter fuchsia.data.Dictionary;

    /// (Required) The dependency type this use represents.
    ///
    /// A component which offers a capability to a child from itself and uses a
    /// capability from the same child, must mark the dependency as `weak`.  A
    /// `weak` dependency implies that the capability may become unavailable at
    /// any point. Taking a strong dependency on a child's capability will
    /// cause this the child to shut down before its parent. When using a weak
    /// dependency, the parent shuts down before the child.
    5: dependency_type DependencyType;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the component is likely to malfunction if this
    /// capability is not provided. If set to `optional`, the component can
    /// handle the capability's absence.
    6: availability Availability;
};

/// Declares a static EventStream used by a component.
@available(removed=14)
type UseEventStreamDeprecated = table {
    /// (Required) The name of the event stream.
    1: name name;

    /// (Required) The set of events to which this EventStream is subscribed.
    /// Note: This vector must be non-empty.
    2: subscriptions vector<EventSubscription>:MAX_NUM_EVENT_STREAM_SUBSCRIPTIONS;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the component is likely to malfunction if this
    /// capability is not provided. If set to `optional`, the component can
    /// handle the capability's absence.
    3: availability Availability;
};

/// Declares an EventStream used by a component.
type UseEventStream = table {
    /// (Required) The names of the event streams.
    1: source_name name;

    /// (Required) The provider of the event. Must be `parent`, `framework`, or `child`.
    2: source Ref;

    /// (Optional) When an event is used from framework, the scope is required
    /// to specify the child (or array of children) which the event will be
    /// about. When the event is used 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 path where the capability should be installed in the
    /// component's namespace. Must be an absolute path starting with /.
    4: target_path name;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the component is likely to malfunction if this
    /// capability is not provided. If set to `optional`, the component can
    /// handle the capability's absence.
    5: availability Availability;

    /// (Optional) Filter for the event stream. The structure of the filter
    /// depends on the event stream type. Only supported for the
    /// `CapabilityRequested` event type.
    @available(added=9)
    6: filter fuchsia.data.Dictionary;
};

/// Declares runner used by a component.
@available(added=HEAD)
type UseRunner = table {
    /// (Required) The provider of the runner relative to the component.
    /// Must be `parent`, `child`, `framework`, or `environment`.
    1: source Ref;

    /// (Required) Name identifying the runner, 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)
    3: source_dictionary dictionary_path;
};

@available(added=20)
type UseConfiguration = table {
    /// (Required) The provider of the configuration relative to the component
    /// itself. Must be `parent`, `self`, `child`.
    1: source Ref;

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

    /// (Required) The name that the component sees for this configuration.
    /// This must match a key in the 'config' schema for this component. The
    /// matching config field's type must match this configuration type.
    3: target_name name;

    /// (Optional, defaults to `REQUIRED`) The availability of this capability.
    /// If set to `required`, the component is likely to malfunction if this
    /// capability is not provided. If set to `optional`, the component can
    /// handle the capability's absence.
    4: availability Availability;

    /// (Required) The type of this config value. If `target_name` matches a
    /// key in the `config` schema, then this type must match that type.
    5: type ConfigType;

    /// (Optional): If this is set, this is the value that will be provided via routing
    /// if the capability is successfully routed from void.
    6: default ConfigValue;
};