decisions/conformance

The storage port’s contract as executable checks. An adapter’s own tests run them; decisions/memory passes them, and so must every adapter.

Each check gets a fresh Adapter and returns Ok(Nil) or a Unmet value that names the check and what it saw. The checks cover what one process can observe: an absent id loads empty and takes its first entry once, a repeated sequence number, a gap and a second release are refused, a rolled-back transaction leaves nothing, a savepoint rolls back alone (whether its body returns an error or raises) and keeps the transaction usable, a savepoint’s writes go with a transaction that rolls back, the head comes back as written, waiting returns only the records still waiting (pending, recommended, awaiting or held) in id order, wake-ups are replaced and cancelled, settlement notices are admitted once, entries come back in order and byte for byte, and a desk driven over the adapter schedules its hold, deadline and policy steps, cancels them when it settles, and keeps every invariant of decisions/testing. Loading a subject lock (decisions.subject_lock) stores nothing and changes no waiting answer, and two admissions about one subject, one after the other, see each other. This package’s own tests break an in-memory adapter in each of these clauses in turn and show that the check naming it fails.

The suite assumes nothing about the clock between two reads: an adapter’s now may return a later time on every call.

What needs several processes, or a real clock, is not checked here: that now is the wall clock at the moment of the call and not the transaction’s start, that schedule leaves alone a wake-up the job queue already delivered (delivery is outside the port), that a second transaction loading an absent or a present id waits for the first, that uncommitted writes are invisible to other transactions, and that a process killed inside a transaction or a savepoint leaves nothing. The stress suites of decisions_otp and decisions_postgres check those.

import decisions/conformance
import decisions/memory

pub fn memory_conforms_test() {
  let assert Ok(Nil) =
    conformance.run(fn() {
      let store = memory.new()
      Ok(conformance.Adapter(
        port: memory.port(),
        inspect: memory.inspection(),
        handle: store,
        transaction: fn(body) { memory.transaction(store, body) },
        cleanup: fn() { Nil },
      ))
    })
}

Target-independent: builds for Erlang and JavaScript.

Types

An adapter under test.

pub type Adapter(tx) {
  Adapter(
    port: store.Port(tx),
    inspect: store.Inspection(tx),
    handle: tx,
    transaction: fn(fn(tx) -> Result(Nil, String)) -> Result(
      Nil,
      String,
    ),
    cleanup: fn() -> Nil,
  )
}

Constructors

  • Adapter(
      port: store.Port(tx),
      inspect: store.Inspection(tx),
      handle: tx,
      transaction: fn(fn(tx) -> Result(Nil, String)) -> Result(
        Nil,
        String,
      ),
      cleanup: fn() -> Nil,
    )

    Arguments

    handle

    A handle usable outside any transaction: each port call on it is a transaction of its own. The checks read through it.

    transaction

    Run body in one transaction: commit on Ok, roll back on Error.

    cleanup

    Called after each check, whatever its result.

A named check of one clause of the contract.

pub type Check(tx) {
  Check(
    name: String,
    run: fn(Adapter(tx)) -> Result(Nil, String),
  )
}

Constructors

  • Check(name: String, run: fn(Adapter(tx)) -> Result(Nil, String))

Why the suite did not pass.

pub type Unmet {
  SetupFailed(reason: String)
  CheckFailed(check: String, saw: String)
}

Constructors

  • SetupFailed(reason: String)

    The adapter factory returned this error.

  • CheckFailed(check: String, saw: String)

    The named check saw this.

Values

pub fn checks() -> List(Check(tx))

Every check, in the order run runs them.

pub fn names() -> List(String)

Every check’s name, for an adapter’s report.

pub fn run(
  fresh: fn() -> Result(Adapter(tx), String),
) -> Result(Nil, List(Unmet))

Run every check, each on a fresh adapter, and report every failure.

pub fn run_check(
  check: Check(tx),
  fresh: fn() -> Result(Adapter(tx), String),
) -> Result(Nil, Unmet)

Run one check on a fresh adapter.

✨ Search Document