Home / Learn / 13 Limits on authority

Release v0.4.0Edition 0.2, 0.3

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:

src/vendor/labels.unadiff
--- 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).

una.tomldiff
--- 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"]
steps/06-unbounded/src/store/app.unacheckrununa
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")
Output
[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]

steps/05-boundary/una.tomltoml
[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]"]
  1. edition = "0.3". [boundaries] exists only in edition 0.3.
  2. [boundaries]. The table of boundaries.
  3. "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.labels covers vendor.labels.fonts, but not vendor.labelsmith.
  4. ["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:

steps/05-boundary/src/vendor/labels.unacheckuna
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:

steps/05-boundary/src/store/app.unacheckrununa
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
Output
[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:

src/store/app.unadiff
--- 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")
Diagnostic
[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:

steps/08-over-ceiling/src/store/app.unauna
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
Diagnostic
[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:

steps/09-narrow-wide/src/store/prices.unauna
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) -> Unit
steps/09-narrow-wide/src/vendor/labels.unauna
module 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]")
steps/09-narrow-wide/una.tomltoml
[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:

steps/09-narrow-wide/src/store/app.unauna
--- 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
Diagnostic
[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.

src/store/app.unadiff
--- 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]
Output
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:

steps/18-narrow-forms/src/pricing.unacheckrununa
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)
  1. show_price("LAMP-01") with @prices = @prices[price]. One operation in the brackets: show_price receives a binding that may only read.
  2. if not dry_run. review may set a price only where not dry_run holds, and a binding narrowed from it keeps that condition. raise_price has no condition, so its call on the next line needs the guard.
  3. raise_price(…) with @prices = @prices[price, set_price]. Several operations, separated by commas, as in the brackets of uses. raise_price never receives remove.
  4. mark_down(…) with @prices = @prices[price, set_price]. No guard here: the condition of mark_down, not dry_run, implies the one the binding carries.

una run . prints:

Output
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-07

The 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

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:

steps/11-fonts/src/vendor/labels/fonts.unauna
module vendor.labels.fonts

--- Prints a shelf label in large letters.
pub print_large(sku: Text) -> Unit
  uses @console: Console[print]
=
  @console.print("** {sku} **")
steps/11-fonts/src/store/app.unauna
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:

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

src/pricing.unadiff
--- 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:

Diagnostic
error U3002 at src/pricing.una:40:3: `show_price` needs `@prices` to permit `price`, which it does not here

show_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].

Next:13.3 Locking a contract: [contracts]