sdk/fidl/fuchsia.sys2/events.fidl - fuchsia - Git at Google

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