Home / Learn / 13 Limits on authority
13.2 A ceiling for a module: boundaries
Page 3 of 9
13.2.1 What a boundary is
When a store lets a contractor in to service the label printer, it gives them a badge that opens the stockroom and nothing else. Whatever the contractor brings, the badge decides which doors open.
A boundary is such a badge for a module, written in una.toml. It marks a module, usually vendored code, a supplier's code copied into the package's src/ (chapter 11), and gives it a ceiling: the most the rest of the package may ever grant it, as a list of capabilities and operations. A call into the module that would grant more fails the check, and every call into it must grant each capability by hand, with with.
13.2.2 Why give a module a ceiling
The store copied a label printer's module into src/vendor/labels.una. A new version of it arrives, and besides printing, it now reads the clock. Its header says so, but the output does not change:
--- a/src/vendor/labels.una
+++ b/src/vendor/labels.una
@@ -3 +3 @@
---- Prints a shelf label for a product.
+--- Prints a shelf label for a product. This version also reads the clock.
@@ -5,0 +6 @@
+ uses @clock: Clock[now]
@@ -6,0 +8 @@
+ let printed_at = @clock.now()This package has no boundary yet. The store accepts the new version with two small edits of its own: main declares that it holds the clock, and una.toml grants it. Without the first, una check reports U3001 at the call; without the second, una check and una run report U3012 (chapter 12).
--- a/una.toml
+++ b/una.toml
@@ -8,5 +8 @@
-grants = ["console"]
-
-# Code from the label printer's supplier: the most the store may ever grant it.
-[boundaries]
-"vendor.labels" = ["Console[print]"]
+grants = ["console", "clock"]module store.app
import vendor.labels (print_label)
pub main() -> Unit
uses @console: Console[print]
uses @clock: Clock[now]
=
print_label("LAMP-01", price: "19.90")[LAMP-01 | 19.90]The package checks and runs, and the label looks as before. The call itself did not change: print_label takes the clock by name, as any call passes the capabilities its callee needs (chapter 12). Nothing at the call says where the clock goes, and once the store's code holds a capability for a job of its own, a later version of the supplier's module can start using it with no change at all in the store's code. With access to files, the same change could read data it was never meant to see. A boundary makes every such grant visible at the call, and turns one beyond the ceiling into an error.
13.2.3 How to write [boundaries]
[package]
name = "store"
version = "0.1.0"
edition = "0.3"
[run]
entry = "store.app"
grants = ["console"]
# Code from the label printer's supplier: the most the store may ever grant it.
[boundaries]
"vendor.labels" = ["Console[print]"]edition = "0.3".[boundaries]exists only in edition0.3.[boundaries]. The table of boundaries."vendor.labels". The key: the module path of a module of the package, in quotes, since it holds a dot. It also covers every module below it, by whole parts of the path:vendor.labelscoversvendor.labels.fonts, but notvendor.labelsmith.["Console[print]"]. The ceiling: an array of texts, each a capability with the operations it may receive,Capability[operation, …], with at least one operation. It names no binding and no condition: a ceiling names capabilities and operations only.
13.2.4 Printing labels through a boundary
The module itself is ordinary Una. It declares what it uses, as any public function does:
module vendor.labels
--- Prints a shelf label for a product.
pub print_label(sku: Text, price: Text) -> Unit
uses @console: Console[print]
=
@console.print("[{sku} | {price}]")The store's code calls it:
module store.app
import vendor.labels (print_label)
pub main() -> Unit
uses @console: Console[print]
=
print_label("LAMP-01", price: "19.90") with @console = @console[LAMP-01 | 19.90]A call into the boundary takes nothing by name. The caller grants each capability with with, here with @console = @console: the label module's @console is the app's own @console. Elsewhere, this rebinding would be redundant; at a boundary it is the grant, so every call into the module shows exactly what it receives.
13.2.5 How calls into a boundary are checked
A call into a boundary is a call from code outside the boundary to a function or a handler inside it. Code inside the boundary calls its own functions as usual.
13.2.5.1 Everything is granted with with (U3020)
Call the label module the usual way, without with:
--- a/src/store/app.una
+++ b/src/store/app.una
@@ -8 +8 @@
- print_label("LAMP-01", price: "19.90") with @console = @console
+ print_label("LAMP-01", price: "19.90")[U3020] Error: `print_label` is in the boundary `vendor.labels` and needs `@console: Console[print]`, which a call into it grants only with `with`
╭─[ src/store/app.una:8:3 ]
│
8 │ print_label("LAMP-01", price: "19.90")
│ ───────────────────┬──────────────────
│ ╰──────────────────── `print_label` is in the boundary `vendor.labels` and needs `@console: Console[print]`, which a call into it grants only with `with`
│
├─[ src/vendor/labels.una:5:3 ]
│
5 │ uses @console: Console[print]
│ ──────────────┬──────────────
│ ╰──────────────── the boundary's requirement
│
│ Help: repair 1: grant `with @console = @console[print]`, narrowed to the operations the callee declares, which lie within the ceiling of `vendor.labels`; edit src/store/app.una:8:41..8:41 to " with @console = @console[print]"
│
│ Note: run `una explain U3020` for an explanation
───╯
1 of 1 diagnostics have an edit that `una fix` applies (`una fix --dry-run` lists them)The first mark is the call, and the second is the requirement inside the boundary that the call left to be met by name. The fix is a with at the call, as in Printing labels through a boundary. The repair writes one, and una fix . applies it: with @console = @console[print], a grant narrowed to the operations that the callee declares, a form that Granting less at the call explains. Here the app's @console permits only print, so the narrowed grant and with @console = @console hand over the same. When no such grant lies within the ceiling, the repair is a description instead, and una fix applies nothing.
13.2.5.2 What a call grants stays within the ceiling (U3021)
Now add the boundary to the package of Why give a module a ceiling, with the new version of the module, and grant it the clock with with:
module store.app
import vendor.labels (print_label)
pub main() -> Unit
uses @console: Console[print]
uses @clock: Clock[now]
=
print_label("LAMP-01", price: "19.90") with @console = @console, @clock = @clock[U3021] Error: the call of `print_label` grants `Clock[now]` to `vendor.labels`, whose ceiling in `una.toml` allows no operation of `Clock`
╭─[ src/store/app.una:9:3 ]
│
9 │ print_label("LAMP-01", price: "19.90") with @console = @console, @clock = @clock
│ ───────────────────┬──────────────────
│ ╰──────────────────── the call of `print_label` grants `Clock[now]` to `vendor.labels`, whose ceiling in `una.toml` allows no operation of `Clock`
│
│ Help: repair 1: no grant keeps both: the callee declares `Clock[now]`, and the ceiling of `vendor.labels` allows no operation of `Clock`, so the consumer decides between this module and its ceiling
│
│ Note: run `una explain U3021` for an explanation
───╯The call grants Clock[now], and the ceiling allows no operation of Clock. The help under the message offers no edit: the callee declares Clock[now], the store's clock permits it, and the ceiling withholds it, so the choice between the new version and the ceiling belongs to the store. To accept the new version, someone must widen the ceiling in una.toml, which a reviewer sees, or the store keeps the old version. una fix . never makes that choice, since it never edits una.toml. A handler for Clock with no uses of its own, written outside the boundary, would lie within the ceiling too, as What counts against the ceiling explains, but it hands the module a stand-in clock, not the store's.
13.2.5.3 What counts against the ceiling
Each binding that the callee's uses name counts, with every operation it permits. A handler installed for the call counts with its own uses too. A binding of the with that the callee does not ask for counts for nothing, since the callee can never use it. A boundary module can never be one of the package's trusted modules, so it can never release labeled data (chapter 17).
13.2.5.4 What a boundary key may say (U7002)
Each of these is U7002, at the key in una.toml: a key that is not a module of the package, a key inside another key's modules, a malformed ceiling, a capability named twice in one ceiling, an unknown capability or operation, a module that [trusted] lists (chapter 17) inside a boundary, and the [run] entry inside a boundary.
13.2.6 Granting less at the call: with @x = @y[ops]
Chapter 12 showed one way authority narrows: a callee's header limits what it may use, whatever binding it receives. A ceiling does not stop at the callee's header, though. It counts every operation that the granted binding permits. So at a boundary, the caller must hand over less, and edition 0.3 lets it say so at the call.
13.2.6.1 What a narrowed rebinding is
When you lend a colleague your key ring for one errand, you can take off every key but the one they need. A narrowed rebinding does that with a binding: it hands the callee the caller's binding with only some of its operations. You write with @x = @y[ops]: the callee's name @x, =, the caller's binding @y, and in brackets the names of the operations the callee may receive, separated by commas. It is the rebinding with @x = @y of chapter 12, with brackets added.
13.2.6.2 Why a boundary needs it
In this step, the price list has two operations, and the label module reads prices to print them:
module store.prices
--- The store's price list: reading a price, and setting one.
pub capability PriceList
op price(sku: Text) -> Int
op set_price(sku: Text, cents: Int) -> Unitmodule vendor.labels
import store.prices (PriceList)
--- Prints a shelf label with the current price of a product, read from the price list.
pub print_price_tag(sku: Text) -> Unit
uses @prices: PriceList[price]
uses @console: Console[print]
=
let cents = @prices.price(sku)
@console.print("[{sku} | {cents} cents]")[package]
name = "store"
version = "0.1.0"
edition = "0.3"
[run]
entry = "store.app"
grants = ["console"]
# Code from the label printer's supplier: the most the store may ever grant it.
[boundaries]
"vendor.labels" = ["Console[print]", "PriceList[price]"]The ceiling allows PriceList[price]. reprice holds PriceList[price, set_price], since it sets a price, and grants its whole binding to the label module:
--- Sets a new price, then prints the shelf label with it.
reprice(sku: Text, cents: Int) -> Unit
uses @prices: PriceList[price, set_price]
uses @console: Console[print]
=
@prices.set_price(sku, cents)
print_price_tag(sku) with @console = @console, @prices = @prices[U3021] Error: the call of `print_price_tag` grants `PriceList[price, set_price]` to `vendor.labels`, whose ceiling in `una.toml` allows `PriceList[price]`The label module asks only for price, but the binding it receives permits set_price too, so the call would grant more than the ceiling. This time a grant exists that keeps both: the callee declares only PriceList[price], which the ceiling allows. The help under the message names it, as a description that una fix does not apply, and the next part writes it.
13.2.6.3 One operation: @prices[price]
Narrow the binding at the call, with @prices = @prices[price]: the label module's @prices is the caller's @prices, restricted to price.
--- a/src/store/app.una
+++ b/src/store/app.una
@@ -18 +18 @@
- print_price_tag(sku) with @console = @console, @prices = @prices
+ print_price_tag(sku) with @console = @console, @prices = @prices[price]set LAMP-01 to 1592
[LAMP-01 | 1592 cents]The call now grants PriceList[price], which is within the ceiling, so the package checks and runs. reprice itself still holds both operations: only what it hands over is narrower.
13.2.6.4 Several operations, and calls outside a boundary
This step has no boundary. The price list has three operations, and review holds all of them. It hands each helper only the operations named at the call:
module pricing
--- The store's price list: reading a price, setting one, and taking a product off the list.
capability PriceList
op price(sku: Text) -> Int
op set_price(sku: Text, cents: Int) -> Unit
op remove(sku: Text) -> Unit
--- Prints the price of a SKU. It only reads.
show_price(sku: Text) -> Unit
uses @prices: PriceList[price]
uses @console: Console[print]
=
let cents = @prices.price(sku)
@console.print("{sku} costs {cents}")
--- Raises the price of a SKU by `cents`.
raise_price(sku: Text, cents: Int) -> Unit
uses @prices: PriceList[price, set_price]
=
let current = @prices.price(sku)
@prices.set_price(sku, cents: current + cents)
--- Takes 10 percent off a SKU, and gives back the new price. A dry run sets no price.
mark_down(sku: Text, dry_run: Bool) -> Int
uses @prices: PriceList[price, set_price where not dry_run]
=
let cents = @prices.price(sku)
let sale = cents - cents / 10
if not dry_run
@prices.set_price(sku, cents: sale)
sale
--- Reviews the price list. It holds every operation, and hands each helper only the ones named
--- at the call. A dry run changes nothing.
review(dry_run: Bool) -> Unit
uses @prices: PriceList[price, set_price where not dry_run, remove where not dry_run]
uses @console: Console[print]
=
show_price("LAMP-01") with @prices = @prices[price]
if not dry_run
raise_price("LAMP-01", cents: 100) with @prices = @prices[price, set_price]
let sale = mark_down("DESK-02", dry_run) with @prices = @prices[price, set_price]
@console.print("DESK-02 goes to {sale}")
if not dry_run
@prices.remove("RUG-07")
--- A price list where every product costs `each` cents, and that prints each change.
handler flat(each: Int) for PriceList
uses @console: Console[print]
op price(sku) = each
op set_price(sku, cents) = @console.print("set {sku} to {cents}")
op remove(sku) = @console.print("removed {sku}")
pub main() -> Unit
uses @console: Console[print]
=
@console.print("Dry run:")
review(dry_run: true) with @prices = flat(1990)
@console.print("Review:")
review(dry_run: false) with @prices = flat(1990)show_price("LAMP-01") with @prices = @prices[price]. One operation in the brackets:show_pricereceives a binding that may only read.if not dry_run.reviewmay set a price only wherenot dry_runholds, and a binding narrowed from it keeps that condition.raise_pricehas no condition, so its call on the next line needs the guard.raise_price(…) with @prices = @prices[price, set_price]. Several operations, separated by commas, as in the brackets ofuses.raise_pricenever receivesremove.mark_down(…) with @prices = @prices[price, set_price]. No guard here: the condition ofmark_down,not dry_run, implies the one the binding carries.
una run . prints:
Dry run:
LAMP-01 costs 1990
DESK-02 goes to 1791
Review:
LAMP-01 costs 1990
set LAMP-01 to 2090
set DESK-02 to 1791
DESK-02 goes to 1791
removed RUG-07The dry run reads two prices and sets none. The review sets two prices and removes a product.
13.2.6.5 How a narrowed rebinding behaves
- The caller must hold each operation. The brackets may name only operations that
@ypermits. Ifreviewheld onlyPriceList[price],@prices[set_price]would be U3002: "@pricespermitsprice, notset_price, so a narrowed rebinding of it cannot grantset_price". - The capability must declare it. An operation that the capability does not declare, such as
@prices[refund], is U1001: "capabilityPriceListhas no operationrefund". - The callee gets only the bracketed operations. A callee that needs another operation of the binding gets U3002 at the call, as for any binding with too few operations, as Check yourself: narrowing shows.
- Names only. The brackets hold names of operations and nothing else: no
whereand no condition, as A condition inside the narrowing brackets shows. - Conditions stay. The narrowed binding runs as the caller's binding, and every condition that binding carries still applies, as the guard around
raise_priceshows. - Any call, in edition 0.3. A narrowed rebinding is allowed at any call, not only at a boundary. In editions
0.1and0.2the brackets are a syntax error, U0101.
13.2.6.6 When to narrow outside a boundary
Outside a boundary, the callee's header already limits what it may use, so narrowing proves nothing more about the callee. It pins, at the call, what the callee receives. If a later edit widens the header of show_price to PriceList[price, set_price], the call with @prices = @prices[price] fails with U3002, instead of quietly handing over the right to set prices. Narrow where a reader of the caller should see at a glance what each helper gets; pass the binding whole where the callee's header is enough.
13.2.7 A boundary, a lock or neither
Which to use:
| The code… | Use |
|---|---|
| Is yours, and its header is reviewed with it | Nothing more: the header and the verifier suffice |
Is yours, and a header must not widen without a review of una.toml |
A lock in [contracts] (section 13.3) |
Comes from a supplier, copied into src/ |
[boundaries], with the least ceiling it needs |
| Comes from a supplier, and you also want its public functions' headers fixed | Both: a boundary for the module, and locks for its functions |
| Receives a binding that permits more than it should get, at a boundary or where you want the call to show it | A narrowed rebinding at the call, with @x = @y[ops] |
13.2.8 Check yourself: a module below the boundary
The supplier adds a second module, src/vendor/labels/fonts.una, and the app calls it as it would call any module, by name:
module vendor.labels.fonts
--- Prints a shelf label in large letters.
pub print_large(sku: Text) -> Unit
uses @console: Console[print]
=
@console.print("** {sku} **")module store.app
import vendor.labels (print_label)
import vendor.labels.fonts (print_large)
pub main() -> Unit
uses @console: Console[print]
=
print_label("LAMP-01", price: "19.90") with @console = @console
print_large("LAMP-01")una.toml is the one of How to write [boundaries], with the key vendor.labels only. Does the package check?
Show the answer
It does not:
[U3020] Error: `print_large` is in the boundary `vendor.labels` and needs `@console: Console[print]`, which a call into it grants only with `with`The key vendor.labels covers every module below it, so vendor.labels.fonts is in the boundary too, and a call into it grants its capabilities only with with. Write print_large("LAMP-01") with @console = @console, or let una fix . write the repair, with @console = @console[print], which grants the same here.
13.2.9 Check yourself: narrowing
In the step of Several operations, and calls outside a boundary, review narrows the binding it gives show_price to the other operation:
--- a/src/pricing.una
+++ b/src/pricing.una
@@ -40 +40 @@
- show_price("LAMP-01") with @prices = @prices[price]
+ show_price("LAMP-01") with @prices = @prices[set_price]review holds set_price, so the brackets are allowed. Does the package check?
Show the answer
No:
error U3002 at src/pricing.una:40:3: `show_price` needs `@prices` to permit `price`, which it does not hereshow_price reads a price, so its header needs @prices to permit price. The narrowed binding permits only set_price, so the call gives show_price too few operations, which is U3002 at the call. Narrow to what the callee's header lists: @prices[price].