// 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 defined by this component.
type Capability = flexible union {
    1: service Service;
    2: protocol Protocol;
    3: directory Directory;
    4: storage Storage;
    5: runner Runner;
    6: resolver Resolver;
    @available(removed=14)
    7: event Event;
    @available(added=8)
    8: event_stream EventStream;
    @available(added=HEAD)
    9: dictionary Dictionary;
    @available(added=20)
    10: config Configuration;
};

/// Declares a service capability backed by this component.
///
/// To learn more about services, see:
/// https://fuchsia.dev/fuchsia-src/glossary#service
type Service = table {
    /// (Required) The name of this service.
    1: name name;

    /// (Optional) The path to the service in the component's outgoing
    /// directory.
    ///
    /// Not set for built-in capabilities.
    2: source_path string:MAX_PATH_LENGTH;
};

/// Declares a protocol capability backed by this component.
///
/// To learn more about protocols, see:
/// https://fuchsia.dev/fuchsia-src/glossary#protocol
type Protocol = table {
    /// (Required) The name of this protocol.
    1: name name;

    /// (Optional) The path to the protocol in the component's outgoing
    /// directory.
    ///
    /// Not set for built-in capabilities.
    2: source_path string:MAX_PATH_LENGTH;

    /// (Optional, defaults to `EAGER`) specifies when the framework will open
    /// the protocol from this component's outgoing directory when someone
    /// requests the capability. See details on `DeliveryType`.
    @available(added=HEAD)
    3: delivery DeliveryType;
};

/// Declares a directory capability backed by this component.
///
/// To learn more about directories, see:
/// https://fuchsia.dev/fuchsia-src/glossary#directory
type Directory = table {
    /// (Required) The name of this directory.
    1: name name;

    /// (Optional) The path to the directory in the component's outgoing
    /// directory.
    ///
    /// Not set for built-in capabilities.
    2: source_path string:MAX_PATH_LENGTH;

    /// (Required) The maximum rights that can be set by a component using this
    /// directory.
    3: rights fuchsia.io.Rights;
};

/// Declares a storage capability backed by a directory from which data, cache,
/// or meta storage can be offered.
type Storage = table {
    /// (Required) The name of this storage
    1: name name;

    /// (Required) The provider of the backing directory capability relative to
    /// the component itself. Must be `parent`, `self`, or `child`.
    2: source Ref;

    /// (Required) The name of the directory capability from `source` that backs
    /// the storage.
    3: backing_dir name;

    /// (Optional) The subdirectory of the source directory that will back the
    /// storage
    4: subdir string:MAX_PATH_LENGTH;

    /// (Required) This enum determines how to key a component's isolated
    /// storage directory. Each option corresponds to a different key'ing
    /// strategy.
    5: storage_id StorageId;
};

/// Declares which identifier to use to key a component's isolated storage
/// directory.
type StorageId = strict enum {
    /// Isolated storage directories are keyed using a component's instance ID
    /// specified in the component ID index. Components which are not listed in
    /// the index cannot use or open this storage capability.
    STATIC_INSTANCE_ID = 1;
    /// Isolated storage directories are keyed using a component's instance ID
    /// if one is specified in the component ID index. Otherwise, a component's
    /// moniker from the storage capability is used to key its isolated
    /// storage directory.
    STATIC_INSTANCE_ID_OR_MONIKER = 2;
};

/// Declares a runner capability backed by a service.
type Runner = table {
    /// (Required) The name of this runner.
    ///
    /// Must unique among runners declared in the same `ComponentDecl`.
    1: name name;

    /// (Optional) The path to the runner protocol in the component's outgoing
    /// directory.
    ///
    /// Not set for built-in capabilities.
    2: source_path string:MAX_PATH_LENGTH;
};

/// Declares a resolver which is responsible for resolving component URLs to
/// actual components. See `fuchsia.component.resolution.Resolver` for the
/// protocol resolvers are expected to implement.
type Resolver = table {
    /// (Required) The name of this resolver.
    ///
    /// Must be unique among resolvers declared in the same `ComponentDecl`.
    1: name name;

    /// (Optional) The path to the resolver protocol in the component's outgoing
    /// directory
    ///
    /// Not set for built-in capabilities.
    2: source_path string:MAX_PATH_LENGTH;
};

/// Declares an event capability which component instances may subscribe to.
/// This type cannot be used in `fuchsia.component.decl.Component`. It is only
/// used for the framework's built-in capabilities declared in
/// `internal.Config`.
@available(removed=14)
type Event = table {
    /// (Required) The name of this event.
    ///
    /// Must be unique among built-in capabilities.
    1: name name;
};

/// Declares an event_stream capability
///
/// This type cannot be used in `fuchsia.component.decl.Component`. It is only
/// used for the framework's built-in capabilities declared in
/// `internal.Config`.
@available(added=8)
type EventStream = table {
    /// (Required) The name of this event stream.
    ///
    /// Must be unique among built-in capabilities.
    1: name name;
};

/// Declares a dictionary capability.
// TODO(https://fxbug.dev/300503731): Add doc link
@available(added=HEAD)
type Dictionary = table {
    /// (Required) The name of this dictionary.
    ///
    /// Must be unique among built-in capabilities.
    1: name name;

    /// (Optional) Source of the contents used to initialize the dictionary.
    /// Must be `parent`, `self`, or `child`.
    2: source Ref;

    /// (Optional) Path in a dictionary provided by `ref` which contains the contents
    /// that will be used to initialize the dictionary.
    ///
    /// This must be set iff `source` is set.
    3: source_dictionary dictionary_path;
};

/// Declares a configuration capability.
///
/// To learn more about configuration capabilities, see:
/// https://fuchsia.dev/fuchsia-src/glossary#configuration-capability
/// or:
/// https://fuchsia.dev/fuchsia-src/docs/concepts/components/v2/capabilities/configuration
@available(added=20)
type Configuration = table {
    /// (Required) The name of this configuration
    1: name name;

    /// (Required) The value of this Configuration.
    2: value ConfigValue;
};