Home / Learn

Release v0.4.0

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:

Output
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 later

You will learn to:

  • read a header's uses clauses 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 capability and op, and give it code with handler;
  • 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:

  1. 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(...).
  2. 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 its uses.
  3. 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.

Key idea

A function's uses, written or inferred, are the complete list of what it may do outside the program. A pub function writes them all, and one with no uses is pure: it can only compute its result. The host's capabilities reach main only as una run grants them: in [run] grants of una.toml, or with a --grant flag.

View the Markdown

Next:12.1 Declaring what a function may do: uses in full