| // 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 destroyed successfully. The instance is stopped and no longer |
| /// exists in the parent's realm. |
| DESTROYED = 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 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 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 Destroyed events. |
| 3: DestroyedError destroyed; |
| |
| /// Payload for DirectoryReady events |
| 4: DirectoryReadyError directory_ready; |
| |
| /// 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 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 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 CapabilityRequested events |
| 1: CapabilityRequestedPayload capability_requested; |
| |
| /// Payload for CapabilityRouted events |
| 2: CapabilityRoutedPayload capability_routed; |
| |
| /// Payload for Destroyed events. |
| 3: DestroyedPayload destroyed; |
| |
| /// Payload for DirectoryReady events |
| 4: DirectoryReadyPayload directory_ready; |
| |
| /// 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 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 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() -> (); |
| }; |