Home / Docs / Language guide

A complete package

Release v0.4.0

The events package: a phone number validated at the boundary, a trusted policy that hashes it, a check-in with two capabilities and its examples, and a main that prints. una check, una test, una run and una build all accept it, and the native executable prints what una run prints.

una.tomltoml
[package]
name = "events"
version = "0.1.0"
edition = "0.2"

[labels]
categories = ["PII", "Location"]

[trusted]
modules = ["events.keys"]

[escape_budget]
checked_per_module = 1

[run]
entry = "events.main"
grants = ["console"]
verification.locktoml
encoding_version = "una-smt-1"
solver           = "z3"
solver_version   = "5.1.0"
logic            = "QF_UFLIA"
step_budget      = 5000000
random_seed      = 0
src/events/types.unauna
module events.types

--- A phone number of 11 digits, validated once at the boundary.
pub kind Phone = Text where valid_phone(it)

pub kind PhoneError = | Malformed

--- Format check only.
pub predicate opaque valid_phone(t: Text) -> Bool = t.len == 11 and is_digits(t)

--- The only way to obtain a Phone from untrusted text.
pub parse_phone(raw: Text) -> Phone
  fails PhoneError
=
  checked(raw, valid_phone(it)) else fail Malformed

example "malformed input is rejected"
  do parse_phone("123")
  expect fails Malformed
src/events/seating.unauna
module events.seating

requirement EVENTS_3
  text "An event with no remaining seats is always shown as sold out"
  source policy "Box Office Handbook 2.1"
  owner box_office
  status active

pub kind Seats = Int in 0..5000

pub kind Availability = SoldOut | Few | Open

pub kind Event
  name: Text
  remaining: Seats

pub kind Registration
  name: Text
  event: Event

--- Availability bands from the Box Office Handbook.
pub availability(e: Event) -> Availability
  ensures e.remaining < 1 implies result is SoldOut
  derived from EVENTS_3
=
  when e.remaining
    in 0..0 -> SoldOut
    in 1..<20 -> Few
    in 20..5000 -> Open

--- Clamps a raw count into the seat range.
pub clamp_seats(raw: Int) -> Seats = if raw < 0 then 0 else if raw > 5000 then 5000 else raw

--- Shows an event in its Una form.
pub describe(e: Event) -> Text = "{e}"

--- Shows a list of events in their Una forms.
pub describe_many(events: List[Event]) -> Text = "{events}"

example "an event with no seats is sold out"
  do availability(Event(name: "Launch", remaining: 0))
  expect result is SoldOut

example "an event record can be interpolated"
  do describe(Event(name: "Launch", remaining: 0))
  expect result == "Event(name: \"Launch\", remaining: 0)"

example "a list of event records can be interpolated"
  do describe_many([Event(name: "Launch", remaining: 0)])
  expect result == "[Event(name: \"Launch\", remaining: 0)]"

example "an event with many seats is open"
  do availability(Event(name: "Meetup", remaining: 120))
  expect result is Open

example "raw counts are clamped"
  do clamp_seats(9000)
  expect result == 5000
src/events/keys.unauna
trusted module events.keys

import events.types (Phone)

pub policy attendee_key
  from secret[PII] Phone
  to internal Hashed
  via hmac_phone
  purpose "registration lookup and audit correlation"
  owner privacy

hmac_phone(phone: secret[PII] Phone) -> internal Hashed
  uses @keys: Keys[hmac]
  fails KeyError
=
  @keys.hmac(key_name: "phone_pepper", data: phone)
    if error pass
src/events/checkin.unauna
module events.checkin

import events.keys (attendee_key)
import events.seating (Availability, Event, Registration, availability)
import events.types (Phone, parse_phone)
import std.testing (fake_hash)

pub kind CheckInError = NotRegistered | Unavailable

pub kind StoreError = Timeout | Corrupted

pub capability Registrations
  op find(key: internal Hashed) -> Option[Registration]
    fails StoreError
    accepts internal

pub capability Audit
  op record(key: internal Hashed, status: Availability) -> Unit
    fails StoreError
    accepts internal

--- Finds a registration by phone, reports the event's availability and audits the check-in.
--- The phone number never leaves this function: only its keyed hash does.
pub check_in(phone: secret[PII] Phone) -> Availability
  uses @registrations: Registrations[find]
  uses @audit: Audit[record]
  uses @keys: Keys[hmac]
  fails CheckInError
=
  let key = attendee_key(phone)
    if error fail Unavailable
  let registration = @registrations.find(key)
    if error fail Unavailable
    if none fail NotRegistered
  let status = availability(registration.event)
  @audit.record(key, status)
    if error fail Unavailable
  status

handler one_registration(r: Registration) for Registrations
  op find(key) = Some(r)

handler no_registrations() for Registrations
  op find(key) = None

handler audit_log() for Audit
  op record(key, status) = unit

handler fake_keys() for Keys
  op hmac(key_name, data) = fake_hash(1)

example "a registered attendee is checked in and audited"
  given @registrations = one_registration(Registration(name: "Ana", event: Event(name: "Meetup", remaining: 120)))
  given @audit = audit_log()
  given @keys = fake_keys()
  do check_in(parse_phone("11900000001"))
  expect result is Open
  expect performed @audit.record

example "an unknown attendee fails and is not audited"
  given @registrations = no_registrations()
  given @audit = audit_log()
  given @keys = fake_keys()
  do check_in(parse_phone("11900000001"))
  expect fails NotRegistered
  expect not performed @audit.record
src/events/main.unauna
module events.main

import events.seating (Availability, Event, availability, clamp_seats, describe)

label(status: Availability) -> Text
=
  when status
    is SoldOut -> "sold out"
    is Few -> "few seats left"
    is Open -> "open"

pub main() -> Unit
  uses @console: Console[print]
=
  let events = [Event(name: "Meetup", remaining: clamp_seats(120)), Event(name: "Launch", remaining: 0)]
  for event in events
    let status = availability(event)
    @console.print("{describe(event)}: {label(status)}")

Running it:

Terminal
$ una check .
$ una test .
6 examples: 6 passed, 0 failed
$ una run .
Meetup (120 seats): open
Launch (0 seats): sold out
$ una build .
built target/una/events
$ ./target/una/events
Meetup (120 seats): open
Launch (0 seats): sold out