Kathikon

Kathikon (Greek: καθήκον — duty, obligation) is a BEAM-native durable job queue and task execution platform for Elixir.

Jobs are treated as durable obligations that must eventually be fulfilled: completed, retried, cancelled, or discarded — but never silently lost.

Kathikon uses Mnesia as its coordination store and OTP as its execution substrate. No PostgreSQL, Redis, RabbitMQ, or external brokers are required.

Status

v0.2.0 — Control, scheduling, batches, and correctness

• Storage behaviour with atomic lifecycle operations
• Formal job state machine and durable history
• Dead-letter queue with rerun semantics
• Kathikon.schedule/3 and scheduler adapters (built-in + optional Quantum)
• Management and reporting APIs
• Parent/child batch workflows

Previous: v0.1.0 — Phase 1: Durable Job Queue

Installation

def deps do
  [
    {:kathikon, "~> 0.2.0"}
  ]
end

Quick start

Define a worker:

defmodule MyApp.EmailWorker do
  use Kathikon.Worker

  @impl true
  def perform(%Kathikon.Job{args: %{"email" => email}}) do
    MyApp.Mailer.deliver(email)
    :ok
  end
end

Configure queues:

# config/config.exs
config :kathikon,
  queues: [
    default: [concurrency: 10],
    emails: [concurrency: 5]
  ]

Enqueue jobs:

{:ok, job} = Kathikon.insert(MyApp.EmailWorker, %{"email" => "user@example.com"})

{:ok, job} =
  Kathikon.insert(MyApp.EmailWorker, %{"email" => "user@example.com"},
    queue: :emails,
    priority: 5,
    schedule_in: 60,
    max_attempts: 10
  )

Cancel a pending job:

{:ok, job} = Kathikon.cancel(job_id)

Architecture

Kathikon.Supervisor
├── Registry
├── Kathikon.Queue (DynamicSupervisor)
│   └── Kathikon.Dispatcher (one per queue)
├── Kathikon.Scheduler.Promoter
└── Kathikon.Pruner

Job states

scheduled → available → claimed → running → completed
                    ↘           ↘ retryable → available
                      cancelled   failed → dead

Telemetry

Kathikon emits standard telemetry events. See Telemetry guide for the full list. Highlights:

• Job: [:kathikon, :job, :inserted], :claimed, :started, :completed, :failed, :sleep, :retry, :discard, :cancel, :dead, :prune
• Runtime: [:kathikon, :scheduler, :tick], [:kathikon, :scheduler, :fired], [:kathikon, :pruner, :tick], [:kathikon, :dispatcher, :poll]

Attach the default logger in development:

Kathikon.Telemetry.attach_default_logger()

Configuration

Examples

Runnable scripts under examples/ (use mix run examples/<name>.exs):

Roadmap

Documentation

Generate HTML docs with ExDoc:

mix docs
open doc/index.html

• Documentation index — guides and module reference (source)
• Quick start
• Module reference
• Configuration
• Interactive demo (Livebook)

License

MIT. See LICENSE.