klokka-ktor/com.eventslooped.klokka.ktor/KlokkaConfig

KlokkaConfig

Configuration receiver for install(Klokka) { ... }. A fresh instance is created per installation. Every property mirrors a KlokkaSettings field and carries the same default; queue declarations and handler bindings (handle) are collected here and applied when the plugin builds the KlokkaRuntime.

Constructors

KlokkaConfig

constructor()

Properties

claimBatch

var claimBatch: Int

Maximum jobs claimed per queue per claim round.

clock

var clock: Clock

Clock used for scheduling and event timestamps.

codec

var codec: PayloadCodec

Payload serialization strategy.

defaultRetry

var defaultRetry: RetryPolicy

Retry policy used when a handler's registration does not specify its own.

defaultTimeout

var defaultTimeout: Duration?

Per-attempt timeout for kinds whose handle call sets none. Null, the default, means no cap: a handler runs until it returns, with its lease renewed by heartbeat the whole time. The timeout is independent of lease: the lease detects dead workers, the timeout bounds live ones.

drainTimeout

var drainTimeout: Duration

How long KlokkaRuntime.drain waits for in-flight jobs before cancelling stragglers.

heartbeatInterval

var heartbeatInterval: Duration

How often in-flight jobs' leases are renewed.

lateThreshold

var lateThreshold: Duration

A start later than scheduledFor by more than this marks the run late in events.

lease

var lease: Duration

How long a claimed job's lease lasts before it is considered abandoned.

pollInterval

var pollInterval: Duration

Fallback interval between claim rounds when no push wakeup arrives.

retention

var retention: RetentionPolicy

Retention for terminal job runs.

role

var role: KlokkaRole

Which parts of the runtime this process runs.

store

var store: JobStore

Backing job storage. Defaults to a non-persistent in-memory store, which logs a startup warning outside development mode. Pass InMemoryJobStore(ephemeral = true) to keep the in-memory store deliberately and downgrade that warning to a one-line INFO.

sweepInterval

var sweepInterval: Duration

How often the retention sweep runs.

workerId

var workerId: WorkerId

Identity this process claims and heartbeats leases under. Defaults to a random worker-<hex> id drawn once per installation. Set a stable value (hostname, pod name) when lease ownership should be attributable to the same node across restarts.

Functions

handle

fun <T> handle(type: JobType<T>, handler: JobHandler<T>, retry: RetryPolicy? = null, timeout: Duration? = null)

Binds a JobHandler object to type: the form for handlers with dependencies or their own unit tests. retry overrides defaultRetry and timeout overrides defaultTimeout for this kind; see JobRegistry.handle for the timeout semantics.

fun <T> handle(type: JobType<T>, retry: RetryPolicy? = null, timeout: Duration? = null, block: suspend JobContext.(T) -> Unit)

Binds a suspend lambda to type. Same semantics as the object form; retry overrides defaultRetry and timeout overrides defaultTimeout for this kind.

queue

fun queue(name: QueueName, concurrency: Int = 8, dispatcher: CoroutineDispatcher? = null)

Declares a queue this process drains. Declaration order is drain priority: queues declared earlier are claimed first, mirroring KlokkaSettings.queues. If no queue is declared, the runtime falls back to a single queue named QueueName.DEFAULT.

fun queue(name: String, concurrency: Int = 8, dispatcher: CoroutineDispatcher? = null)

queue with the name as a plain string.

recurring

fun recurring(id: String, schedule: Schedule, misfire: MisfirePolicy = MisfirePolicy.FireOnce, misfireThreshold: Duration = 1.minutes, overlap: OverlapPolicy = OverlapPolicy.Allow, queue: QueueName? = null, block: suspend JobContext.() -> Unit)

The zero-payload convenience form: declares the schedule AND binds block as the handler in one call. The schedule id doubles as the job kind, so it shares the kind namespace and character rules and must not collide with a kind bound via handle. Graduating to the full form (a JobType, a payload, a standalone handler) changes the descriptor, not the enqueue model.

fun <T> recurring(id: String, type: JobType<T>, payload: T, schedule: Schedule, misfire: MisfirePolicy = MisfirePolicy.FireOnce, misfireThreshold: Duration = 1.minutes, overlap: OverlapPolicy = OverlapPolicy.Allow, queue: QueueName? = null)

Declares a recurring schedule; see KlokkaRuntime.recurring for the semantics of every parameter. Declared here so the schedule exists before the runtime starts, which is when schedules are registered with the store.