Component identifiers

<<../_v2_banner.md>>

The Component Framework uses different identifiers to describe components. This section describes the relationship between the following component identifiers, and their usage:

• Component URLs: Identifies a component as a resource to be fetched by a component resolver.
• Monikers: Identifies specific component instances in the component instance tree.

Component URLs

A component URL is a URL that locates a component, including its declaration, program, and assets. Component Framework uses component resolvers to resolve a component URL into a component declaration.

Usage

The primary use of component URLs is to identify a component in the definition of a component instance, as part of a child declaration:

{
    children: [
        {
            name: "logger",
            url: "fuchsia-pkg://fuchsia.com/logger#logger.cm",
        },
    ],
}

The above example declares the logger component as an absolute resource in a Fuchsia package hosted in a package repository.

Component Framework also supports relative URLs to identify components built into the same package as the parent component. This allows component reuse between packages without creating additional manifests:

{
    children: [
        {
            name: "child",
            url: "#meta/child.cm",
        }
    ],
}

This pattern is often used in tests, where the best practice is to re-package production components in a test-specific package to promote hermeticity.

For more details on component URL syntax, see the component URL reference.

Monikers

A component moniker identifies a specific component instance in the component instance tree using a topological path.

Design principles

Stability

Monikers are stable identifiers. Assuming the component topology does not change, the monikers used to identify component instances in the topology will remain the same.

Uniqueness

Each time a component instance is destroyed and a new component instance with the same name is created in its place in the component topology (as a child of the same parent), the new instance is assigned a unique instance identifier to distinguish it from prior instances in that place.

Monikers include unique instance identifiers to prevent confusion of old component instances with new component instances of the same name as the tree evolves.

Privacy

Monikers may contain privacy-sensitive information about other components that the user is running.

To preserve the encapsulation of the system, components should be unable to determine the identity of other components running outside of their own realm. Accordingly, monikers are only transmitted on a need-to-know basis or in an obfuscated form.

For example, components are not given information about their own absolute moniker because it would also reveal information about their parents and ancestors.

Monikers may be collected in system logs. They are also used to implement the component framework's persistence features.

Usage

The primary use of monikers is to identify component instances at runtime. There are three types of component monikers:

• Absolute moniker: Denotes the path from the root of the component instance tree to a target component instance.
• Child moniker: Denotes the path of a child of a component instance relative to its parent.
• Relative moniker: Denotes the path from a source component instance to a target component instance.

Every component instance has a unique absolute moniker. Consider the following example component instance tree:

• /alice:0/carol:0/sandy:0: Uniquely identifies the component instance “sandy” as the descendent of “alice” and “carol”.
• /alice:0/support:dan:0: Uniquely identifies the component instance “dan” as an element in the “support” collection descended from “alice”.

Note: Both components could resolve from the same component URL, but since they are two different instances at runtime they have different monikers.

Monikers are used by developer tools to interact with component instances on a target device.

For more details on component moniker syntax, see the component moniker reference.