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.4.0 - Bulk job submission

• Kathikon.insert_many/2 — chunked enqueue of independent jobs
• Kathikon.Batch.open/2, append/2, and close/1 — stream map/reduce children without holding every spec in memory
• Storage insert_jobs/2, implemented transactionally by Mnesia

v0.3.0 - LiveDashboard

• Kathikon.LiveDashboard.Page — Kathikon tab in Phoenix LiveDashboard
• Pause, resume, cancel, filter, search, retry, and paginated job lists
• Phoenix setup guide, Playground demo, and Livebook

v0.2.1 - Operations tooling

• Kathikon.Dashboard - inspect and control facade for UIs and RPC
• mix kathikon.ops - terminal CLI (summary, jobs, pause/resume, retry, purge, …)
• Remote ops over Erlang distribution (Kathikon.Dashboard.RPC)

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.4.0"}
  ]
end

The Quick start guide covers configuration, a worker, and the first job (v0.4.0). A short version:

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):

Operations CLI

Inspect and control a running node from the terminal:

mix kathikon.ops summary
mix kathikon.ops jobs --queue default --tab completed --limit 20
mix kathikon.ops pause --all

Remote (named node + matching cookie on both sides):

elixir --name ops@127.0.0.1 --cookie SECRET -S mix kathikon.ops --node kathikon@127.0.0.1 summary

See Management API and Kathikon.Dashboard docs.

Roadmap

Documentation

Generate HTML docs with ExDoc:

mix docs
open doc/index.html

• Documentation index - guides and module reference (source)
• CHANGELOG - release history
• Quick start
• LiveDashboard in a Phoenix app
• Module reference
• Configuration
• Interactive demo (Livebook)

License

MIT. See LICENSE.