Directory capabilities allow components to connect to directories provided by other components.
Providing directory capabilities
To provide a directory capability, a component must define the capability and
route it from self
. The component hosts the
directory capability in its outgoing directory.
To define the capability, add a capabilities
declaration for it:
{
capabilities: [
{
directory: "data",
rights: ["r*"],
path: "/published-data",
},
],
}
This defines a capability hosted by this component whose outgoing directory path
is /published-data
, and whose maximum usable
rights are r*
.
Routing directory capabilities
Components route directory capabilities by either:
When a component wants to make one of its directories available to other components, it specifies the path of that directory in its outgoing directory in one of the following ways:
Exposing
To expose the directory to a parent:
{
expose: [
{
directory: "data",
from: "#child-a",
},
],
}
Optionally, you may narrow the rights on the directory:
{
expose: [
{
directory: "data",
from: "#child-a",
rights: ["r*"],
},
],
}
Offering
To offer a directory to a child:
{
offer: [
{
directory: "data",
from: "self",
to: [ "#child-a", "#child-b" ],
},
],
}
Optionally, you may narrow the rights on the directory:
{
offer: [
{
directory: "data",
from: "self",
rights: ["rw*"],
to: [ "#child-a", "#child-b" ],
},
],
}
Consuming directory capabilities
When a component wants to make use of a directory from its parent, it does so by using the directory. This will make the directory accessible from the component's namespace.
This example shows a directory named data
that is included in the component's
namespace. If the component instance accesses this directory during its
execution, the component framework performs
capability routing to find the component that provides it.
Then, the framework connects the directory from the component's namespace to
this provider.
{
use: [
{
directory: "data",
rights: ["r*"],
path: "/data",
},
],
}
rights
must be a subset of the rights attached
to the directory.
See //examples/components/routing
for a working example of
routing a directory capability from one component to another.
Directory capability rights
As directories are offered and exposed throughout the system a user may want to restrict what components who have access to this directory may do. For example, a component could expose a directory as read-write to its parent realm, which could expose that directory it to its children as read-write but to its parent as read-only.
Directory rights allow any directory declaration to specify a rights field that indicates the set of rights that the directory would like to offer, expose or use.
Example
This example shows component A
requesting access to data
with read-write
rights:
// A.cml
{
use: [
{
directory: "data",
rights: ["rw*"],
path: "/data",
},
],
}
Furthermore, parent component B
offers the directory data
to component A but
with only read-only rights. In this case the routing fails and data
wouldn't
be present in A's namespace.
// B.cml
{
capabilities: [
{
directory: "data",
rights: ["r*"],
path: "/published-data",
},
],
offer: [
{
directory: "data",
from: "self",
to: [ "#A" ],
},
],
}
Inference Rules
Directory rights are required in the following situations:
- use - All directories use statements must specify their directory rights.
- capability - All
directory
capability
declarations must specify rights.
If an expose or offer directory declaration does not specify optional rights, it
will inherit the rights from the source of the expose or offer. Rights specified
in a use
, offer
, or expose
declaration must be a subset of the rights set
on the capability's source.
Framework directory capabilities
Some directory capabilities are available to all components through the
framework. When a component wants to use one of these directories, it does so by
using the directory with a source of framework
.
{
use: [
{
directory: "hub",
from: "framework",
rights: ["r*"],
path: "/hub",
},
],
}