Kathikon.Cron (Kathikon v0.2.0)

Cron-based recurring job scheduling.

Registers durable recurring schedules that enqueue Kathikon jobs when their cron expression matches. Schedules are stored in Mnesia and evaluated by Kathikon.Scheduler.BuiltIn.Tick.

Cron fields and presets are interpreted in config :kathikon, timezone.

Examples

# Register a daily job
{:ok, id} =
  Kathikon.Cron.insert(MyApp.Workers.SendDigest, %{"list" => "all"},
    cron: "0 9 * * *",
    queue: :email
  )

# Change the schedule at runtime
{:ok, schedule} = Kathikon.Cron.update(id, cron: "0 10 * * *")

# Cancel
:ok = Kathikon.Cron.cancel(id)

See Kathikon.Cron.Expression for supported cron syntax.

Summary

Functions

cancel(schedule_id)

Cancels a recurring schedule.

expand(expression)

Expands preset macros (@daily, @hourly, etc.) to canonical cron strings.

fetch(schedule_id)

Fetches a recurring schedule by id.

insert(worker, args, opts \\ [])

Registers a recurring cron schedule.

list(opts \\ [])

Lists all registered recurring schedules.

update(schedule_id, opts)

Updates a recurring schedule in real time.

valid?(expression)

Returns whether a cron expression is valid.

Functions

cancel(schedule_id)

@spec cancel(String.t()) :: :ok | {:error, term()}

Cancels a recurring schedule.

Examples

:ok = Kathikon.Cron.cancel(schedule_id)

expand(expression)

@spec expand(String.t()) :: String.t()

Expands preset macros (@daily, @hourly, etc.) to canonical cron strings.

Examples

Kathikon.Cron.expand("@daily")
#=> "0 0 * * *"

fetch(schedule_id)

@spec fetch(String.t()) :: {:ok, map()} | {:error, term()}

Fetches a recurring schedule by id.

Examples

{:ok, schedule} = Kathikon.Cron.fetch(schedule_id)

insert(worker, args, opts \\ [])

@spec insert(module(), map(), keyword()) :: {:ok, String.t()} | {:error, term()}

Registers a recurring cron schedule.

Options

:cron — required 5-field cron expression
:queue — target queue (default :default)
:id — optional stable schedule id for idempotent registration

Returns {:ok, schedule_id} or {:error, reason}.

Examples

{:ok, id} =
  Kathikon.Cron.insert(MyApp.SendDigest, %{"list" => "all"},
    cron: "0 9 * * *",
    queue: :email
  )

list(opts \\ [])

@spec list(keyword()) :: {:ok, [map()]} | {:error, term()}

Lists all registered recurring schedules.

Examples

{:ok, schedules} = Kathikon.Cron.list()

update(schedule_id, opts)

@spec update(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Updates a recurring schedule in real time.

Supported keys: :cron, :worker, :args, :queue, and any job insert options.

Changing :cron resets the last-fired timestamp.

Examples

{:ok, schedule} = Kathikon.Cron.update(schedule_id, cron: "0 10 * * *")

valid?(expression)

@spec valid?(String.t()) :: boolean()

Returns whether a cron expression is valid.

Examples

Kathikon.Cron.valid?("0 9 * * *")
#=> true

Kathikon.Cron.valid?("not a cron")
#=> false