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.1.0 — Phase 1: Durable Job Queue

• Job insertion and queue execution
• Retries with exponential backoff
• Scheduling (schedule_in, schedule_at)
• Priorities
• Telemetry
• Pruning / retention

Installation

def deps do
  [
    {:kathikon, "~> 0.1.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
└── Kathikon.Pruner

Job states

scheduled → available → executing → completed
                    ↘           ↘ retryable → ...
                      cancelled   discarded

Telemetry

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

• Job: [:kathikon, :job, :insert], :start, :stop, :sleep, :retry, :discard, :cancel, :prune
• Runtime: [:kathikon, :scheduler, :tick], [:kathikon, :pruner, :tick], [:kathikon, :dispatcher, :poll]

Attach the default logger in development:

Kathikon.Telemetry.attach_default_logger()

Configuration

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.