Jobs
Processes
Durable background jobs for BEAM apps (Oban-shaped).
Declare work in a job module with Args and perform. The compiler derives JSON codecs plus enqueue / worker. Enqueue inside Repo.transaction with insert, and run pollers under supervised next to Repo.supervised. See examples/15_jobs.
-- job module RecordWork exposing (enqueue, worker)
-- perform args = Ok ()
jobsConfig =
Jobs.config
|> Jobs.workers [ RecordWork.worker ]
|> Jobs.queues [ Jobs.queue "default" 10 ]
-- Server.application init:
Supervisor.new OneForOne
|> Supervisor.add (Repo.supervised repo)
|> Supervisor.add (Jobs.supervised jobsConfig)
-- HTTP handler:
Repo.transaction (Jobs.insert (RecordWork.enqueue { message = "hello" }))Schedule later with scheduleIn / scheduleAt, or register UTC cron with cron + crontab. Uniqueness uses unique.
Types
Job
type Job = JobOpaque queued job ready for insert.
Examples
Jobs.job "emails" 1 "welcome" payload : JobJobId
type JobId = JobIdPrimary key of a row in selm_jobs.
Examples
Jobs.insert jobWorker
type Worker = WorkerRegistered worker produced by a job module (or defineWorker).
Examples
RecordWork.workerConfig
type Config = ConfigPoller / cron configuration for supervised.
Examples
Jobs.configCrontab
type Crontab = CrontabCron schedule entry.
Examples
Jobs.cron "0 * * * *" RecordWork.enqueue { message = "hourly" }Queue
type Queue = QueueNamed queue with a concurrency limit.
Examples
Jobs.queue "default" 10Jobs
type Jobs = JobsOpaque handle for the jobs supervisor child.
Examples
Jobs.supervised jobsConfigJobInfo
type alias JobInfo =
{ id : JobId
, queue : String
, worker : String
, args : String
, state : String
, attempt : Int
, maxAttempts : Int
, priority : Int
, scheduledAt : Int
, attemptedAt : Maybe Int
, completedAt : Maybe Int
, discardedAt : Maybe Int
, insertedAt : Int
, errors : String
, uniqueKey : Maybe String
}One row from selm_jobs for Ops UIs and agents.
StateCount
type alias StateCount =
{ state : String
, count : Int
}Count of jobs in one state.
ListFilter
type alias ListFilter =
{ state : Maybe String
, queue : Maybe String
, worker : Maybe String
, limit : Int
}Filters for list. Nothing means no filter on that field.
Values
job
job : String -> Int -> String -> JE.Value -> JobPack a job for insert. Used by generated job module enqueue.
Examples
Jobs.job "RecordWork" 3 "default" (JE.object [])defineWorker
defineWorker : String -> Int -> String -> JD.Decoder a -> (a -> Result String ()) -> WorkerBuild a worker from name, attempts, queue, decoder, and perform. Used by generated job module worker.
Examples
Jobs.defineWorker "RecordWork" 3 "default" decoder performinsert
insert : Job -> Transaction JobIdInsert a job on the active transaction connection.
Examples
Repo.transaction (Jobs.insert (RecordWork.enqueue { message = "hello" }))cancel
cancel : JobId -> Transaction ()Cancel a non-executing job by id.
Examples
Jobs.cancel jobIdretry
retry : JobId -> Transaction ()Re-queue a discarded or retryable job as available.
Examples
Jobs.retry jobIdjobId
jobId : Int -> JobIdWrap a numeric primary key as a JobId.
Examples
Jobs.jobId 42idToInt
idToInt : JobId -> IntUnwrap a JobId to its integer primary key.
Examples
Jobs.idToInt jobIdget
get : JobId -> Transaction (Maybe JobInfo)Load one job by id.
Examples
Repo.transaction (Jobs.get jobId)list
list : ListFilter -> Transaction (List JobInfo)Newest jobs matching optional state/queue/worker filters.
Examples
Repo.transaction
(Jobs.list
{ state = Just "available"
, queue = Nothing
, worker = Nothing
, limit = 20
}
)counts
counts : Transaction (List StateCount)Counts grouped by state (Oban-style summary).
Examples
Repo.transaction Jobs.countsunique
unique : String -> Job -> JobSet a uniqueness key (active-state unique index). Duplicate active jobs with the same key are rejected.
Examples
Jobs.unique "record:42" jobscheduleAt
scheduleAt : Posix -> Job -> JobRun at an absolute Posix time.
Examples
Jobs.scheduleAt when jobscheduleIn
scheduleIn : Int -> Job -> JobDelay execution by milliseconds from now.
Examples
RecordWork.enqueue args
|> Jobs.scheduleIn (60 * 1000)
|> Jobs.insertpriority
priority : Int -> Job -> JobHigher priority runs first among due jobs.
Examples
Jobs.priority 10 jobonQueue
onQueue : String -> Job -> JobOverride the worker's default queue.
Examples
Jobs.onQueue "mailers" jobconfig
config : ConfigEmpty jobs config (default repo, one default queue).
Examples
Jobs.configrepo
repo : String -> Config -> ConfigNamed Repo to poll (default "default").
Examples
Jobs.repo "default" jobsConfigqueues
queues : List Queue -> Config -> ConfigReplace queue list.
Examples
Jobs.queues [ Jobs.queue "default" 10 ] jobsConfigqueue
queue : String -> Int -> QueueQueue name and concurrency.
Examples
Jobs.queue "default" 10workers
workers : List Worker -> Config -> ConfigWorkers to register (from job module worker values).
Examples
Jobs.workers [ RecordWork.worker ] jobsConfigcrontab
crontab : List Crontab -> Config -> ConfigCron entries.
Examples
Jobs.crontab [ hourly ] jobsConfigpollIntervalMs
pollIntervalMs : Int -> Config -> ConfigPoll interval in milliseconds (default 1000).
Examples
Jobs.pollIntervalMs 1000 jobsConfigcron
cron : String -> (a -> Job) -> a -> CrontabFive-field UTC cron expression with a job builder and args.
Examples
Jobs.cron "0 * * * *" RecordWork.enqueue { message = "hourly" }supervised
supervised : Config -> ChildSpecification JobsSupervise pollers and the cron ticker. Add beside Repo.supervised.
Examples
Jobs.supervised jobsConfig