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:
- each capability the callee needs is handed over by name at the call, with
with(seewith), never taken from the caller's own capabilities implicitly (U3020); - what the call hands over lies within the ceiling (U3021);
- no release of a label can happen during the call (U3024).
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.
[package]
name = "shop"
version = "0.1.0"
edition = "0.3"
[boundaries]
"shop.resize" = ["Files[read]"]module shop.store
pub capability Files
op read(path: Text) -> Text
op write(path: Text, data: Text) -> Unitmodule shop.resize
import shop.store (Files)
pub shrink(path: Text) -> Text
uses @files: Files[read]
=
@files.read(path)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
[boundaries]
"<module path>" = ["<Capability>[<op>, ...]", ...]- Key. The path of a module of the package. It covers that module and every module below it by whole path segments:
"a.b"coversa.b.c, nota.bc. - Value. The ceiling: an array of names-only strings
C[op, ...], each with at least one operation, each operation once, and no condition or label.Cis a capability that the key's module sees, and eachopan operation it declares. An empty array,[], grants nothing.
Examples
A call that leaves the callee's capability to the caller's own context is U3020: the boundary takes nothing by name.
[package]
name = "shop"
version = "0.1.0"
edition = "0.3"
[boundaries]
"shop.resize" = ["Files[read]"]module shop.store
pub capability Files
op read(path: Text) -> Text
op write(path: Text, data: Text) -> Unitmodule shop.resize
import shop.store (Files)
pub shrink(path: Text) -> Text
uses @files: Files[read]
=
@files.read(path)-- 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:
[package]
name = "shop"
version = "0.1.0"
edition = "0.3"
[boundaries]
"shop.resize" = ["Files[read]"]module shop.store
pub capability Files
op read(path: Text) -> Text
op write(path: Text, data: Text) -> Unitmodule shop.resize
import shop.store (Files)
pub shrink(path: Text) -> Text
uses @files: Files[read]
=
@files.read(path)-- 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 = @filesAn 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:
[package]
name = "shop"
version = "0.1.0"
edition = "0.3"
[boundaries]
"shop.resize" = ["Files[read]"]module shop.store
pub capability Files
op read(path: Text) -> Text
op write(path: Text, data: Text) -> Unitmodule shop.resize
import shop.store (Files)
pub shrink(path: Text) -> Text
uses @files: Files[read]
=
@files.read(path)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.readWritten 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:
[package]
name = "shop"
version = "0.1.0"
edition = "0.3"
[boundaries]
"shop.vendor" = []
[trusted]
modules = ["shop.release"]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 = balancemodule shop.vendor
import shop.release (reveal)
pub count(balance: secret Int) -> Int = reveal(balance) + 1-- 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:
- Every way in is checked. A call is the usual way into a boundary, but not the only one. A boundary function used as a value outside it, a boundary's handler installed outside it, a policy call when the policy or its
viafunction is in a boundary, and a call from one boundary into another are checked the same way. - A callee that needs nothing. A call of a boundary function with no
usesneeds no grant. - Functions handed over. A lambda or a function value given to a boundary function runs inside the boundary, so what it may do counts against the ceiling (U3021), and a release it may reach counts too (U3024). An argument evaluated before the call, such as
count(reveal(balance)), runs in the caller and hands over nothing. - Examples. An example's
doline takes nowith, so an example outside a boundary can call into it directly only for functions with nouses. Otherwise it calls a function of its own module that hands the boundary its capabilities withwith, as in the example above. - Invalid tables. Each of these is U7002: a key that is not a module of the package, a key for a module that another key already covers, a malformed ceiling string, a capability named twice in one ceiling, an unknown capability or operation, a module of
[trusted] modulesinside a boundary, and a[run] entryinside a boundary. A malformed or unknown ceiling entry permits nothing. - The rest. Handlers, effect parameters (a parameter whose effects its caller chooses), function values whose code is not known at the call, and how a private caller's
usesare inferred have rules of their own, which the normative source gives in full.
Diagnostics
- U3020: a call into a boundary whose capability is not granted with
with. - U3021: a call that grants a boundary more than its ceiling.
- U3024: a call into a boundary from which a release is reachable.
- U7002: an invalid
[boundaries]table, or[boundaries]in an edition before0.3.
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
- spec/13 §7:
[boundaries]. - spec/05 §4 rule 5: calls into a boundary; spec/05 §9 rules 2, 4 and 5: inference, handlers and examples.
- spec/07 §6: U3024, and which function values a call into a boundary follows.
- Decision record: ADR 0093, for authority at module boundaries.