Events
A handler can wait for an event as a durable step. If the event hasn’t been published yet, the
attempt ends and the job is suspended in state WAITING, without holding a thread or a concurrency
slot. Publishing the event resumes it, and the handler runs again from the top: completed steps are
skipped, and the wait now returns the event’s payload. Like a step, the wait stores it: publishing
copies the payload into the step, so later runs return it even after the event was deleted.
Waiting and publishing
bikesched.registerJobHandler("order", job -> {
Order order = job.payload(Order.class);
Payment payment = job.waitForEvent("await-payment", "payment-received", order.id(), Payment.class)
.receive();
job.step("ship", () -> shipping.ship(order, payment));
});
// e.g. in a payment webhook; .connection(connection) publishes in your own transaction
UUID eventId = bikesched.newEvent("payment-received", order.id())
.payload(payment)
.publish(); // the id of the published event, e.g. to log it or store it with your data- An event is identified by its name and key and goes to every step waiting for it.
receive()returns the payload mapped to the class given towaitForEventby theJsonMapper; the step stores the payload as it is.- Payload that already is JSON text, e.g. a forwarded webhook body, goes in with
.payloadJson(body)instead of.payload(...): stored as it is, without theJsonMapper(a Jackson mapper would turn aStringinto a JSON string). Invalid JSON failspublish(). - To derive something from the payload, do it after
receive: a pure conversion can run again on every resume; anything with side effects belongs in a step after the wait. To keep the stored copy small, keep the event’s payload small (e.g. ids instead of whole documents). - Events are stored in
bikesched_eventsfor their retention. A step that starts waiting after the event was published receives the latest one whose retention has not passed, right away. See Retention. - Waiting does not use up an attempt.
- Code outside steps runs again on every resume, so it must be cheap and deterministic.
Idempotency keys
A webhook the provider delivers twice publishes the event twice. With an idempotency key, it is published once:
bikesched.newEvent("payment-received", order.id())
.payload(payment)
.idempotencyKey(webhook.deliveryId())
.publish(); // a repeated delivery returns the first event's id- While an event with the same name, key and idempotency key is kept (its
retention has not passed),
publishreturns that event’s id: nothing is stored, no waiting step receives anything, and the duplicate’s payload is ignored. With a retention ofDuration.ZERO, the key has no effect. - The check runs under the advisory lock
publishtakes on name and key, so concurrent duplicates are published once, also with.connection(connection). - Keys have 1 to 500 characters and at most 1500 bytes in UTF-8. The event listener is not called for a duplicate.
- Events published by a job (
Job.newEvent) have no key: their step publishes them once.
Jobs have the same option, see Idempotency keys.
References
Like a job, an event can name the external entity it is about, so it can be found by it in the admin UI:
bikesched.newEvent("payment-received", order.id())
.payload(payment)
.reference(payment.id())
.publish();- Optional, 1 to 200 characters, not unique, never changed; the
event listener gets it in
EventPublication. - Unlike the key, the reference is not matched against waiting steps.
- An event published by a job (
Job.newEvent) has the job’s reference unless its builder sets one (reference(null)for none).
See References for jobs.
Lifecycle
How a job and its wait step move through their states:
stateDiagram-v2
direction LR
[*] --> WAITING: wait reached, event not published yet
[*] --> SUCCEEDED: event already published, payload copied
WAITING --> SUCCEEDED: event published, payload copied
WAITING --> TIMED_OUT: deadline passed
WAITING --> CANCELLED: job cancelled
-
The handler reaches the wait. If no matching, unexpired event exists, the step is created
WAITING(withwake_atif it has a timeout). The attempt ends: the job becomesWAITING, due at the deadline (or never without one), its lock is released and the attempt is given back, so waiting does not count as an attempt. -
The event is published. In one transaction, holding the advisory lock on name and key:
- the event is inserted with its expiry (
expires_at); - every step
WAITINGfor that name and key becomesSUCCEEDED, with a copy of the payload as its result and the event’s id (event_id); - every job
WAITINGat such a step becomesSCHEDULED, due now.
A job that is still
RUNNINGat that moment (it is just suspending) is left alone: suspending finds its stepSUCCEEDEDand schedules the job right away instead of letting it wait. - the event is inserted with its expiry (
-
A node claims the job. It becomes
RUNNINGwith a new attempt, and its handler runs from the top: completed steps return their stored results, and so does the wait. -
The handler continues after the wait and the job ends as usual, e.g.
SUCCEEDED, or it waits again at the next wait.
Other paths:
- Published before the wait: the step is created
SUCCEEDEDwith the latest unexpired event’s payload right away; the job is never suspended. - Timeout: the job becomes due at
wake_at. Its next run finds the deadline passed and marks the stepTIMED_OUT; the job fails, unless the wait’s failure handler resolves it with a fallback, whichreceivereturns on this and every later run. See Timeouts. - Cancellation: cancelling the job marks a
WAITINGstepCANCELLED; it no longer receives events. - Later runs (after another wait or a retry) return the step’s copy of the payload, also after the event was deleted.
With the history enabled, each of these changes is recorded: the
step WAITING, RECEIVED or TIMED_OUT, the job SUSPENDED and RESUMED. Publishing records
the event’s own PUBLISHED entry (with its key, retention and the number of steps that
received it); the steps it completes and the jobs it resumes name the event as their cause.
bikesched.findEventHistory(eventId) reads both, also after the event and the jobs were deleted:
for (HistoryEntry entry : bikesched.findEventHistory(eventId)) {
System.out.println(entry.action() + " " + entry.subjectId()); // PUBLISHED, RECEIVED, RESUMED
}A publish in the name of a user, e.g. from a support tool, names the user on the PUBLISHED entry
with actor(Actor.user(name)); the entries it causes stay the application’s:
bikesched.newEvent("payment-received", orderId).actor(Actor.user("simon")).publish();Publishing from jobs
Use Job.newEvent to publish as a durable step. The event, delivery to waiting jobs and completion
of the publishing step commit together. A retry or replay finds the step and returns the same
event id without publishing the event again:
UUID eventId = job.newEvent("order-shipped", order.id())
.payload(shipment)
.publish();The default step name is publish <eventName>. If a handler publishes that event more than once
(for example, in a loop), provide distinct names with .stepName("publish shipment " + index);
otherwise the repeated default name is rejected. The prefix counts toward the 200-character step
name limit. retention(...) works as on node-published events and defaults to eventRetention.
The step records the event’s name, key and id; a later run publishing another event under the same
step name is rejected, like a wait for another event.
Publishing from inside another step handler is rejected because publishing is itself a durable
step. Compensation handlers cannot publish through this API.
The Kotlin companion provides job.publishEvent(name, key, payload, retention, stepName) with the
same durable behavior.
Typed events
An TypedEvent names an event together with its payload class, shared by the publisher and the
waiting jobs:
static final TypedEvent<Payment> PAYMENT_RECEIVED = TypedEvent.of("payment-received", Payment.class);
Payment payment = job.awaitEvent("await-payment", PAYMENT_RECEIVED, order.id());
bikesched.newEvent(PAYMENT_RECEIVED, order.id()).payload(payment).publish(); // payload(Payment) onlyawaitEvent returns the payload directly, as the result of the wait step. For a
timeout or a fallback, use waitForEvent with the type instead:
Payment payment = job.waitForEvent("await-payment", PAYMENT_RECEIVED, order.id())
.timeout(Duration.ofDays(3))
.onFailure(failing -> failing.resolve(null))
.receive();Only the name is stored, so events published with the string-based API reach typed waits and vice versa. Like job payloads, event payloads should be objects rather than bare values or collections, see Payload design.
Timeouts
To stop waiting after a while, add a timeout. Once it passes, the wait fails with an
EventTimeoutException and the job fails without further attempts (waiting again would time out
again). Without a timeout of its own, a wait uses the node’s defaultEventTimeout, if set.
To continue instead, give the wait a failure handler, the same as a
step’s: it may resolve the wait with a fallback, which
receive returns.
Payment payment = job.waitForEvent("await-payment", "payment-received", order.id(), Payment.class)
.timeout(Duration.ofDays(3))
.onFailure(failing -> failing.resolve(Payment.MISSING))
.receive();- The handler runs right away once the wait timed out, whatever attempt of the job it is. Its
error()is theEventTimeoutException’stoString(). - The step goes from
TIMED_OUTtoFAILINGwhile the handler runs, thenSUCCEEDEDwith the fallback (stored and returned on later runs like a received payload) orFAILED, and the job fails. - A handler that throws runs again in an extra attempt of the job, up to the node’s
failureHandlerAttemptsruns, so it must be idempotent. - Like every failure handler, it cannot run steps, waits or polls. To fall back on a poll, resolve
with
nulland poll afterreceive, see Webhooks with a polling fallback.
Retention
An event’s retention only matters for steps that start waiting after it was published: steps
already waiting receive it when it is published, whatever its retention. It defaults to the
publishing node’s eventRetention (7 days) and can be set per event:
bikesched.newEvent("driver-accepted", rideId).payload(offer).retention(Duration.ofMinutes(5)).publish();
bikesched.newEvent("location-updated", rideId).payload(location).retention(Duration.ZERO).publish();- The expiry (
expires_at) is fixed when the event is published, so all nodes agree on it, whatever their owneventRetention. Duration.ZEROdelivers the event only to the steps waiting right now; later waits never receive it. Useful for signals that make no sense once missed.- Expired events are no longer received, and every polling node deletes them every
eventCleanUpInterval(default 1 hour). Steps that received an event keep their copy of its payload.
Consistency
Waiting, suspending and publishing lock the event’s name and key for the length of their
transaction (a PostgreSQL advisory lock), so an event published while a job starts waiting is never
missed. Cancelling a waiting job marks its wait CANCELLED; it no longer receives events.
An EventListener (BikeschedBuilder.eventListener(…)) is told about every committed
publication, e.g. for Metrics; events published in the
caller’s transaction are not reported.