Cookbook
Surefold cookbook
Forty-three problems you have had, and the few lines of Kotlin that solve each.
fun hedged(id: Int): String =
raceN(
{ fetch(id) },
{
Thread.sleep(200)
fetch(id)
},
).merge()
If the first call has not answered in 200 ms, a second starts, and whichever finishes first wins. No suspend, no callbacks, and the loser is interrupted before the call returns.
Every recipe is compiled against the library. Stand-in types and functions, such as findUser, are left out. Recipes use 0.18.0 unless one says otherwise.
- Start with
- surefold
- Version
- 0.18.0 · Maven Central
- Needs
- JDK 25, Kotlin 2.4.10
- Recipes
- 43
Install
Most recipes need only surefold, which brings nothing but the Kotlin standard library. Add the others as a recipe calls for them.
dependencies {
implementation("dev.surefold:surefold:0.18.0")
implementation("dev.surefold:surefold-cache:0.18.0") // Caches
implementation("dev.surefold:surefold-stream-forks:0.18.0") // Streams
implementation("dev.surefold:surefold-actor:0.18.0") // Actors
testImplementation("dev.surefold:surefold-test:0.18.0") // Stories
testImplementation("dev.surefold:surefold-assert:0.18.0") // shouldBe
}
Calls at once
Blocking calls, run side by side on virtual threads.
Two calls at once, under one deadline
Both run together. If one fails the other is interrupted, and at two seconds both are.
import dev.surefold.fail.Either
import dev.surefold.fail.attempt
import dev.surefold.fail.bind
import dev.surefold.parZip
import dev.surefold.timeout
import kotlin.time.Duration.Companion.seconds
fun page(id: Int): Either<Err, Page> = attempt {
timeout(2.seconds) {
parZip(
{ findUser(id).bind() },
{ ordersFor(id).bind() },
) { user, orders -> Page(user, orders) }
}
}
Fan out over a list, eight at a time
One fork per element, answered in the input's order, with never more than eight in flight.
import dev.surefold.Limit
import dev.surefold.fail.Either
import dev.surefold.fail.bind
import dev.surefold.parTraverse
val usersDb = Limit.fixed(8)
fun users(ids: List<Int>): Either<Err, List<String>> =
ids.parTraverse(usersDb) { id -> findUser(id).bind() }
The first failure interrupts the rest and becomes the Left.
Take whichever answers first
The loser is interrupted, and the call returns only once it has stopped.
import dev.surefold.fail.merge
import dev.surefold.raceN
fun quote(): Long = raceN({ quoteFrom("primary") }, { quoteFrom("replica") }).merge()
Hedge a slow call
If the first call has not answered in 200 ms, a second starts, and whichever finishes first wins.
import dev.surefold.fail.merge
import dev.surefold.raceN
fun hedged(id: Int): String =
raceN(
{ fetch(id) },
{
Thread.sleep(200)
fetch(id)
},
).merge()
Ask every mirror, keep the first success
Any number of calls race for one answer. A mirror that fails only drops out.
import dev.surefold.Promise
import dev.surefold.Shared
import dev.surefold.fail.Either
import dev.surefold.fail.onLeft
import dev.surefold.fail.onRight
import dev.surefold.scope
fun pageFromAny(
mirrors: List<String>,
fetch: (String) -> Either<Unreachable, String>,
): Either<Unreachable, String> =
scope {
val page = Promise<Unreachable, String>()
val failed = Shared(0)
val calls = mirrors.map { mirror ->
async {
fetch(mirror)
.onRight { page.succeed(it) } // false after the first
.onLeft { error ->
val failures = failed.modify { n -> (n + 1) to (n + 1) }
if (failures == mirrors.size) page.fail(error)
}
}
}
page.await().also { calls.forEach { it.cancel() } }
}
Start expensive work early, and cancel it if it is not wanted
cancel() interrupts the fork and returns once it has ended.
import dev.surefold.scope
fun page(id: Int): String = scope {
val report = async { buildReport(id) }
if (hasCredit(id)) {
report.await()
} else {
report.cancel()
"no report"
}
}
Wait for a CompletableFuture
await() parks the virtual thread until the future completes, and cancels the future if the fork is cancelled.
import dev.surefold.await
import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
fun rate(http: HttpClient, currency: String): String {
val uri = URI.create("https://rates.example/$currency")
val request = HttpRequest.newBuilder(uri).build()
return http.sendAsync(request, HttpResponse.BodyHandlers.ofString()).await().body()
}
Hand a future back to a caller that wants one
For Spring's @Async, Vert.x or a Java API. Cancelling the future stops every branch inside.
import dev.surefold.parMap
import dev.surefold.surefoldFuture
import java.util.concurrent.CompletableFuture
fun profilesAsync(
ids: List<Long>,
find: (Long) -> String?,
): CompletableFuture<List<String?>> =
surefoldFuture { parMap(ids) { id -> find(id) } }
Errors as values
A failure is declared in the return type, and the compiler checks who handles it.
Turn a missing value or a broken rule into a typed error
fail and ensure end the block with a Left. Nothing is thrown.
import dev.surefold.fail.Either
import dev.surefold.fail.attempt
import dev.surefold.fail.ensure
fun withdraw(account: Account?, pence: Long): Either<Refused, Account> = attempt {
val open = account ?: fail(Refused.NoAccount)
ensure(open.balance >= pence) { Refused.Funds }
open.copy(balance = open.balance - pence)
}
Report every invalid field, not just the first
Each check runs, and the caller gets all the failures in the order the checks were written.
import dev.surefold.fail.Either
import dev.surefold.fail.NonEmptyList
import dev.surefold.fail.attempt
import dev.surefold.fail.ensure
import dev.surefold.zipOrAccumulate
fun validate(form: Form): Either<NonEmptyList<Invalid>, Account> = attempt {
zipOrAccumulate(
{ form.name.also { ensure(it.isNotBlank()) { Invalid("name") } } },
{ form.email.also { ensure('@' in it) { Invalid("email") } } },
) { name, email -> Account(name, email) }
}
Check a list of any length, and collect every error
accumulate { } records each failure, carries on, and fails with all of them at the end.
import dev.surefold.fail.Either
import dev.surefold.fail.NonEmptyList
import dev.surefold.fail.accumulate
import dev.surefold.fail.attempt
import dev.surefold.fail.ensureOrAccumulate
fun check(lines: List<Line>): Either<NonEmptyList<Invalid>, List<Line>> = attempt {
accumulate {
ensureOrAccumulate(lines.isNotEmpty()) { Invalid("lines") }
lines.forEach { line ->
ensureOrAccumulate(line.qty > 0) { Invalid("qty:${line.sku}") }
}
}
lines
}
Stop at the first failure in a list
One element at a time on the calling thread. Nothing after the first failure runs.
import dev.surefold.fail.Either
import dev.surefold.fail.bind
import dev.surefold.fail.traverse
fun loadAll(ids: List<Int>): Either<Err, List<String>> =
ids.traverse { id -> findUser(id).bind() }
Fall back when one kind of failure happens
Only an IOException is recovered. Any other failure passes through unchanged.
import dev.surefold.fail.Either
import dev.surefold.fail.recover
import java.io.IOException
fun greeting(fetch: () -> String): Either<Throwable, String> =
Either.catch { fetch() }.recover(IOException::class) { "hello" }
Retries, deadlines and limits
Policies are values: build one once, apply it to every call.
Retry with exponential backoff and jitter
At most five retries, then the last failure is rethrown.
import dev.surefold.Schedule
import dev.surefold.retry
import kotlin.time.Duration.Companion.milliseconds
val backoff =
Schedule.exponential<Throwable>(100.milliseconds).jittered() and Schedule.recurs(5)
fun fetch(id: Int): String = backoff.retry { fetchRow(id) }
Keep trying for five seconds
Bounded by elapsed time, not by a number of attempts.
import dev.surefold.Schedule
import dev.surefold.retry
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
val patiently =
Schedule.spaced<Throwable>(20.milliseconds) zipLeft Schedule.upTo(5.seconds)
fun awaitDrained() = patiently.retry { check(pending() == 0L) }
Retry a declared error
The schedule is fed the Left, and the last one is the answer.
import dev.surefold.Schedule
import dev.surefold.fail.Either
import dev.surefold.fail.bind
import dev.surefold.retrying
fun user(id: Int): Either<Err, String> =
Schedule.recurs<Err>(5).retrying { findUser(id).bind() }
Give up after two seconds, with null and no exception
The block is interrupted at the deadline, and the call returns once it has stopped.
import dev.surefold.timeoutOrNull
import kotlin.time.Duration.Companion.seconds
fun maybeQuote(id: Int): String? = timeoutOrNull(2.seconds) { slowQuote(id) }
Protect a flaky partner API
One deadline for the whole call, retries inside it, and three guards that every caller shares.
import dev.surefold.Bulkhead
import dev.surefold.CircuitBreaker
import dev.surefold.RateLimiter
import dev.surefold.Schedule
import dev.surefold.policy
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
class Partner(private val call: (String) -> String) {
private val breaker = CircuitBreaker(
name = "partner-api",
maxFailures = 5,
resetAfter = Schedule.spaced(30.seconds),
)
private val limiter = RateLimiter(
name = "partner-api",
rate = 50,
per = 1.seconds,
burst = 10,
maxWait = 200.milliseconds,
)
private val bulkhead =
Bulkhead(name = "partner-api", maxConcurrent = 20, maxWait = 50.milliseconds)
private val backoff = Schedule.exponential<Throwable>(100.milliseconds)
private val partner = policy("partner-api") {
deadline(2.seconds)
retry(backoff zipLeft Schedule.recurs(3))
guard(breaker)
guard(limiter, cost = 1)
guard(bulkhead)
attemptTimeout(500.milliseconds)
}
fun quote(id: String): String = partner { call(id) }
}
Turn a refused call into a typed error
An open breaker, an empty bucket or a full bulkhead becomes a Left the caller must handle.
import dev.surefold.Bulkhead
import dev.surefold.fail.Either
import dev.surefold.fail.attempt
import dev.surefold.guarded
import dev.surefold.policy
import kotlin.time.Duration.Companion.milliseconds
val reports = policy("reports") {
guard(Bulkhead(name = "reports", maxConcurrent = 4, maxWait = 50.milliseconds))
}
fun report(id: Int): Either<Busy, String> = attempt {
guarded(reports, ifRejected = { Busy(it.guard) }) { buildReport(id) }
}
Resources
Whatever is opened is closed, in reverse order, on every way out.
Commit on success, roll back on a throw
The release is told how the block ended.
import dev.surefold.ExitCase
import dev.surefold.Resource
import dev.surefold.resource
import dev.surefold.use
val connection: Resource<Connection> = resource {
install({ Connection() }) { held, exit ->
if (exit is ExitCase.Failure) held.rollback() else held.commit()
held.close()
}
}
fun rows(id: Int): List<String> = connection use { it.rows(id) }
Open two things, and close both in reverse
A return, a fail, a throw or an interrupt releases the file first and then the connection.
import dev.surefold.resourceScope
import java.io.StringWriter
fun export(id: Int): String = resourceScope {
val db = install({ Connection() }) { held, _ -> held.close() }
val out = install({ StringWriter() }) { held, _ -> held.close() }
db.rows(id).forEach { out.appendLine(it) }
out.toString()
}
Finish a shutdown even when the thread was cancelled
New in 0.18.1.
draining clears the interrupt for the cleanup, uninterruptible repeats the wait, and both hand the interrupt back.
import dev.surefold.draining
import dev.surefold.uninterruptible
import java.util.concurrent.CompletableFuture
class Worker(private val stopped: CompletableFuture<Unit>) {
fun stop() = Unit
fun close() {
draining { stop() }
uninterruptible { stopped.get() }
}
}
Shared state
Values that forks change together, with no lock to take.
Move money between two accounts, or move none
Both balances change in one step. No other thread sees the debit without the credit.
import dev.surefold.Shared
import dev.surefold.fail.Either
import dev.surefold.fail.attempt
import dev.surefold.transact
class Account(pence: Long) {
val balance = Shared(pence)
}
fun transfer(from: Account, to: Account, pence: Long): Either<Insufficient, Unit> =
attempt {
transact {
if (from.balance.get() < pence) fail(Insufficient)
from.balance.update { it - pence }
to.balance.update { it + pence }
}
}
Wait until there is stock, but not for ever
waitForChange() parks until the value is committed again. On timeout nothing is taken.
import dev.surefold.Shared
import dev.surefold.timeoutOrNull
import dev.surefold.transact
import kotlin.time.Duration.Companion.seconds
val stock = Shared(0)
fun take(n: Int) = transact {
val left = stock.get()
if (left < n) waitForChange()
stock.set(left - n)
}
fun takeSoon(n: Int): Boolean = timeoutOrNull(2.seconds) { take(n) } != null
Count from many forks
update is a step of its own, so no increment is lost.
import dev.surefold.Shared
import dev.surefold.parMap
fun imported(rows: List<String>): Int {
val done = Shared(0)
parMap(rows) { row ->
store(row)
done.update { it + 1 }
}
return done.peek()
}
Log once, however many times the step ran
A step that loses to another commit runs again. afterCommit runs once, after it has landed.
import dev.surefold.Shared
import dev.surefold.logInfo
import dev.surefold.transact
class Seats(count: Int) {
private val free = Shared(count)
fun hold(orderId: String, n: Int) = transact {
val left = free.get()
if (left < n) waitForChange()
free.set(left - n)
afterCommit { logInfo("held $n for $orderId, ${left - n} left") }
}
}
Hold callers until warm-up is done
A latch is a promise with nothing in it. Every waiter is released by the one succeed.
import dev.surefold.Promise
import dev.surefold.awaitValue
import kotlin.time.Duration.Companion.seconds
class Warmup {
private val ready = Promise<Nothing, Unit>()
fun finished() {
ready.succeed(Unit)
}
// False if the caches are still cold after thirty seconds.
fun awaitReady(): Boolean = ready.awaitValue(30.seconds) != null
}
Handing work between forks
A bounded channel, and a way to wait on several things at once.
Read on one fork and write on another, with a bound
At most 64 rows wait between the two, so a fast reader parks instead of filling memory.
import dev.surefold.channel
import dev.surefold.scope
fun copy(source: Sequence<Row>, write: (Row) -> Unit) = scope {
val rows = channel<Row>(capacity = 64)
async {
for (row in source) if (!rows.send(row)) break
rows.close()
}
for (row in rows) write(row) // ends once the channel is closed and drained
}
Stop a producer from the consumer's side
After cancel() the producer's next send answers false, and its loop ends without an interrupt.
import dev.surefold.channel
import dev.surefold.scope
fun firstTen(): List<Int> = scope {
val numbers = channel<Int>(capacity = 8)
async {
var n = 0
while (numbers.send(n)) n++
}
numbers.take(10).also { numbers.cancel() }
}
Work until a time budget runs out, and finish the item in hand
A timeout would interrupt write partway through a row. select lets it finish, then stops.
import dev.surefold.channel
import dev.surefold.scope
import dev.surefold.select
import kotlin.time.Duration
fun copyWithin(budget: Duration, source: Sequence<Row>, write: (Row) -> Unit): Int =
scope {
val rows = channel<Row>(capacity = 64)
async {
for (row in source) if (!rows.send(row)) break
rows.close()
}
val deadline = async { Thread.sleep(budget.inWholeMilliseconds) }
var written = 0
var more = true
while (more) {
more = select {
deadline.onAwait { false } // written first, so it wins a tie with a row
rows.onReceive { row ->
if (row != null) {
write(row)
written++
}
row != null
}
}
}
deadline.cancel()
rows.cancel()
written
}
Several systems, one outcome
When there is no transaction to share, undo what worked.
Debit one bank, credit another, and refund if the credit fails
New in 0.18.1.
Each step pairs an action with its undo. Undos run newest first, and a step whose outcome is unknown is checked before anything is undone.
import dev.surefold.Settled
import dev.surefold.fail.Either
import dev.surefold.fail.attempt
import dev.surefold.saga
fun transfer(
bank: Bank,
id: String,
from: String,
to: String,
pence: Long,
): Either<Refused, Long> = attempt {
saga(id, name = "transfer") {
val taken = step(
"debit",
action = { key -> bank.debit(key, from, pence) ?: fail(Refused.Funds) },
check = { key -> settled(bank, key) },
) { key, debited, _ -> bank.refund(key, from, debited) }
step(
"credit",
action = { key -> bank.credit(key, to, taken) ?: fail(Refused.Closed) },
check = { key -> settled(bank, key) },
) { key, credited, _ -> bank.reverse(key, to, credited) }
}
}
// What the bank says about a step whose outcome is unknown.
fun settled(bank: Bank, key: String): Settled<Long> =
bank.find(key)?.let { Settled.Happened(it) } ?: Settled.DidNot
The key is built from the saga's id and the step's name, so the bank can recognise a repeat.
Caches
From surefold-cache: a lookup with a memory.
One lookup per key, and the last good answer during an outage
Two hundred callers asking for the same pair share one call. While the provider is down, a rate up to ten minutes old still answers.
import dev.surefold.cache.Cache
import dev.surefold.fail.Either
import java.math.BigDecimal
import kotlin.time.Duration.Companion.minutes
import kotlin.time.Duration.Companion.seconds
class Rates(source: RateSource) : AutoCloseable {
private val cache = Cache<String, RateError, BigDecimal>(
ttl = { answer ->
when (answer) {
is Either.Right -> 30.seconds // a rate is good for half a minute
is Either.Left -> 2.seconds // a failure is kept for two seconds
}
},
stale = 10.minutes,
capacity = 1_000,
) { pair -> source.rate(pair) }
fun rate(pair: String): Either<RateError, BigDecimal> = cache.get(pair)
override fun close() = cache.closeAndJoin()
}
Context, logs and metrics
What a request carries reaches every fork it starts.
Carry a request id into every fork
A plain virtual thread inherits nothing. A SurefoldLocal is bound again inside each fork.
import dev.surefold.parMap
import dev.surefold.surefoldLocal
val requestId = surefoldLocal { "none" }
fun tagged(rows: List<String>): List<String> =
requestId.locally("abc-123") {
parMap(rows) { row -> "${requestId.get()}: $row" } // every branch reads abc-123
}
Put a correlation id on every log line, forks included
Each line logged inside the block carries the annotation, whichever thread wrote it.
import dev.surefold.logAnnotated
import dev.surefold.logInfo
import dev.surefold.parMap
fun importAll(batch: String, rows: List<String>) =
logAnnotated("batch" to batch) {
parMap(rows) { row -> logInfo("imported $row") }
}
Count something, with tags
The counter goes to whichever registry is bound: Micrometer or OpenTelemetry in a service, a capture in a test.
import dev.surefold.counter
import dev.surefold.increment
fun placed(channel: String) {
counter("orders.placed", "channel" to channel).increment()
}
Testing
Time, logs and metrics are values a test can hold.
Test a backoff without waiting for it
Under fixedClock() a sleep returns at once, so five retries take microseconds.
import dev.surefold.Schedule
import dev.surefold.clock
import dev.surefold.fixedClock
import dev.surefold.retry
import kotlin.time.Duration.Companion.seconds
val backoff = Schedule.exponential<Throwable>(1.seconds) and Schedule.recurs(5)
fun succeedsOnTheFourthTry() {
var attempts = 0
val row = clock.locally(fixedClock()) {
backoff.retry { if (++attempts < 4) error("not yet") else "row" }
}
check(row == "row" && attempts == 4)
}
Move time by hand
A TestClock moves only when the test says so.
import dev.surefold.TestClock
import dev.surefold.clock
import java.time.Duration
import java.time.Instant
import kotlin.time.Duration.Companion.minutes
class Session(private val issued: Instant) {
fun expired(): Boolean =
Duration.between(issued, clock.get().now()) > Duration.ofMinutes(30)
}
fun aSessionExpiresAfterHalfAnHour() {
val time = TestClock()
clock.locally(time) {
val session = Session(issued = clock.get().now())
time.adjust(29.minutes)
check(!session.expired())
time.adjust(2.minutes)
check(session.expired())
}
}
Assert on what was logged and counted
Both captures bind an in-memory logger or registry for the block.
import dev.surefold.capturingLogs
import dev.surefold.capturingMetrics
import dev.surefold.counter
import dev.surefold.increment
import dev.surefold.logInfo
fun registeringLogsALine() = capturingLogs { logs ->
logInfo("registered")
check(logs.all().size == 1)
}
fun adoptingCountsOne() = capturingMetrics { measured ->
counter("petshop.adoptions").increment()
check(measured.counter("petshop.adoptions") == 1.0)
}
Write a test as a story, and wait for what is eventually true
From surefold-test. When a step fails, the message shows the story up to that step.
import dev.surefold.assert.shouldBe
import dev.surefold.test.story
import kotlin.time.Duration.Companion.seconds
import org.junit.jupiter.api.Test
class AdoptionTest {
@Test
fun `an adopted pet is listed as taken`() = story {
val shop = Given("a shop with two pets") { PetShop("Nibbles", "Barnaby") }
val taken = When("Ada adopts the first") { shop.adoptFirst("Ada") }
Then("Ada has Nibbles") { taken shouldBe "Nibbles" }
And("the listing says so").eventually(within = 5.seconds) {
shop.status("Nibbles") shouldBe "taken"
}
}
}
Streams
From surefold-stream: a pipeline described once, with its failure in the type.
Total a list, and stop with a named error at the first bad row
The description names no backend. Forks() runs it on one virtual thread.
import dev.surefold.await
import dev.surefold.stream.Exit
import dev.surefold.stream.Forks
import dev.surefold.stream.Stream
import dev.surefold.stream.from
import dev.surefold.stream.mapOrFail
import dev.surefold.stream.run
import dev.surefold.stream.runFold
fun takings(orders: List<Order>): String {
val exit =
Stream.from(orders)
.mapOrFail { order -> order.pence ?: fail(Unpriced(order.id)) }
.runFold(0L) { total, pence -> total + pence }
.run(Forks())
.await()
return when (exit) {
is Exit.Done -> "took ${exit.value}p"
is Exit.Failed -> "order ${exit.error.id} has no price"
is Exit.Died -> "died: ${exit.cause}"
}
}
Run a blocking call per element, four at a time, in order
Each element in flight gets a virtual thread. The fifth waits, which is the backpressure.
import dev.surefold.stream.Stream
import dev.surefold.stream.from
import dev.surefold.stream.mapPar
fun receipts(records: List<Record>, store: Store): Stream<Nothing, Receipt> =
Stream.from(records).mapPar(4) { record -> store.write(record) }
Let the concurrency find its own level
An adaptive limit grows while calls stay fast and drops when they start to queue. Share one per dependency.
import dev.surefold.Limit
import dev.surefold.stream.Stream
import dev.surefold.stream.from
import dev.surefold.stream.mapPar
val ordersDb = Limit.adaptive("orders-db", initial = 20, max = 1_000)
fun written(orders: List<Order>, db: OrdersDb): Stream<Nothing, Int> =
Stream.from(orders).mapPar(ordersDb) { order -> db.write(order) }
Actors
From surefold-actor: one owner for state that changes.
Keep a running total with no lock
Messages are handled one at a time, so the state is never shared. ask answers an Either, never an exception.
import dev.surefold.actor.Reply
import dev.surefold.actor.ask
import dev.surefold.actor.become
import dev.surefold.actor.behaviour
import dev.surefold.actor.spawn
import dev.surefold.actor.stay
import dev.surefold.scope
import kotlin.time.Duration.Companion.seconds
sealed interface Till
data class Ring(val pence: Int) : Till
data class Total(val reply: Reply<Int>) : Till
fun till() = behaviour<Till, Int>(0) { _, total, message ->
when (message) {
is Ring -> become(total + message.pence)
is Total -> stay().also { message.reply(total) }
}
}
fun main() {
val total = scope {
val till = spawn("till", till())
till.tell(Ring(250))
till.tell(Ring(120))
till.ask(1.seconds) { Total(it) }
}
println(total) // Right(value=370)
}