Home / Docs / Language guide / Capabilities and effects

Host capabilities and grants

Release v0.4.0Edition 0.1 and laterU3012U4003U6005

What it does

Host capabilities are the ones the runtime implements: Console, Clock, Env, Files and Keys, from edition 0.2 on also Http, and from edition 0.4 on also HttpServer, which a module imports from std.host (see Serving HTTP). They enter a program only through main's uses clauses, and the runtime provides them only when they are granted (allowed by whoever runs the program), in una.toml or with --grant. Other functions receive them from their callers by name, like any capability.

Learn more: The host's capabilities and grants.

una.tomltoml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

[run]
entry = "shop"
grants = ["console"]
src/shop.unauna
module shop

pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("The shop is open")

Forms

The host capabilities:

Capability Operation Fails Accepts
Console print(line: Text) -> Unit public
Clock now() -> Int 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
Http (edition 0.2) get(url: Text, headers: List[Header], key_name: Option[Text]) -> internal Response HttpError internal
Http (edition 0.2) post(url: Text, headers: List[Header], body: Text, key_name: Option[Text]) -> internal Response HttpError internal
Http (edition 0.2) put(url: Text, headers: List[Header], body: Text, key_name: Option[Text]) -> internal Response HttpError internal
Http (edition 0.2) delete(url: Text, headers: List[Header], key_name: Option[Text]) -> internal Response HttpError internal

internal is a label: a mark on data that says how sensitive it is, which the checker follows wherever the data goes (see labels).

The grant specs:

They are given in [run] grants of una.toml, or as --grant flags of una run.

Examples

A host operation of main that no grant allows is reported by una check, before the program runs:

una.tomltoml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

[run]
entry = "shop"
grants = ["console"]
src/shop.unauna
-- fails with U3012
module shop

pub main() -> Unit
  uses @console: Console[print]
  uses @clock: Clock[now]
=
  let opened = @clock.now()
  @console.print("opened at {opened}")

What Env.get and Files.read return is internal, so printing it to the console, which accepts only public, is rejected. Lowering a label takes a policy, a declared and reviewed release of data:

una.tomltoml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

[run]
entry = "shop"
grants = ["console", "env"]
src/shop.unauna
-- fails with U4003
module shop

pub main() -> Unit
  uses @console: Console[print]
  uses @env: Env[get]
=
  let name = @env.get("SHOP_NAME")
    if none use ""
  @console.print(name)

Edge cases

Further rules:

Diagnostics

Edition

The five host capabilities of v0.1 are in every edition. Edition 0.2 adds Http, with its grants http:<origin> and http:<origin>:<methods>. Edition 0.4, a preview, adds HttpServer, imported from std.host and granted by a serve: grant (spec/31 §1, spec/31 §2), lets an http grant carry limits, and moves a package's grants to ita.una.

Normative source