Home / Docs / Configure a package
[run] grants
What it does
grants lists the host capabilities, the authority to use the console, files, the clock and the like, that una run gives the entry's main. Each is written as a grant spec, a short text such as "console" or "files:./data:read" that names one capability and how far it reaches. There is no ambient authority, no authority a program has just by running: a host capability that is not granted is not there, and una check reports a main that needs one.
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
[run]
grants = ["console", "clock", "env", "keys:<keyfile>", "files:<path>:read", "files:<path>:write", "files:<path>:read,write", ...]The grant specs:
| Grant spec | Grants |
|---|---|
console |
Console[print] |
clock |
Clock[now] |
env |
Env[get] |
keys:<keyfile> |
Keys[hmac], with the keys of the file |
files:<path>:read, files:<path>:write, files:<path>:read,write |
the Files operations of the mode, under the path |
http:<origin>, http:<origin>:<methods> (edition 0.2) |
Http operations for the origin |
http: with limit suffixes, such as http:<origin>;10/second (edition 0.4; this spec form is for --grant, and ita.una writes limits as lines) |
the same, at most at that rate (spec/27 §9) |
serve:<scheme>://<address>:<port>, with ;<item> suffixes (edition 0.4; this spec form is for --grant, and ita.una writes a serve line with item lines) |
accepting connections at that address, and HttpServer (spec/31 §2; see Serving HTTP) |
una run also takes --grant <spec> flags; the grants of una.toml and of the flags apply together. The grants of edition 0.4 are given with --grant, or in the run section of ita.una (see ita.una); in ita.una, limits and serve items are lines below their grant. In una.toml, a serve: spec is U7002 in every edition.
Examples
A host operation of main that no grant allows is reported before the program runs. Here the grant reads files and main writes one:
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"
[run]
entry = "shop"
grants = ["files:./data:read"]-- fails with U3012
module shop
pub main() -> Unit
uses @files: Files[read, write]
=
@files.write("orders.txt", content: "order 42")
if error use unitEdge cases
Only grant specs:
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"
[run]
entry = "shop"
grants = ["network"]-- fails with U7002
module shop
pub price(cents: Int) -> Int = centsFurther rules:
- Files stay under the grant. A
Filespath is resolved under the grant's path, and path resolution never escapes it. Races on a path and hard links are outside the model. - Relative paths in
una.tomlgrants resolve against the package root, and those of flags against the current directory. - Host capabilities. See host capabilities and grants.
Diagnostics
Edition
The grant specs of v0.1 are in editions 0.1, 0.2 and 0.3. Edition 0.2 adds the http: grants, which edition 0.3 keeps. From edition 0.4, a package lists its grants in ita.una instead of una.toml, an http grant may carry limits, and the serve grant lets a program accept connections.
Normative source
- spec/13 §7:
[run]; spec/13 §5: grant specs anduna run. - spec/05 §7: host capabilities; spec/14 §3: their operations; spec/24 §2:
Httpgrants. - spec/07 §1: what is outside the model.