Home / Docs / Configure a package

[boundaries]

What it does

A capability is the authority to act outside the program, such as reading or writing files, and each of its operations is one such action, such as read. Una code holds only the capabilities its callers hand it. A boundary is a part of the package that should never hold more than a fixed set of them: a library copied in from a vendor, or a plug-in written by another team. Its ceiling is that set. A release is the one way labeled data, such as a customer's secret balance, may go to a lower label: a call of a policy (see policy).

Take a shop that copies in an image-resizing library as the module shop.resize. The library only needs to read image files. With a ceiling of Files[read], the shop knows, from una.toml alone, that the library can never write or delete a file, whatever its code says and however it changes. [boundaries] names each boundary module and its ceiling, and every call from outside a boundary into it is checked:

So the code that calls a boundary states, at each call, exactly what it hands over, and the boundary can never receive more than its ceiling.

Learn more: A ceiling for a module: boundaries and Limits on authority.

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

[boundaries]
"shop.resize" = ["Files[read]"]
src/shop/store.unauna
module shop.store

pub capability Files
  op read(path: Text) -> Text
  op write(path: Text, data: Text) -> Unit
src/shop/resize.unauna
module shop.resize

import shop.store (Files)

pub shrink(path: Text) -> Text
  uses @files: Files[read]
=
  @files.read(path)
src/shop/app.unauna
module shop.app

import shop.resize (shrink)
import shop.store (Files)

pub preview(path: Text) -> Text
  uses @files: Files[read, write]
=
  shrink(path) with @files = @files[read]

preview holds Files[read, write], and grants the boundary only read, with a narrowed rebinding (see with).

Forms

toml
[boundaries]
"<module path>" = ["<Capability>[<op>, ...]", ...]

Examples

A call that leaves the callee's capability to the caller's own context is U3020: the boundary takes nothing by name.

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

[boundaries]
"shop.resize" = ["Files[read]"]
src/shop/store.unauna
module shop.store

pub capability Files
  op read(path: Text) -> Text
  op write(path: Text, data: Text) -> Unit
src/shop/resize.unauna
module shop.resize

import shop.store (Files)

pub shrink(path: Text) -> Text
  uses @files: Files[read]
=
  @files.read(path)
src/shop/app.unauna
-- fails with U3020
module shop.app

import shop.resize (shrink)
import shop.store (Files)

pub preview(path: Text) -> Text
  uses @files: Files[read]
=
  shrink(path)

The first repair of that U3020 is the grant with @files = @files[read], narrowed to what shrink declares, since it lies within the ceiling, and una fix applies it. When the caller holds several bindings that permit read and none is named @files, the repair lists them and una fix applies nothing: which store the library reads is yours to decide. When the callee needs an operation the ceiling withholds, the repair offers no grant: it suggests a handler whose own uses lie within the ceiling, and names the operations the ceiling withholds. No repair raises a ceiling.

A grant counts at every operation its binding permits, not only those the callee needs. Rebinding a read-write binding into a boundary whose ceiling is Files[read] is U3021:

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

[boundaries]
"shop.resize" = ["Files[read]"]
src/shop/store.unauna
module shop.store

pub capability Files
  op read(path: Text) -> Text
  op write(path: Text, data: Text) -> Unit
src/shop/resize.unauna
module shop.resize

import shop.store (Files)

pub shrink(path: Text) -> Text
  uses @files: Files[read]
=
  @files.read(path)
src/shop/app.unauna
-- fails with U3021
module shop.app

import shop.resize (shrink)
import shop.store (Files)

pub preview(path: Text) -> Text
  uses @files: Files[read, write]
=
  shrink(path) with @files = @files

An example outside a boundary cannot hand over capabilities at its do line, which takes no with. To exercise a boundary function that needs a capability, the example calls a function of its own module that hands it over. The example's given handler, a stand-in for the real files, reaches that function, which is outside the boundary, and is checked where it is installed, at the given line, as any handler that ends up handed to a boundary is:

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

[boundaries]
"shop.resize" = ["Files[read]"]
src/shop/store.unauna
module shop.store

pub capability Files
  op read(path: Text) -> Text
  op write(path: Text, data: Text) -> Unit
src/shop/resize.unauna
module shop.resize

import shop.store (Files)

pub shrink(path: Text) -> Text
  uses @files: Files[read]
=
  @files.read(path)
src/shop/app.unauna
module shop.app

import shop.resize (shrink)
import shop.store (Files)

handler fixed(text: Text) for Files
  op read(path) = text
  op write(path, data) = unit

pub preview(path: Text) -> Text
  uses @files: Files[read, write]
=
  shrink(path) with @files = @files[read]

test "a preview reads through the boundary"
  given @files = fixed("pixels")
  do preview("a.png")
  expect result == "pixels"
  expect performed @files.read

Written as do shrink("a.png"), the same example is U3020: nothing hands its given binding to the boundary by name.

A boundary never releases a label. A call into a boundary that may lead to a policy call, in the callee or in any function it calls, is U3024:

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

[boundaries]
"shop.vendor" = []

[trusted]
modules = ["shop.release"]
src/shop/release.unauna
trusted module shop.release

pub policy reveal
  from secret Int
  to public Int
  via open
  purpose "count"
  owner ops

open(balance: secret Int) -> public Int = balance
src/shop/vendor.unauna
module shop.vendor

import shop.release (reveal)

pub count(balance: secret Int) -> Int = reveal(balance) + 1
src/shop/app.unauna
-- fails with U3024
module shop.app

import shop.vendor (count)

pub total(balance: secret Int) -> Int = count(balance)

The repair is to keep releases in the consumer's trusted modules, before or after the call into the boundary.

Edge cases

Further rules:

Diagnostics

Edition

From edition 0.3, a preview. In edition 0.3 the boundaries are the [boundaries] table of una.toml; from edition 0.4 they are the boundaries section of ita.una, with the same rules (see ita.una). In editions 0.1 and 0.2, [boundaries] is an unknown table (U7002), and the narrowed rebinding with @x = @y[ops] is a syntax error.

Normative source