<<../../_v2_banner.md>>
Directory capabilities allows components to connect to directories provided by other components.
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*
.
Components route directory capabilities by either exposing them or offering them.
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:
To expose the directory to a parent:
{ expose: [ { directory: "data", from: "#child-a", }, ], }
You may optionally specify:
To offer a directory to a child:
{ offer: [ { directory: "data", from: "parent", to: [ "#child-a", "#child-b" ], }, ], }
You may optionally specify:
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][glossary.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", }, ], }
You must specify rights
. You may optionally specify subdir
.
As directories are offered and exposed throughout the system a user may want to restrict the actions that other components may perform with this directory. For example, a component might expose a directory as read-write to its parent realm, which could in turn expose that directory to its children as read-only.
Directory rights enable any directory declaration, as well as mentions of it in offer, expose, and use, to include a rights field that restricts the set of rights for that directory.
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" ], }, ], }
Directory rights are required in the following situations:
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.
You may expose
, offer
, or use
a subdirectory of a directory capability:
{ offer: [ { directory: "data", from: "parent", to: [ "#child-a", "#child-b" ], subdir: "children", }, ], }
You may expose
or offer
a directory capability by a different name:
{ offer: [ { directory: "data", from: "#child-a", to: [ "#child-b" ], as: "a-data", }, ], }
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", }, ], }