src/sys/component_manager/tests/fidl/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.test.events;

/// The maximum number of event types that a receiver can listen to.
/// This capacity should match the actual number of event types.
const uint64 MAX_NUM_EVENT_TYPES_RECEIVED = 9;

/// The maximum string length of a component moniker.
const uint64 MAX_MONIKER_LENGTH = 100;

/// The maximum string length of a capability ID.
/// This value is currently set arbitrarily.
const uint64 MAX_CAPABILITY_ID_LENGTH = 50;

/// These EventTypes are used for the Breakpoints protocol.
/// They are FIDL versions of the EventType enum in hooks.rs and have
/// the same meaning.
enum EventType {
    /// A dynamic child was added to the parent instance.
    /// Depending on its eagerness, this child may/may not be started yet.
    ADD_DYNAMIC_CHILD = 1;

    /// An instance is about to be started.
    BEFORE_START_INSTANCE = 2;

    /// An instance was destroyed successfully. The instance is stopped and no longer
    /// exists in the parent's realm.
    POST_DESTROY_INSTANCE = 3;

    /// 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.
    PRE_DESTROY_INSTANCE = 4;

    /// An instance's declaration was resolved successfully for the first time.
    RESOLVE_INSTANCE = 5;

    /// A builtin capability is being requested by a component and requires routing.
    /// The event propagation system is used to supply the capability being requested.
    ROUTE_CAPABILITY = 6;

    /// An instance was stopped successfully.
    /// This event must occur before PostDestroyInstance.
    STOP_INSTANCE = 7;
};

/// Describes the source of a routed capability.
xunion CapabilitySource {
    /// The capability is provided by the framework and may be
    /// scoped down to a component.
    1: FrameworkCapability framework;

    /// The capability is provided by another component.
    2: ComponentCapability component;
};

/// Describes a capability provided by the framework
table FrameworkCapability {
    /// The moniker of the instance that this capability is scoped to.
    1: string: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:MAX_MONIKER_LENGTH source_moniker;
};

/// Encapsulates additional data/protocols for some event types.
table EventPayload {
    /// Payload for RouteCapability events
    1: RoutingPayload routing_payload;
};

/// Payload for RouteCapability events
table RoutingPayload {
    /// Allows setting a capability provider for
    /// RouteCapability events
    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;
};

/// Contains all information about a single event of a breakpoint
table Event {
    /// Event type corresponding to the event
    1: EventType event_type;

    /// Moniker of instance corresponding to the event
    2: string:MAX_MONIKER_LENGTH target_moniker;

    /// Handler for resuming from event
    3: Handler handler;

    /// Optional payload for some event types
    4: EventPayload event_payload;
};

/// Registers breakpoints in component manager.
[Discoverable]
protocol EventSourceSync {
    /// Subscribes to the events of the provided EventTypes.
    /// Returns a EventStreamSync which can be used
    /// to expect the registered types.
    Subscribe(vector<EventType>:MAX_NUM_EVENT_TYPES_RECEIVED event_types, request<EventStreamSync> server_end) -> ();

    /// Resume the execution of components within the realm using a scoped
    /// EventSourceSync.  This method is idempotent.
    StartComponentTree() -> ();
};

/// Receives events for registered events in component manager.
protocol EventStreamSync {
    /// Blocks until the next event is dispatched.
    ///
    /// Note: The component manager is blocked after this call and will not be
    /// allowed to proceed until resumed explicitly via the Handler.
    Next() -> (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, 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(handle<channel> server_end) -> ();
};