# `JoobQ.Job`
[🔗](https://github.com/azutoolkit/joobqui/tree/master/sdks/elixir/blob/main/lib/joobq/job.ex#L2)

A job: the `%JoobQ.Job{}` a worker leased and hands to `c: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).

# `t`

```elixir
@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
}
```

# `batches`

```elixir
@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`

```elixir
@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`

```elixir
@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).

---

*Consult [api-reference.md](api-reference.md) for complete listing*
