sdk/fidl/fuchsia.sys2/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.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;

    /// An instance was purged successfully. The instance is stopped and no longer
    /// exists in the parent's realm.
    PURGED = 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 is guranteed to be shut down at
    /// this point. The instance still exists in the parent's realm but will soon be removed.
    /// The instance is considered destroyed when this event is received.
    /// TODO(fxbug.dev/39417): Ensure the instance is stopped before this event.
    DESTROYED = 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 Purged.
    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.
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;
};

/// 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 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 {};

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

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

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