// Copyright 2019 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.sys2;

using fuchsia.io2;
using fuchsia.component;
using fuchsia.data;

/// 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.
flexible union OfferDecl {
    1: OfferServiceDecl service;
    2: OfferProtocolDecl protocol;
    3: OfferDirectoryDecl directory;
    4: OfferStorageDecl storage;
    5: OfferRunnerDecl runner;
    6: OfferResolverDecl resolver;
    7: OfferEventDecl event;
};

/// Describes the type of dependency implied by the capability.
enum DependencyType {
    /// A strong dependency which may be required by components that use it.
    STRONG = 1;
    /// A weak dependency specifically used to mark cyclic dependencies of
    /// migrated components. Components that use a weak dependency must support
    /// the dependency being unavailable at arbitrary times.
    WEAK_FOR_MIGRATION = 2;
};

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    /// The source of the storage capability. Must be `parent` or `storage`.
    2: Ref source;

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

    /// The name the storage capability is being offered as
    4: fuchsia.component.name target_name;
};

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

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

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

    /// Name under which the capability is being offered.
    4: fuchsia.component.name target_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.
table OfferResolverDecl {
    /// The provider of the capability relative to the component itself. Must be
    /// `parent`, `self`, or `child`.
    1: Ref source;

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

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

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

/// Declares an event offered by a component.
table OfferEventDecl {
    /// The provider of the event. Must be `parent`.
    1: Ref source;

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

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

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

    /// The mode offered for the event.
    5: EventMode mode;

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