sdk/fidl/fuchsia.sys2/decls/offer_decl.fidl

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

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

/// 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
    /// `realm`, `self`, or `child`.
    1: Ref source;

    /// Path identifying the service being offered.
    ///
    /// Must be an absolute path starting with /.
    2: string:fuchsia.component.MAX_PATH_LENGTH source_path;

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

    /// The path under which the capability is being offered.
    ///
    /// Must be an absolute path starting with /.
    4: string:fuchsia.component.MAX_PATH_LENGTH target_path;
};

/// Declares a legacy 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.
///
/// A legacy service is a service with a single instance, provided by a single
/// FIDL protocol.
table OfferProtocolDecl {
    /// The provider of the capability relative to the component itself. Must be
    /// `realm`, `self`, or `child`.
    1: Ref source;

    /// Path identifying the legacy service being offered.
    2: string:fuchsia.component.MAX_PATH_LENGTH source_path;

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

    /// The path under which the capability is being offered.
    ///
    /// Must be an absolute path starting with /.
    4: string:fuchsia.component.MAX_PATH_LENGTH target_path;

    /// 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
    /// `realm`, `self`, or `child`.
    1: Ref source;

    /// Path identifying the directory being offered.
    2: string:fuchsia.component.MAX_PATH_LENGTH source_path;

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

    /// The path under which the capability is being offered.
    ///
    /// Must be an absolute path starting with /.
    4: string:fuchsia.component.MAX_PATH_LENGTH target_path;

    /// The rights this directory should be offered with, 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 type of storage being offered.
    1: StorageType type;

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

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

/// 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
    /// `realm`, `self`, or `child`.
    1: Ref source;

    /// Name of the runner being offered.
    2: fuchsia.component.runner_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.runner_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
    /// `realm`, `self`, or `child`.
    1: Ref source;

    /// Name of the resolver being offered.
    2: fuchsia.component.resolver_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.resolver_name target_name;
};