12 Capabilities
Page 1 of 10
A service that sends shipping notices talks to a customer directory, a mail server and a log. In most languages any function can open a connection, read a file or print, so you learn what a function touches only by reading its body and every body it calls. In Una a function can only compute unless its uses, written or inferred, say otherwise. Every effect outside the program goes through a capability that the header names and that the caller hands over. This chapter shows how to read and write uses, how a run grants the host's capabilities, how to declare services of your own with handlers, and how to pass and narrow authority from one function to the next.
What you'll build
A dispatch step for a small store. For each order that has left the warehouse, it looks the customer up in a directory service, emails them a shipping notice through a mail service, and writes one line to a log. A customer who is unknown, who asked for no notices, or whose mail cannot be sent is skipped with a reason:
sent A-1001 to rosa@example.invalid
sent A-1002 to tomas@example.invalid
skipped A-1003: no customer has the id C-99
skipped A-1004: customer C-21 asked for no notices
skipped A-1005: the mail service did not answer; retry laterYou will learn to:
- read a header's
usesclauses as the complete list of what a function may do; - grant the host's capabilities to a program in
una.toml, and nothing more; - declare a capability with
capabilityandop, and give it code withhandler; - pass, rebind and narrow authority with
with; - run the same code against another service by installing another handler.
Download this chapter's packages: each step is a package under steps/, and the chapter's program is day-to-day/; run una check . and una run . in one.
Why it works this way
In a language with ambient authority, where code may act outside the program without being handed the right, any line of any library can reach the network, the file system or the clock. That is convenient until you review a change. A new dependency, or a helper three calls deep, can start sending data somewhere, and nothing in the signatures shows it. Tests have the same problem. A function that reaches for a global client is hard to run against a stand-in.
Una has no ambient authority. Three rules replace it:
- A capability is the only way out of the program. Printing, reading a file, asking the time or calling a service are operations on a capability, written
@name.operation(...). - A header lists the capabilities a function uses.
uses @mailer: Mailer[send]names a binding,@mailer, its capability,Mailer, and the operations allowed,send. A function's effects, including those of every function it calls, stay within itsuses. - Authority moves only downward, by name. A caller hands its bindings to a callee, under the callee's names, with
with. A capability reference is not a value: it cannot be stored, returned or passed as an ordinary argument.
The cost is a line in the header for each capability. In return, a reviewer reads what a function may do from its header, the checker holds every body to it, and the same code runs against another service by installing another handler.
A function's
uses, written or inferred, are the complete list of what it may do outside the program. Apubfunction writes them all, and one with nousesis pure: it can only compute its result. The host's capabilities reachmainonly asuna rungrants them: in[run] grantsofuna.toml, or with a--grantflag.