Steps and compensation
Steps make the work inside a job durable: a completed step is not repeated when the job is retried or resumed, and it can declare how to undo itself.
Durable steps
Steps work like durable functions. A step that completed in an earlier attempt is not executed again; its stored result is returned instead:
bikesched.registerJobHandler("order", job -> {
Order order = job.payload(Order.class);
Payment payment = job.step("charge-card", Payment.class, step -> payments.charge(order));
job.step("send-confirmation", Void.class, step -> {
mailer.send(order, payment); // if this fails, the retry does not charge the card again
return null; // Void steps store no result
});
});For a step with no result, job.step(name, Runnable) is shorter than job.step(name, Void.class, step -> { … ; return null; }):
job.step("send-confirmation", () -> mailer.send(order, payment));- The result is mapped by the
JsonMapperand stored inbikesched_stepsright after the step completes. - Step names identify steps across attempts, so they must be unique within a job and called in a deterministic way.
- The step handler receives the
Step(job id, name and attempt number), e.g. for idempotency keys. - Code outside of steps runs again on every attempt, so it should be cheap and deterministic.
- Steps cannot be nested: while a step handler runs,
job.step(...),job.newStep(...), event waits and sleeps of the same job throw anIllegalStateException(from any thread, so steps of one job cannot run in parallel either). An inner step would complete durably even if the outer step failed, and its retry would skip it. Run the steps one after the other instead. The same applies inside compensations.
Idempotency keys
Steps run at least once: a completed step is not repeated, but a step whose side effect happened before its completion was stored runs again, e.g. after a crash right after the side effect, or on a node that lost its job (see Nodes) while another node runs the step too. bikesched stores only one result, but cannot undo the side effect. Pass an idempotency key derived from the step to external systems, so they recognize a repeated call:
Payment payment = job.step("charge-card", Payment.class, step ->
payments.charge(order, step.jobId() + ":" + step.name())); // same key in every attemptUse the job id and step name, not the attempt number, which changes between attempts.
Business outcomes as results
A step that throws fails, and the job is retried. That suits technical errors (a timeout, a connection reset), but not expected business outcomes: a declined payment stays declined on every retry, uses up the job’s attempts and, once they are exhausted, starts its compensations. Return such outcomes as the step’s result instead, with a sealed type for success and the expected errors:
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME)
@JsonSubTypes({@JsonSubTypes.Type(Charged.class), @JsonSubTypes.Type(Declined.class)})
sealed interface ChargeOutcome permits Charged, Declined {}
record Charged(String receiptId) implements ChargeOutcome {}
record Declined(String code, String reason) implements ChargeOutcome {}
ChargeOutcome outcome = job.step("charge-card", ChargeOutcome.class, step -> {
var response = payments.charge(order, step.jobId() + ":" + step.name());
return response.approved()
? new Charged(response.receiptId())
: new Declined(response.declineCode(), response.message()); // stored, not retried
});
switch (outcome) {
case Charged c -> job.step("send-receipt", () -> mailer.sendReceipt(order, c.receiptId()));
case Declined d -> job.cancel("payment declined: " + d.code());
}- The outcome is stored like any step result, so a later attempt or resume takes the same branch.
- Exceptions stay for what a retry may fix.
- The
JsonMappermust restore the concrete type: with Jackson, declare the subtypes as above.
Sleeping
A handler can pause for a duration or until a point in time, as a durable step. Like an
event wait, the attempt ends at the sleep and the job is suspended in state WAITING,
without holding a thread or a concurrency slot; once the wake-up time has passed, the handler runs
again from the top, completed steps are skipped and the sleep returns:
bikesched.registerJobHandler("trial", job -> {
Account account = job.payload(Account.class);
job.step("send-welcome", () -> mail.welcome(account));
job.sleep("trial-period", Duration.ofDays(14));
job.step("send-trial-ended", () -> mail.trialEnded(account));
});
job.sleepUntil("until-check-in", booking.checkIn().minus(Duration.ofDays(1)));- The step name identifies the sleep across runs, like any step name; it must be unique within the job.
- The first run stores the wake-up time with the step (
wake_at, computed by the database forsleep). Later runs ignore the argument, so a duration changed in a deploy or a time computed fromInstant.now()doesn’t move a sleep that already started. sleepUntilwith a time that has passed returns right away; the step is stored as completed.- The node that suspended the job wakes up at the wake-up time; other nodes find it with their next-due query, see Due jobs start right away.
- Sleeping does not use up an attempt. Cancelling a sleeping job marks the step
CANCELLEDand runs the compensations of its completed steps. - Sleeping inside a step handler or a compensation is rejected, like nested steps.
Polling
A handler can poll an external service until a result is ready, as one durable step. Each run of
the handler checks once: if the result is not ready, the attempt ends at the poll and the job is
suspended in state WAITING until the next check, without holding a thread or a concurrency slot,
like a sleep. Once a check is ready, the poll returns the value, which is stored and
returned on later runs without checking again:
Report report = job.newPoll("await-report", Report.class, Duration.ofSeconds(30))
.timeout(Duration.ofHours(2)) // optional
.run(step -> switch (reports.status(reportId)) {
case Done d -> Poll.ready(d.report());
case Pending pending -> Poll.notReady();
});| The poll handler… | Step | Job |
|---|---|---|
returns Poll.ready(value) |
SUCCEEDED, the value stored |
continues |
returns Poll.notReady() |
WAITING until the next check |
suspended, the attempt given back |
returns Poll.notReady() after the deadline |
TIMED_OUT |
fails with a PollTimeoutException, unless the failure handler resolves the poll |
| throws | FAILED |
the attempt fails and is retried (with the node’s retry backoff); the next attempt checks right away. In the last attempt the failure handler runs, if any |
- A poll is one row in
bikesched_stepsfor all its checks; the step’sattemptscounts them, and the poll handler receives it asstep.attempts(). Checks that are not ready don’t use up attempts. - The interval is required. For a growing one, pass a
RetryBackoffinstead of aDuration: it is called after each check that is not ready, with the number of that check, e.g.job.newPoll("await-report", Report.class, RetryBackoff.exponential(Duration.ofSeconds(5), Duration.ofMinutes(5))).Poll.notReady(Duration)sets the time until the next check for one check, e.g. from aRetry-Afterheader. timeout(Duration)stops polling after the given time, counted from the first check; the last check runs at the deadline. Then the job fails without further attempts with aPollTimeoutException. Without a timeout, the poll checks until it is ready or the job is cancelled.onFailure(…)sets a failure handler, the same as a step’s. It runs right away once the poll timed out, and when a check throws in the job’s last attempt. It may resolve the poll with a fallback, whichrunreturns and which is stored like a ready value:.timeout(Duration.ofHours(2)).onFailure(failing -> failing.resolve(Report.UNAVAILABLE)).- The deadline stored on the first check wins: a timeout changed in a deploy doesn’t move a poll that already started. Polling again after a timeout needs a new step name.
- A due check runs when it is due, like a sleep wakes up. Each check is a claim and a suspension of the job; for checks every second or faster, loop inside a step instead.
- An expected negative answer (e.g. the report failed) is a ready value too, see Business outcomes as results; exceptions are for errors a retry may fix.
- The history records the poll’s first wait and its outcome (with
the number of
checks), not every check. - Polling inside a step handler or a compensation is rejected, like nested steps. Cancelling a
polling job marks the poll
CANCELLEDand runs the compensations of its completed steps.
Polling with a loop of steps and sleeps (check-1, wait-1, check-2, …) works too, but adds two
rows per check, and every run replays all earlier checks. Failing the attempt with
job.fail(…).retryAfter(…) while the result is not ready uses up attempts and counts as a failure.
Webhooks with a polling fallback
When a service sends a webhook but may lose it, wait for the webhook for a short time and poll if it doesn’t arrive:
PaymentSettled webhook = job.waitForEvent("await-webhook", PAYMENT_SETTLED, paymentId)
.timeout(Duration.ofSeconds(30))
.onFailure(failing -> failing.resolve(null)) // no webhook in time: poll instead
.receive();
PaymentSettled settled = webhook != null
? webhook
: job.newPoll("poll-payment", PaymentSettled.class, Duration.ofMinutes(1))
.timeout(Duration.ofHours(1))
.run(step -> provider.status(paymentId).map(Poll::ready).orElseGet(Poll::notReady));The failure handler can’t poll itself (it can’t run steps), so the poll comes after the wait. The poll example shows both paths.
Working with a workflow engine
Bikesched is not a workflow or process orchestration engine: there are no process models (BPMN), no visual modelling and no orchestration across services. It is, however, a good building block for an application that wants to integrate nicely with an external workflow or process engine (e.g. Camunda, Temporal, AWS Step Functions): a step starts a process there and stores its process id, and a poll step durably waits for the process to finish, without holding a thread or a concurrency slot while it runs. The job is created in the same transaction as the customer row it is onboarding, so one never exists without the other:
try (Connection connection = dataSource.getConnection()) {
connection.setAutoCommit(false);
insertCustomer(connection, customer);
bikesched.newJob("onboard-customer").payload(customer).connection(connection).schedule();
connection.commit();
}bikesched.registerJobHandler("onboard-customer", job -> {
Customer customer = job.payload(Customer.class);
String processId = job.step("start-onboarding-process", String.class,
step -> workflowEngine.startProcess("onboard-customer", Map.of("customerId", customer.id())));
ProcessResult result = job.newPoll("await-onboarding-process", ProcessResult.class, Duration.ofSeconds(30))
.timeout(Duration.ofHours(4))
.run(step -> switch (workflowEngine.status(processId)) {
case Completed c -> Poll.ready(c.result());
case Running running -> Poll.notReady();
});
job.step("activate-account", () -> accounts.activate(customer, result));
});- The process id is the step’s result, stored like any other step result, so a retry or resume does not start the process again.
- The poll step checks the workflow engine’s own status API on an interval, exactly like polling an external service; nothing about it is specific to workflow engines.
- Business decisions, side effects and compensation stay in bikesched’s jobs and steps; the workflow engine only runs the process between the start step and the poll.
Compensation
Steps with side effects can declare a compensation that undoes them if the job is cancelled or fails permanently (a saga). Compensation is optional, per step:
bikesched.registerJobHandler("order", job -> {
Order order = job.payload(Order.class);
Reservation reservation = job.newStep("reserve-payment", Reservation.class)
.compensateWith((step, r) -> payments.release(r)) // gets the step and its stored result
.run(step -> payments.reserve(order));
job.step("ship", () -> shipping.ship(order, reservation));
});
bikesched.cancel(orderJobId, "order withdrawn"); // releases the reservation if it was madenewStep(name, Class).run(handler) without compensateWith is the same as step(...).
- A job without completed compensable steps is cancelled or failed right away.
- Otherwise it becomes
COMPENSATING. A node replays its handler in compensation mode: completed steps return their stored results and register their compensations, and the replay ends at the first step, event wait or sleep that has not completed. Then the compensations run, latest step first, and each compensated step becomesCOMPENSATED. The job then endsCANCELLEDorFAILED. - A failing compensation is retried (up to
maxAttemptscompensation attempts, with the node’s retry backoff); compensations that already succeeded are not run again. After that the job isCOMPENSATION_FAILEDand needs manual attention. - Compensations run at least once, so they must be idempotent. The handler’s code outside of
steps runs again during the replay;
job.isCompensating()tells it apart.
Retry delay per step
A failed step makes the attempt fail, and the job is retried after the node’s RetryBackoff. A step
can have its own delay with retryBackoff(…) on the step builder, e.g.
job.newStep("charge", Payment.class).retryBackoff(RetryBackoff.exponential(Duration.ofSeconds(1), Duration.ofSeconds(30))).run(…).
The backoff receives the step’s number of failed attempts. job.fail(…).retryAfter(…) still takes
precedence. In Kotlin: step<Payment>("charge", retryBackoff = …) { … }.
Failure handler per step
A step can have a failure handler with onFailure(…) on the step builder. It runs when the step
failed in the last attempt of its job, before the step and the job are recorded as failed:
job.newStep("charge", Payment.class)
.onFailure(failing -> orders.markFailed(orderId, failing.error()))
.run(step -> paymentService.charge(orderId));The handler gets a FailingStep with the job id, the step name and the stored error (the
exception’s toString()), never the exception itself: it may run again in a later attempt or on
another node, where only the stored text exists.
It can also resolve the step with a fallback result, so the job continues; this is how a step gets its retries first and a fallback after them:
Rate rate = job.newStep("fetch-rate", Rate.class)
.onFailure(failing -> failing.resolve(Rate.DEFAULT))
.run(step -> rates.fetch(currency));- The step is
FAILINGwhile the handler runs, thenFAILEDand the job fails, orSUCCEEDEDwith the fallback if resolved (stored and returned on later runs like any step result). - A resolved step is not compensated, even with
compensateWith: its side effect failed. - If the handler throws, or the node dies before the outcome is recorded, the job gets an extra
attempt that runs the handler again, so it must be idempotent. After the node’s
failureHandlerAttemptsruns (default 3, see Configuration) the step isFAILEDwithout it. - Steps without a handler just fail.
Event waits and polls take the same onFailure(…): it handles
their timeout (right away, not only in the last attempt) and a poll check failing in the last
attempt.
In Kotlin: step<Rate>("fetch-rate", onFailure = { failing -> failing.resolve(Rate.DEFAULT) }) { … }.