{"id":51033757,"url":"https://github.com/thanos/kathikon","last_synced_at":"2026-06-23T04:01:12.343Z","repository":{"id":365548447,"uuid":"1271359341","full_name":"thanos/kathikon","owner":"thanos","description":"Kathikon is a BEAM-native durable job queue and task execution platform for Elixir. Built on Mnesia and OTP, it provides distributed workers, retries, scheduling, cron, uniqueness, rate limiting, batches, and operational visibility without requiring PostgreSQL, Redis, or external brokers.","archived":false,"fork":false,"pushed_at":"2026-06-18T17:03:21.000Z","size":99,"stargazers_count":1,"open_issues_count":15,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T03:21:51.379Z","etag":null,"topics":["background-jobs","beam","cron","distributed-computing","distributed-systems","distributed-workers","elixir","fault-tolerance","high-availability","job-queue","mnesia","observability","orchestration","otp","rate-limiting","scheduling","task-queue","telemetry","workflow"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thanos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-16T15:28:35.000Z","updated_at":"2026-06-19T13:21:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/thanos/kathikon","commit_stats":null,"previous_names":["thanos/kathikon"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/thanos/kathikon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thanos%2Fkathikon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thanos%2Fkathikon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thanos%2Fkathikon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thanos%2Fkathikon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thanos","download_url":"https://codeload.github.com/thanos/kathikon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thanos%2Fkathikon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34659911,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["background-jobs","beam","cron","distributed-computing","distributed-systems","distributed-workers","elixir","fault-tolerance","high-availability","job-queue","mnesia","observability","orchestration","otp","rate-limiting","scheduling","task-queue","telemetry","workflow"],"created_at":"2026-06-22T03:01:58.895Z","updated_at":"2026-06-23T04:01:12.335Z","avatar_url":"https://github.com/thanos.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kathikon\n\n**Kathikon** (Greek: καθήκον — duty, obligation) is a BEAM-native durable job queue and task execution platform for Elixir.\n\nJobs are treated as durable obligations that must eventually be fulfilled: completed, retried, cancelled, or discarded — but never silently lost.\n\nKathikon uses **Mnesia** as its coordination store and **OTP** as its execution substrate. No PostgreSQL, Redis, RabbitMQ, or external brokers are required.\n\n## Status\n\n**v0.1.0 — Phase 1: Durable Job Queue**\n\n- Job insertion and queue execution\n- Retries with exponential backoff\n- Scheduling (`schedule_in`, `schedule_at`)\n- Priorities\n- Telemetry\n- Pruning / retention\n\n## Installation\n\n```elixir\ndef deps do\n  [\n    {:kathikon, \"~\u003e 0.1.0\"}\n  ]\nend\n```\n\n## Quick start\n\nDefine a worker:\n\n```elixir\ndefmodule MyApp.EmailWorker do\n  use Kathikon.Worker\n\n  @impl true\n  def perform(%Kathikon.Job{args: %{\"email\" =\u003e email}}) do\n    MyApp.Mailer.deliver(email)\n    :ok\n  end\nend\n```\n\nConfigure queues:\n\n```elixir\n# config/config.exs\nconfig :kathikon,\n  queues: [\n    default: [concurrency: 10],\n    emails: [concurrency: 5]\n  ]\n```\n\nEnqueue jobs:\n\n```elixir\n{:ok, job} = Kathikon.insert(MyApp.EmailWorker, %{\"email\" =\u003e \"user@example.com\"})\n\n{:ok, job} =\n  Kathikon.insert(MyApp.EmailWorker, %{\"email\" =\u003e \"user@example.com\"},\n    queue: :emails,\n    priority: 5,\n    schedule_in: 60,\n    max_attempts: 10\n  )\n```\n\nCancel a pending job:\n\n```elixir\n{:ok, job} = Kathikon.cancel(job_id)\n```\n\n## Architecture\n\n```\nKathikon.Supervisor\n├── Registry\n├── Kathikon.Queue (DynamicSupervisor)\n│   └── Kathikon.Dispatcher (one per queue)\n├── Kathikon.Scheduler\n└── Kathikon.Pruner\n```\n\n| Module | Role |\n|--------|------|\n| `Kathikon.Job` | Job struct and state machine |\n| `Kathikon.Worker` | Worker behaviour (`perform/1`) |\n| `Kathikon.Storage` | Storage facade over `Kathikon.Backend.Storage` |\n| `Kathikon.Dispatcher` | Claims and executes jobs per queue |\n| `Kathikon.Scheduler` | Promotes scheduled jobs to available |\n| `Kathikon.Pruner` | Enforces retention on terminal jobs |\n| `Kathikon.Backend.Storage` | Storage behaviour (default: `…Mnesia`) |\n| `Kathikon.Telemetry` | `[:kathikon, ...]` telemetry events |\n\n## Job states\n\n```\nscheduled → available → executing → completed\n                    ↘           ↘ retryable → ...\n                      cancelled   discarded\n```\n\n## Telemetry\n\nKathikon emits standard telemetry events. See [Telemetry guide](docs/guides/telemetry-and-observability.md) for the full list. Highlights:\n\n- Job: `[:kathikon, :job, :insert]`, `:start`, `:stop`, `:sleep`, `:retry`, `:discard`, `:cancel`, `:prune`\n- Runtime: `[:kathikon, :scheduler, :tick]`, `[:kathikon, :pruner, :tick]`, `[:kathikon, :dispatcher, :poll]`\n\nAttach the default logger in development:\n\n```elixir\nKathikon.Telemetry.attach_default_logger()\n```\n\n## Configuration\n\n| Key | Default | Description |\n|-----|---------|-------------|\n| `:queues` | `[default: [concurrency: 10]]` | Queue names and concurrency |\n| `:poll_interval` | `200` | Dispatcher poll interval (ms) |\n| `:scheduler_interval` | `1000` | Scheduler tick interval (ms) |\n| `:prune_interval` | `60000` | Pruner tick interval (ms) |\n| `:retention_period` | `7 days` | How long to keep terminal jobs (ms) |\n| `:max_attempts` | `20` | Default retry limit |\n| `:mnesia_copies` | `:auto` | Mnesia storage: `:ram`, `:disc`, or `:auto` (`ram` on `nonode@nohost` and Livebook nodes) |\n\n## Roadmap\n\n| Phase | Focus |\n|-------|-------|\n| 1 | Durable job queue (current) |\n| 2 | Distributed coordination, leases, lifeline |\n| 3 | Cron, uniqueness, dynamic queues |\n| 4 | Rate limits, pause/resume |\n| 5 | Batches |\n| 6 | Observability APIs |\n| 7 | Workflows and DAGs |\n| 8 | Optional LiveView dashboard |\n\n## Documentation\n\nGenerate HTML docs with [ExDoc](https://github.com/elixir-lang/ex_doc):\n\n```bash\nmix docs\nopen doc/index.html\n```\n\n- **[Documentation index](docs/documentation.md)** — guides and module reference (source)\n- [Quick start](docs/guides/quick-start.md)\n- [Module reference](docs/reference/modules.md)\n- [Configuration](docs/guides/configuration.md)\n- [Interactive demo (Livebook)](livebooks/kathikon_demo.livemd)\n\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthanos%2Fkathikon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthanos%2Fkathikon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthanos%2Fkathikon/lists"}