// 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.component;
using fuchsia.io;
using zx;

/// The maximum number of event types that a receiver can listen to.
/// This capacity should match the actual number of event types.
const uint64 MAX_NUM_EVENTS_RECEIVED = 8;

/// The maximum string length of a capability ID.
/// This value is currently set arbitrarily.
const uint64 MAX_CAPABILITY_ID_LENGTH = 50;

/// The maximum string length of an error description.
const uint64 MAX_ERROR_DESCRIPTION_LENGTH = 100;

/// These EventTypes are used for the EventStream protocol.
/// They are FIDL versions of the EventType enum in hooks.rs and have
/// the same meaning.
enum EventType {
    /// A capability exposed to the framework by a component is available.
    CAPABILITY_READY = 1;

    /// A capability is being requested by a component and its routing
    /// has also been determined.
    /// The event propagation system is used to supply the capability being requested.
    CAPABILITY_ROUTED = 2;

    /// An instance was destroyed successfully. The instance is stopped and no longer
    /// exists in the parent's realm.
    DESTROYED = 3;

    /// A component instance was discovered. This is the first stage in the lifecycle
    /// of components. Dispatched for dynamic children when they're created, for static
    /// children when their parent is resolved, and for the root when the component manager
    /// starts.
    DISCOVERED = 4;

    /// Destruction of an instance has begun. The instance may/may not be stopped by this point.
    /// The instance still exists in the parent's realm but will soon be removed.
    /// TODO(fxb/39417): Ensure the instance is stopped before this event.
    MARKED_FOR_DESTRUCTION = 5;

    /// An instance's declaration was resolved successfully for the first time.
    RESOLVED = 6;

    /// This instance has started, according to component manager. However, if this is an
    /// executable component, the runner has further work to do to launch the component.
    STARTED = 7;

    /// An instance was stopped successfully.
    /// This event must occur before Destroyed.
    STOPPED = 8;

    /// If requested, this event is dispatched on subscription and indicates
    /// that the instance has already started and is still running.
    RUNNING = 9;
};

/// Describes the source of a routed capability.
flexible union CapabilitySource {
    /// The capability is provided by the framework and may be
    /// scoped down to a component.
    1: FrameworkCapability framework;

    /// The capability is provided by another component.
    2: ComponentCapability component;
};

/// Describes a capability provided by the framework
table FrameworkCapability {
    /// The moniker of the instance that this capability is scoped to.
    1: string:fuchsia.component.MAX_MONIKER_LENGTH scope_moniker;
};

/// Describes a capability provided by a component
table ComponentCapability {
    /// The moniker of the instance that is providing this capability.
    1: string:fuchsia.component.MAX_MONIKER_LENGTH source_moniker;
};

/// Describes the result of a state transition.
flexible union EventResult {
    /// The payload of the event if the state transition described by the event
    /// succeeds.
    1: EventPayload payload;

    /// The error that caused the state transition described by the event to
    /// fail.
    2: EventError error;
};

/// Corresponds to an error that occurred during a state transition.
table EventError {
    /// A string describing the error that occurred.
    /// TODO(fxb/49792): We should be sending structured errors, and not simply strings.
    /// This is a placeholder pending further internal component manager refactors.
    1: string:MAX_ERROR_DESCRIPTION_LENGTH description;

    /// The error payload of the event if any.
    2: EventErrorPayload error_payload;
};

/// Encapsulates additional data for some event errors.
flexible union EventErrorPayload {
    /// Payload for CapabilityReady events
    1: CapabilityReadyError capability_ready;

    /// Payload for CapabilityRouted events
    2: CapabilityRoutedError capability_routed;
};

/// Error payload for CapabilityReady events
table CapabilityReadyError {
    /// The path of the capability.
    1: string:fuchsia.component.MAX_PATH_LENGTH path;
};

/// Error payload for CapabilityRouted events
table CapabilityRoutedError {
    /// Identifier of capability being requested.
    /// For a path-based capability, this is the path.
    /// For a runner capability, this is the name.
    1: string:MAX_CAPABILITY_ID_LENGTH capability_id;
};

/// Encapsulates additional data/protocols for some event types.
flexible union EventPayload {
    /// Payload for CapabilityReady events
    1: CapabilityReadyPayload capability_ready;

    /// Payload for CapabilityRouted events
    2: CapabilityRoutedPayload capability_routed;
};

/// Payload for CapabilityReady events
table CapabilityReadyPayload {
    /// The path of the capability.
    1: string:fuchsia.component.MAX_PATH_LENGTH path;

    /// Channel to the node exposed by the event source at `path`.
    2: fuchsia.io.Node node;
};

/// Payload for CapabilityRouted events
table CapabilityRoutedPayload {
    /// Allows setting a capability provider for
    /// CapabilityRouted events
    /// This will not be available with an async event.
    1: RoutingProtocol routing_protocol;

    /// Identifier of capability being requested.
    /// For a path-based capability, this is the path.
    /// For a runner capability, this is the name.
    2: string:MAX_CAPABILITY_ID_LENGTH capability_id;

    /// Source of the capability that needs to be routed.
    3: CapabilitySource source;
};

/// Contains all information about a single event
table Event {
    /// Event type corresponding to the event
    1: EventType event_type;

    /// Moniker of instance corresponding to the event
    2: string:fuchsia.component.MAX_MONIKER_LENGTH target_moniker;

    /// Handler for resuming from event
    /// This will be absent if this is an async event.
    3: Handler handler;

    /// Optional payload for some event types
    4: EventResult event_result;

    /// Time when the event occurred.
    5: zx.time timestamp;
};

/// Subscribe to events in component manager.
[Discoverable, FragileBase]
protocol EventSource {
    /// Subscribes to the events of the provided EventTypes.
    ///
    /// Returns a EventStreamSync which can be used
    /// to expect the registered types.
    ///
    /// Errors:
    /// - `RESOURCE_UNAVAILABLE` when the component hasn't been granted the capability to subscribe
    ///   to some event in the requested `events`.
    Subscribe(vector<fuchsia.component.event_name>:MAX_NUM_EVENTS_RECEIVED events,
              EventStream stream)
        -> () error fuchsia.component.Error;
};

/// Subscribe to events in component manager.
[Discoverable]
protocol BlockingEventSource {
    compose EventSource;

    /// Resume the execution of components within the realm using a scoped
    /// BlockingEventSource.  This method is idempotent.
    StartComponentTree() -> ();
};

/// Listener for events on the component hierarchy. The server won't wait for the client
/// to handle the request before sending more events.
protocol EventStream {
    OnEvent(Event event);
};

/// Every Event supports this basic handler to allow resumption.
protocol Handler {
    /// Resumes/unblocks from an event.
    Resume() -> ();
};

/// Allows injecting capabilities over FIDL.
/// Used by RouteFrameworkCapability and RouteBuiltinCapability
protocol RoutingProtocol {
    /// Set a CapabilityProvider. Invoking this method will replace
    /// any existing provider.
    ///
    /// When a component attempts to connect to a capability,
    /// this method can be used to mock/inject that capability.
    SetProvider(CapabilityProvider client_end) -> ();

    /// Replace the existing provider with the given client_end and
    /// open the existing provider with given server end.
    ///
    /// This method is used to interpose between a client and service:
    /// Client <---> Interposer <---> Server
    ///
    /// Opening the existing provider sets up Interposer <---> Server
    /// Replacing the existing provider sets up Client <---> Interposer
    ReplaceAndOpen(CapabilityProvider client_end, handle<channel> server_end) -> ();
};

/// A FIDL-based version of a CapabilityProvider
protocol CapabilityProvider {
    /// Called to bind a server end of a channel to the provided framework capability.
    /// TODO(xbhatnag): provide all arguments (flags, mode, path) to this method.
    Open(handle<channel> server_end) -> ();
};