Making an impossible payment unrepresentable
In the first post I said we design types where the bug will not compile. This post shows what that means on a problem every payments team knows: a payment that ends up in a state that should never exist.
The record that allows anything
Here is a shape of payment record that appears, in one form or another, in many codebases:
type payment = {
id : string;
amount : int;
mutable status : string;
mutable settled_at : float option;
mutable failure_reason : string option;
}
let settle p ~now =
p.status <- "settled";
p.settled_at <- Some now
let fail p ~reason =
p.status <- "failed";
p.failure_reason <- Some reason
It looks reasonable, and it compiles. So does this session in the OCaml toplevel:
# let p = { id = "TX1"; amount = -5000; status = "pending";
settled_at = None; failure_reason = None };;
val p : payment =
{id = "TX1"; amount = -5000; status = "pending"; settled_at = None;
failure_reason = None}
# settle p ~now:1.0; fail p ~reason:"timeout"; settle p ~now:2.0;
p.status <- "setled";;
- : unit = ()
# p;;
- : payment =
{id = "TX1"; amount = -5000; status = "setled"; settled_at = Some 2.;
failure_reason = Some "timeout"}
In three lines we built a payment with a negative amount, settled it, failed it, settled it again, and gave it a status that does not exist. The record now carries a settlement time and a failure reason. Every one of those is a real incident waiting to happen, and the compiler accepted all of them, because the type allows them.
Tests can catch some of this, if someone thought to write the right test. The problem is that the type says these states are fine.
Types that only allow real payments
Now the same domain, with each state as its own type:
module Kobo : sig
type t = private int
val of_int : int -> t option
end = struct
type t = int
let of_int n = if n > 0 then Some n else None
end
type pending = { id : string; amount : Kobo.t }
type settled = { payment : pending; settled_at : float }
type failed = { attempt : pending; reason : string }
let settle (p : pending) ~now : settled = { payment = p; settled_at = now }
let fail (p : pending) ~reason : failed = { attempt = p; reason }
Three things changed.
- An amount can only be positive.
Kobo.tis private, so the only way to get one isKobo.of_int, which refuses zero and negatives. - There is no status string to misspell. The state is the type.
settledandfailedare different types, so a payment that is both cannot be written down. - Only a pending payment can be settled.
settletakes apendingand returns asettled.
Here is the compiler refusing the same mistakes:
# let bad : pending = { id = "TX1"; amount = -5000 };;
Line 1, characters 44-49:
Error: The constant -5000 has type int but an expression was expected of type
Kobo.t
# let p : pending = { id = "TX1"; amount = Option.get (Kobo.of_int 5000) };;
val p : pending = {id = "TX1"; amount = 5000}
# let s = settle p ~now:1.0;;
val s : settled = {payment = {id = "TX1"; amount = 5000}; settled_at = 1.}
# settle s ~now:2.0;;
Line 1, characters 8-9:
Error: The value s has type settled but an expression was expected of type
pending
The negative amount and the second settlement are not caught by a test someone remembered to write. They cannot be written at all.
Every code block in this post is checked on each build with mdx, so the output and errors above are what the compiler really says. Nothing here is clever. It is ordinary OCaml: records, a private type, and functions whose signatures say exactly which transitions exist. The rules moved out of code reviews and into the types, where the compiler checks them on every build.
What types cannot do
Candor matters more than a neat ending. These types stop the program from constructing an impossible payment. They do not stop two servers from settling the same pending payment at the same moment, because each holds its own copy of the value. That invariant belongs to the database: a unique constraint on the payment's idempotency key, and a state transition that only succeeds if the row is still pending.
That is the real lesson. An invariant has to be enforced at every layer where it can be broken: in the types for the program, in the schema for the data, in the protocol for the network. The work is finding each place a wrong state can enter and closing it there.
Try it on your own code
You do not need to rewrite anything in OCaml to start. Take one critical record in your system, list every combination of its fields, and mark which combinations should never exist. If that list is long, your type is allowing states your business forbids. That exercise is the first step of our invariant audit, and we are happy to do it with you. Get in touch.
— Chukwuma