v0.2.1

Changelog

All notable changes to this project are documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[0.2.1] - 2026-06-24

Added

• Kathikon.Dashboard — operations facade for queue summaries, paginated job lists, job drill-down, bulk cancel/retry/rerun/discard/purge, and actions_for_state/1 for UIs.
• Kathikon.Dashboard.RPC — whitelisted remote calls over Erlang distribution.
• mix kathikon.ops — terminal CLI for inspect and control (summary, jobs, show, pause, resume, cancel, retry, rerun, purge, prune).
• Storage.list_jobs_page/1 — storage-level pagination for dashboard job lists.
• Public @doc for Kathikon.pause_queue/1, resume_queue/1, and queue_status/1.
• Public Kathikon.Report.count_by_state/1 for shared state counting.
• docs/dashboard_spec.md — operator UI layout, state tabs, and Dashboard API mapping.
• Expanded dashboard, ops, RPC, cron expression, and queue test coverage.

Fixed

• Kathikon.Dashboard.RPC.call/4 no longer double-wraps {:ok, result} tuples from remote nodes (fixes mix kathikon.ops --node … summary).
• Dashboard.queue_summary/1 extends Kathikon.Report and includes queues present in storage but not in config.
• Dashboard.pause_all/1 and resume_all/1 operate on all known queues (storage + config).
• Dashboard.purge_jobs/1 returns per-job delete failures in errors.
• Running jobs no longer expose :discard in actions_for_state/1.
• mix kathikon.ops validates missing job IDs, negative pagination, and unknown state tabs.

Documentation

• Management API guide expanded with Dashboard and remote ops examples.
• Module reference and documentation index updated for v0.2.1.
• Kathikon.Dashboard included in ExDoc module grouping.

[0.2.0] - 2026-06-23

First feature release after Phase 1. Storage behaviour, formal job state machine, cron scheduling, timezone support, batches, reporting, management APIs, and expanded test coverage. See the v0.2.0 release on GitHub.

v0.2.0

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

Module	Role
Kathikon.Job	Job struct and state machine
Kathikon.Worker	Worker behaviour (perform/1)
Kathikon.Storage	Storage behaviour (default: Kathikon.Storage.Mnesia)
Kathikon.Report	Queue/job reporting helpers
Kathikon.Batch	Fan-out/fan-in batch workflows
Kathikon.Scheduler.Promoter	Promotes scheduled jobs to available
Kathikon.Pruner	Enforces retention on terminal jobs
Kathikon.Telemetry	[:kathikon, ...] telemetry events

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

Key	Default	Description
:queues	[default: [concurrency: 10]]	Queue names and concurrency
:poll_interval	200	Dispatcher poll interval (ms)
:scheduler_interval	1000	Scheduler tick interval (ms)
:prune_interval	60000	Pruner tick interval (ms)
:retention_period	7 days	How long to keep terminal jobs (ms)
:max_attempts	20	Default retry limit
:storage_backend	Kathikon.Storage.Mnesia	Storage implementation
:mnesia_copies	:auto	Mnesia storage: :ram, :disc, or :auto (ram on nonode@nohost and Livebook nodes)

Examples

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

Script	Demonstrates
basic_worker.exs	Insert and poll status
scheduled_job.exs	schedule with :at / :in
dead_letter_retry.exs	Failures, dead letter, rerun
batch_fanout_fanin.exs	Parent/child batches
reporting.exs	Kathikon.Report summaries
quantum_scheduler_adapter.exs	Optional Quantum scheduler

Roadmap

Phase	Focus
1	Durable job queue (done)
2	Distributed coordination, leases, lifeline
3	Uniqueness, dynamic queues (cron done in v0.2)
4	Rate limits (pause/resume done in v0.2)
5	Batches (done in v0.2)
6	Observability APIs (reporting done in v0.2)
7	Workflows and DAGs
8	Optional LiveView dashboard

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.

v0.1.0

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

Module	Role
Kathikon.Job	Job struct and state machine
Kathikon.Worker	Worker behaviour (perform/1)
Kathikon.Storage	Storage facade over Kathikon.Backend.Storage
Kathikon.Dispatcher	Claims and executes jobs per queue
Kathikon.Scheduler	Promotes scheduled jobs to available
Kathikon.Pruner	Enforces retention on terminal jobs
Kathikon.Backend.Storage	Storage behaviour (default: …Mnesia)
Kathikon.Telemetry	[:kathikon, ...] telemetry events

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

Key	Default	Description
:queues	[default: [concurrency: 10]]	Queue names and concurrency
:poll_interval	200	Dispatcher poll interval (ms)
:scheduler_interval	1000	Scheduler tick interval (ms)
:prune_interval	60000	Pruner tick interval (ms)
:retention_period	7 days	How long to keep terminal jobs (ms)
:max_attempts	20	Default retry limit
:mnesia_copies	:auto	Mnesia storage: :ram, :disc, or :auto (ram on nonode@nohost and Livebook nodes)

Roadmap

Phase	Focus
1	Durable job queue (current)
2	Distributed coordination, leases, lifeline
3	Cron, uniqueness, dynamic queues
4	Rate limits, pause/resume
5	Batches
6	Observability APIs
7	Workflows and DAGs
8	Optional LiveView dashboard

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.