blob: 944ebd460e960e0b5bcb74a3578359c125022544 [file] [log] [blame]
// 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.io;
using fuchsia.data;
using fuchsia.component;
/// 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`.
///
/// If an error is returned, the runner must ensure that resources
/// are cleaned up; the caller will not invoke the `controller`
/// interfaces, for example.
///
/// Errors:
/// - `INVALID_ARGUMENTS`: `resolved_url` is not supported by this runner;
/// `program` contains missing or invalid arguments; or a required field
/// in `start_info` (such `ns`, `outgoing_dir`, or `runtime_dir`) was not
/// provided.
/// - `INSTANCE_CANNOT_START`: The runner could not start the component.
/// For example, a critical part of the program could not be found or
/// loaded, or the referenced binary was invalid for this runner.
/// - `NO_SPACE`: The component could not be launched due to lack of
/// resources.
/// - `INTERNAL`: An unexpected internal runner error was encountered.
Start(ComponentStartInfo start_info,
request<ComponentController> controller) -> () error fuchsia.component.Error;
};
/// 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();
};