This document demonstrates how to connect [components][glossary.component] together using capabilities and additional tools for parent components to manage their children.
You should understand the following concepts before continuing with this guide:
Directory channel called the outgoing directory. The component's program makes discoverable any capabilities that it provides through this directory.fuchsia.component.Realm framework protocol.For more details on these concepts, see Realms and Capabilities.
Note: For a complete example using routed capabilities, see //examples/components/routing.
Components interact with each other through capabilities. Capabilities served by a component need to be declared in that component's manifest and, for them to be usable by others, routed to parent/child components through expose and offer declarations. Other components that use that capability also need to declare their use in their manifests. In order for their programs to use the capability at runtime, the used capability must be routed to that component - either offered from a parent or exposed by a child.
Capability routing refers to the recursive process, performed by the component manager, of identifying a serving component by following individual routing steps described in manifest files. Capability routing is initiated when:
ffx component route.Routing is performed lazily: while a capability may be configured to be provided by a parent or child (directly or indirectly through further delegation), the target component may not have been resolved yet when the routing operation is initiated. Practically, this means that the full route from the requesting component to the final serving component may not be known until routing is attempted.
Components that provide a capability must declare the capability in their component manifest using a capabilities declaration.
See the following example that declares a FIDL protocol capability in the providing component's manifest:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/rust/echo_server/meta/echo_server.cml" region_tag="example_snippet" adjust_indentation="auto" highlight="16,17,18,19" %}
At runtime, the server component provides an implementation of the capability by serving it in its outgoing directory using the fuchsia.io protocol. The generated FIDL bindings wrap this handle and enable the provider to begin receiving incoming requests:
{Rust}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/rust/echo_server/src/main.rs" region_tag="main_body" adjust_indentation="auto" highlight="1,2,3,4,8,14,15,16,21,22,23,24,25,26,27,28" %} {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/rust/echo_server/src/main.rs" region_tag="handler" adjust_indentation="auto" highlight="1,2,3,4,5,6,7" %}
{C++}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/cpp/echo_server/main.cc" region_tag="handler" adjust_indentation="auto" highlight="1,2,3,4,5,6" %} {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/cpp/echo_server/main.cc" region_tag="main_body" adjust_indentation="auto" highlight="3,9,10,11,12,13,14,15,16,17" %}
Client components declare capabilities they may request in their component manifest with a use declaration.
See the following example of a client component's manifest that uses the FIDL protocol provided by the previous component:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/rust/echo_client/meta/echo_client.cml" region_tag="example_snippet" adjust_indentation="auto" highlight="19,20,21,22" %}
At runtime, the client component opens paths populated in its namespace using the fuchsia.io protocol in order to acquire capabilities provided by other components. The Fuchsia component library works with the generated FIDL bindings to provide a structured interface for communicating over the channel:
{Rust}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/rust/echo_client/src/main.rs" region_tag="main_body" adjust_indentation="auto" highlight="7,8,9,10,11,12,13,14" %}
{C++}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/cpp/echo_client/main.cc" region_tag="main_body" adjust_indentation="auto" highlight="2,3,4,5,7,8,10" %}
It is the responsibility of the component's parent to route to it all necessary capabilities.
Not all capabilities used by a component are required for it to operate successfully. Sometimes a component can still execute without issue if a capability is missing, and its presence will merely enable some additional or alternative behavior.
To enable the component framework to understand which capabilities a component requires and which capabilities are optional for a component, use the availability field.
use: [
{
// It is ok if this protocol is unavailable
protocol: "fuchsia.examples.Echo1",
availability: "optional",
},
{
// This protocol MUST be provided for the component to function correctly.
protocol: "fuchsia.examples.Echo2",
availability: "required",
},
]
If a component has a required use declaration for a capability (the default) but its parent offers the capability as optional, then the static capability analyzer will generate an error and connection attempts at runtime will always fail.
In the case that a component's parent has offered a capabilitity with availability: "optional", the capability may not be usable at runtime.
An entry in the component's namespace will be present whether the capability is available or not. Any attempt to open the path for that capability will result in the handle provided to the Directory.Open() call being closed with a ZX_ERR_NOT_FOUND epitaph.
Usage of libc methods like open() or stat() will return ENOENT.
Components may only access capabilities routed to them. Capabilities can originate from anywhere in the component topology as long as a valid capability route exists as a chain of the following declarations from the capability provider to any consumers:
expose: Routes a capability up to the component's parent.offer: Routes a capability down to one of the component's children.To connect capability providers with components requesting those capabilities, do the following:
Add an offer or expose declaration to the capability provider component:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/rust/echo_server/meta/echo_server.cml" region_tag="example_snippet" adjust_indentation="auto" highlight="20,21,22,23,24,25" %}
For each intermediate component in the component instance tree, include additional expose and offer declarations until you reach the consuming component containing a use declaration:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/meta/echo_realm.cml" region_tag="example_snippet" highlight="13,14,15,16,17,18,19,21,22,23,24,25,26,27,28,29,30" %}
When a component has an optional dependency on a capability, it is then up to that component's parent to decide if the component will receive that capability or not. When offering a capability, a component may set the availability field to either optional, required, or same_as_target. Each value has the following semantics:
optional: The target of the offer must declare its ability to handle the absence of this capability by marking it's use declaration as optional. If the target cannot do this, (i.e. the target has an availability of required for this capability), then routing the capability will cause an error.required: The target must receive this capability. If the offer source is parent and the component‘s parent (the target’s grandparent) offered this as an optional capability, then routing the capability will cause an error because the parent cannot guarantee the capability's availability.same_as_target: The availability of this capability is determined by the target's expectations. If the target has an optional dependency on this capability, then this offer will also be optional. If the target has a required dependency on this capability, then this offer will also be required.offer: [ { // child-1 MUST receive the protocol 'fuchsia.logger.LogSink'. protocol: "fuchsia.logger.LogSink", to: "#child-1", from: "#child-2", availability: "required", }, { // child-1 MUST be able to handle the absence of the protocol // 'fuchsia.tracing.provider.Registry'. protocol: "fuchsia.tracing.provider.Registry", to: "#child-1", from: "parent", availability: "optional", }, { // child-1 decides if it must receive the protocol // 'fuchsia.posix.socket.Provider', or if it must be able to support its // absence. protocol: "fuchsia.posix.socket.Provider", to: "#child-1", from: "parent", availability: "same_as_target", }, ]
Like with use declarations, the availability field may be omitted, in which case it defaults to required.
The component framework allows components to soft-transition into using and offering both optional and required capabilities. With the transitional availability marker, a component using a capability, will not cause Scrutiny validation errors whether or not the parent is required, optional, or same as target. Note, though this field exists to enable soft-transitions, components should ultimately settle on either optional or required.
To use this feature, the child component will mark its availability as “transitional”:
use: [ { // It is ok if this protocol is offered as "required" or "optional" protocol: "fuchsia.examples.Echo", availability: "transitional", }, ]
Note: For a complete example using child components, see //examples/components/lifecycle.
Components can interact with each other from anywhere in the component topology through capabilities as long as a valid capability route exists between them. There are additional methods that enable parent components to interact with their direct children.
The following example component declares a single static child named lifecycle and a collection named echo where additional child components may be created at runtime:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/rust/meta/manager.cml" region_tag="example_snippet" adjust_indentation="auto" %}
Notice that a collection behaves like a static child instance in the parent component's manifest — you can give it a name and offer specific capabilities to it. All child components in the collection may access the set of capabilities offered to it.
The Component Framework provides the fuchsia.component.Binder protocol for parent components to explicitly start a child that may not expose any other capabilities. Since this capability is provided by the framework, child components only need to expose it from their component manifest:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/rust/meta/lifecycle.cml" region_tag="example_snippet" adjust_indentation="auto" %}
To create a new child component at runtime, use the fuchsia.component.Realm protocol to create the component inside of an existing collection. Call the CreateChild method with the following parameters:
CollectionRef: Describes the collection where the component will be added.
Child: Component declaration, including its name and component URL.
{Rust}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/rust/src/manager.rs" region_tag="imports" adjust_indentation="auto" %} // ... {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/rust/src/manager.rs" region_tag="create_child" adjust_indentation="auto" %}
{C++}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/cpp/manager.cc" region_tag="imports" adjust_indentation="auto" %} // ... {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/cpp/manager.cc" region_tag="create_child" adjust_indentation="auto" %}
Because the parent of a dynamic component is not known at build time, its exposed capabilities cannot be named in capability routes expressed in the component manifest.
To connect with the capabilities exposed by a dynamic child instance:
Use the fuchsia.component.Realm protocol to open the child‘s exposed directory. Call the OpenExposedDir method with the child component’s name and the collection name:
{Rust}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/rust/src/manager.rs" region_tag="imports" adjust_indentation="auto" %} // ... {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/rust/src/manager.rs" region_tag="connect_child" adjust_indentation="auto" %}
{C++}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/cpp/manager.cc" region_tag="imports" adjust_indentation="auto" %} // ... {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/cpp/manager.cc" region_tag="connect_child" adjust_indentation="auto" %}
Connect to the child's exposed capabilities using the exposed directory handle as the root:
{Rust}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/rust/src/manager.rs" region_tag="echo_send" adjust_indentation="auto" %}
{C++}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/cpp/manager.cc" region_tag="echo_send" adjust_indentation="auto" %}
When the dynamic child is no longer needed, use the fuchsia.component.Realm protocol to destroy the component instance. Call the DestroyChild method with a ChildRef representing the child inside the collection.
{Rust}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/rust/src/manager.rs" region_tag="imports" adjust_indentation="auto" %} // ... {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/rust/src/manager.rs" region_tag="destroy_child" adjust_indentation="auto" %}
{C++}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/cpp/manager.cc" region_tag="imports" adjust_indentation="auto" %} // ... {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/cpp/manager.cc" region_tag="destroy_child" adjust_indentation="auto" %}
This causes the component to stop if it is currently running. To handle this event in your component, see listen for stop events.
The Component Framework provides features to modify and interact with various parts of the component lifecycle.
For more details on lifecycle concepts, see Component lifecycle.
The ELF runner notifies components of lifecycle events using the fuchsia.process.lifecycle.Lifecycle protocol.
To listen for stop notifications in your child component:
Subscribe to the lifecycle event in your component manifest:
{Rust}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/rust/meta/lifecycle.cml" region_tag="lifecycle_event" adjust_indentation="auto" highlight="9,10" %}
{C++}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/cpp/meta/lifecycle.cml" region_tag="lifecycle_event" adjust_indentation="auto" highlight="9,10" %}
Register a lifecycle handler using the startup handle provided by the runner:
{Rust}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/rust/src/lifecycle.rs" region_tag="imports" adjust_indentation="auto" %} // ... {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/rust/src/lifecycle.rs" region_tag="lifecycle_handler" adjust_indentation="auto" %}
{C++}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/cpp/lifecycle.cc" region_tag="imports" adjust_indentation="auto" %} // ... {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/lifecycle/cpp/lifecycle.cc" region_tag="lifecycle_handler" adjust_indentation="auto" %}
Component manifests let you mark a child as eager, which causes the component framework to implicitly start that child with the parent.
If the eager child fails to start for any reason (such as a missing component), component manager exhibits the following behavior:
If the parent is not the root component, the parent will start but the component that bound to it will observe a dropped connection (just like any other failed binding).
If the parent is the root component, component manager will crash, with an error message like:
[component_manager] ERROR: protocol `fuchsia.component.CoreBinder` was not available for target `startup`: failed to resolve `fuchsia-pkg://fuchsia.com/your_component#meta/your_component.cm`: package not found: remote resolver responded with PackageNotFound For more, run `ffx component doctor `startup`
Components marked as eager can cause system crashes when they are not present if their ancestors are also marked eager up to the root component. This is important because many build configurations create system images containing a subset of the available components. To avoid this problem, declare these components using core realm shards to ensure they can be safely excluded from test builds and product images.
An eager component should also be in the same package set as its parent since the component will be started at the same time as its parent. Typically, eager components should be in the product's base package set.
To determine if your package is in the base package set, run the following command:
fx list-packages --verbose {{ '<var label="package name">my-package</var>' }}
This command outputs a list of the package sets where the matching package is found. For example, system-update-checker is in the base and universe package sets:
$ fx list-packages --verbose system-update-checker system-update-checker [base universe]
You can also look at all the packages in the base package set using the --base option:
fx list-packages --base
Component manifests let you control the termination policy of your component using on_terminate. Components with the “reboot-on-terminate” policy set cause the system to gracefully reboot if the component terminates for any reason other than successful exit.
Note: This is a special feature intended for use only by system components deemed critical to the system's function. Therefore, its use is governed by a security policy allowlist.
To enable this feature, do the following:
Mark the child as on_terminate: "reboot" in the parent's component manifest:
// core.cml { children: [ ... { name: "system-update-checker", url: "fuchsia-pkg://fuchsia.com/system-update-checker#meta/system-update-checker.cm", startup: "eager", {{ '<strong>' }}on_terminate: "reboot",{{ '</strong>' }} }, ], }
Add the component‘s moniker to component manager’s security policy allowlist at //src/security/policy/component_manager_policy.json5:
// //src/security/policy/component_manager_policy.json5 { security_policy: { ... child_policy: { reboot_on_terminate: [ ... "/core/system-update-checker", ], }, }, }
When routing is initiated by a requesting client by performing a Directory.Open() request on its namespace, or on the exposed directory, it passes the server-end handle of a zircon object that will provide the capability once routed. Errors will result in that handle's object being closed with an epitaph. The epitaph payload is always a Zircon status code.
Since routing is lazy and asynchronous, this message may arrive at any time after the routing operation is initiated.
NOTE: once routing has succeeded, the serving component can also close the same object with a status code of their choice. It is impossible for a client to discern if the object was closed by component manager or by the serving component, or another party delegated to thereafter.
The same error signaling mechanism is used for libc-like calls like open().
See the section Troubleshooting for practical examples.
The following error codes may be sent by component manager to indicate a failed routing operation:
ZX_ERR_NOT_FOUND: the capability was unable to be routed for one of the following reasons:ZX_ERR_ACCESS_DENIED: the capability was unable to be routed because the requesting component is not allowed to access it. For example:ZX_ERR_TIMED_OUT: one of the routing steps timed out.ZX_ERR_INTERNAL: component manager itself encountered an unexpected error, indicating a bug in the platform.NOT_FOUND, ACCESS_DENIED, and INTERNAL errors will reproduce for the same capability so long as no software on the platform is updated. A software update, even for a single component, can change a capability's route and might affect the availability of that capability.
NOT_FOUND for the requesting client.This section contains common issues you may encounter trying to use and connect to capabilities from your component with suggested solutions.
Component manager performs capability routing to find the source of a given capability once your component attempts to access the capability. Routing can fail if one of the component manifests in the routing path is configured incorrectly. For example, an offer or expose declaration is missing from some component in the path, or one of the components in the chain could not be resolved.
Do the following to check if a routing failure was the cause of channel closure:
Use ffx component route to check the routing for your component. This can either be used with the moniker of your component or your component's URL. For example:
# check with the moniker ffx component route /core/ffx-laboratory:echo_realm/echo_client # check with a partial URL ffx component route echo_client.cm
Check the component logs with ffx log for a message beginning with Failed to route that explains where the routing chain failed. For example:
[echo_client][][W] protocol `fidl.examples.routing.echo.Echo` was not available for target `/core/ffx-laboratory:echo_realm/echo_client`: `fidl.examples.routing.echo.Echo` was not offered to `/core/ffx-laboratory:echo_realm/echo_client` by parent For more, run `ffx component doctor /core/ffx-laboratory:echo_realm/echo_client`
Check for an epitaph on the closed channel. The epitaph set for the most common routing failures is ZX_ERR_NOT_FOUND:
[echo_client][][I] Connecting to Echo protocol failed with error "A FIDL client's channel to the service fidl.examples.routing.echo.Echo was closed: NOT_FOUND"
See routing errors for more.
For a self-contained example of failed capability routing, see //examples/components/routing_failed.
When capability routing fails, the underlying FIDL channel closes. FIDL protocol bindings return an error status if the channel was closed. Consider the following example:
{Rust}
let echo = connect_to_protocol::<EchoMarker>() .context("Failed to connect to echo service")?; let res = echo.echo_string(Some("Hippos rule!")).await; match res { Ok(_) => { info!("Call succeeded!"); } {{ '<strong>' }}Err(fidl::Error::ClientChannelClosed { status, service_name } => { {{ '</strong>' }} {{ '<strong>' }}error!("Channel to service {} was closed with status: {}", service_name, status); {{ '</strong>' }} {{ '<strong>' }}} {{ '</strong>' }} Err(e) => { error!("Unexpected error: {}", e); } };
{C++}
fuchsia::examples::EchoPtr echo_proxy; auto context = sys::ComponentContext::Create(); context->svc()->Connect(echo_proxy.NewRequest()); {{ '<strong>' }}// Sets an error handler that will be called if an error causes the underlying {{ '</strong>' }} {{ '<strong>' }}// channel to be closed. {{ '</strong>' }} {{ '<strong>' }}echo_proxy.set_error_handler([&loop](zx_status_t status) { {{ '</strong>' }} {{ '<strong>' }}printf("Channel was closed with status: %d\n", status); {{ '</strong>' }} {{ '<strong>' }}// ... {{ '</strong>' }} {{ '<strong>' }}}); {{ '</strong>' }} echo_proxy->EchoString("Hippos rule!", [&](std::string response) { // ... });
Note: If the protocol method doesn't return a value (such as a one-way method), the error status is only set if the channel was closed prior to the method call.
To determine the underlying cause of a channel closure, you can inspect the optional epitaph set on the channel. To retrieve the epitaph on a closed channel, do the following:
{Rust}
let stream = echo.take_event_stream(); match stream.next().await { Some(Err(fidl::Error::ClientChannelClosed { status, .. })) => { info!("Channel was closed with epitaph: {}", status); } Some(m) => { info!("Received message other than epitaph or peer closed: {:?}", m); } None => { info!("Component failed to start or channel was closed by server"); } }
{C++}
echo_proxy.set_error_handler([&loop](zx_status_t status) { // If an Epitaph was present on the channel, its error value will be passed as // the parameter. printf("Channel was closed with epitaph: %d\n", status); });
You may encounter an error if capability routing was successful, but an issue occurred resolving or starting the component. The form of the error message depends on the component runner:
For the ELF runner, check the component manager logs with ffx log --filter component_manager. Look for a message starting with Failed to start component. For example:
[component_manager] WARN: Failed to start component `fuchsia-pkg://fuchsia.com/components-routing-failed-example#meta/echo_server_bad.cm`: unable to load component with url "fuchsia-pkg://fuchsia.com/components-routing-failed-example#meta/echo_server_bad.cm": error loading executable: "reading object at \"bin/routing_failed_echo_server_oops\" failed: A FIDL client's channel to the service fuchsia.io.File was closed: PEER_CLOSED"
For other runners, check the logs of the runner component. You can do this by running the following command:
ffx log --tags {{ '<var label="component runner">runner-name</var>' }}
To address the issue, verify the following:
program declaration in your component manifest is configured properly. For example, verify that the binary's path is spelled correctly.For an example of a component that failed to start due to a misconfigured component manifest, see //examples/components/routing_failed.
If you have verified that routing succeeded and the component started successfully, you may be experiencing an issue where the source component closed the channel itself. This can happen while the component was running, or can be a side effect of the component terminating.
If the component terminated because it crashed, you can look for a crash report in ffx log that contains the component name in the dump:
[33860.645][klog][klog][I] crashsvc: exception received, processing [33860.645][klog][klog][I] <== fatal : process echo_client.cm[21090] thread initial-thread[21092] <stack trace follows...>
If the source component closed the channel itself, here are some tips to further troubleshoot the cause: