Package-level declarations

Execution context available to a handler as its receiver.

The most recent failure recorded against a job: what a dead-letter is triaged from and what a Failed job is waiting on. Written by the runtime on every transition to JobState.Failed and JobState.DeadLettered through com.eventslooped.klokka.spi.JobStore.transition, and read back through com.eventslooped.klokka.spi.JobDetails.lastError.

In-process lifecycle events, emitted by the runtime as a hot kotlinx.coroutines.flow.SharedFlow. This is the only observability primitive in the core: metrics and tracing modules are built on it, and applications may subscribe directly for custom alerting.

A job handler. The simple registration path wraps a lambda in this interface, so graduating to a class (for constructor-injected dependencies and direct unit testing) changes no enqueue site and no registration semantics.

Opaque identifier of a single job run. Generated by the com.eventslooped.klokka.spi.JobStore.

Per-enqueue options. All fields have defaults so the simple path stays one argument shorter.

Maps a job's stored kind string back to its JobType and JobHandler. Registration happens once at startup; lookups happen on every execution.

The lifecycle of a job run.

The kind of a JobState, without per-state data. What queries filter by and dashboards group by: JobState.Failed carries its retry time, but "show me failed jobs" is about the kind of state, not one specific value of it. Names match JobState one to one.

The failure recorded when a handler exceeds its per-kind timeout. The attempt is cancelled cooperatively and then treated as an ordinary failure: the retry policy sees this exception and decides whether to book another attempt. Match on it to retry timeouts differently from other errors.

A registered job type: a stable string kind, the payload serializer, and the queue its jobs go to unless an enqueue call overrides it.

The default codec: JSON via kotlinx-serialization, configured leniently so a new-version producer does not break an old-version consumer mid-rolling-deploy: unknown keys are ignored, defaults are encoded.

What to do when a recurring schedule missed one or more fire times (downtime, saturation), beyond the configured misfire threshold.

Marker for exceptions that must never be retried. The runtime short-circuits to dead-letter BEFORE consulting any RetryPolicy, so custom policies do not need to check for this type themselves.

Continuation trigger conditions for continueWith-style chaining.

Whether a recurring schedule may emit a run while a previous run of the same schedule is still non-terminal.

Serializes job payloads to and from the string form stored by the com.eventslooped.klokka.spi.JobStore. The default is lenient JSON; a custom codec lets non-kotlinx users plug in Jackson, protobuf-as-base64, or anything else.

Raised when a stored payload cannot be decoded. Implements NonRetryable, which is what makes "decode failures skip retries and dead-letter immediately" fall out of the ordinary failure path instead of needing a special case.

Name of a queue. Workers drain queues in the order they are declared: declared order is priority. There are no per-job priority numbers.

Retention for terminal job runs. Cleanup executes as a built-in recurring job on Klokka's own machinery. Dead-lettered runs default to being kept forever (null): they are deleted only when an operator or an explicit policy says so.

Decides the delay before the next attempt, or null to give up (dead-letter).

When a recurring job fires. Schedule evaluation happens entirely in the runtime; a com.eventslooped.klokka.spi.JobStore only persists the next fire time and never sees or evaluates an expression, so custom implementations of this interface (a "last business day of the month" builder, for example) work with every store unchanged.

Identifies a worker instance for lease ownership. Stable for the lifetime of one runtime.

The JobStatus classifying this state.

Standard 5-field cron (minute hour day-of-month month day-of-week), evaluated in zone and validated here, at construction. With withSeconds a seconds field is prepended (6 fields). Names (MON, JAN), lists, ranges and steps are supported; Quartz L/W/# operators are not and never will be: complex business calendars are served by the typed DSL. DST behavior matches dailyAt.

Fires once a day at the wall-clock time hour:minute in zone, tracking live zone rules. On a day when that local time does not exist (spring-forward DST gap) the fire shifts to the first valid instant after the gap; when it exists twice (fall-back overlap) it fires once, at the earlier offset.

Fires every interval, anchored at the previous fire: each fire time is exactly interval after the one before it, so the cadence never drifts with execution timing. The first fire is one interval after the schedule is first registered.

Creates a JobType for a @Serializable payload type; queue is the default queue for its jobs.

Builder-style factory so call sites read as options { uniqueKey = "receipt-42" }.