blob: e58e5a9807f20e73b848b96bf5e0e9a0b40582e5 [file] [log] [blame]
// Copyright 2017 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.modular;
using fuchsia.sys;
/// An agent is a component whose lifecycle is not tied to any Story.
///
/// - An agent is a singleton instance.
/// - Components can connect to an Agent using the
/// fuchsia.modular.ComponentContext capability.
/// - An agent vends services to components that connect to it over a
/// ServiceProvider.
/// - An agent is started when someone wants to connect to it, or when a task it
/// has scheduled has triggered.
///
/// This FIDL interface should be implemented by a component that is meant to be
/// run as an Agent.
///
/// When an agent application implements the `Lifecycle` interface, it can
/// receive a signal for when it should stop. An agent may be stopped for the
/// following reasons:
///
/// (1) All `AgentController` connections associated with this agent are closed.
///
/// (2) The system wants to optimize for resources.
///
/// Once the framework delivers a `Lifecycle.Terminate()`, the agent application
/// may exit itself, or is killed by framework after a timeout.
///
/// For more info see:
/// - fuchsia.modular.ComponentContext for capabilities an agent has.
/// - fuchsia.modular.Lifecycle for how Components get lifecycle events.
@discoverable // Created by each agent.
protocol Agent {
/// Called when some component tries to connect to this agent. `requestor_url`
/// identifies the requesting client. Different client roles are identified differently:
/// * For Module clients in the general case, `requestor_url` will be the name provided at
/// Module create time (ie, in calls to StoryPuppetMaster's StoryCommand.AddMod/mod_name)
/// with :'s escaped (see below for a complete explanation).
/// * For all other clients (Agents and Shells), `requestor_url` is set to the requesting
/// component's URL.
///
/// `services` must be connected to an implementation of fuchsia.sys.ServiceProvider offering
/// services specific to the requesting client.
///
/// Details on module naming: modules are named hierarchically based on what client created
/// them. This is called a module path. If created by 1) an agent or 2) an existing module, the
/// path is constructed differently.
///
/// In the case of (2), the module path is the concatenation of the existing module's path with
/// the new module's name, as provided by the parent module. In the case of (1), the module
/// path is the concatenation of StoryCommand.AddMod/mod_name and
/// StoryCommand.AddMod/surface_relation_parent.
///
/// The full path is encoded into `requestor_url` as escape_colons(module_path).join(':').
Connect(resource struct {
requestor_url string:MAX;
services server_end:fuchsia.sys.ServiceProvider;
});
};