klokka-core/com.eventslooped.klokka.spi

Package-level declarations

Types

data class ClaimedJob(val id: JobId, val kind: String, val payload: String, val payloadVersion: Int, val queue: QueueName, val attempt: Int, val enqueuedAt: Instant, val scheduledFor: Instant, val leaseUntil: Instant, val fence: Long, val scheduleId: String? = null)

A job claimed under a lease, with everything a worker needs to execute it.

JobDetails

data class JobDetails(val summary: JobSummary, val payload: String, val payloadVersion: Int, val uniqueKey: String?, val fence: Long, val leaseUntil: Instant?, val holder: WorkerId?, val lastError: JobError?)

One job in full, for a detail view. payload is the serialized form as stored; anything mounted on top of this (the dashboard) shows it to operators, which is worth remembering when payloads carry sensitive data: the dashboard fails closed on authentication for exactly that reason.

JobQuery

data class JobQuery(val status: JobStatus? = null, val kind: String? = null, val queue: QueueName? = null, val limit: Int = 50, val offset: Int = 0)

Filter and page for QueryableStore.listJobs. Null filter fields mean "any". limit/offset page through the filtered set; stores order results most recently persisted first, so page 0 is the newest work.

JobStore

interface JobStore

The storage contract. Implementations plus the conformance kit (klokka-tck) ARE the portability story: any store passing the TCK is a valid backend.

JobSummary

data class JobSummary(val id: JobId, val kind: String, val queue: QueueName, val status: JobStatus, val attempt: Int, val runAt: Instant, val enqueuedAt: Instant, val scheduleId: String?, val retryAt: Instant?, val terminalAt: Instant?)

One job row as a listing sees it: everything but the payload and lease internals.

NewJob

data class NewJob(val kind: String, val payload: String, val payloadVersion: Int = 1, val queue: QueueName = QueueName.DEFAULT, val runAt: Instant, val uniqueKey: String? = null, val scheduleId: String? = null)

A job to persist. payload is the serialized form (JSON by default); payloadVersion is the envelope version, present from v1 so wire-format evolution never needs a data migration.

PushCapableStore

interface PushCapableStore : JobStore

Optional capability: the store can push "new work may be available" signals (Postgres LISTEN/NOTIFY, an in-process channel for the in-memory store), so the runtime does not depend on polling for latency. Emissions are wake-up hints and carry no payload; spurious emissions are allowed.

QueryableStore

interface QueryableStore : JobStore

Optional capability: read access for dashboards and tooling. Kept OUT of JobStore deliberately: the core contract is the minimal thing a store must get right to run jobs safely, and observation is additive. A store without this capability is still a valid backend; it just cannot serve the dashboard.

ScheduleFire

data class ScheduleFire(val scheduleId: String, val scheduledFor: Instant, val now: Instant, val fence: Long)

A due schedule claimed under a lease, with what the runtime needs to compute the fire.

ScheduleSpec

data class ScheduleSpec(val id: String, val kind: String, val fingerprint: String, val description: String, val fireAt: Instant?)

A recurring schedule's persisted identity and timing state, as the runtime registers it. The store never sees or evaluates a schedule expression: all schedule math (cron, DSL, misfire policy, payloads) lives in the runtime, and the store only keeps the fields below plus per-row lease state. fingerprint is an opaque string the runtime derives from the full definition; stores compare it for equality and never parse it.

TransactionalStore

interface TransactionalStore<TX> : JobStore

Optional capability: enqueue participating in a caller-supplied transaction of type TX. The job is visible to workers if and only if the transaction commits. The transaction is passed explicitly because thread-local transaction state does not survive coroutine thread hops.