Namespaces are the backbone of file access and service discovery in Fuchsia.
A namespace is a composite hierarchy of files, directories, sockets, services, devices, and other named objects which are provided to a component by its environment.
Let's unpack that a little bit.
Objects are named: The namespace contains objects which can be enumerated and accessed by name, much like listing a directory or opening a file.
Composite hierarchy: The namespace is a tree of objects which has been assembled by combining together subtrees of objects from other namespaces into a composite structure where each part has been assigned a path prefix by convention.
Namespace per component: Every component receives its own namespace tailored to meet its own needs. It can also publish objects of its own to be included in other namespaces.
Constructed by the environment: The environment which instantiates a component is responsible for constructing an appropriate namespace for that component within that scope.
Namespaces can also be created and used independently from components although this document focuses on typical component-bound usage.
You have probably already spent some time exploring a Fuchsia namespace; they are everywhere. If you type
ls / at a command-line shell prompt you will see a list of some of the objects which are accessible from the shell's namespace.
Unlike other operating systems, Fuchsia does not have a “root filesystem”. As described earlier, namespaces are defined per-component rather than globally or per-process.
This has some interesting implications:
The items within a namespace are called objects. They come in various flavors, including:
To access an object within a namespace, you must already have another object in your possession. A component typically receives channel handles for objects in the scope of its namespace during Namespace Transfer.
You can also create new objects out of thin air by implementing the appropriate FIDL interfaces.
Given an object's channel, you can open a channel for one of its sub-objects by sending it a FIDL message which includes an object relative path expression which identifies the desired sub-object. This is much like opening files in a directory.
Notice that you can only access objects which are reachable from the ones you already have access to. There is no ambient authority.
We will now define how object names and paths are constructed.
An object name is a locally unique label by which an object can be located within a container (such as a directory). Note that the name is a property of the container's table of sub-objects rather than a property of the object itself.
cat designates a furry object located within some unspecified recipient of an
Objects are fundamentally nameless but they may be called many names by others.
Object names are represented as binary octet strings (arbitrary sequences of bytes) subject to the following constraints:
Object names are valid arguments to a container's
Open() method. See FIDL Interfaces.
It is intended that object names be encoded and interpreted as human-readable sequences of UTF-8 graphic characters, however this property is not enforced by the namespace itself.
Consequently clients are responsible for deciding how to present names which contain invalid, undisplayable, or ambiguous character sequences to the user.
TODO(jeffbrown): Document a specific strategy for how to present names.
An object relative path expression is an object name or a
/-delimited sequence of object names designating a sequence of nested objects to be traversed in order to locate an object within a container (such as a directory).
house/box/cat designates a furry object located within its containing object called
box located within its containing object called
house located within some unspecified recipient of an
An object relative path expression always traverses deeper into the namespace. Notably, the namespace does not directly support upwards traversal out of containers (e.g. via
..) but this feature may be partially emulated by clients (see below).
Object relative path expressions have the following additional constraints:
Object relative path expressions are valid arguments to a container's
Open() method. See FIDL Interfaces.
A client interpreted path expression is a generalization of object relative path expressions which includes optional features which may be emulated by client code to enhance compatibility with programs which expect a rooted file-like interface.
Technically these features are beyond the scope of the Fuchsia namespace protocol itself but they are often used so we describe them here.
..path segments by folding segments together (assuming the container's path is known) through a process known as client-side “canonicalization”.
/places/house/box/../sofa/cat designates a furry object located at
places/house/sofa/cat within some client designated “root” container.
Client interpreted path expressions that contain these optional features are not valid arguments to a container's
Open() method; they must be translated by the client prior to communicating with the namespace. See FIDL Interfaces.
fdio implements client-side interpretation of
.. paths in file manipulation APIs such as
When a component is instantiated in an environment (e.g. its process is started), it receives a table which maps one or more namespace path prefixes to object handles.
The path prefixes in the table encode the intended significance of their associated objects by convention. For example, the
pkg prefix should be associated with a directory object which contains the component's own binaries and assets.
More on this in the next section.
This section describes the conventional layout of namespaces for typical components running on Fuchsia.
The precise contents and organization of a component‘s namespace varies greatly depending on the component’s role, type, identity, scope, relation to other components, and rights. See [sandboxing.md] for information about how namespaces are used to create sandboxes for applications.
For more information about the namespace your component can expect to receive from its environment, please consult the documentation related to the component type you are implementing.
There are some typical objects which a component namespace might contain:
pkg/: binaries and assets (read-only, except perhaps for development)
data/: local persistent storage (read-write, private to the package)
tmp/: temporary storage (read-write, private to the package)
svc/: services offered to the component
fuchsia.com/: services defined by the Fuchsia SDK
compositor/: create graphical objects
log/: logging service
vendor.com/: services defined by some vendor
dev/: device tree (relevant portions visible to privileged components as needed)
env/: introspect the structure of the environment (privileged components only)
boot/: information about the “boot” environment
components/: information about components within the boot environment
1234/: information about component instance #1234
name: component name
origin: component origin url
local/: component's own namespace as defined by its environment
pub/: objects published by the component
2345/: information about component instance #2345
children/: information about sub-environments of the boot environment
device/: information about the “device” sub-environment
3456/: information about component instance #3456
Here is some more information about a few abstractions which interact with and support the Fuchsia namespace protocol.
Filesystems make files available in namespaces.
A filesystem is simply a component which publishes file-like objects which are included in someone else's namespace.
Services live in namespaces.
A service is a well-known object which provides an implementation of a FIDL interface which can be discovered using the namespace.
A service name corresponds to a path within the
svc branch of the namespace from which a component can access an implementation of the service.
For example, the name of the default Fuchsia logging service is
fuchsia.com/log and its location in the namespace is
Components consume and extend namespaces.
A component is an executable program object which has been instantiated within some environment and given a namespace.
A component participates in the Fuchsia namespace in two ways:
It can use objects from the namespace which it received from its environment, notably to access its own package contents and incoming services.
It can publish objects through its environment in the form of a namespace, parts of which its environment may subsequently make available to other components upon request. This is how services are implemented by components.
Environments construct namespaces.
An environment is a container of components. Each environment is responsible for constructing the namespace which its components will receive.
The environment decides what objects a component may access and how the component's request for services by name will be bound to specific implementations.
TODO(jeffbrown): Explain how the namespace interfaces work.