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

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

/// Describes the consumption mode of an event.
enum EventMode {
    /// The event source dispatches the event and doesn't wait for the listener
    /// to handle it.
    ASYNC = 0;

    /// The event source awaits the listener to notify it that it's done handling the event.
    SYNC = 1;
};

/// 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 provided by this component has been requested. The event
    /// payload carries the request channel.
    CAPABILITY_REQUESTED = 2;

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

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

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

    /// 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(fxbug.dev/39417): Ensure the instance is stopped before this event.
    MARKED_FOR_DESTRUCTION = 6;

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

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

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

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

/// Describes the source of a routed capability.
flexible union CapabilitySource {
    /// The capability is provided by another component.
    1: ComponentCapability component;

    /// The capability is provided by the framework and is scoped to a
    /// realm.
    2: FrameworkCapability framework;

    /// The capability is provided by realm above the root, which is component manager itself.
    3: AboveRootCapability above_root;
};

/// Describes a capability provided by the framework, scoped to a realm.
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 a capability provided by component manager at the realm above the
/// root.
table AboveRootCapability {
};

/// Describes the result of a state transition.
flexible resource 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(fxbug.dev/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 CapabilityRequested events
    2.: CapabilityRequestedError capability_requested;

    /// Payload for CapabilityRouted events
    3: CapabilityRoutedError capability_routed;

    /// Payload for Destroyed events.
    4: DestroyedError destroyed;

    /// Payload for Discovered events.
    5: DiscoveredError discovered;

    /// Payload for MarkedForDestruction events.
    6: MarkedForDestructionError marked_for_destruction;

    /// Payload for Resolved events
    7: ResolvedError resolved;

    /// Payload for Running events
    8: RunningError running;

    /// Payload for Started events
    9: StartedError started;

    /// Payload for Stopped events
    10: StoppedError stopped;
};

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

/// Error payload for CapabilityRequested events
table CapabilityRequestedError {
    /// The name of the capability being requested.
    1: fuchsia.component.name name;
};

/// Error payload for CapabilityRouted events
table CapabilityRoutedError {
    /// Name of the capability being requested.
    1: fuchsia.component.name name;
};

/// Error payload for Discovered events.
table DiscoveredError {
};

/// Error payload for Destroyed events.
table DestroyedError {
};

/// Error payload for Resolved events.
table ResolvedError {
};

/// Error payload for Running events.
table RunningError {
    /// Time when the component started.
    1: zx.time started_timestamp;
};

/// Error payload for MarkedForDestruction events.
table MarkedForDestructionError {
};

/// Error payload for Started events.
table StartedError {
};

/// Error payload for Stopped events.
table StoppedError {
};

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

    /// Payload for CapabilityRequested events
    2: CapabilityRequestedPayload capability_requested;

    /// Payload for CapabilityRouted events
    3: CapabilityRoutedPayload capability_routed;

    /// Payload for Destroyed events.
    4: DestroyedPayload destroyed;

    /// Payload for Discovered events.
    5: DiscoveredPayload discovered;

    /// Payload for MarkedForDestruction events.
    6: MarkedForDestructionPayload marked_for_destruction;

    /// Payload for Resolved events
    7: ResolvedPayload resolved;

    /// Payload for Running events
    8: RunningPayload running;

    /// Payload for Started events
    9: StartedPayload started;

    /// Payload for Stopped events
    10: StoppedPayload stopped;
};

/// Payload for CapabilityReady events
resource table CapabilityReadyPayload {
    /// The name of the capability.
    1: fuchsia.component.name name;

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

/// Payload for CapabilityRequested events
resource table CapabilityRequestedPayload {
    /// The name of the capability.
    1: fuchsia.component.name name;

    /// A handle to the server end of the channel to host
    /// capability.
    2: zx.handle:CHANNEL capability;
};

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

    /// Name of capability being requested.
    2: fuchsia.component.name name;

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

/// Payload for Destroyed events.
table DestroyedPayload {
};

/// Payload for Discovered events.
table DiscoveredPayload {
};

/// Payload for MarkedForDestruction events.
table MarkedForDestructionPayload {
};

/// Payload for Resolved events.
table ResolvedPayload {
};

/// Payload for Running events.
table RunningPayload {
    /// Time when the component started.
    1: zx.time started_timestamp;
};

/// Payload for Started events.
table StartedPayload {
};

/// Payload for Stopped events.
table StoppedPayload {
    /// The epitaph set on the fuchsia.component.runner/ComponentController
    /// protocol channel. This is the exit status of the component. The
    /// possible status values and their meaning are described in the definition
    /// of the ComponentController protocol.
    1: zx.status status;
};

/// A head providing metadata about a target component instance.
table EventHeader {
    /// Event type corresponding to the event
    1: EventType event_type;

    /// Relative moniker identifying the component instance. Relative to the scope of the event.
    2: string:fuchsia.component.MAX_MONIKER_LENGTH moniker;

    /// URL used to resolve the component.
    3: fuchsia.url.Url component_url;

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

/// Contains all information about a single event
resource table Event {
    /// Information about the component for which this event was generated.
    1: EventHeader header;

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

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

/// Indicates the event name to subscribe to with a given event mode.
table EventSubscription {
    // The event names to subscribe to.
    1: fuchsia.component.name event_name;
    /// The event mode with which to subscribe to the event names above.
    2: EventMode mode;
};

/// Subscribe to events in component manager.
[Discoverable]
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<EventSubscription>:fuchsia.component.MAX_SUBSCRIPTION_REQUESTS events,
              EventStream stream)
        -> () error fuchsia.component.Error;

    /// Returns the server end of a static EventStream of the provided path if it exists.
    /// If this stream is discarded afterward then all `sync` events on the channel will be
    /// immediately canceled.
    /// Errors:
    /// - `RESOURCE_UNAVAILABLE` when an event stream at the requested path is unavailable
    /// or has already been taken.
    TakeStaticEventStream(string:fuchsia.io.MAX_PATH path)
        -> (request<EventStream> server_end) error fuchsia.component.Error;
};

/// Listener for events on the component hierarchy. The server won't wait for the client
/// to handle the request before sending more events.
[Discoverable]
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, zx.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 capability.
    /// The flags, mode and path specified here are passed on from the fuchsia.io.Directory.Open
    /// FIDL call that caused this capability routing to occur.
    Open(zx.handle:CHANNEL server_end, uint32 flags, uint32 mode, string:fuchsia.io.MAX_PATH path) -> ();
};