Home / Docs / Language guide / Capabilities and effects
Host capabilities and grants
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.
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"
[run]
entry = "shop"
grants = ["console"]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:
console,clockandenv;keys:<keyfile>;files:<path>:read,files:<path>:writeandfiles:<path>:read,write;- from edition
0.2on,http:<origin>andhttp:<origin>:<methods>.
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:
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"
[run]
entry = "shop"
grants = ["console"]-- 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:
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"
[run]
entry = "shop"
grants = ["console", "env"]-- 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:
- Files stay inside the grant. A
Filespath is resolved against the grant's prefix (the directory the grant names). An absolute path, a..that leaves the prefix, or a final component that is a symbolic link (a file that points to another file) fails withDenied; path resolution never escapes the prefix. - Keys stay outside values.
Keysloads its keys from the grant's file, and key material never enters Una values. The result ofhmacis labeledinternal, joined with every label of the type ofdata, and lowering it takes a policy.key_nameaccepts onlypublic, so a labeled key name, or a call under a raised program counter (when the conditions that decided whether this line runs read labeled data; see Branches and failures: implicit flows), is U4003. - Labeled failures. Whether a host operation fails is labeled by the arguments that decide it: the path of
Files, not the content; the key name ofKeys.hmac, not the data; and every argument ofHttp, so its failures areinternal. AFiles.writeto aninternalpath failsinternal, and everyFilesfailure also carries the package's file-state label: the labels that decide where the package's writes land and whether they run. - Host text. When
Files.readorEnv.getmeets bytes that are not valid UTF-8, the run aborts with U6005. - Out of the model. Races on a path, hard links, resource limits and other processes are outside what the checker reasons about, and
una reportlists such channels underout_of_model. - User handlers. Code may implement a host capability with its own handler, such as a fake
Keysin examples. The host implementations are used only byuna runand by an executable thatuna buildmakes. - Declared in
std.host. A user capability with the same name is a different declaration.
Diagnostics
- U3012: a host operation of
mainthat no grant allows, or ausesofmainthat no grant can provide. - U4003: labeled data sent to an operation that does not accept its label.
- U6005: at run time, host text that is not valid UTF-8.
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
- spec/05 §7: host capabilities, rules 1 to 4.
- spec/14 §3: the operations,
Filespaths,Keys, labels and host text. - spec/13 §5: grant specs and
una run; spec/13 §7:[run] grants. - spec/07 §4: sinks; spec/07 §7 rule 4: labeled failures.
- spec/24 §1: the
Httpoperations; spec/24 §2:Httpgrants; spec/24 §5 rule 3: the labels ofHttpfailures. - spec/31 §1:
HttpServer; spec/31 §2:serve:grants (edition0.4). - Decision record: ADR 0039, for the labels of
Keys.hmac.