shortlinks
A link shortener: it stores short slugs that lead to longer links, and checks each slug once, where it enters the program.
This example is about failure and validation at a boundary. Text from users is checked once, by a parser that returns a refined type, and from then on the type carries the fact: the store's operations take a Slug, so they never see unchecked text. Each layer turns the failures of the layer below into its own error kind, and callers choose between handling a failure on the spot and keeping it as a value.
What it demonstrates:
- a refinement by an
opaquepredicate, established at run time bychecked, under an escape budget; - error kinds per layer, with
fails,failand the handling clausesif errorandif none; - failures as values with
attemptandResult; - a requirement proposed by a tool, which a person must activate;
- fake stores as handlers, and an
examplefor every failure path.
Run it
From this directory:
una check . # copy examples/shortlinks
una test .
una report .
una run .
una build .
./target/una/shortlinks-exampleuna run . and the native executable print:
docs leads to https://example.org/docs
blog leads to /main uses a store that holds one link, docs. The slug blog is valid but unknown, so resolve_or_home falls back to the home page, /. una test . runs six examples, one for each path through the module:
example shortlinks.links "a short link leads to its target" ... ok
example shortlinks.links "a malformed slug is rejected before the store is asked" ... ok
example shortlinks.links "an unknown slug fails" ... ok
example shortlinks.links "an attempt reports a failure as a value" ... ok
example shortlinks.links "without a store the home page is shown" ... ok
example shortlinks.links "a slug is stored" ... ok
6 examples: 6 passed, 0 failedHow it works
shortlinks.links holds everything but main, which is in shortlinks.main.
A slug is a checked text
pub kind Slug = Text where valid_slug(it)
...
pub predicate opaque valid_slug(t: Text) -> Bool = t.len >= 3 and t.len <= 16 and not starts_with(t, prefix: "-")A predicate comes in two forms. The solver sees the body of a reflect predicate, so it can prove the fact from other facts. It sees only the name of an opaque one, so a value can get the fact only from a test at run time, or from the ensures of a capability operation. This package uses the test. valid_slug is opaque because a slug comes from a user: no proof can show that a typed string is valid, so the program has to look at it.
The only way in: parse_slug
pub parse_slug(raw: Text) -> Slug
fails SlugError
derived from LINKS_1
=
let text = trim(raw)
checked(text, valid_slug(it)) else fail Malformedchecked(text, valid_slug(it)) evaluates the predicate at run time. When it holds, the result is text with the type Slug. When it does not, parse_slug fails with Malformed. Since checked replaces a proof with a test, every use costs part of the module's escape budget, which una.toml sets to 1:
[escape_budget]
checked_per_module = 1The default budget is 0, so a reviewer always sees in the manifest that a package tests facts at run time, and una report . lists each use: shortlinks.links: 1 checked, budget 1.
One error kind per layer
pub resolve(raw: Text) -> Text
uses @links: Links[get]
fails LinkError
=
let slug = parse_slug(raw)
if error fail BadSlug
let target = @links.get(slug)
if error fail StoreDown
if none fail Unknown(slug: raw)
targetresolve declares one error kind, LinkError = BadSlug | Unknown(slug: Text) | StoreDown. Each call that can fail is followed by its handling clauses, one effect per line:
if error fail BadSlugturns the parser'sSlugErrorinto the caller's vocabulary;if error fail StoreDowndoes the same for the store'sStoreError;if none fail Unknown(slug: raw)turns a missing link, anOption, into a failure that carries the slug.
A caller of resolve handles only LinkError. It never sees the error kinds of the store or of the parser.
Handling now, or keeping the failure as a value
The module shows three ways to handle a failure of the store:
try_resolvewritesattempt resolve(raw), which turns the outcome into aResult[Text, LinkError]:Ok(target)orErr(failure). It does not fail itself, so it needs nofails.resolve_or_homematches on thatResultwithwhenand returns/for anyErr.lookuprecovers on the spot.if error use Nonetreats a store that is down as a missing link, andif none use "/"then sends both cases to the home page.
Use a handling clause when the caller can decide at once, and attempt when it needs to keep the outcome, for example to report every line of a batch instead of stopping at the first bad one.
A requirement that a tool proposed
requirement LINKS_1
text "A slug has 3 to 16 characters and never starts with a dash"
source generated "task 17: short link rules"
owner web_team
status proposedsource generated marks a rule that a tool, such as a coding agent, wrote. Such a requirement must stay proposed. Functions derived from it compile as usual, and una report . flags them, LINKS_1 (proposed): shortlinks.links.parse_slug. Only a person activates it, by changing its source to human, policy or regulation.
What una check proves
- Every value used as a
Slugcame fromparse_slug: the store's operations, which take aSlug, never see unchecked text. - The package spends exactly its escape budget: one
checked, whichuna report .lists. - Every failure is declared or handled: a failure leaves a function only when its
failsdeclares that kind.
The proof that a slug is valid rests on one run-time test, in one place. That is the point of the design: to review the validation, you read valid_slug and parse_slug, and nothing else.
Common mistakes
Passing raw text where a checked value is needed
In resolve, call the store with the raw text, @links.get(raw):
[U5001] Error: refinement `valid_slug(raw)` is refuted
╭─[ src/shortlinks/links.una:54:27 ]
│
10 │ pub kind Slug = Text where valid_slug(it)
│ ───────┬──────
│ ╰──────── where clause
│
54 │ let target = @links.get(raw)
│ ─┬─
│ ╰─── refinement `valid_slug(raw)` is refuted
│
│ Help 1: repair 1: strengthen the type of the parameter `raw` to a refined kind that implies `valid_slug(raw)`
│
│ Help 2: repair 2: add a guard (`if` or a `when` arm) that handles the values where `valid_slug(raw)` does not hold
│
│ Help 3: repair 3 (escape: checked; a runtime test replaces the static proof: the program fails at run time where the proof would have rejected it; it counts against [escape_budget] and is listed in the build report): check the value with `checked(value, valid_slug(raw)) else fail <Variant>`
│
│ Note 1: obligation ob-cf53981acc2f (refinement) is refuted: valid_slug(raw)
│
│ Note 2: counterexample: raw = Text#1, slug = Text#0
│
│ Note 3: run `una explain U5001` for an explanation
────╯The fix is already in scope: pass slug, which parse_slug returned.
A second run-time check instead of the parser
In shorten, replace the two lines that parse the slug, let slug = parse_slug(raw) and its if error fail BadSlug, with one inline check: let slug = checked(raw, valid_slug(it)) else fail BadSlug. The module now uses checked twice:
[U7003] Error: module `shortlinks.links` uses `checked` 2 times, and `[escape_budget] checked_per_module` allows 1
╭─[ src/shortlinks/links.una:41:14 ]
│
41 │ let slug = checked(raw, valid_slug(it)) else fail BadSlug
│ ───────────────────────┬──────────────────────
│ ╰──────────────────────── module `shortlinks.links` uses `checked` 2 times, and `[escape_budget] checked_per_module` allows 1
│
│ Help 1: repair 1: state the fact in a refined type or a `requires` clause, so that the solver proves it, and remove the `checked`
│
│ Help 2: repair 2: handle the values where the fact does not hold with a guard (`if` or a `when` arm), and remove the `checked`
│
│ Help 3: repair 3 (escape: escape_budget; the module may use more runtime tests in place of proofs; each one is listed in the build report and needs review): raise `checked_per_module` in `[escape_budget]` of `una.toml`
│
│ Note: run `una explain U7003` for an explanation
────╯The budget keeps validation in one place. Note also what the inline version loses: the trim that parse_slug applies.
Activating a generated requirement
Change status proposed to status active in LINKS_1:
[U1007] Error: requirement `LINKS_1` has source `generated`, so its status must be `proposed`
╭─[ src/shortlinks/links.una:7:10 ]
│
7 │ status active
│ ───┬──
│ ╰──── requirement `LINKS_1` has source `generated`, so its status must be `proposed`
│
│ Help: repair 1: mark it `proposed`; a person activates it by changing its source; edit src/shortlinks/links.una:7:10..7:16 to "proposed"
│
│ Note: run `una explain U1007` for an explanation
───╯
1 of 1 diagnostics have an edit that `una fix` applies (`una fix --dry-run` lists them)Extend it
- Delete a link. Add an operation to
Links,op remove(slug: Slug) -> Unitwithfails StoreError.una check .reports U3011 for both handlers: a handler must implement every operation of its capability. Implement it in both, then addpub unshorten(raw: Text) -> Unit, which parses the slug and removes it, with an example that usesexpect performed @links.remove. - Test
lookup.lookuphas no example yet. Add two: one withone_link, and one withoffline_linksthat expects/. Hint:lookuptakes aSlug, so thedoline needs one fromparse_slug. An example'sdoline may call a function that fails. - Activate the rule. Suppose the slug rules were reviewed and adopted. Change the source of
LINKS_1tohumanand its status toactive, and check thatuna report .lists it as(active).
Learn more
- Construct pages: predicates,
where,checked,fails,fail,if error,attempt,requirement,handler. - Configuration:
checked_per_module. - Learn, the tutorial on the Una website: "Results and failures" (
/learn/failure/); "Contracts and the verifier" (/learn/contracts/). - Specification: predicates (spec/03 §4), handling clauses (spec/06 §3),
attempt(spec/06 §5),checked(spec/06 §6), requirements (spec/08 §1).
Edition
Edition 0.1 (edition).
Files
[package]
name = "shortlinks-example"
version = "0.1.0"
edition = "0.1"
[escape_budget]
checked_per_module = 1
[run]
entry = "shortlinks.main"
grants = ["console"]module shortlinks.links
requirement LINKS_1
text "A slug has 3 to 16 characters and never starts with a dash"
source generated "task 17: short link rules"
owner web_team
status proposed
--- A slug, checked once where it enters the program.
pub kind Slug = Text where valid_slug(it)
pub kind SlugError = | Malformed
pub kind LinkError = BadSlug | Unknown(slug: Text) | StoreDown
pub kind StoreError = | Offline
--- Format check only. The solver sees an opaque symbol; `checked` establishes it.
pub predicate opaque valid_slug(t: Text) -> Bool = t.len >= 3 and t.len <= 16 and not starts_with(t, prefix: "-")
--- Where short links are kept.
pub capability Links
op put(slug: Slug, target: Text) -> Unit
fails StoreError
op get(slug: Slug) -> Option[Text]
fails StoreError
--- The only way to obtain a Slug from untrusted text.
pub parse_slug(raw: Text) -> Slug
fails SlugError
derived from LINKS_1
=
let text = trim(raw)
checked(text, valid_slug(it)) else fail Malformed
--- Stores a short link and returns its slug.
pub shorten(raw: Text, target: Text) -> Slug
uses @links: Links[put]
fails LinkError
=
let slug = parse_slug(raw)
if error fail BadSlug
@links.put(slug, target)
if error fail StoreDown
slug
--- Where a short link leads.
pub resolve(raw: Text) -> Text
uses @links: Links[get]
fails LinkError
=
let slug = parse_slug(raw)
if error fail BadSlug
let target = @links.get(slug)
if error fail StoreDown
if none fail Unknown(slug: raw)
target
--- Resolves a short link, with the failure as a value rather than a failure.
pub try_resolve(raw: Text) -> Result[Text, LinkError]
uses @links: Links[get]
=
attempt resolve(raw)
--- Where a short link leads, or the home page when it cannot be resolved.
pub resolve_or_home(raw: Text) -> Text
uses @links: Links[get]
=
let outcome = try_resolve(raw)
when outcome
is Ok(target) -> target
is Err -> "/"
--- Where a checked slug leads, or the home page when the store is down or has no such slug.
pub lookup(slug: Slug) -> Text
uses @links: Links[get]
=
let found = @links.get(slug)
if error use None
if none use "/"
found
--- A store holding one link.
pub handler one_link(saved: Text, leads_to: Text) for Links
op put(slug, target) = unit
op get(slug) = if slug == saved then Some(leads_to) else None
--- A store that cannot be reached.
pub handler offline_links() for Links
op put(slug, target) = fail Offline
op get(slug) = fail Offline
example "a short link leads to its target"
given @links = one_link(saved: "docs", leads_to: "https://example.org/docs")
do resolve("docs")
expect result == "https://example.org/docs"
expect performed @links.get
example "a malformed slug is rejected before the store is asked"
given @links = one_link(saved: "docs", leads_to: "https://example.org/docs")
do resolve("-x")
expect fails BadSlug
expect not performed @links.get
example "an unknown slug fails"
given @links = one_link(saved: "docs", leads_to: "https://example.org/docs")
do resolve("blog")
expect fails Unknown
example "an attempt reports a failure as a value"
given @links = offline_links()
do try_resolve("docs")
expect result is Err
example "without a store the home page is shown"
given @links = offline_links()
do resolve_or_home("docs")
expect result == "/"
example "a slug is stored"
given @links = one_link(saved: "docs", leads_to: "https://example.org/docs")
do shorten(" news ", target: "https://example.org/news")
expect result == "news"
expect performed @links.putmodule shortlinks.main
import shortlinks.links (one_link, resolve_or_home)
pub main() -> Unit
uses @console: Console[print]
=
let docs = resolve_or_home("docs") with @links = one_link(saved: "docs", leads_to: "https://example.org/docs")
@console.print("docs leads to {docs}")
let blog = resolve_or_home("blog") with @links = one_link(saved: "docs", leads_to: "https://example.org/docs")
@console.print("blog leads to {blog}")