JoobQ.Job (joobq_ex v0.8.0)

Copy Markdown View Source

A job: the %JoobQ.Job{} a worker leased and hands to JoobQ.Worker.perform/1, and the body of POST /sdk/jobs that JoobQ.enqueue/4 sends.

A leased job has its jid, queue, type (the job type), payload (decoded JSON, string keys), context (the request context the producer attached), attempt (1 on the first run) and max_retries. A workflow step's job also has its kind ("activity", "compensation" or "update"), workflow_id, step_id and checkpoints (the outputs of the run's completed steps, by step name).

The options of an enqueue follow. Options left out (or nil) are not sent, and the gateway applies its defaults.

  • :jid: the job's id (the gateway makes one when it is absent).
  • :context: the request context a handler reads (tenant_id, request_id, traceparent, ...), a map.
  • :max_retries: 0 to 100 (the gateway's default is 3).
  • :delay_ms: run the job after this many milliseconds, 0 to 86 400 000.
  • :run_at_ms (unix epoch milliseconds) or :scheduled_at (a DateTime): run the job at that time; it wins over :delay_ms, a time at or before now runs at once.
  • :expires_ms: the job's lifetime from when it is due; a job still waiting then goes to the dead letter queue as JobExpired (the gateway's default is JoobQ's configured lifetime).
  • :timeout_ms: how long one run may take from when a worker claims it; it then fails as JobTimeout.

The gateway clamps both deadlines to its limits.

  • :unique_key: a job with a live key answers status: "deduplicated" and is dropped, for :unique_ttl_ms.
  • :unique_mode: when the key frees: :while_locked (the gateway's default, after its lifetime), :until_executing (when a worker claims the job) or :until_executed (when it completes); the last two answer 402 pro_required without a JoobQ Pro licence.
  • :encrypt_fields: payload fields the gateway seals before it stores the job (atoms or strings).

Summary

Functions

The bodies of POST /sdk/jobs/batch for jobs, in calls of at most 500 jobs, in order. A job is {queue, job_type}, {queue, job_type, payload} or {queue, job_type, payload, opts}; context is the context of every job that has none of its own. Every job is checked before any is sent.

The body for a job of job_type on queue; raises ArgumentError naming a wrong option.

Whether the run of job was asked to stop (cancelled, or past its timeout_ms): what the worker's last lease renewal said, answered without waiting for the gateway. A job with heartbeat_ms (a workflow step's heartbeat timeout) must call it more often than that: it then also tells the gateway the run is alive, at most every third of heartbeat_ms, and that call waits for the gateway (a failed one is ignored; the next window's tries again).

Types

t()

@type t() :: %JoobQ.Job{
  attempt: pos_integer(),
  checkpoints: map(),
  context: map(),
  heartbeat_ms: pos_integer() | nil,
  instance: atom(),
  jid: String.t(),
  kind: String.t(),
  lease_token: String.t(),
  lease_until_ms: integer() | nil,
  max_retries: non_neg_integer(),
  payload: term(),
  queue: String.t(),
  step_id: String.t() | nil,
  type: String.t(),
  workflow_id: String.t() | nil
}

Functions

batches(jobs, context \\ nil)

@spec batches([tuple()], map() | nil) :: [[map()]]

The bodies of POST /sdk/jobs/batch for jobs, in calls of at most 500 jobs, in order. A job is {queue, job_type}, {queue, job_type, payload} or {queue, job_type, payload, opts}; context is the context of every job that has none of its own. Every job is checked before any is sent.

body(queue, job_type, payload \\ %{}, opts \\ [])

@spec body(String.t(), String.t(), term(), keyword()) :: map()

The body for a job of job_type on queue; raises ArgumentError naming a wrong option.

heartbeat(job)

@spec heartbeat(t()) :: boolean()

Whether the run of job was asked to stop (cancelled, or past its timeout_ms): what the worker's last lease renewal said, answered without waiting for the gateway. A job with heartbeat_ms (a workflow step's heartbeat timeout) must call it more often than that: it then also tells the gateway the run is alive, at most every third of heartbeat_ms, and that call waits for the gateway (a failed one is ignored; the next window's tries again).