blob: da02184a2905e8487fc9f95d9b40441565ed9375 [file] [log] [blame]
// 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;
/// 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(fxb/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 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(fxb/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 path of the capability.
1: string:fuchsia.component.MAX_PATH_LENGTH path;
};
/// Error payload for CapabilityRequested events
table CapabilityRequestedError {
/// Identifier of capability being requested.
/// For a path-based capability, this is the path.
/// For a runner capability, this is the name.
1: string:MAX_CAPABILITY_ID_LENGTH path;
};
/// Error payload for CapabilityRouted events
table CapabilityRoutedError {
/// Identifier of capability being requested.
/// For a path-based capability, this is the path.
/// For a runner capability, this is the name.
1: string:MAX_CAPABILITY_ID_LENGTH capability_id;
};
/// 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 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
table CapabilityReadyPayload {
/// The path of the capability.
1: string:fuchsia.component.MAX_PATH_LENGTH path;
/// Channel to the node exposed by the event source at `path`.
2: fuchsia.io.Node node;
};
/// Payload for CapabilityRequested events
table CapabilityRequestedPayload {
/// The path of the capability.
1: string:fuchsia.component.MAX_PATH_LENGTH path;
/// A handle to the server end of the channel to host
/// capability.
2: handle<channel> capability;
};
/// Payload for CapabilityRouted events
table CapabilityRoutedPayload {
/// Allows setting a capability provider for
/// CapabilityRouted events
/// This will not be available with an async event.
1: RoutingProtocol routing_protocol;
/// Identifier of capability being requested.
/// For a path-based capability, this is the path.
/// For a runner capability, this is the name.
2: string:MAX_CAPABILITY_ID_LENGTH capability_id;
/// 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 {
};
/// A descriptor providing metadata about a target component instance.
table ComponentDescriptor {
/// Relative moniker identifying the component instance. Relative to the scope of the event.
1: string:fuchsia.component.MAX_MONIKER_LENGTH moniker;
/// URL used to resolve the component.
2: fuchsia.url.Url component_url;
};
/// Contains all information about a single event
table Event {
/// Event type corresponding to the event
1: EventType event_type;
/// Information about the component for which this event was generated.
2: ComponentDescriptor descriptor;
/// Handler for resuming from event
/// This will be absent if this is an async event.
3: Handler handler;
/// Optional payload for some event types
4: EventResult event_result;
/// Time when the event occurred.
5: zx.time timestamp;
};
/// Subscribe to events in component manager.
[Discoverable, FragileBase]
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<fuchsia.component.name>:fuchsia.component.MAX_NUM_EVENTS_RECEIVED events,
EventStream stream)
-> () error fuchsia.component.Error;
};
/// Subscribe to events in component manager.
[Discoverable]
protocol BlockingEventSource {
compose EventSource;
/// Resume the execution of components within the realm using a scoped
/// BlockingEventSource. This method is idempotent.
StartComponentTree() -> ();
};
/// 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 framework capability.
/// TODO(xbhatnag): provide all arguments (flags, mode, path) to this method.
Open(zx.handle:CHANNEL server_end) -> ();
};