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 = Job

Opaque queued job ready for insert.

Examples

Jobs.job "emails" 1 "welcome" payload : Job

JobId

type JobId = JobId

Primary key of a row in selm_jobs.

Examples

Jobs.insert job

Worker

type Worker = Worker

Registered worker produced by a job module (or defineWorker).

Examples

RecordWork.worker

Config

type Config = Config

Poller / cron configuration for supervised.

Examples

Jobs.config

Crontab

type Crontab = Crontab

Cron schedule entry.

Examples

Jobs.cron "0 * * * *" RecordWork.enqueue { message = "hourly" }

Queue

type Queue = Queue

Named queue with a concurrency limit.

Examples

Jobs.queue "default" 10

Jobs

type Jobs = Jobs

Opaque handle for the jobs supervisor child.

Examples

Jobs.supervised jobsConfig

JobInfo

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 -> Job

Pack 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 ()) -> Worker

Build a worker from name, attempts, queue, decoder, and perform. Used by generated job module worker.

Examples

Jobs.defineWorker "RecordWork" 3 "default" decoder perform

insert

insert : Job -> Transaction JobId

Insert 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 jobId

retry

retry : JobId -> Transaction ()

Re-queue a discarded or retryable job as available.

Examples

Jobs.retry jobId

jobId

jobId : Int -> JobId

Wrap a numeric primary key as a JobId.

Examples

Jobs.jobId 42

idToInt

idToInt : JobId -> Int

Unwrap a JobId to its integer primary key.

Examples

Jobs.idToInt jobId

get

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.counts

unique

unique : String -> Job -> Job

Set a uniqueness key (active-state unique index). Duplicate active jobs with the same key are rejected.

Examples

Jobs.unique "record:42" job

scheduleAt

scheduleAt : Posix -> Job -> Job

Run at an absolute Posix time.

Examples

Jobs.scheduleAt when job

scheduleIn

scheduleIn : Int -> Job -> Job

Delay execution by milliseconds from now.

Examples

RecordWork.enqueue args
    |> Jobs.scheduleIn (60 * 1000)
    |> Jobs.insert

priority

priority : Int -> Job -> Job

Higher priority runs first among due jobs.

Examples

Jobs.priority 10 job

onQueue

onQueue : String -> Job -> Job

Override the worker's default queue.

Examples

Jobs.onQueue "mailers" job

config

config : Config

Empty jobs config (default repo, one default queue).

Examples

Jobs.config

repo

repo : String -> Config -> Config

Named Repo to poll (default "default").

Examples

Jobs.repo "default" jobsConfig

queues

queues : List Queue -> Config -> Config

Replace queue list.

Examples

Jobs.queues [ Jobs.queue "default" 10 ] jobsConfig

queue

queue : String -> Int -> Queue

Queue name and concurrency.

Examples

Jobs.queue "default" 10

workers

workers : List Worker -> Config -> Config

Workers to register (from job module worker values).

Examples

Jobs.workers [ RecordWork.worker ] jobsConfig

crontab

crontab : List Crontab -> Config -> Config

Cron entries.

Examples

Jobs.crontab [ hourly ] jobsConfig

pollIntervalMs

pollIntervalMs : Int -> Config -> Config

Poll interval in milliseconds (default 1000).

Examples

Jobs.pollIntervalMs 1000 jobsConfig

cron

cron : String -> (a -> Job) -> a -> Crontab

Five-field UTC cron expression with a job builder and args.

Examples

Jobs.cron "0 * * * *" RecordWork.enqueue { message = "hourly" }

supervised

supervised : Config -> ChildSpecification Jobs

Supervise pollers and the cron ticker. Add beside Repo.supervised.

Examples

Jobs.supervised jobsConfig