Skip to content
Patterns

Patterns

Common problems and how to solve them with bikesched. Each pattern links a runnable example with a test in bikesched-examples and the concept pages for the details.

Pattern Use it when Example
Transactional outbox a database change must trigger a call to another system Kotlin shop
Deduplicating incoming messages a sender delivers the same message more than once Chat
Calling an unreliable API a call can fail for technical reasons or with a business answer Outcome
Staying within a rate limit a provider accepts only so many calls per second Rate limit
Waiting for a webhook another system reports back later, or not at all Poll
Approval with reminder and escalation a person has to decide, maybe not in time Approval
Fan-out/fan-in work splits into parallel parts that are combined Fan-out
Periodic work a clean-up or sync must run on a schedule, once per run across all nodes Recurring
Saga a sequence of calls must be undone if a later one fails Taxi booking

Transactional outbox

Writing to your database and calling another system can’t be atomic. Schedule a job in the same transaction instead: it exists only if your change commits, and then makes the call.

transaction {
    Orders.insert { … }
    bikesched.createJob(PROCESS_ORDER, ProcessOrderPayload(orderId), connection = connection.connection as Connection)
}
  • The job is the outbox entry: no outbox table, no relay process.
  • The job runs at least once, so its calls need idempotency keys (next patterns).

Example: Kotlin shop. Details: Transactional scheduling.

Deduplicating incoming messages

Webhooks and message brokers deliver at least once. Use the sender’s message id as the job’s idempotency key, and a redelivery schedules nothing:

UUID jobId = bikesched.newJob(ANSWER_MESSAGE)
        .payload(message)
        .idempotencyKey(message.messageId())   // a redelivery returns the first job's id
        .schedule();
  • Concurrent deliveries are deduplicated too: the second waits for the first transaction.
  • A key stays taken while the job exists (its retention). Keys are unique per job name, so add the tenant to keys from several tenants.

Example: Chat. Details: Idempotency keys.

Calling an unreliable API

Let technical errors throw, so the job is retried. Return expected business answers as the step’s result, so they are stored and not retried. Pass an idempotency key derived from the step:

ChargeOutcome outcome = job.step("charge-card", ChargeOutcome.class, step -> {
    try {
        return new Charged(provider.charge(order, step.jobId() + ":" + step.name()));
    } catch (CardDeclinedException e) {
        return new Declined(e.code());   // stored, not retried
    }
});
  • An IOException fails the attempt; the retry repeats the step with the same key, so the provider charges once.
  • A completed step is never repeated, also when a later step fails.

Example: Outcome. Details: Business outcomes as results, Failures and retries.

Staying within a rate limit

Take a token from a shared bucket before the call. Without one, postpone the job until the bucket refills:

job.step("send", String.class, step -> {
    ConsumptionProbe probe = bucket.tryConsumeAndReturnRemaining(1);   // Bucket4j, stored in PostgreSQL
    if (!probe.isConsumed()) {
        job.postpone(Duration.ofNanos(probe.getNanosToWaitForRefill()));
    }
    return provider.send(sms.to(), sms.text());
});
  • Postponing uses up no attempt, records no failure and frees the node’s slot while waiting.
  • A bucket in the database holds the limit across all nodes.

Example: Rate limit. Details: Postponing.

Waiting for a webhook

Start the remote operation in a step and wait for an event keyed by the id it returns. The webhook endpoint publishes the event. If the webhook doesn’t arrive in time, poll:

String paymentId = job.step("create-payment", String.class, step -> provider.createPayment(…));
PaymentSettled settled = job.waitForEvent("await-webhook", PAYMENT_SETTLED, paymentId)
        .timeout(Duration.ofMinutes(5))
        .onFailure(failing -> failing.resolve(null))
        .receive();
if (settled == null) {
    settled = job.newPoll("poll-payment", PaymentSettled.class, Duration.ofMinutes(1))
            .run(step -> provider.status(paymentId).map(Poll::ready).orElseGet(Poll::notReady));
}
// webhook endpoint
bikesched.newEvent(PAYMENT_SETTLED, payment.paymentId())
        .payload(payment)
        .idempotencyKey(delivery.deliveryId())
        .publish();
  • The job waits without a thread. A webhook arriving before the job waits is not lost: the wait receives it right away.
  • The payment id is a stored step result, so every resume waits for the same payment.

Example: Poll. Details: Events, Polling.

Approval with reminder and escalation

Wait for the decision with a timeout. A failure handler resolving with null turns the timeout into the next stage instead of a failure:

job.step("request-approval", () -> inbox.requestApproval(expense.manager(), expense));
Decision decision = job.waitForEvent("await-decision", EXPENSE_DECIDED, id)
        .timeout(Duration.ofDays(3))
        .onFailure(failing -> failing.resolve(null))
        .receive();
if (decision == null) {
    job.step("send-reminder", () -> inbox.remind(expense.manager(), expense));
    decision = job.waitForEvent("await-decision-after-reminder", EXPENSE_DECIDED, id)
            .timeout(Duration.ofDays(2))
            .onFailure(failing -> failing.resolve(null))
            .receive();
}
if (decision == null) {
    job.step("escalate", () -> inbox.requestApproval(FINANCE_LEAD, expense));
    decision = job.awaitEvent("await-escalated-decision", EXPENSE_DECIDED, id);
}
  • Each stage is a separate wait step on the same event: a decision published after a stage timed out is received by the next one.
  • The job holds no thread or slot during the days it waits.

Example: Approval. Details: Timeouts.

Fan-out/fan-in

Start one child job per part, then wait for each. The children run in parallel, on any node:

List<UUID> children = album.files().stream()
        .map(file -> job.newJob(RESIZE_PHOTO).payload(new Photo(albumId, file)).stepName("resize " + file).schedule())
        .toList();
for (UUID child : children) {
    switch (job.waitForJob(child, Thumbnail.class)) {
        case JobResult.Succeeded<Thumbnail>(UUID childId, Thumbnail thumbnail) -> thumbnails.add(thumbnail);
        case JobResult.Failed<Thumbnail> failed -> skipped++;
        case JobResult<Thumbnail> other -> throw new IllegalStateException("Unexpected outcome: " + other);
    }
}
  • Each child is started once: the start is a step of the parent.
  • The parent waits without a thread. A failed child doesn’t fail the parent; it decides from the outcome.

Example: Fan-out. Details: Child jobs.

Periodic work

Register a recurring job on every node at startup. bikesched keeps exactly one occurrence pending, so each run happens once, on whichever node claims it:

bikesched.newJob("clean-up-sessions")
        .handler(job -> sessions.removeExpired())
        .schedule(Recurrence.every(Duration.ofHours(1)));   // or daily/weekly, cron via bikesched-cron
  • Registering is idempotent: no leader election or lock needed. Runs missed while no node was up are skipped, not caught up.
  • Each occurrence is a regular job with retries and timeouts. To keep a long sync resumable, split it into steps.

Example: Recurring. Details: Recurring jobs.

Saga

Give each step with a side effect a compensation. If the job is cancelled or fails for good, the completed steps are undone, latest first:

job.newStep("send-to-broker", Void.class)
        .compensateWith((step, result) -> broker.cancelRide(ride.rideId()))
        .run(step -> { broker.requestRide(ride); return null; });
PaymentReservation reservation = job.newStep("reserve-payment", PaymentReservation.class)
        .compensateWith((step, stored) -> payments.release(stored))
        .run(step -> payments.reserve(customer, offer.price(), offer.currency(), ride.rideId()));
job.step("approve-ride", RideApproval.class, step -> broker.approveRide(ride.rideId(), offer, reservation));
  • bikesched.cancel(jobId, reason) from outside and job.cancel(reason) inside run the same compensations.
  • Compensations run at least once, so they must be idempotent.

Example: Taxi booking. Details: Compensation.