Kathikon.Job (Kathikon v0.1.0)

Represents a durable job obligation in Kathikon.

Jobs move through explicit states:

:scheduled — waiting until scheduled_at (enqueue delay or {:sleep, seconds})
:available — ready for a dispatcher to claim
:executing — currently being processed
:retryable — failed but will be retried after backoff
:completed — successfully finished
:cancelled — explicitly cancelled
:discarded — exhausted retries or permanently failed

Example

{:ok, job} = Kathikon.insert(MyWorker, %{"key" => "value"})
job.id
job.state       # :available
job.worker      # MyWorker
job.args        # %{"key" => "value"}

See docs/guides/workers.md and docs/reference/modules.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.

decode_payload(binary)

Deserializes a job payload written by to_record/1.

Types

t()

@type t() :: %Kathikon.Job{
  args: map(),
  attempts: non_neg_integer(),
  available_at: DateTime.t() | nil,
  cancelled_at: DateTime.t() | nil,
  completed_at: DateTime.t() | nil,
  errors: [map()],
  id: String.t(),
  inserted_at: DateTime.t() | nil,
  max_attempts: pos_integer(),
  priority: non_neg_integer(),
  queue: atom(),
  scheduled_at: DateTime.t() | nil,
  started_at: DateTime.t() | nil,
  state:
    :scheduled
    | :available
    | :executing
    | :retryable
    | :completed
    | :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.

Formula: min(attempt² × 5, 86400) seconds (minimum 1 for attempt ≤ 0).

Examples

Kathikon.Job.backoff_seconds(1)  # 5
Kathikon.Job.backoff_seconds(2)  # 20
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.

Options

Same as Kathikon.insert/3: :queue, :priority, :max_attempts, :schedule_in, :schedule_at.

Example

job = Kathikon.Job.build(MyWorker, %{"x" => 1}, queue: :default)
job.state  # :available

claimable?(job, now)

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

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

A job is claimable when its state is :available or :retryable and available_at is not in the future.

Example

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

{:ok, job} = Kathikon.fetch(job_id)
Kathikon.Job.claimable?(job, DateTime.utc_now())  # true when due

decode_payload(binary)

@spec decode_payload(binary()) :: t()

Deserializes a job payload written by to_record/1.

Uses :erlang.binary_to_term/2 with [:safe]. Payloads are produced internally by Kathikon on the same node; this is not an untrusted boundary in Phase 1.