dev.skivi.scheduler.interface — dev.skivi/skivi 0.1.0

Cron scheduler that enqueues jobs via job-manager when schedules are due.

Each cron entry has an identifier (used as both task-identifier and job-key), a standard UNIX 5-field cron expression, and optional per-entry job creation overrides. Cron state (last_execution) is persisted to skivi.known_crontabs so the scheduler survives restarts without double-firing.

Jobs are enqueued with job_key_mode = unsafe_dedupe: if the previous run's job is still queued or in flight, the new enqueue is a no-op.

Typical usage:

(def crontabs [{:identifier "daily-report" :schedule "0 2 * * *" :spec {:queue-name "maintenance" :max-attempts 3}} {:identifier "hourly-cleanup" :schedule "0 * * * *"}])

(def scheduler (-> (scheduler/create-scheduler sys crontabs emitter {:timezone "Europe/London"}) scheduler/start!))

;; On application shutdown (scheduler/stop! scheduler 5000)

Standard events emitted: :cron/fired - a cron entry fired and a job was enqueued; :identifier in data

create-scheduler clj

(create-scheduler job-system crontabs emitter)

(create-scheduler job-system crontabs emitter config)

Creates a cron scheduler. Call start! to begin processing. job-system is {:pool datasource :validator validator}. crontabs is a vector of CrontabEntry maps (see schema/CrontabEntry). emitter is a monitoring/Emitter. config keys: :poll-interval-ms (default 10000), :timezone (default "UTC").

cron-next clj

(cron-next schedule base-time timezone)

Returns the next java.time.Instant a cron schedule fires after base-time in timezone. schedule is a standard UNIX 5-field cron expression. base-time is a java.time.Instant from which to compute the next occurrence. timezone is an IANA timezone string (e.g. "UTC", "America/New_York"). Returns nil if the expression has no future occurrence.

fire-due-jobs! clj

(fire-due-jobs! scheduler)

Evaluates all crontab entries and enqueues jobs for any whose schedule is due. Returns a map with :fired (count enqueued) and :skipped (count not yet due). Works on both started and stopped schedulers; does not require the background thread to be running. Useful for testing and for explicit one-shot evaluation.

running? clj

(running? scheduler)

Returns true if the polling loop is active.

start! clj

(start! scheduler)

Upserts crontab records in the database then starts the background polling loop. Throws if already running. Returns scheduler.

stats clj

(stats scheduler)

Returns a snapshot of scheduler operational metrics. Keys: :fired (total jobs enqueued), :errors (evaluation errors caught).

stop! clj

(stop! scheduler)

(stop! scheduler timeout-ms)

Signals the polling loop to stop, interrupts the thread, and joins it up to timeout-ms milliseconds. Returns scheduler.