// 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;
    7: event OfferEvent;
    8: event_stream OfferEventStream;
};

/// 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;
    /// A weak dependency specifically used to mark cyclic dependencies from
    /// migrated v1 components.
    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.
type Availability = strict enum {
    REQUIRED = 1;
    OPTIONAL = 2;
    SAME_AS_TARGET = 3;
};

/// 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 {
    /// 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` availability.
    1: source Ref;

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

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

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

    /// The list of allow listed 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;

    /// List of renamed service instances.
    6: renamed_instances vector<NameMapping>:MAX;

    /// 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 {
    /// The provider of the capability relative to the component itself. Must be
    /// `parent`, `self`, `child`, `framework`, or `void`. If set to `void`,
    /// then the target must offer or use the capability with `optional`
    /// availability.
    1: source Ref;

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

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

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

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

    /// 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 {
    /// The provider of the capability relative to the component itself. Must be
    /// `parent`, `self`, `child`, `framework`, or `void`. If set to `void`,
    /// then the target must offer or use the capability with `optional`
    /// availability.
    1: source Ref;

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

    /// Reference to the target of the capability. Must be `child` or
    /// `collection`.
    3: target Ref;

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

    /// The maximum rights that can be set by a component using this directory,
    /// required iff `source == self`.
    5: rights fuchsia.io.Rights;

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

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

    /// 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 {
    /// The name of the storage capability being offered
    1: source_name name;

    /// The provider of the capability relative to the component itself. Must be
    /// `parent`, `storage`, or `void`. If set to `void`, then the target must
    /// offer or use the capability with `optional` availability.
    2: source Ref;

    /// Reference to the target of the capability. Must be `child` or
    /// `collection`.
    3: target Ref;

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

    /// 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 {
    /// The provider of the capability relative to the component itself. Must be
    /// `parent`, `self`, or `child`.
    1: source Ref;

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

    /// Reference to the target of the capability. Must be `child` or
    /// `collection`.
    3: target Ref;

    /// 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 {
    /// The provider of the capability relative to the component itself. Must be
    /// `parent`, `self`, or `child`.
    1: source Ref;

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

    /// Reference to the target of the capability. Must be `child` or
    /// `collection`.
    3: target Ref;

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

/// Declares an event offered by a component.
type OfferEvent = table {
    /// 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;

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

    /// Reference to the target of the event. Must be `child` or `collection`.
    3: target Ref;

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

    /// Filter for the event. The structure of the filter depends on the event type. May be absent
    /// for some events.
    5: filter fuchsia.data.Dictionary;

    /// 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 {
    /// 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` availability.
    1: source Ref;

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

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

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

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

    /// Filter for the event stream. Only present for DirectoryReady events
    /// and CapabilityRequested events
    6: filter fuchsia.data.Dictionary;

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