Home / Docs / Configure a package

[run] grants

Release v0.4.0Edition 0.1 and laterU3012U7002

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.

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

toml
[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:

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

[run]
entry = "shop"
grants = ["files:./data:read"]
src/shop.unauna
-- fails with U3012
module shop

pub main() -> Unit
  uses @files: Files[read, write]
=
  @files.write("orders.txt", content: "order 42")
    if error use unit

Edge cases

Only grant specs:

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

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

pub price(cents: Int) -> Int = cents

Further rules:

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