How Chaufr prices a chauffeur booking
Chaufr is our first product: a chauffeur marketplace built entirely in OCaml. It offers two services side by side. A standard ride is the familiar one, where a driver takes you somewhere in their car. A chauffeur booking is different: a driver drives your car, for as long as you need them.
Standard rides are priced by the rider's offer, which the driver accepts or declines. Chauffeur bookings needed real rules, and this post walks through them. The samples are simplified versions written for this post rather than Chaufr's production code, and like everything on this blog they are compiled and checked on every build with mdx.
The rules
- A chauffeur sets their own hourly rate, but only within a band that Chaufr sets, and Chaufr can move the band as prices change.
- Time is booked in minutes and billed in 15-minute blocks.
- The fare is for the longer of the booked time and the actual time. The rider can end a trip early, but a booking reserved the chauffeur's time.
- A chauffeur can accept a booking any time before it starts, but not after.
- Riders and chauffeurs may hold several bookings, as long as none overlap.
- A trip cannot start before its scheduled time.
Money and rates
Money is never a bare integer. Amounts are kobo, the smallest unit of the naira, and only positive amounts can exist:
module Kobo : sig
type t = private int
val of_int : int -> t option
val to_naira : t -> string
end = struct
type t = int
let of_int n = if n > 0 then Some n else None
let to_naira k = Printf.sprintf "N%d.%02d" (k / 100) (k mod 100)
end
type band = { floor : Kobo.t; ceiling : Kobo.t }
module Hourly_rate : sig
type t = private Kobo.t
val within : band -> Kobo.t -> t option
end = struct
type t = Kobo.t
let within band r = if r >= band.floor && r <= band.ceiling then Some r else None
end
Rule 1 now lives in the type. An Hourly_rate.t can only come from within, so a rate outside the band cannot exist anywhere in the program. The band itself is data, not code, which is how Chaufr can move it without a release. With an example band of ₦5,000 to ₦15,000 an hour:
# let naira n = Option.get (Kobo.of_int (n * 100));;
val naira : int -> Kobo.t = <fun>
# let band = { floor = naira 5_000; ceiling = naira 15_000 };;
val band : band = {floor = 500000; ceiling = 1500000}
# Hourly_rate.within band (naira 20_000);;
- : Hourly_rate.t option = None
# let rate = Option.get (Hourly_rate.within band (naira 8_000));;
val rate : Hourly_rate.t = 800000
The fare
Rules 2 and 3 are a small pure function:
let blocks minutes = (minutes + 14) / 15
let fare ~(rate : Hourly_rate.t) ~booked ~actual =
let hourly = ((rate :> Kobo.t) :> int) in
let billed = blocks (max booked actual) in
Option.get (Kobo.of_int ((billed * hourly + 3) / 4))
A rider books 90 minutes at ₦8,000 an hour. If the trip runs to 100 minutes, they pay for seven blocks. If they end it at 40 minutes, they still pay for the six blocks they reserved:
# Kobo.to_naira (fare ~rate ~booked:90 ~actual:100);;
- : string = "N14000.00"
# Kobo.to_naira (fare ~rate ~booked:90 ~actual:40);;
- : string = "N12000.00"
Because fare is pure, it is trivial to test exhaustively, and the same function runs when quoting the rider and when settling the trip, so the quote and the bill cannot disagree.
Bookings and the clock
A booking moves from requested, to accepted, to started, and each stage is its own type, the same technique as in our payments post. A trip cannot be started without first being accepted, because start only takes an accepted.
type slot = { start : int; finish : int }
let overlaps a b = a.start < b.finish && b.start < a.finish
type requested = { slot : slot; rate : Hourly_rate.t }
type accepted = { booking : requested }
type started = { trip : accepted; started_at : int }
let accept ~now ~schedule (r : requested) : (accepted, string) result =
if now >= r.slot.start then Error "too late: the booking has already started"
else if List.exists (overlaps r.slot) schedule then Error "overlaps another booking"
else Ok { booking = r }
let start ~now (a : accepted) : (started, string) result =
if now < a.booking.slot.start then Error "a trip cannot start before its scheduled time"
else Ok { trip = a; started_at = now }
Here is the candid part. Types cannot know what time it is. Rules 4, 5 and 6 depend on the clock and on the chauffeur's other bookings, so they are checked when the action happens, and the result type forces every caller to handle the refusal:
# let morning = { slot = { start = 540; finish = 630 }; rate };;
val morning : requested = {slot = {start = 540; finish = 630}; rate = 800000}
# let overlapping = { slot = { start = 600; finish = 660 }; rate };;
val overlapping : requested =
{slot = {start = 600; finish = 660}; rate = 800000}
# let accepted = Result.get_ok (accept ~now:480 ~schedule:[] morning);;
val accepted : accepted =
{booking = {slot = {start = 540; finish = 630}; rate = 800000}}
# accept ~now:480 ~schedule:[ morning.slot ] overlapping;;
- : (accepted, string) result = Error "overlaps another booking"
# start ~now:530 accepted;;
- : (started, string) result =
Error "a trip cannot start before its scheduled time"
The useful split is this: what can be decided from the data alone goes into the types, and what depends on the world is checked at the boundary and returned as a value the compiler will not let you ignore.
Why write this down
Pricing rules are where marketplaces lose trust: a fare that changes after the trip, a booking that silently double-books a driver. Writing the rules as types and small pure functions means the rules in this post are the rules in the code, and a reader can check one against the other.
Chaufr launches in Lagos this December. If you are building something where the rules have to hold, we would like to hear about it.
— Chukwuma