sdk/fidl/fuchsia.sys2/events.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.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 provided by this component has been requested. The event
    /// payload carries the request channel.
    CAPABILITY_REQUESTED = 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 purged successfully. The instance is stopped and no longer
    /// exists in the parent's realm.
    PURGED = 3;

    /// A directory exposed to the framework by a component is available.
    DIRECTORY_READY = 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 is guranteed to be shut down at
    /// this point. The instance still exists in the parent's realm but will soon be removed.
    /// The instance is considered destroyed when this event is received.
    /// TODO(fxbug.dev/39417): Ensure the instance is stopped before this event.
    DESTROYED = 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 Purged.
    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 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 CapabilityRequested events
    1: CapabilityRequestedError capability_requested;

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

    /// Payload for Purged events.
    3: PurgedError purged;

    /// Payload for DirectoryReady events
    4: DirectoryReadyError directory_ready;

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

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

    /// 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 DirectoryReady events
table DirectoryReadyError {
    /// 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 Purged events.
table PurgedError {
};

/// 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 Destroyed events.
table DestroyedError {
};

/// 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 CapabilityRequested events
    1: CapabilityRequestedPayload capability_requested;

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

    /// Payload for Purged events.
    3: PurgedPayload purged;

    /// Payload for DirectoryReady events
    4: DirectoryReadyPayload directory_ready;

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

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

    /// 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 DirectoryReady events
resource table DirectoryReadyPayload {
    /// The name of the capability.
    1: fuchsia.component.name name;

    /// Channel to the directory capability.
    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 {
    /// Name of capability being requested.
    1: fuchsia.component.name name;
};

/// Payload for Purged events.
table PurgedPayload {
};

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

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

/// 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() -> ();
};