Home / Docs / Language guide
Capabilities and effects
7.1 Declaring capabilities
A capability describes authority over something outside the program. Its operations are signatures, which are assumptions about the external system.
module demo
pub kind Availability = SoldOut | Few | Open
pub kind Registration
name: Text
status: Availability
pub kind StoreError = Timeout | Corrupted
pub capability Registrations
op find(key: internal Hashed) -> Option[Registration]
fails StoreError
accepts internal
pub capability Audit
op record(key: internal Hashed, status: Availability) -> Unit
fails StoreError
accepts internal| Op clause | Meaning |
|---|---|
requires p |
precondition on arguments, proven at each call |
ensures q |
postcondition: an assumption callers may rely on; handlers are verified against it |
fails E |
the operation may fail with E |
accepts l |
the most sensitive label its arguments may carry (default public) |
Canonical op clause order: every requires, every ensures, then at most one fails and at most one accepts (U0102). Operations cannot declare edit or take parameters (U2020).
7.2 Using capabilities
module demo
pub kind Availability = SoldOut | Few | Open
pub kind Registration
name: Text
status: Availability
pub kind StoreError = Timeout | Corrupted
pub kind CheckInError = NotRegistered | Unavailable
pub capability Registrations
op find(key: internal Hashed) -> Option[Registration]
fails StoreError
accepts internal
pub capability Audit
op record(key: internal Hashed, status: Availability) -> Unit
fails StoreError
accepts internal
pub check_in(key: internal Hashed) -> Availability
uses @registrations: Registrations[find]
uses @audit: Audit[record]
fails CheckInError
=
let registration = @registrations.find(key)
if error fail Unavailable
if none fail NotRegistered
@audit.record(key, status: registration.status)
if error fail Unavailable
registration.statususes @x: C[ops]grants operationsopsof capabilityCunder the name@x. Omitting[ops]grants all of them.@x.op(args)works only if@xis in scope (U3001) andopis granted (U3002).
7.3 Passing capabilities: by name, downward only
A callee whose header says uses @x: C[ops] receives the caller's @x automatically. The caller must hold @x with at least those operations (U3001, U3002). Holding more is fine: the callee is limited to what it declares, so passing a capability attenuates it.
7.4 with: rebinding and handler instances
module demo
pub kind Registration
name: Text
pub capability Registrations
op find(key: Text) -> Option[Registration]
handler in_memory(rows: List[Registration]) for Registrations
op find(key) = rows.first()
handler none_found() for Registrations
op find(key) = None
known(key: Text) -> Bool
uses @registrations: Registrations[find]
=
let found = @registrations.find(key)
found.is_some()
pub check(key: Text, rows: List[Registration]) -> Bool
uses @primary_store: Registrations[find]
=
let in_store = known(key) with @registrations = @primary_store
let in_rows = known(key) with @registrations = in_memory(rows: rows)
let nowhere = known(key) with @registrations = none_found()
in_store or in_rows or nowhere@x = @ymakes the callee's@xthe caller's@y. Both must be the same capability.@x = h(args)installs handlerhas@x. The handler's ownusesbecome effects of the caller. What happens when the caller lacks them depends on the caller:- a
pubcaller that does not declare them gets U3003 at the statement: "handlerhuses@inner: Inner[ping], but this code declares nouses, so its effects would exceed its header"; - a private caller has them inferred, and the error appears where the capability is really missing. In an example, for instance, it is U3001: "
gneeds@inner: Inner[ping], which nogivenline binds".
- a
- Scope: the binding covers only that statement's expression.
- Statements only.
withis part of a statement, so it cannot appear in the short function form:g() -> Unit = f() with @a = h()is U0101. Use the long form, with the statement in the body. - Several bindings are separated by commas:
with @a = @b, @c = h().
7.5 Handlers
A handler implements a capability in Una. in_memory and none_found above are handlers:
- Complete and matching. A handler implements every operation (U3011), with the right parameter count (U3010). Types come from the capability declaration.
- Ordinary code. Operation bodies are type-checked, flow-checked and verified against the operation's
ensures. They may fail only with the operation's error kind. - Parameters (
rowsabove) are captured values. - Own authority. A handler may declare its own
usesbefore its operations. - Not values. Handlers are installed only through
withorgiven.
7.6 The second-class rule
Capability references are not values. @x cannot be:
- bound with
let; - passed as an ordinary argument;
- returned;
- stored in a kind;
- compared or interpolated.
Any of these is U3005. A bare @x is allowed only on either side of a with binding or in given. Effectful or fallible lambdas follow the same restrictions, except that they can be passed as arguments (U3006). Such a lambda cannot handle a failure, so it calls only operations that cannot fail (U3007 otherwise, §4.6). Second-class types are not type arguments either (U3016).
Consequence: authority only flows downward through calls, and every function's reachable authority is visible in headers.
7.7 Host capabilities
The runtime implements these; they are part of the prelude.
| Capability | Operation | Fails | Accepts |
|---|---|---|---|
Console |
print(line: Text) -> Unit |
public |
|
Clock |
now() -> Int (ms since Unix epoch) |
public |
|
Env |
get(name: Text) -> Option[internal Text] |
public |
|
Files |
read(path: Text) -> internal Text |
FileError |
public |
Files |
write(path: Text, content: Text) -> Unit |
FileError |
internal |
Keys |
hmac(key_name: Text, data: Text) -> internal Hashed |
KeyError |
public for key_name, any label for data; the result carries the label of data |
Http (edition 0.2) |
get(url: Text, headers: List[Header], key_name: Option[Text]) -> internal Response |
HttpError |
internal |
Http |
post(url: Text, headers: List[Header], body: Text, key_name: Option[Text]) -> internal Response |
HttpError |
internal |
Http |
put(url: Text, headers: List[Header], body: Text, key_name: Option[Text]) -> internal Response |
HttpError |
internal |
Http |
delete(url: Text, headers: List[Header], key_name: Option[Text]) -> internal Response |
HttpError |
internal |
- Entry. Host capabilities enter only through
main'suses, and only ifuna run, or the native executable, grants them. An ungranted capability is U3012 before execution starts. - Grant syntax:
console,clock,env,keys:<keyfile>,files:<path>:read,files:<path>:write, and in edition0.2http:<origin>orhttp:<origin>:<methods>(by defaultget). Http(spec/24).Headerhasname: Textandvalue: internal Text, andResponsehasstatus: Int,headers: List[Header]andbody: Text. A status is not a failure:HttpErrorisDenied,BadUrl,BadRequest,Unreachable,TimedOut,TooLarge,TlsorProtocol.key_name: Some(n)sends the keynof thekeys:grants asAuthorization: Bearer <key>; a token another header carries goes in as a header value, through a policy tointernalwhen it issecret. The guide for agents, §17, has an example with a stand-in handler.Filespaths. A path is relative to the grant's prefix: withfiles:data:read,@files.read("readings.txt")readsdata/readings.txt, and"data/readings.txt"would look fordata/data/readings.txtand fail withNotFound. A path stays confined to the prefix: an absolute path, or a..that leaves it, fails withDenied.FileErrorisNotFound,DeniedorIo, andKeyErrorisUnknownKey.- Tests and handlers. You can write handlers for host capabilities, for example a fake
Keysin tests (§17).