// Copyright 2016 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.data;
using fuchsia.io;

/// An interface for running components.
///
/// This interface is implemented by components that provide an execution
/// environment for running particular classes of programs.  For example,
/// the Dart virtual machine exposes a service with this interface to run
/// Dart programs.
///
/// To specify the runner needed to run your component, set the "runner_url"
/// property in your component's manifest.
///
/// Note: The component manager is the only intended direct client of this
/// interface.
[Discoverable]
protocol ComponentRunner {
    /// Starts running a new component instance described by `start_info`.
    ///
    /// The caller of this method takes responsibility for binding client
    /// connections and controlling the lifetime of the newly started
    /// component instance through the requested `controller`.
    Start(ComponentStartInfo start_info,
          request<ComponentController> controller);
};

/// Parameters for starting a new component instance.
table ComponentStartInfo {
    /// The resolved URL of the component.
    /// This is the canonical URL obtained by the component resolver after
    /// following redirects and resolving relative paths.
    1: string resolved_url;

    /// The component's program declaration.
    /// This information originates from `ComponentDecl.program`.
    2: fuchsia.data.Dictionary program;

    /// The namespace to provide to the component instance.
    3: ComponentNamespace ns;

    /// The directory this component serves.
    4: request<fuchsia.io.Directory> outgoing_dir;

    /// The directory served by the runner to present runtime information about
    /// the component.
    5: request<fuchsia.io.Directory> runtime_dir;
};

/// An interface for binding client connections and controlling the lifetime
/// of a component instance started using `ComponentRunner.Start()`.
///
/// When the controlled component instance terminates or becomes inaccessible
/// for any reason, the server invokes `OnEpitaph()` and closes its endpoint
/// of the controller interface.
///
/// LIFECYCLE
///
/// A component may exist in one of two states, Started or Stopped. The component
/// is Started from time `ComponentRunner.Start()` is called until the
/// ComponentRunner closes the ComponentController handle. The component then
/// transitions to Stopped.
///
/// `Stop()` is called to indicate a ComponentRunner should end a component's
/// execution. `Kill()` indicates that a runner must halt a component's
/// execution immediately and close the ComponentController's server end. After
/// the ComponentController is closed the component manager can tear down the
/// namespace it hosts for the stopped component. The component manager may
/// call `Kill()` without first having called `Stop()`.
///
/// EPITAPH
///
/// This interface uses a FIDL epitaph to indicate that the controller
/// component instance has terminated and to describe its final disposition.
///
/// The following epitaph status codes have particular significance:
///
/// - `ZX_OK`: The component instance was successfully terminated in response
///   to `Stop()` and its runtime resources have been fully released.
/// - `ZX_ERR_UNAVAILABLE`: The runner was unable to start the component
///   instance.  e.g. The runner could not retrieve the component's assets.
/// - `ERR_COMPONENT_DIED`: The component instance was started but
///   subsequently terminated unexpectedly.
///
/// Other status codes (e.g. `ZX_ERR_PEER_CLOSED`) may indicate a failure
/// of the component runner itself.  The component manager may respond to such
/// failures by terminating the component runner's job to ensure system
/// stability.
protocol ComponentController {
    /// Requests the runner to stop the controlled component instance.
    ///
    /// After stopping the component instance, the server should report
    /// an epitaph then close its endpoint of the controller interface.
    Stop();

    /// Stop this component immediately. This ComponentRunner must immediately
    /// kill the component instance, set an epitaph set on the channel, and
    /// close the channel. After the channel closes, the component instance will
    /// be considered by the component manager to be Stopped and the component's
    /// namespace will be torn down.
    ///
    /// Kill() may have been preceeded by Stop(), but that is not guaranteed.
    Kill();
};