Kathikon.Job (Kathikon v0.2.0)

Represents a durable job obligation in Kathikon.

Jobs move through explicit states enforced by Kathikon.Job.StateMachine:

:scheduled — waiting until scheduled_at
:available — ready to be claimed
:claimed — atomically claimed, not yet running
:running — currently being processed (v0.1 :executing)
:retryable — failed but will be retried after backoff
:waiting_for_children — batch parent waiting on child jobs
:completed — successfully finished
:failed — exhausted retries or terminal worker failure
:dead — in the dead-letter queue
:cancelled — explicitly cancelled
:discarded — permanently discarded

See docs/job_lifecycle.md.

Summary

Types

t()

Functions

backoff_seconds(attempt)

Computes exponential backoff in seconds for the given attempt number.

build(worker, args, opts)

Builds a new job from worker module, args, and options.

claimable?(job, now)

Returns true when the job can be claimed for execution at now.

history(job_id)

Returns job history events from storage.

normalize(job)

Normalizes legacy :executing to :running.

to_map(job)

Converts a job struct to a map for storage callbacks and reporting.

Types

t()

@type t() :: %Kathikon.Job{
  args: map(),
  attempts: non_neg_integer(),
  available_at: DateTime.t() | nil,
  batch_id: String.t() | nil,
  cancelled_at: DateTime.t() | nil,
  claimant: map() | nil,
  claimed_at: DateTime.t() | nil,
  completed_at: DateTime.t() | nil,
  discarded_at: DateTime.t() | nil,
  error: term(),
  errors: [map()],
  failed_at: DateTime.t() | nil,
  id: String.t(),
  inserted_at: DateTime.t() | nil,
  last_error: term(),
  max_attempts: pos_integer(),
  node: node() | nil,
  original_job_id: String.t() | nil,
  parent_job_id: String.t() | nil,
  priority: non_neg_integer(),
  queue: atom(),
  rerun_of: String.t() | nil,
  result: term(),
  result_mode: :store | :discard,
  scheduled_at: DateTime.t() | nil,
  started_at: DateTime.t() | nil,
  state:
    :scheduled
    | :available
    | :claimed
    | :running
    | :executing
    | :retryable
    | :waiting_for_children
    | :completed
    | :failed
    | :dead
    | :cancelled
    | :discarded,
  worker: module()
}

Functions

backoff_seconds(attempt)

@spec backoff_seconds(non_neg_integer()) :: non_neg_integer()

Computes exponential backoff in seconds for the given attempt number.

Examples

Kathikon.Job.backoff_seconds(1)
#=> 5

Kathikon.Job.backoff_seconds(3)
#=> 45

build(worker, args, opts)

@spec build(module(), map(), keyword()) :: t()

Builds a new job from worker module, args, and options.

Prefer Kathikon.insert/3 for enqueueing — it persists the job and starts the queue dispatcher.

Examples

job = Kathikon.Job.build(MyApp.EmailWorker, %{"to" => "a@b.com"},
  queue: :emails,
  priority: 2,
  schedule_in: 60
)

job.state
#=> :scheduled

claimable?(job, now)

@spec claimable?(t(), DateTime.t()) :: boolean()

Returns true when the job can be claimed for execution at now.

Examples

job = Kathikon.Job.build(MyWorker, %{})
Kathikon.Job.claimable?(job, DateTime.utc_now())
#=> true

scheduled = Kathikon.Job.build(MyWorker, %{}, schedule_in: 3600)
Kathikon.Job.claimable?(scheduled, DateTime.utc_now())
#=> false

history(job_id)

@spec history(String.t()) :: {:ok, [map()]} | {:error, term()}

Returns job history events from storage.

Prefer Kathikon.history/1 in application code.

Examples

{:ok, events} = Kathikon.Job.history(job_id)

normalize(job)

@spec normalize(t()) :: t()

Normalizes legacy :executing to :running.

to_map(job)

@spec to_map(t()) :: %{required(atom()) => term()}

Converts a job struct to a map for storage callbacks and reporting.

Examples

Kathikon.Job.to_map(job)
#=> %{id: "...", state: :completed, worker: MyWorker, ...}