Home / Docs / Language guide

Capabilities and effects

Release v0.4.0

7.1 Declaring capabilities

A capability describes authority over something outside the program. Its operations are signatures, which are assumptions about the external system.

una
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

una
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.status

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

una
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

7.5 Handlers

A handler implements a capability in Una. in_memory and none_found above are handlers:

7.6 The second-class rule

Capability references are not values. @x cannot be:

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

Constructs