| // 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 MAX_CAPABILITY_ID_LENGTH uint64 = 50; |
| |
| /// The maximum string length of an error description. |
| const MAX_ERROR_DESCRIPTION_LENGTH uint64 = 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. |
| type EventType = strict enum { |
| /// 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; |
| |
| /// A directory exposed to the framework by a component is available. |
| DIRECTORY_READY = 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; |
| |
| /// The instance is destroyed and no longer exists. |
| DESTROYED = 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. |
| STOPPED = 8; |
| |
| /// If requested, this event is dispatched on subscription and indicates |
| /// that the instance has already started and is still running. |
| RUNNING = 9; |
| |
| /// Similar to STARTED, except the payload will carry an eventpair that the subscriber |
| /// could use to defer the launch of the component. This allows, e.g., a debugger to |
| /// perform some setup before any processes are created. |
| DEBUG_STARTED = 10; |
| |
| /// An instance was unresolved successfully. |
| UNRESOLVED = 11; |
| }; |
| |
| /// Describes the result of a state transition. |
| type EventResult = flexible resource union { |
| /// The payload of the event if the state transition described by the event |
| /// succeeds. |
| 1: payload EventPayload; |
| |
| /// The error that caused the state transition described by the event to |
| /// fail. |
| 2: error EventError; |
| }; |
| |
| /// Corresponds to an error that occurred during a state transition. |
| type EventError = table { |
| /// 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: description string:MAX_ERROR_DESCRIPTION_LENGTH; |
| |
| /// The error payload of the event if any. |
| 2: error_payload EventErrorPayload; |
| }; |
| |
| /// Encapsulates additional data for some event errors. |
| type EventErrorPayload = flexible union { |
| /// Payload for CapabilityRequested events |
| 1: capability_requested CapabilityRequestedError; |
| |
| /// Payload for CapabilityRouted events |
| 2: capability_routed CapabilityRoutedError; |
| |
| /// Payload for Purged events. |
| 3: purged PurgedError; |
| |
| /// Payload for DirectoryReady events |
| 4: directory_ready DirectoryReadyError; |
| |
| /// Payload for Discovered events. |
| 5: discovered DiscoveredError; |
| |
| /// Payload for Destroyed events. |
| 6: destroyed DestroyedError; |
| |
| /// Payload for Resolved events |
| 7: resolved ResolvedError; |
| |
| /// Payload for Running events |
| 8: running RunningError; |
| |
| /// Payload for Started events |
| 9: started StartedError; |
| |
| /// Payload for Stopped events |
| 10: stopped StoppedError; |
| |
| /// Payload for DebugStarted events |
| 11: debug_started DebugStartedError; |
| |
| /// Payload for Unresolved events. |
| 12: unresolved UnresolvedError; |
| }; |
| |
| /// Error payload for DirectoryReady events |
| type DirectoryReadyError = table { |
| /// The name of the capability. |
| 1: name fuchsia.component.name; |
| }; |
| |
| /// Error payload for CapabilityRequested events |
| type CapabilityRequestedError = table { |
| /// The name of the capability being requested. |
| 1: name fuchsia.component.name; |
| }; |
| |
| /// Error payload for CapabilityRouted events |
| type CapabilityRoutedError = table { |
| /// Name of the capability being requested. |
| 1: name fuchsia.component.name; |
| }; |
| |
| /// Error payload for Discovered events. |
| type DiscoveredError = table {}; |
| |
| /// Error payload for Purged events. |
| type PurgedError = table {}; |
| |
| /// Error payload for Resolved events. |
| type ResolvedError = table {}; |
| |
| /// Error payload for Unresolved events. |
| type UnresolvedError = table {}; |
| |
| /// Error payload for Running events. |
| type RunningError = table { |
| /// Time when the component started. |
| 1: started_timestamp zx.time; |
| }; |
| |
| /// Error payload for Destroyed events. |
| type DestroyedError = table {}; |
| |
| /// Error payload for Started events. |
| type StartedError = table {}; |
| |
| /// Error payload for Stopped events. |
| type StoppedError = table {}; |
| |
| /// Error payload for DebugStarted events. |
| type DebugStartedError = table {}; |
| |
| /// Encapsulates additional data/protocols for some event types. |
| type EventPayload = flexible resource union { |
| /// Payload for CapabilityRequested events |
| 1: capability_requested CapabilityRequestedPayload; |
| |
| /// Payload for CapabilityRouted events |
| 2: capability_routed CapabilityRoutedPayload; |
| |
| /// Payload for Purged events. |
| 3: purged PurgedPayload; |
| |
| /// Payload for DirectoryReady events |
| 4: directory_ready DirectoryReadyPayload; |
| |
| /// Payload for Discovered events. |
| 5: discovered DiscoveredPayload; |
| |
| /// Payload for Destroyed events. |
| 6: destroyed DestroyedPayload; |
| |
| /// Payload for Resolved events |
| 7: resolved ResolvedPayload; |
| |
| /// Payload for Running events |
| 8: running RunningPayload; |
| |
| /// Payload for Started events |
| 9: started StartedPayload; |
| |
| /// Payload for Stopped events |
| 10: stopped StoppedPayload; |
| |
| /// Payload for DebugStarted events |
| 11: debug_started DebugStartedPayload; |
| |
| /// Payload for Unresolved events |
| 12: unresolved UnresolvedPayload; |
| }; |
| |
| /// Payload for DirectoryReady events |
| type DirectoryReadyPayload = resource table { |
| /// The name of the capability. |
| 1: name fuchsia.component.name; |
| |
| /// Channel to the directory capability. |
| 2: node client_end:fuchsia.io.Node; |
| }; |
| |
| /// Payload for CapabilityRequested events |
| type CapabilityRequestedPayload = resource table { |
| /// The name of the capability. |
| 1: name fuchsia.component.name; |
| |
| /// A handle to the server end of the channel to host |
| /// capability. |
| 2: capability zx.handle:CHANNEL; |
| }; |
| |
| /// Payload for CapabilityRouted events |
| type CapabilityRoutedPayload = resource table { |
| /// Name of capability being requested. |
| 1: name fuchsia.component.name; |
| }; |
| |
| /// Payload for Purged events. |
| type PurgedPayload = table {}; |
| |
| /// Payload for Discovered events. |
| type DiscoveredPayload = table {}; |
| |
| /// Payload for Destroyed events. |
| type DestroyedPayload = table {}; |
| |
| /// Payload for Resolved events. |
| type ResolvedPayload = table {}; |
| |
| /// Payload for Unresolved events. |
| type UnresolvedPayload = table {}; |
| |
| /// Payload for Running events. |
| type RunningPayload = table { |
| /// Time when the component started. |
| 1: started_timestamp zx.time; |
| }; |
| |
| /// Payload for Started events. |
| type StartedPayload = table {}; |
| |
| /// Payload for Stopped events. |
| type StoppedPayload = table { |
| /// 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: status zx.status; |
| }; |
| |
| /// Payload for DebugStarted events. |
| type DebugStartedPayload = resource table { |
| /// The directory served by the runner to present runtime and runner-specific information |
| /// about the component. The other side is sent to the runner in ComponentStartInfo. |
| /// For example, it can be queried to know whether the component is an ELF component and |
| /// supports the break_on_start protocol below. |
| 1: runtime_dir client_end:fuchsia.io.Directory; |
| |
| /// An eventpair that can be used by debuggers to defer the launch of the component, |
| /// e.g., ELF debuggers can setup the exception channel on the job while holding |
| /// the eventpair, then drop the eventpair to notify the runner that processes could |
| /// be created. The other side is sent to the runner in ComponentStartInfo. |
| 2: break_on_start zx.handle:EVENTPAIR; |
| }; |
| |
| /// A head providing metadata about a target component instance. |
| type EventHeader = table { |
| /// Event type corresponding to the event |
| 1: event_type EventType; |
| |
| /// Relative moniker identifying the component instance. Relative to the scope of the event. |
| 2: moniker string:fuchsia.component.MAX_MONIKER_LENGTH; |
| |
| /// URL used to resolve the component. |
| 3: component_url fuchsia.url.Url; |
| |
| /// Time when the event occurred. |
| 4: timestamp zx.time; |
| }; |
| |
| /// Contains all information about a single event |
| type Event = resource table { |
| /// Information about the component for which this event was generated. |
| 1: header EventHeader; |
| |
| /// Optional payload for some event types |
| 2: event_result EventResult; |
| }; |
| |
| /// Indicates the event name to subscribe to with a given event mode. |
| type EventSubscription = table { |
| // The event names to subscribe to. |
| 1: event_name fuchsia.component.name; |
| }; |
| |
| /// 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(resource struct { |
| events vector<EventSubscription>:fuchsia.component.MAX_SUBSCRIPTION_REQUESTS; |
| stream client_end:EventStream; |
| }) -> (struct {}) 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(struct { |
| path string:fuchsia.io.MAX_PATH; |
| }) -> (resource struct { |
| server_end server_end:EventStream; |
| }) error fuchsia.component.Error; |
| }; |
| |
| /// Subscribe to events in component manager. |
| @discoverable |
| protocol EventSource2 { |
| /// 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(resource struct { |
| events vector<fuchsia.component.name>:MAX; |
| stream server_end:EventStream2; |
| }) -> (struct {}) error fuchsia.component.Error; |
| }; |
| |
| /// Listener for events on the component hierarchy. |
| @discoverable |
| protocol EventStream2 { |
| GetNext() -> (resource struct { |
| events vector<Event>:MAX; |
| }); |
| }; |
| |
| /// 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(resource struct { |
| event Event; |
| }); |
| }; |