Job context
Every #perform receives a ctx (a Zeridion::Flare::JobContext). It carries
this execution's metadata, the cancellation handle, and progress reporting. The
worker builds it for you — you never construct one yourself.
def perform(payload, ctx)
ctx.logger&.info("running #{ctx.job_id}, attempt #{ctx.attempt}/#{ctx.max_attempts}")
return if ctx.cancelled?
ctx.report_progress(0.5)
# ...
ctx.report_progress(1.0)
end
Fields
| Accessor | Type | Meaning |
|---|---|---|
ctx.job_id | String | Unique id of this execution. Dedupe on this for idempotency. |
ctx.job_type | String | The routing type that matched this handler. |
ctx.attempt | Integer | 1-based attempt counter. |
ctx.max_attempts | Integer | Attempt ceiling for this job. |
ctx.enqueued_at | Time or nil | When the job was originally enqueued (offset-aware). nil if the timestamp was unparseable — reading it never raises. |
ctx.logger | Logger or nil | The worker's logger, pre-bound to this job so your logs correlate. |
ctx.cancellation | handle | The cooperative cancellation handle. |
Methods
ctx.cancelled? → Boolean
true once cancellation has been requested — a server cancel, host shutdown,
or this job hitting its timeout. Check it at safe points in a long handler and
return early. See Cancellation & timeouts.
ctx.check_cancellation!
Raise if cancellation has been requested. A convenient one-liner inside a loop when you'd rather abort with an exception than branch.
ctx.report_progress(fraction)
Report progress between 0.0 and 1.0, surfaced on the dashboard. The latest
value rides the next heartbeat — calling it more often than the heartbeat
cadence simply means the most recent value wins (last-write-wins). Values that
are out of range are ignored: anything above 1.0 is clamped to 1.0, and
nil, NaN, or values at or below 0 are dropped (no progress is sent for
them). It never raises.
total = items.length
items.each_with_index do |item, i|
process(item)
ctx.report_progress((i + 1).to_f / total)
end