// 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.component;

using fuchsia.io;
using fuchsia.url;
using zx;

/// The maximum string length of a capability ID.
/// This value is currently set arbitrarily.
@available(added=11)
const MAX_CAPABILITY_ID_LENGTH uint64 = 50;

/// The maximum string length of an error description.
@available(added=11)
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.
@available(added=11)
type EventType = strict enum {
    /// A capability provided by this component has been requested. The event
    /// payload carries the request channel.
    CAPABILITY_REQUESTED = 1;

    /// A directory exposed to the framework by a component is available.
    DIRECTORY_READY = 2;

    /// 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 = 3;

    /// The instance is destroyed and no longer exists.
    DESTROYED = 4;

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

    /// 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 = 6;

    /// An instance was stopped successfully.
    STOPPED = 7;

    /// 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 = 8;

    /// An instance was unresolved successfully.
    UNRESOLVED = 9;
};

/// Encapsulates additional data/protocols for some event types.
@available(added=11)
type EventPayload = flexible resource union {
    /// Payload for CapabilityRequested events
    1: capability_requested CapabilityRequestedPayload;

    /// Payload for Purged events.
    2: purged PurgedPayload;

    /// Payload for DirectoryReady events
    3: directory_ready DirectoryReadyPayload;

    /// Payload for Discovered events.
    4: discovered DiscoveredPayload;

    /// Payload for Destroyed events.
    5: destroyed DestroyedPayload;

    /// Payload for Resolved events
    6: resolved ResolvedPayload;

    /// Payload for Started events
    7: started StartedPayload;

    /// Payload for Stopped events
    8: stopped StoppedPayload;

    /// Payload for DebugStarted events
    9: debug_started DebugStartedPayload;

    /// Payload for Unresolved events
   10: unresolved UnresolvedPayload;
};

/// Payload for DirectoryReady events
@available(added=11)
type DirectoryReadyPayload = resource table {
    /// The name of the capability.
    1: name name;

    /// Channel to the directory capability.
    2: node client_end:fuchsia.io.Node;
};

/// Payload for CapabilityRequested events
@available(added=11)
type CapabilityRequestedPayload = resource table {
    /// The name of the capability.
    1: name name;

    /// A handle to the server end of the channel to host
    /// capability.
    2: capability zx.Handle:CHANNEL;
};

/// Payload for Purged events.
@available(added=11)
type PurgedPayload = table {};

/// Payload for Discovered events.
@available(added=11)
type DiscoveredPayload = table {};

/// Payload for Destroyed events.
@available(added=11)
type DestroyedPayload = table {};

/// Payload for Resolved events.
@available(added=11)
type ResolvedPayload = table {};

/// Payload for Unresolved events.
@available(added=11)
type UnresolvedPayload = table {};

/// Payload for Started events.
@available(added=11)
type StartedPayload = table {};

/// Payload for Stopped events.
@available(added=11)
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.
@available(added=11)
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.
@available(added=11)
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: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
@available(added=11)
type Event = resource table {
    /// Information about the component for which this event was generated.
    1: header EventHeader;

    /// Optional payload for some event types
    2: payload EventPayload;
};

/// Listener for events on the component hierarchy.
@discoverable
@available(added=11)
closed protocol EventStream {
    strict GetNext() -> (resource struct {
        events vector<Event>:MAX;
    });

    /// Returns immediately. Used to indicate that the FIDL connection
    /// completed. This is needed for non-static streams to verify
    /// that subscribe has completed before components are started.
    strict WaitForReady() -> ();
};